ts-procedures 7.3.0 → 8.0.0

package/src/implementations/http/hono-api/index.ts

@@ -1,519 +0,0 @@
-import { Hono, Context } from 'hono'
-import { TProcedureRegistration } from '../../../index.js'
-import {
-  ExtractConfig,
-  ExtractContext,
-  ProceduresFactory,
-  APIConfig,
-  APIHttpRouteDoc,
-  APIInput,
-  HttpMethod,
-} from '../../types.js'
-import {
-  ErrorTaxonomy,
-  ErrorTaxonomyEntry,
-  UnknownErrorConfig,
-  defineErrorTaxonomy,
-  resolveErrorResponse,
-} from '../error-taxonomy.js'
-import { HonoAPIFactoryItem } from './types.js'
-
-export type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod }
-export { defineErrorTaxonomy }
-export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig }
-
-// ================
-// Query string parsing
-// ================
-
-export type QueryParser = (queryString: string) => Record<string, unknown>
-
-/** Default query parser using native URLSearchParams. */
-function parseQueryNative(queryString: string): Record<string, unknown> {
-  const searchParams = new URLSearchParams(queryString)
-  const result: Record<string, unknown> = {}
-  for (const key of new Set(searchParams.keys())) {
-    const values = searchParams.getAll(key)
-    result[key] = values.length > 1 ? values : values[0]
-  }
-  return result
-}
-
-/** Extract path parameter names from a route pattern (e.g., '/users/:id' → ['id']) */
-function extractPathParamNames(path: string): string[] {
-  const matches = path.match(/:([a-zA-Z_][a-zA-Z0-9_]*)/g)
-  return matches ? matches.map((m) => m.slice(1)) : []
-}
-
-/** Default success status codes by HTTP method */
-function defaultSuccessStatus(method: HttpMethod): number {
-  switch (method) {
-    case 'post':
-      return 201
-    case 'delete':
-      return 204
-    default:
-      return 200
-  }
-}
-
-/** HTTP methods that typically carry a request body */
-const BODY_METHODS: HttpMethod[] = ['post', 'put', 'patch']
-
-/** Extracts the raw query string from a URL and runs it through the resolved parser. */
-function extractQuery(url: string, queryParser: QueryParser): Record<string, unknown> {
-  const questionMark = url.indexOf('?')
-  if (questionMark === -1) return {}
-  const rawQuery = url.slice(questionMark + 1)
-  if (!rawQuery) return {}
-  return queryParser(rawQuery)
-}
-
-// ================
-// Builder
-// ================
-
-export type HonoAPIAppBuilderConfig = {
-  /**
-   * An existing Hono application instance to use.
-   * If not provided, a new instance will be created.
-   */
-  app?: Hono
-  /** Optional path prefix for all API routes. */
-  pathPrefix?: string
-  /**
-   * Custom query string parser. Receives the raw query string (without '?').
-   *
-   * Default: native `URLSearchParams`. The default handles:
-   *   - flat keys:      `?page=2&limit=10` → `{ page: '2', limit: '10' }`
-   *   - repeated keys:  `?tag=a&tag=b`     → `{ tag: ['a', 'b'] }`
-   *
-   * The default does NOT parse any of these — the bracket/dot syntax is kept
-   * as part of the literal key name, not interpreted:
-   *   - bracket objects:    `?user[name]=John`       → `{ 'user[name]': 'John' }`
-   *   - bracket arrays:     `?tags[]=a&tags[]=b`     → `{ 'tags[]': ['a', 'b'] }`
-   *   - dot paths:          `?user.name=John`        → `{ 'user.name': 'John' }`
-   *   - comma-split arrays: `?tags=a,b,c`            → `{ tags: 'a,b,c' }`
-   *
-   * For any of the above, install `qs` and opt in explicitly:
-   *   `queryParser: (raw) => qs.parse(raw) as Record<string, unknown>`
-   */
-  queryParser?: QueryParser
-  onRequestStart?: (c: Context) => void
-  onRequestEnd?: (c: Context) => void
-  onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
-  /**
-   * Declarative error-to-response mapping (one of the two peer error modes).
-   * When a thrown error matches an entry (by `class` or `match`), the builder
-   * serializes it automatically. User entries are checked before the framework
-   * defaults (`ProcedureValidationError`, `ProcedureYieldValidationError`,
-   * `ProcedureError`).
-   */
-  errors?: ErrorTaxonomy
-  /**
-   * Fallback serializer for errors not matched by the taxonomy. Used together
-   * with `errors` for apps that want declarative dispatch plus a well-defined
-   * shape for unexpected errors.
-   */
-  unknownError?: UnknownErrorConfig
-  /**
-   * Imperative error callback — the other peer error mode. Receives every
-   * error directly and returns the HTTP response. Use this when you want full
-   * control over the response shape, or alongside `errors` for the tail of
-   * errors the taxonomy doesn't cover.
-   */
-  onError?: (
-    procedure: TProcedureRegistration,
-    c: Context,
-    error: Error
-  ) => Response | Promise<Response>
-  /**
-   * Cross-cutting observer — fires for every caught error, BEFORE dispatch to
-   * the taxonomy or `onError`. Awaited. Cannot mutate the response. Intended
-   * for logging, tracing, and metrics (Sentry, Datadog, OpenTelemetry). Any
-   * error thrown inside the observer is swallowed and logged so the primary
-   * dispatch flow is never disrupted.
-   */
-  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
-}
-
-/**
- * Context passed to the `onRequestError` observer. `raw` is the Hono
- * `Context` for the in-flight request.
- */
-export type OnRequestErrorContext = {
-  err: unknown
-  procedure: TProcedureRegistration
-  raw: Context
-}
-
-/**
- * Builder class for creating a Hono application with REST-style API routes.
- *
- * Uses `schema.input` for per-channel type safety:
- *   - `input.pathParams` → validated path parameters
- *   - `input.query` → validated query string parameters
- *   - `input.body` → validated request body
- *   - `input.headers` → validated request headers
- *
- * Usage:
- *   const API = Procedures<MyContext, APIConfig>()
- *
- *   API.Create('GetUser', {
- *     path: '/users/:id',
- *     method: 'get',
- *     schema: {
- *       input: {
- *         pathParams: Type.Object({ id: Type.String() }),
- *         query: Type.Object({ include: Type.Optional(Type.String()) }),
- *       },
- *       returnType: Type.Object({ id: Type.String(), name: Type.String() }),
- *     }
- *   }, async (ctx, { pathParams, query }) => {
- *     return { id: pathParams.id, name: 'John' }
- *   })
- *
- *   const apiApp = new HonoAPIAppBuilder()
- *     .register(API, (c) => ({ ... }))
- *     .build()
- */
-export class HonoAPIAppBuilder {
-  constructor(readonly config?: HonoAPIAppBuilderConfig) {
-    if (config?.app) {
-      this._app = config.app
-    }
-
-    if (config?.onRequestStart) {
-      this._app.use('*', async (c, next) => {
-        config.onRequestStart!(c)
-        await next()
-      })
-    }
-
-    if (config?.onRequestEnd) {
-      this._app.use('*', async (c, next) => {
-        await next()
-        config.onRequestEnd!(c)
-      })
-    }
-  }
-
-  private factories: HonoAPIFactoryItem<any>[] = []
-
-  private _app: Hono = new Hono()
-  private _docs: (APIHttpRouteDoc & object)[] = []
-
-  get app(): Hono {
-    return this._app
-  }
-
-  get docs(): APIHttpRouteDoc[] {
-    return this._docs
-  }
-
-  /**
-   * Registers a procedure factory with its context.
-   * @param factory - The procedure factory created by Procedures<Context, APIConfig>()
-   * @param factoryContext - Context for handlers. Direct value, sync function, or async function.
-   * @param extendProcedureDoc - Custom function to extend the generated route documentation.
-   */
-  register<TFactory extends ProceduresFactory>(
-    factory: TFactory,
-    factoryContext:
-      | ExtractContext<TFactory>
-      | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
-    extendProcedureDoc?: (params: {
-      base: APIHttpRouteDoc
-      procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
-    }) => Record<string, any>
-  ): this {
-    this.factories.push({ factory, factoryContext, extendProcedureDoc } as HonoAPIFactoryItem<any>)
-    return this
-  }
-
-  /**
-   * Resolves the full path for a route, combining pathPrefix and the procedure's path.
-   */
-  private resolveFullPath(procedurePath: string): string {
-    const prefix = this.config?.pathPrefix
-    const normalizedPrefix = prefix ? (prefix.startsWith('/') ? prefix : `/${prefix}`) : ''
-    const normalizedPath = procedurePath.startsWith('/') ? procedurePath : `/${procedurePath}`
-    return `${normalizedPrefix}${normalizedPath}`
-  }
-
-  /**
-   * Builds and returns the Hono application with registered API routes.
-   */
-  build(): Hono {
-    const queryParser = this.config?.queryParser ?? parseQueryNative
-
-    this.factories.forEach(({ factory, factoryContext, extendProcedureDoc }) => {
-      factory.getProcedures().map((procedure: TProcedureRegistration<any, APIConfig>) => {
-        const { config } = procedure
-        const fullPath = this.resolveFullPath(config.path)
-        const inputSchema = procedure.config.schema?.input
-
-        // Validate consistency: path params in path template must match schema.input.pathParams
-        this.validatePathParamConsistency(procedure.name, config.path, inputSchema)
-
-        const route = this.buildApiHttpRouteDoc(procedure, fullPath, extendProcedureDoc)
-        this._docs.push(route)
-
-        const method = config.method as HttpMethod
-        const handler = this.createRouteHandler(procedure, factoryContext, config, inputSchema, queryParser)
-
-        this._app.on(method.toUpperCase(), fullPath, handler)
-      })
-    })
-
-    return this._app
-  }
-
-  /**
-   * Validates that path parameter names in the path template match the schema.input.pathParams declaration.
-   */
-  private validatePathParamConsistency(
-    procedureName: string,
-    path: string,
-    inputSchema?: Record<string, unknown>
-  ): void {
-    // Only validate when schema.input is used; schema.params (flat mode) skips this check
-    if (!inputSchema) return
-
-    const pathParamNames = extractPathParamNames(path)
-
-    if (pathParamNames.length > 0 && !inputSchema.pathParams) {
-      throw new Error(
-        `Path "${path}" has path parameters [${pathParamNames.join(', ')}] but schema.input.pathParams is not defined for procedure "${procedureName}". ` +
-          `Define schema.input.pathParams to validate path parameters.`
-      )
-    }
-
-    if (inputSchema.pathParams && pathParamNames.length === 0) {
-      throw new Error(
-        `schema.input.pathParams is defined for procedure "${procedureName}" but path "${path}" has no path parameters. ` +
-          `Remove schema.input.pathParams or add path parameters to the path.`
-      )
-    }
-
-    // Deep validation: verify schema property names match the :param names in the path
-    if (inputSchema.pathParams && pathParamNames.length > 0) {
-      const pathParamsJsonSchema = inputSchema.pathParams as Record<string, unknown>
-      const schemaProperties = pathParamsJsonSchema.properties as Record<string, unknown> | undefined
-
-      if (schemaProperties) {
-        const schemaKeys = Object.keys(schemaProperties)
-        const missingInSchema = pathParamNames.filter((p) => !schemaKeys.includes(p))
-        const extraInSchema = schemaKeys.filter((k) => !pathParamNames.includes(k))
-
-        if (missingInSchema.length > 0 || extraInSchema.length > 0) {
-          const parts: string[] = []
-          if (missingInSchema.length > 0) {
-            parts.push(`path has [${missingInSchema.join(', ')}] but they are missing from schema`)
-          }
-          if (extraInSchema.length > 0) {
-            parts.push(`schema has [${extraInSchema.join(', ')}] but they are not in the path`)
-          }
-          throw new Error(
-            `Path param mismatch for procedure "${procedureName}": ${parts.join('; ')}. ` +
-              `Path "${path}" expects [${pathParamNames.join(', ')}], schema defines [${schemaKeys.join(', ')}].`
-          )
-        }
-      }
-    }
-  }
-
-  /**
-   * Creates the async route handler for a procedure.
-   */
-  private createRouteHandler(
-    procedure: TProcedureRegistration<any, APIConfig>,
-    factoryContext: HonoAPIFactoryItem['factoryContext'],
-    config: APIConfig,
-    inputSchema: Record<string, unknown> | undefined,
-    queryParser: QueryParser
-  ) {
-    const successStatus = config.successStatus ?? defaultSuccessStatus(config.method)
-
-    return async (c: Context) => {
-      try {
-        const context =
-          typeof factoryContext === 'function'
-            ? await factoryContext(c)
-            : (factoryContext as any)
-
-        let params: unknown
-
-        if (inputSchema) {
-          // schema.input mode: build structured params from HTTP sources
-          params = await this.extractInputParams(c, config.method, inputSchema, queryParser)
-        } else if (procedure.config.schema?.params) {
-          // schema.params mode: extract from body or query based on method
-          if (BODY_METHODS.includes(config.method)) {
-            params = await c.req.json().catch(() => ({}))
-          } else {
-            params = extractQuery(c.req.url, queryParser)
-          }
-        } else {
-          params = await c.req.json().catch(() => undefined)
-        }
-
-        const result = await procedure.handler({ ...context, signal: c.req.raw.signal }, params)
-
-        if (this.config?.onSuccess) {
-          this.config.onSuccess(procedure, c)
-        }
-
-        // 204 No Content returns no body
-        if (successStatus === 204) {
-          return c.body(null, 204)
-        }
-
-        return c.json(result, successStatus as any)
-      } catch (error) {
-        // Observer fires first — cross-cutting, cannot alter dispatch or the
-        // response. Swallow any throw from the observer so instrumentation
-        // bugs never break the primary error-response flow.
-        if (this.config?.onRequestError) {
-          try {
-            await this.config.onRequestError({ err: error, procedure, raw: c })
-          } catch (observerErr) {
-            console.error('[ts-procedures hono-api] onRequestError threw — swallowed:', observerErr)
-          }
-        }
-
-        // Dispatch: taxonomy → onError → hard default. The two modes are
-        // peers; apps configure whichever fits (or both, in which case the
-        // taxonomy handles what it covers and `onError` handles the tail).
-        if (this.config?.errors || this.config?.unknownError) {
-          const resolved = resolveErrorResponse({
-            err: error,
-            userTaxonomy: this.config.errors,
-            unknownError: this.config.unknownError,
-            procedure,
-            raw: c,
-          })
-          if (resolved) {
-            await resolved.runOnCatch()
-            return c.json(resolved.body, resolved.statusCode as never)
-          }
-        }
-        if (this.config?.onError) {
-          return this.config.onError(procedure, c, error as Error)
-        }
-        return c.json({ error: (error as Error).message }, 500)
-      }
-    }
-  }
-
-  /**
-   * Extracts and assembles structured input params from HTTP request sources.
-   * Each channel (pathParams, query, body, headers) is extracted from its HTTP source.
-   * The core validates each channel independently via schema.input validators.
-   */
-  private async extractInputParams(
-    c: Context,
-    method: HttpMethod,
-    inputSchema: Record<string, unknown>,
-    queryParser: QueryParser
-  ): Promise<Record<string, unknown>> {
-    const params: Record<string, unknown> = {}
-    const channelNames = Object.keys(inputSchema)
-
-    for (const channel of channelNames) {
-      switch (channel) {
-        case 'pathParams':
-          params.pathParams = c.req.param()
-          break
-
-        case 'query':
-          params.query = extractQuery(c.req.url, queryParser)
-          break
-
-        case 'body':
-          if (BODY_METHODS.includes(method)) {
-            params.body = await c.req.json().catch(() => ({}))
-          }
-          break
-
-        case 'headers': {
-          // Pass all request headers; AJV's removeAdditional strips non-declared keys
-          const headersObj: Record<string, string> = {}
-          c.req.raw.headers.forEach((value, key) => {
-            headersObj[key] = value
-          })
-          params.headers = headersObj
-          break
-        }
-
-        default:
-          // Unknown channel — pass through empty. Core validation will catch mismatches.
-          params[channel] = undefined
-          break
-      }
-    }
-
-    return params
-  }
-
-  /**
-   * Generates the API HTTP route documentation for the given procedure.
-   */
-  private buildApiHttpRouteDoc(
-    procedure: TProcedureRegistration<any, APIConfig>,
-    fullPath: string,
-    extendProcedureDoc?: HonoAPIFactoryItem['extendProcedureDoc']
-  ): APIHttpRouteDoc {
-    const { config } = procedure
-    const inputSchema = config.schema?.input
-    const jsonSchema: APIHttpRouteDoc['jsonSchema'] = {}
-
-    // Populate per-channel JSON schemas from schema.input
-    if (inputSchema) {
-      if (inputSchema.pathParams) jsonSchema.pathParams = inputSchema.pathParams as Record<string, unknown>
-      if (inputSchema.query) jsonSchema.query = inputSchema.query as Record<string, unknown>
-      if (inputSchema.body) jsonSchema.body = inputSchema.body as Record<string, unknown>
-      if (inputSchema.headers) jsonSchema.headers = inputSchema.headers as Record<string, unknown>
-    } else if (config.schema?.params) {
-      // Fallback: schema.params treated as body/query depending on method
-      if (BODY_METHODS.includes(config.method)) {
-        jsonSchema.body = config.schema.params
-      } else {
-        jsonSchema.query = config.schema.params
-      }
-    }
-
-    if (config.schema?.returnType) {
-      jsonSchema.response = config.schema.returnType
-    }
-
-    const base: APIHttpRouteDoc = {
-      kind: 'api',
-      name: procedure.name,
-      scope: config.scope,
-      path: config.path,
-      method: config.method,
-      fullPath,
-      jsonSchema,
-    }
-
-    if (config.successStatus) {
-      base.successStatus = config.successStatus
-    }
-
-    if (config.errors && config.errors.length > 0) {
-      base.errors = [...config.errors]
-    }
-
-    let extendedDoc: object = {}
-
-    if (extendProcedureDoc) {
-      extendedDoc = extendProcedureDoc({ base, procedure })
-    }
-
-    return {
-      ...extendedDoc,
-      ...base,
-    }
-  }
-}

package/src/implementations/http/hono-api/types.ts

@@ -1,16 +0,0 @@
-import { ExtractConfig, ExtractContext, APIConfig, APIHttpRouteDoc } from '../../types.js'
-import { Procedures, TProcedureRegistration } from '../../../index.js'
-import { Context } from 'hono'
-
-export type HonoAPIFactoryItem<TFactory = ReturnType<typeof Procedures<any, APIConfig>>> = {
-  factory: TFactory
-  factoryContext:
-    | ExtractContext<TFactory>
-    | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
-  extendProcedureDoc?: (params: {
-    /** API App builder base http route doc */
-    base: APIHttpRouteDoc
-    /** Procedure registration */
-    procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
-  }) => Record<string, any>
-}