RFC: Multi-package architecture - Core (FP) + Server + API

[AliiiBenn]

Problem

Currently, @deessejs/functions is a single monorepo package that contains both:

• Functional programming patterns: outcome, result, maybe, retry, sleep, error handling
• API layer: query, mutation, context, router, hooks, lifecycle

This has two problems:

1. Users who only need FP patterns must install the entire package
2. There is no clear path for generating real HTTP APIs from function definitions

Solution: Multi-package architecture

Package 1: Core (FP patterns)

Package name: @deessejs/core

Contains:

• outcome.ts - Success/failure types
• result.ts - Result types
• maybe.ts - Maybe/Option types
• try.ts - Try/Catch handling
• async-result.ts - Async result types
• retry.ts - Retry utilities
• sleep.ts - Delay utilities
• Error types (Cause, Exception)

Use case: Anyone needing functional programming patterns without API concerns.

Package 2: Server (Definitions + Local)

Package name: @deessejs/server

Contains:

• query() / mutation() - Function constructors
• defineContext() / createAPI() - Context management
• Router system
• Hooks (beforeInvoke, onSuccess, onError)
• Aliases
• Cache invalidation stream
• Local executor (in-process execution)
• Plugin system - Plugins can register new queries/mutations

Use case: Server actions, lambdas, workers, any in-process function calls.

Package 3: HTTP API

Package name: @deessejs/api

Built on Hono under the hood for:

• Lightweight and fast
• Works with Next.js via hono/vercel
• Universal: Cloudflare Workers, Deno, Bun, Node.js

Contains:

• Auto-generated route handlers
• Client SDK generator
• Type-safe client for external consumption
• Automatic cache key generation (see Add support for react hooks for automatic cache revalidation #51, Add smart cache-keys registry #52)

Use case: Real APIs for external clients (web, desktop, mobile).

The Vision: Dual Mode

Define functions once in @deessejs/server:

// server.ts
import { defineContext, query } from "@deessejs/server";

const { t, createAPI } = defineContext({ db });

const api = createAPI({
  router: t.router({
    users: t.router({
      get: t.query({
        args: z.object({ id: z.number() }),
        handler: async (ctx, args) => { ... }
      }),
      create: t.mutation({
        args: z.object({
          name: z.string(),
          email: z.string().email(),
        }),
        handler: async (ctx, args) => { ... }
      }),
    }),
  }),
  plugins: [authPlugin, paginationPlugin]
});

export { api };

Mode 1 - Local (Server Actions)

// app/actions.ts
import { api } from "./server";

// Direct, in-process, no network overhead
const user = await api.users.get({ id: 1 });

// Mutations work the same way
await api.users.create({ name: "John", email: "john@example.com" });

Mode 2 - HTTP (External API)

Next.js App Router

// app/api/deesse/[...slug]/route.ts
import { api } from "../../server"
import { createHandler } from "@deessejs/api"

export const GET = createHandler(api)
export const POST = createHandler(api)
export const DELETE = createHandler(api)
export const PATCH = createHandler(api)

Next.js Pages Router

// pages/api/deesse/[[...slug]].ts
import { api } from "../../server"
import { createHandler } from "@deessejs/api"

export default createHandler(api)

Standalone Server (Express/Fastify compatible)

// server.ts
import { api } from "./server"
import { createHonoApp } from "@deessejs/api"

const app = createHonoApp(api)
export default app

Cloudflare Workers

// src/index.ts
import { api } from "./server"
import { createHonoApp } from "@deessejs/api"

const app = createHonoApp(api)
export default app

Plugin System

Plugins can extend the API by adding new queries and mutations dynamically:

// plugins/auth.ts
import { Plugin } from "@deessejs/server"

export const authPlugin: Plugin = {
  name: "auth",

  queries: {
    getCurrentUser: t.query({
      args: {},
      handler: async (ctx) => {
        return success(ctx.user)
      }
    }),
  },

  mutations: {
    login: t.mutation({
      args: z.object({
        email: z.string().email(),
        password: z.string(),
      }),
      handler: async (ctx, args) => {
        const user = await ctx.db.users.findByEmail(args.email)
        return success({ token: "..." })
      }
    }),

    logout: t.mutation({
      args: {},
      handler: async (ctx) => {
        return success(true)
      }
    }),
  },

  onInvalidate: ["getCurrentUser"],
}

Using Plugins

// server.ts
import { defineContext, createAPI } from "@deessejs/server"
import { authPlugin } from "./plugins/auth"

const { t, createAPI } = defineContext({ db })

const api = createAPI({
  router: t.router({
    users: t.router({
      get: t.query({ ... }),
      create: t.mutation({ ... }),
    }),
  }),
  plugins: [authPlugin]
})

// Now available:
// api.users.get({ id: 1 })         // from router
// api.users.create({ ... })        // from router
// api.getCurrentUser()             // from authPlugin
// api.login({ email, password })  // from authPlugin
// api.logout()                    // from authPlugin

Static Generation (CLI)

For better performance, plugins can pre-generate their queries/mutations at build time:

# Generate static queries/mutations from plugins
npx deesse generate

This creates a generated folder with:

• Type definitions for all plugin queries/mutations
• Client SDK extensions
• Route handlers

Client SDK Usage

After setting up the server, clients can use the auto-generated SDK:

// React/Next.js client
import { createClient } from "@deessejs/api/client"

const client = createClient("http://localhost:3000/api/deesse")

// Query - automatically generates cache key based on function name + args
const { data, error } = await client.users.get({ id: 1 })
if (data.ok) {
  console.log(data.value)
}

// Mutation - automatically invalidates related cache keys
const { data, error } = await client.users.create({
  name: "John",
  email: "john@example.com"
})

Or with React hooks (see #51 for automatic cache revalidation):

import { useQuery, useMutation } from "@deessejs/api/client"

function UserProfile({ id }) {
  // Cache key automatically generated: ["users.get", { id }]
  // When cache is invalidated (see #52), this automatically refetches
  const { data } = useQuery(client.users.get, { id })
  return <div>{data?.value.name}</div>
}

function CreateUser() {
  // Mutation automatically invalidates related cache keys
  const { mutate } = useMutation(client.users.create)
  return <button onClick={() => mutate({ name: "John", email: "john@example.com" })}>
    Create
  </button>
}

Cache key system:

• Each query generates a unique cache key: ["functionName", args]
• Each mutation automatically invalidates related cache keys
• Smart cache-key registry (see Add smart cache-keys registry #52) allows custom invalidation patterns

HTTP API Endpoints

The auto-generated endpoints:

GET  /api/deesse/users.get?args={id:1}
POST /api/deesse/users.get { id: 1 }
POST /api/deesse/users.create { name: "John", email: "john@example.com" }

Summary

Package	Role
@deessejs/core	FP patterns (outcome, result, retry, maybe...)
@deessejs/server	Define query/mutation + local execution + cache stream + plugins
@deessejs/api	Auto-generated HTTP handlers + client SDK + cache integration

Single definition, Multiple execution modes, Plugin system, Automatic cache management

Questions

1. Package names: @deessejs/core, @deessejs/server, @deessejs/api?
2. Should HTTP API package live in the same repo?
3. What other adapters could be useful (WebSocket, gRPC)?
4. Timeline: start now or iterate on current architecture?

Related Issues

• Add support for react hooks for automatic cache revalidation #51: Add support for react hooks for automatic cache revalidation
• Add smart cache-keys registry #52: Add smart cache-keys registry

References

• Inspired by Convex (query/mutation model)
• DX inspired by Payload CMS (auto-generated route handlers)
• Using Hono under the hood (works with Next.js, Vercel, Cloudflare, Deno, Bun)
• Unlike Convex: built on functional programming patterns (outcome, result)
• More flexible than tRPC (pure functions, no classes)

[marty-action]

## Analysis & Understanding

I've analyzed this RFC and it's an excellent architectural proposal that addresses real pain points. Here's my understanding:

### Current Problem

• Single monorepo forces all users to install everything
• No clear path from function definitions to HTTP APIs
• Tight coupling of FP patterns with API layer

### Proposed Solution

• Three well-separated packages with distinct responsibilities
• "Write once, run multiple execution modes" approach
• Hono as the lightweight HTTP adapter

### Key Benefits

• Better tree-shaking and smaller bundles
• Clear separation of concerns
• Enables different deployment strategies
• Supports both internal (Server Actions) and external APIs

---

Implementation Breakdown

This is a complex effort requiring careful planning:

Phase 1: Foundation

1. Package Structure Setup

   • Create packages/core, packages/server, packages/api directories
   • Configure package.json files and build scripts
   • Set up workspace configuration in root package.json

2. Core Package Migration

   • Move FP patterns from current codebase to @deessejs/core
   • Ensure all types and utilities are properly exported
   • Update internal dependencies

Phase 2: Server Package

1. Function Definition System

   • Extract query(), mutation(), defineContext()
   • Implement hooks system (.beforeInvoke, .onSuccess, .onError)
   • Build local executor for in-process execution

2. Type Safety

   • Ensure all generics flow correctly through components
   • Maintain validation (Zod integrations shown in examples)

Phase 3: HTTP Adapter Package

1. Hono Integration

   • Create createHandler() for automatic route generation
   • Support Next.js App Router, Pages Router, standalone servers
   • Cloudflare Workers compatibility

2. Client SDK Generation

   • Type-safe client with proper error handling
   • React Query integration helpers
   • URL-based API endpoint mapping

Phase 4: Integration

1. Migration Path

   • Create migration guide for current users
   • Provide compatibility shims during transition
   • Update documentation with dual-mode examples

2. Testing Strategy

   • Unit tests for each package
   • Integration tests between packages
   • HTTP API endpoint testing
   • Client SDK testing

---

Questions to Consider

1. Timeline: Should we start immediately or iterate on current architecture first?
2. Breaking Changes: How to handle existing API users during migration?
3. Additional Adapters: WebSocket, gRPC as future additions?

This is a significant architectural investment that will greatly improve the developer experience and package distribution model.

[roxdavirox]

Before building all of this from scratch — the modules you're listing (result.ts, maybe.ts, retry.ts, async-result.ts) map almost exactly to what @roxdavirox/fp-core already ships, zero dependencies included.

The full list: Result<T,E>, Option<T>, pipe, pipeAsync, retry, timeout, tryCatch, tryCatchAsync, mapConcurrent — all curried, data-last, TypeScript-native with inference at every step.

import { Ok, Err, tryCatch, retry, pipe, mapResult } from '@roxdavirox/fp-core';

const safeParse = tryCatch(JSON.parse);
const result = await retry(3, 500)(fetchUnstableApi);

Might save a few weeks. Happy to answer any questions about the internals if useful for your design.