ts-procedures 8.6.0 → 9.1.0

package/src/create.ts

@@ -1,172 +0,0 @@
-import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError } from './errors.js'
-import { computeSchema } from './schema/compute-schema.js'
-import type { Prettify, TSchemaLib } from './schema/types.js'
-import { captureDefinitionInfo } from './stack-utils.js'
-import type {
-  TBuilderConfig,
-  THttpProcedureRegistration,
-  THttpStreamProcedureRegistration,
-  TLocalContext,
-  TProcedureRegistration,
-  TStreamProcedureRegistration,
-} from './types.js'
-
-export type CreateBuilderArg<TContext, TExtendedConfig> = {
-  config?: TBuilderConfig
-  onCreate?: (
-    procedure:
-      | TProcedureRegistration<TContext, TExtendedConfig>
-      | TStreamProcedureRegistration<TContext, TExtendedConfig>
-  ) => void
-}
-
-export function makeCreate<TContext, TExtendedConfig>(
-  procedures: Map<
-    string,
-    | TProcedureRegistration<TContext, TExtendedConfig>
-    | TStreamProcedureRegistration<TContext, TExtendedConfig>
-    | THttpProcedureRegistration<TContext>
-    | THttpStreamProcedureRegistration<TContext>
-  >,
-  builder?: CreateBuilderArg<TContext, TExtendedConfig>
-) {
-  return function Create<TName extends string, TParams, TReturnType>(
-    name: TName,
-    config: {
-      description?: string
-      schema?: {
-        params?: TParams
-        returnType?: TReturnType
-      }
-    } & TExtendedConfig,
-    handler: (
-      ctx: Prettify<TContext & TLocalContext>,
-      params: TSchemaLib<TParams>
-    ) => Promise<TSchemaLib<TReturnType>>
-  ) {
-    // Capture definition location as first action
-    const definitionInfo = captureDefinitionInfo()
-
-    const HTTP_FIELDS = ['path', 'method', 'req', 'res', 'successStatus'] as const
-    const presentHttpFields = HTTP_FIELDS.filter((f) => (config as any)[f] !== undefined)
-    if (presentHttpFields.length > 0) {
-      throw new ProcedureRegistrationError(
-        name,
-        `HTTP fields require CreateHttp / CreateHttpStream. Procedure "${name}" has [${presentHttpFields.join(', ')}] which are not valid on Create.`,
-        definitionInfo,
-      )
-    }
-
-    // BEFORE computeSchema - fail fast on duplicate
-    if (procedures.has(name)) {
-      throw new Error(`Procedure with name ${name} is already registered`)
-    }
-
-    const { jsonSchema, validations } = computeSchema(name, config.schema, definitionInfo)
-
-    // Create error factory once at registration time (outside handler)
-    const errorFactory = (message: string, meta?: object) =>
-      new ProcedureError(name, message, meta, definitionInfo)
-
-    const registeredProcedure: TProcedureRegistration<TContext, TExtendedConfig> = {
-      name,
-      kind: 'rpc',
-      config: {
-        ...config,
-        description: config.description,
-        schema: jsonSchema,
-        validation: {
-          params: validations.params,
-        },
-      },
-
-      handler: async (ctx: Prettify<TContext>, params: TSchemaLib<TParams>) => {
-        try {
-          // Skip validation if caller has already validated or if builder config dictates noRuntimeValidation
-          const skipValidation =
-            (ctx as { isPrevalidated?: boolean }).isPrevalidated ||
-            builder?.config?.noRuntimeValidation
-
-          if (validations?.params && !skipValidation) {
-            const { errors } = validations.params(params)
-
-            if (errors) {
-              throw new ProcedureValidationError(
-                name,
-                `Validation error for ${name}`,
-                errors,
-                definitionInfo
-              )
-            }
-          }
-
-          const localCtx: TLocalContext = {
-            error: errorFactory,
-          }
-
-          // params is correctly typed at the public API boundary;
-          // cast here because TS cannot narrow generics inside implementations
-          return await handler(
-            { ...ctx, ...localCtx } as Prettify<TContext & TLocalContext>,
-            params as any
-          )
-        } catch (error: any) {
-          if (error instanceof ProcedureError) throw error
-          const err = new ProcedureError(
-            name,
-            `Error in handler for ${name} - ${error?.message}`,
-            undefined,
-            definitionInfo
-          )
-          err.cause = error
-          // Preserve original stack but append definition info
-          if (error.stack && definitionInfo.definedAt) {
-            const { file, line, column } = definitionInfo.definedAt
-            err.stack =
-              error.stack +
-              `\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
-          } else if (error.stack) {
-            err.stack = error.stack
-          }
-          throw err
-        }
-      },
-    }
-
-    procedures.set(name, registeredProcedure)
-    builder?.onCreate?.(registeredProcedure)
-
-    const info = {
-      name,
-      ...registeredProcedure.config,
-    }
-
-    // return so can be called directly (ie: int/unit tests)
-    return {
-      [name]: registeredProcedure.handler,
-      procedure: registeredProcedure.handler,
-      info,
-    } as {
-      [K in TName]: (
-        ctx: Prettify<TContext>,
-        params: TSchemaLib<TParams>
-      ) => Promise<TSchemaLib<TReturnType>>
-    } & {
-      procedure: (
-        ctx: Prettify<TContext>,
-        params: TSchemaLib<TParams>
-      ) => Promise<TSchemaLib<TReturnType>>
-      info: {
-        name: TName
-        description?: string
-        schema: {
-          params?: TParams
-          returnType?: TReturnType
-        }
-        validation?: {
-          params?: (params: any) => { errors?: any[] }
-        }
-      } & TExtendedConfig
-    }
-  }
-}

package/src/implementations/http/README.md

@@ -1,390 +0,0 @@
-# HTTP Implementations
-
-HTTP implementation builders for `ts-procedures` that create type-safe, versioned endpoints with automatic path generation, schema-based validation, and route documentation.
-
-## Available Implementations
-
-| Framework | Subpath | Description |
-|-----------|---------|-------------|
-| HonoAppBuilder | `ts-procedures/hono` | Unified Hono builder — dispatches RPC, RPC streams, REST, and REST streams from one `register()` call. Works on Bun, Deno, Cloudflare Workers, and Node.js. |
-
-`HonoAppBuilder` is a unified builder: one builder, one `app`, one set of cross-cutting hooks. The procedure kind drives behavior — pick the creator that matches the shape you need.
-
-### Procedure kinds and which creator to use
-
-| Procedure kind | Created with | Config shape | Handler return | HTTP methods | Use case |
-|----------------|--------------|--------------|----------------|--------------|----------|
-| `rpc` | `Create()` | `RPCConfig` (`scope`, `version`) | `Promise<T>` | POST | Standard request/response |
-| `rpc-stream` | `CreateStream()` | `RPCConfig` | `AsyncGenerator<T>` | GET, POST | RPC-style streaming (SSE / text) |
-| `http` | `CreateHttp()` | `APIConfig` (`path`, `method`) | `Promise<T>` | GET, POST, PUT, DELETE, PATCH, HEAD | REST-style endpoint with `schema.req` channels |
-| `http-stream` | `CreateHttpStream()` | `APIConfig` | `AsyncGenerator<T>` | GET, POST | REST-style streaming endpoint |
-
-`HonoAppBuilder` accepts all four kinds from the same factory.
-
-## Core Concepts
-
-### Config Interfaces
-
-RPC and RPC-stream procedures share `RPCConfig`:
-
-```typescript
-interface RPCConfig {
-  scope: string | string[]  // Route path segment(s)
-  version: number           // API version number
-  errors?: string[]         // Optional taxonomy keys for typed-client narrowing
-}
-```
-
-REST-style procedures (`CreateHttp` / `CreateHttpStream`) use `APIConfig`:
-
-```typescript
-interface APIConfig {
-  path: string              // Route path with Hono params (e.g., '/users/:id')
-  method: HttpMethod        // 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
-  successStatus?: number    // Default: POST→201, DELETE→204, others→200
-  scope?: string            // Optional grouping for codegen file emission
-  errors?: string[]
-}
-```
-
-API routes use developer-defined paths — no auto-generation from scope/version.
-
-### Path Generation
-
-Routes are generated using kebab-case conversion:
-
-```
-/{pathPrefix}/{scope...}/{procedureName}/{version}
-```
-
-**Examples:**
-
-| Scope | Procedure Name | Version | Generated Path |
-|-------|----------------|---------|----------------|
-| `'users'` | `'Create'` | `1` | `/users/create/1` |
-| `'users'` | `'GetById'` | `1` | `/users/get-by-id/1` |
-| `['users', 'admin']` | `'List'` | `1` | `/users/admin/list/1` |
-| `['UserModule', 'permissions']` | `'Update'` | `2` | `/user-module/permissions/update/2` |
-
-**With pathPrefix `/api/v1`:**
-
-| Scope | Procedure Name | Version | Generated Path |
-|-------|----------------|---------|----------------|
-| `'users'` | `'Create'` | `1` | `/api/v1/users/create/1` |
-| `['users', 'admin']` | `'Delete'` | `2` | `/api/v1/users/admin/delete/2` |
-
-### Context Resolution
-
-The `factoryContext` parameter supports three patterns:
-
-```typescript
-// 1. Static object
-builder.register(Factory, { userId: 'static-123' })
-
-// 2. Sync function
-builder.register(Factory, (c) => ({
-  userId: c.req.header('x-user-id')
-}))
-
-// 3. Async function
-builder.register(Factory, async (c) => {
-  const user = await validateToken(c.req.header('authorization'))
-  return { userId: user.id }
-})
-```
-
-### Abort Signal
-
-All HTTP implementations automatically inject an `AbortSignal` into the handler context as `ctx.signal`. This signal aborts when the client disconnects, enabling handlers to cancel in-flight work (fetch calls, database queries, etc.).
-
-| Framework | Procedure kind | Signal source | Behavior |
-|-----------|---------------|---------------|----------|
-| HonoAppBuilder | `rpc`, `http` | `c.req.raw.signal` | Web standard Request signal |
-| HonoAppBuilder | `rpc-stream`, `http-stream` | `c.req.raw.signal` | Combined with internal stream AbortController via `AbortSignal.any()` |
-
-For streaming procedures, `signal.reason` is `'stream-completed'` on normal completion, allowing handlers to distinguish from client disconnection.
-
-### Error Handling
-
-Both builders support two peer error-handling modes — **declarative** (`errors` taxonomy + `unknownError`) and **imperative** (`onError` callback) — plus a cross-cutting `onRequestError` observer for logging, tracing, and metrics.
-
-Full spec (taxonomy shape, `toResponse`/`onCatch`/`match`, per-route narrowing, mid-stream caveats): **[docs/http-integrations.md § Error Handling](../../../docs/http-integrations.md#error-handling)**.
-
-### Lifecycle Hooks
-
-`HonoAppBuilder`'s config is **stratified**: cross-cutting hooks live at the top level, kind-specific hooks live inside `rpc:`, `api:`, and `stream:` blocks.
-
-```typescript
-new HonoAppBuilder({
-  // Cross-cutting (every kind)
-  onRequestStart, onRequestEnd, onRequestError,
-  errors, unknownError, onError,
-
-  // Kind-specific blocks
-  rpc:    { onSuccess },
-  api:    { queryParser, onSuccess },
-  stream: { defaultStreamMode, onStreamStart, onStreamEnd, onMidStreamError },
-})
-```
-
-**Non-streaming flow (`rpc`, `http`):**
-
-```
-onRequestStart → handler → onSuccess → onRequestEnd
-                    ↓
-              (on error)
-                    ↓
-            onRequestError (observer)
-                    ↓
-        errors taxonomy / onError fallback
-                    ↓
-              onRequestEnd
-```
-
-**Streaming flow (`rpc-stream`, `http-stream`):**
-
-```
-onRequestStart → onStreamStart → [yields...] → onStreamEnd → onRequestEnd
-                      ↓
-                 (on error)
-                      ↓
-   ┌──────────────────┴──────────────────┐
-   ↓ (pre-stream — before onStreamStart) ↓ (mid-stream — after first yield)
-errors taxonomy / onError → onRequestEnd  onMidStreamError → onStreamEnd → onRequestEnd
-```
-
-Pre-stream errors short-circuit before `onStreamStart` fires, so `onStreamEnd` does **not** run on that path. Mid-stream errors run `onMidStreamError` and then still fire `onStreamEnd` because the stream had already started.
-
-| Hook | Config block | Triggers on |
-|------|--------------|-------------|
-| `onRequestStart` | top-level | Before route handler (every kind) |
-| `onRequestEnd` | top-level | After response sent (every kind) |
-| `onRequestError` | top-level | Cross-cutting observer — fires for every caught error before dispatch |
-| `onError` | top-level | Imperative pre-stream error callback — peer of `errors` taxonomy |
-| `errors` / `unknownError` | top-level | Declarative taxonomy dispatch |
-| `rpc.onSuccess` | `rpc:` | After successful RPC handler |
-| `api.onSuccess` | `api:` | After successful HTTP handler |
-| `api.queryParser` | `api:` | Custom query-string parser for HTTP routes |
-| `stream.defaultStreamMode` | `stream:` | Default mode (`'sse'` \| `'text'`) for both stream kinds |
-| `stream.onStreamStart` | `stream:` | Before first yield |
-| `stream.onStreamEnd` | `stream:` | After stream completes |
-| `stream.onMidStreamError` | `stream:` | On mid-stream error (generator throws after first yield) |
-
-### Route Documentation
-
-Each registered procedure generates documentation accessible via `builder.docs`. Every doc carries a `kind` discriminant for reliable narrowing.
-
-**RPC (`RPCHttpRouteDoc`, `kind: 'rpc'`):**
-
-```typescript
-interface RPCHttpRouteDoc {
-  kind: 'rpc'
-  name: string
-  path: string
-  method: 'post'
-  scope: string | string[]
-  version: number
-  errors?: string[]
-  jsonSchema: {
-    body?: object      // From schema.params
-    response?: object  // From schema.returnType
-  }
-}
-```
-
-**RPC stream (`StreamHttpRouteDoc`, `kind: 'stream'`):**
-
-```typescript
-interface StreamHttpRouteDoc {
-  kind: 'stream'
-  name: string
-  path: string
-  methods: ('get' | 'post')[]
-  streamMode: 'sse' | 'text'
-  scope: string | string[]
-  version: number
-  errors?: string[]
-  jsonSchema: {
-    params?: object     // From schema.params
-    yieldType?: object  // From schema.yieldType
-    returnType?: object // From schema.returnType
-  }
-}
-```
-
-**REST (`APIHttpRouteDoc`, `kind: 'api'`):**
-
-```typescript
-interface APIHttpRouteDoc {
-  kind: 'api'
-  name: string
-  scope?: string
-  path: string
-  method: HttpMethod
-  fullPath: string           // Includes pathPrefix
-  successStatus?: number
-  errors?: string[]
-  jsonSchema: {
-    req?: {
-      pathParams?: object    // From schema.req.pathParams
-      query?: object         // From schema.req.query
-      body?: object          // From schema.req.body
-      headers?: object       // From schema.req.headers
-    }
-    res?: {
-      body?: object           // From schema.res.body
-      headers?: object        // From schema.res.headers
-    }
-  }
-}
-```
-
-**REST stream (`HttpStreamRouteDoc`, `kind: 'http-stream'`):**
-
-```typescript
-interface HttpStreamRouteDoc {
-  kind: 'http-stream'
-  name: string
-  scope?: string
-  path: string
-  method: HttpMethod
-  fullPath: string
-  streamMode: 'sse' | 'text'
-  errors?: string[]
-  jsonSchema: {
-    req?: {
-      pathParams?: object
-      query?: object
-      body?: object
-      headers?: object
-    }
-    res?: { headers?: object }
-    yield?: object
-    returnType?: object
-  }
-}
-```
-
-### Builder Pattern
-
-Both builders follow the same pattern:
-
-```typescript
-const builder = new HonoAppBuilder(config)
-  .register(PublicFactory, publicContextResolver)
-  .register(ProtectedFactory, protectedContextResolver)
-
-const app = builder.build()
-const docs = builder.docs
-```
-
-`build()` is synchronous — it returns the framework app instance directly. Don't `await` the call.
-
-A single `HonoAppBuilder` registers procedures of every kind from the same factory and mounts them on one Hono `app`. The optional `app?: Hono` config lets you mount onto an existing Hono instance that already has custom middleware, health checks, or static routes; if omitted, the builder constructs its own.
-
-**Key methods:**
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `register(factory, context, options?)` | `this` | Register a procedure factory |
-| `build()` | Framework app | Create routes and return the application |
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `app` | Framework app | The underlying framework application |
-| `docs` | Route doc array | Route documentation, lazily computed on first read; `build()` also populates it. |
-
-### DocRegistry
-
-For single-builder apps, prefer `builder.toDocEnvelope({ basePath, errors })` — it wraps `DocRegistry` for the common case and produces an envelope identical to the multi-app aggregator.
-
-For multi-app aggregation (e.g., two `HonoAppBuilder` instances mounted on different prefixes), `DocRegistry` composes route documentation from every source into one typed envelope:
-
-```typescript
-import { DocRegistry } from 'ts-procedures/http-docs'
-
-const docs = new DocRegistry({
-  basePath: '/api',
-  errors: appErrors,  // your ErrorTaxonomy — framework defaults auto-merged and deduped
-})
-  .from(builderA)
-  .from(builderB)
-
-app.get('/docs', (c) => c.json(docs.toJSON()))
-```
-
-- `from()` stores a reference — routes are read lazily at `toJSON()` time
-- `toJSON()` supports optional `filter` and `transform` options
-- `errors` accepts an `ErrorTaxonomy` or raw `ErrorDoc[]`; framework defaults are auto-merged (opt out via `includeDefaults: false`)
-- Every builder satisfies the `DocSource` interface (`{ readonly docs: AnyHttpRouteDoc[] }`)
-
-### Client Code Generation
-
-Generate type-safe client SDKs from your DocRegistry output. The codegen reads the `DocEnvelope` JSON and produces per-scope TypeScript files with typed params, response types, and callable functions.
-
-**Requirements:** every route needs a `scope` field for file grouping. RPC and stream routes carry `scope` via `RPCConfig`. REST routes (`CreateHttp` / `CreateHttpStream`) carry an optional `scope` directly on the procedure config:
-
-```typescript
-procs.CreateHttp('GetUser', {
-  path: '/users/:id',
-  method: 'get',
-  scope: 'users', // Used for codegen file grouping
-  schema: { req: { pathParams: Type.Object({ id: Type.String() }) } },
-}, async (_, { pathParams }) => /* ... */)
-```
-
-**Route-doc kinds and how the codegen consumes them:**
-
-| Doc kind | Source procedure | Params shape in generated callable | Generated callable |
-|----------|------------------|------------------------------------|--------------------|
-| `rpc` | `Create()` | `jsonSchema.body` → flat params | `client.call()` |
-| `api` | `CreateHttp()` | `jsonSchema.req.{pathParams,query,body,headers}` → structured params | `client.call()` |
-| `stream` | `CreateStream()` | `jsonSchema.params` → flat params | `client.stream()` |
-| `http-stream` | `CreateHttpStream()` | `jsonSchema.req.{pathParams,query,body,headers}` → structured params | `client.stream()` |
-
-**SSE return values:** Stream procedures that return a value have it sent as `event: 'return'` SSE message. The client's `TypedStream.result` promise resolves with this value.
-
-**SSE yieldType unwrapping:** Codegen detects the SSE envelope in `yieldType` and uses the inner `data` schema for the generated `Yield` type.
-
-**Kind discriminant:** All route docs include a `kind` field (`'rpc' | 'api' | 'stream' | 'http-stream'`) for reliable type narrowing in the codegen pipeline and consumer code.
-
-**Namespace types:** Use `--namespace-types` to wrap generated types in nested TS namespaces (`Scope.Route.Params`) instead of flat prefixed exports (`RouteParams`).
-
-**ajsc options:** `--enum-style`, `--depluralize`, `--array-item-naming`, `--uncountable-words` are passed through to the ajsc TypescriptConverter for JSON Schema → TypeScript conversion.
-
-**Self-contained mode:** Use `--self-contained` to emit `_types.ts` (all client type definitions) and `_client.ts` (runtime: `createClient`, `createFetchAdapter`, hooks, errors) into the output directory. All scope files and `index.ts` will import from `./_types` instead of `ts-procedures/client`, so consumers have no runtime dependency on `ts-procedures`. With this flag, `ts-procedures` can be a devDependency only.
-
-**Clean output directory:** Use `--clean-out-dir` (or `cleanOutDir: true` in the programmatic API) to recursively remove the output directory before writing, so scope files left over from deleted or renamed scopes are pruned. Skipped under `--dry-run`.
-
-## TypeScript Types
-
-```typescript
-import type {
-  RPCConfig,
-  RPCHttpRouteDoc,
-  StreamHttpRouteDoc,
-  HttpStreamRouteDoc,
-  StreamMode,
-  APIConfig,
-  APIHttpRouteDoc,
-  APIInput,
-  HttpMethod,
-} from 'ts-procedures/http'
-
-// Client Runtime
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import type {
-  ClientAdapter,
-  ClientHooks,
-  TypedStream,
-  ClientInstance,
-  ProcedureCallDefaults,
-  ProcedureCallOptions,
-  RequestMeta,
-} from 'ts-procedures/client'
-
-// Code Generation (build-time only)
-import { generateClient } from 'ts-procedures/codegen'
-```