ts-procedures 5.3.0 → 5.4.0

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

@@ -0,0 +1,461 @@
+import { Hono, Context } from 'hono'
+import { TProcedureRegistration } from '../../../index.js'
+import {
+  ExtractConfig,
+  ExtractContext,
+  ProceduresFactory,
+  APIConfig,
+  APIHttpRouteDoc,
+  APIInput,
+  HttpMethod,
+} from '../../types.js'
+import { HonoAPIFactoryItem } from './types.js'
+
+export type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod }
+
+// ================
+// Query string parsing
+// ================
+
+export type QueryParser = (queryString: string) => Record<string, unknown>
+
+/** Lazy-loaded qs module (optional peer dependency) */
+let _qsModule: { parse: (str: string, opts?: any) => any } | false | undefined
+
+async function loadQs(): Promise<{ parse: (str: string, opts?: any) => any } | undefined> {
+  if (_qsModule === undefined) {
+    try {
+      const mod = await import('qs')
+      _qsModule = mod.default ?? mod
+    } catch {
+      _qsModule = false
+    }
+  }
+  return _qsModule || undefined
+}
+
+/** Fallback 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
+}
+
+/**
+ * Resolves the query parser once. Called during build() so handlers use a sync parser.
+ * Priority: custom queryParser > qs (optional peer dep) > native URLSearchParams
+ */
+async function resolveQueryParser(custom?: QueryParser): Promise<QueryParser> {
+  if (custom) return custom
+
+  const qs = await loadQs()
+  if (qs) {
+    return (raw: string) => qs.parse(raw) as Record<string, unknown>
+  }
+
+  return parseQueryNative
+}
+
+/** 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: uses `qs` (optional peer dependency) if available, otherwise native URLSearchParams.
+   */
+  queryParser?: QueryParser
+  onRequestStart?: (c: Context) => void
+  onRequestEnd?: (c: Context) => void
+  onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
+  /**
+   * Error handler called when a procedure throws an error.
+   */
+  onError?: (
+    procedure: TProcedureRegistration,
+    c: Context,
+    error: Error
+  ) => Response | Promise<Response>
+}
+
+/**
+ * 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.
+   * Async because it resolves the query parser (qs optional peer dep) once at build time.
+   */
+  async build(): Promise<Hono> {
+    // Resolve query parser once so handlers use it synchronously
+    const queryParser = await resolveQueryParser(this.config?.queryParser)
+
+    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) {
+        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 = {
+      name: procedure.name,
+      path: config.path,
+      method: config.method,
+      fullPath,
+      jsonSchema,
+    }
+
+    if (config.successStatus) {
+      base.successStatus = config.successStatus
+    }
+
+    let extendedDoc: object = {}
+
+    if (extendProcedureDoc) {
+      extendedDoc = extendProcedureDoc({ base, procedure })
+    }
+
+    return {
+      ...extendedDoc,
+      ...base,
+    }
+  }
+}

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

@@ -0,0 +1,16 @@
+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>
+}

package/src/implementations/types.ts

@@ -23,6 +23,58 @@ export interface RPCHttpRouteDoc extends RPCConfig {
 
 export type StreamMode = 'sse' | 'text'
 
+// ================
+// API (REST-style) types
+// ================
+
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
+
+export interface APIConfig {
+  /** HTTP route path (supports Hono path params, e.g., '/users/:id') */
+  path: string
+  /** HTTP method for this endpoint */
+  method: HttpMethod
+  /** HTTP status code on success. Defaults: POST→201, DELETE→204, others→200 */
+  successStatus?: number
+}
+
+export interface APIHttpRouteDoc extends APIConfig {
+  name: string
+  /** Full resolved path including pathPrefix */
+  fullPath: string
+  jsonSchema: {
+    pathParams?: Record<string, unknown>
+    query?: Record<string, unknown>
+    body?: Record<string, unknown>
+    headers?: Record<string, unknown>
+    response?: Record<string, unknown>
+  }
+}
+
+/**
+ * Constrains schema.input channel names to valid HTTP input sources.
+ * Use with `satisfies` or as a type annotation to catch typos at compile time:
+ *
+ * @example
+ * schema: {
+ *   input: {
+ *     pathParams: Type.Object({ id: Type.String() }),
+ *     qurey: Type.Object({ ... }), // TS error: 'qurey' not in APIInput
+ *   } satisfies APIInput
+ * }
+ */
+export type APIInput<T extends {
+  pathParams?: unknown
+  query?: unknown
+  body?: unknown
+  headers?: unknown
+} = {
+  pathParams?: unknown
+  query?: unknown
+  body?: unknown
+  headers?: unknown
+}> = T
+
 export interface StreamHttpRouteDoc extends RPCConfig {
   name: string // procedure name
   path: string