ts-procedures 8.6.0 → 9.1.0

package/src/create-http-stream.ts

@@ -1,191 +0,0 @@
-import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError, ProcedureYieldValidationError } 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 {
-  HttpMethod, TBuilderConfig, TStreamContext,
-  THttpStreamProcedureRegistration, TProcedureRegistration, TStreamProcedureRegistration, THttpProcedureRegistration,
-} from './types.js'
-import { checkPathParamConsistency } from './create-http.js'
-
-/**
- * Wraps a user's AsyncIterator in a generator that:
- * - optionally validates each yielded value
- * - augments error stack traces with the procedure definition site
- * - aborts the stream controller on completion
- */
-async function* yieldingWrapper(
-  userIterator: AsyncIterator<any, any, unknown>,
-  validateYields: boolean,
-  validations: { yield?: (value: any) => { errors?: any[] } },
-  abortController: AbortController,
-  definitionInfo: ReturnType<typeof captureDefinitionInfo>,
-  name: string,
-): AsyncGenerator<any, any, unknown> {
-  try {
-    let result = await userIterator.next()
-    while (!result.done) {
-      const value = result.value
-      if (validateYields && validations.yield) {
-        const { errors } = validations.yield(value)
-        if (errors) throw new ProcedureYieldValidationError(name, `Yield validation error for ${name}`, errors, definitionInfo)
-      }
-      yield value
-      result = await userIterator.next()
-    }
-    return result.value
-  } catch (error: any) {
-    if (definitionInfo.definedAt && error && typeof error.stack === 'string') {
-      const { file, line, column } = definitionInfo.definedAt
-      error.stack = `${error.stack}\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
-    }
-    throw error
-  } finally {
-    try { await userIterator.return?.(undefined) } catch { /* swallow */ }
-    abortController.abort('stream-completed')
-  }
-}
-
-export function makeCreateHttpStream<TContext>(
-  procedures: Map<string, TProcedureRegistration<TContext, any> | TStreamProcedureRegistration<TContext, any> | THttpProcedureRegistration<TContext> | THttpStreamProcedureRegistration<TContext>>,
-  builder?: { config?: TBuilderConfig; onCreate?: (procedure: any) => void },
-) {
-  return function CreateHttpStream<
-    TName extends string,
-    TReq extends Record<string, unknown> | undefined,
-    TYieldType,
-    TReturnType = void,
-    TResHeaders = undefined,
-    TErrorKey extends string = string,
-  >(
-    name: TName,
-    config: {
-      path: string
-      method: HttpMethod
-      scope?: string
-      errors?: TErrorKey[]
-      description?: string
-      schema: {
-        req?: TReq
-        yield?: TYieldType
-        returnType?: TReturnType
-        res?: TResHeaders extends undefined ? undefined : { headers: TResHeaders }
-      }
-      validateYields?: boolean
-    },
-    handler: TResHeaders extends undefined
-      ? (
-          ctx: Prettify<TContext & TStreamContext>,
-          req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
-        ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
-      : (
-          ctx: Prettify<TContext & TStreamContext>,
-          req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
-        ) => Promise<{ headers: TSchemaLib<TResHeaders>; stream: AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown> }>,
-  ) {
-    const definitionInfo = captureDefinitionInfo()
-
-    if (procedures.has(name)) throw new Error(`Procedure with name ${name} is already registered`)
-    if ((config.schema as any)?.params) {
-      throw new ProcedureRegistrationError(name, `Use schema.req.body (or schema.req.query) instead of schema.params on CreateHttpStream. Procedure: "${name}".`, definitionInfo)
-    }
-
-    const { jsonSchema, validations } = computeSchema(name, {
-      req: config.schema.req as Record<string, unknown> | undefined,
-      yieldType: config.schema.yield,
-      returnType: config.schema.returnType,
-    }, definitionInfo)
-
-    const pathParamsSchema = (jsonSchema.req as Record<string, unknown> | undefined)?.pathParams
-    checkPathParamConsistency(name, config.path, pathParamsSchema as Record<string, unknown> | undefined, definitionInfo)
-
-    const errorFactory = (message: string, meta?: object) => new ProcedureError(name, message, meta, definitionInfo)
-    const validateYields = config.validateYields ?? false
-
-    const wrappedHandler = async (ctx: TContext, req: any): Promise<{ stream: AsyncGenerator<any, any, unknown>; initialHeaders?: Record<string, string> }> => {
-      const abortController = new AbortController()
-      const skipValidation = (ctx as { isPrevalidated?: boolean }).isPrevalidated || builder?.config?.noRuntimeValidation
-
-      if (validations?.req && !skipValidation) {
-        for (const [channel, validator] of Object.entries(validations.req)) {
-          const channelValue = (req as Record<string, unknown>)?.[channel]
-          const { errors } = validator(channelValue)
-          if (errors) {
-            throw new ProcedureValidationError(name, `Validation error for ${name} in req.${channel}`, errors, definitionInfo)
-          }
-        }
-      }
-
-      const incomingSignal = (ctx as { signal?: AbortSignal }).signal
-      const signal = incomingSignal ? AbortSignal.any([incomingSignal, abortController.signal]) : abortController.signal
-      const streamCtx: TStreamContext = { error: errorFactory, signal }
-
-      const handlerResult: any = (handler as any)({ ...ctx, ...streamCtx }, req)
-
-      if (typeof handlerResult?.[Symbol.asyncIterator] === 'function') {
-        // Plain async generator from user
-        const userIterator = (handlerResult as AsyncGenerator<any, any, unknown>)[Symbol.asyncIterator]()
-        return { stream: yieldingWrapper(userIterator, validateYields, validations, abortController, definitionInfo, name) }
-      } else if (typeof handlerResult?.then === 'function') {
-        // Async preamble: Promise<{ headers, stream }>
-        const resolved = await handlerResult
-        if (!resolved || typeof resolved !== 'object' || !('stream' in resolved)) {
-          throw new ProcedureError(name, `CreateHttpStream handler returned a Promise that did not resolve to { headers, stream }. Got: ${JSON.stringify(resolved)}`, undefined, definitionInfo)
-        }
-        const userIterator = (resolved.stream as AsyncGenerator<any, any, unknown>)[Symbol.asyncIterator]()
-        return {
-          stream: yieldingWrapper(userIterator, validateYields, validations, abortController, definitionInfo, name),
-          initialHeaders: resolved.headers,
-        }
-      } else {
-        throw new ProcedureError(name, `CreateHttpStream handler must return an AsyncGenerator or Promise<{ headers, stream }>.`, undefined, definitionInfo)
-      }
-    }
-
-    const registeredProcedure: THttpStreamProcedureRegistration<TContext> = {
-      name,
-      kind: 'http-stream',
-      config: {
-        path: config.path,
-        method: config.method,
-        scope: config.scope,
-        errors: config.errors as string[] | undefined,
-        description: config.description,
-        schema: jsonSchema as any,
-        validation: { req: validations.req, yield: validations.yield },
-        validateYields,
-      },
-      handler: wrappedHandler as any,
-    }
-
-    procedures.set(name, registeredProcedure as any)
-    builder?.onCreate?.(registeredProcedure)
-
-    const info = { name, kind: 'http-stream' as const, ...registeredProcedure.config }
-
-    // Explicit return type — preserves TReq/TYieldType/TReturnType through the public callable.
-    // Do NOT use `typeof registeredProcedure.handler` — that erases generics to `any`.
-    return {
-      [name]: registeredProcedure.handler,
-      procedure: registeredProcedure.handler,
-      info,
-    } as {
-      [K in TName]: (
-        ctx: Prettify<TContext>,
-        req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
-      ) => Promise<{
-        stream: AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
-        initialHeaders?: Record<string, string>
-      }>
-    } & {
-      procedure: (
-        ctx: Prettify<TContext>,
-        req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
-      ) => Promise<{
-        stream: AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
-        initialHeaders?: Record<string, string>
-      }>
-      info: typeof info
-    }
-  }
-}

package/src/create-http.ts

@@ -1,210 +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,
-  TCreateHttpConfig,
-  TLocalContext,
-  THttpProcedureRegistration,
-  THttpStreamProcedureRegistration,
-  TProcedureRegistration,
-  TStreamProcedureRegistration,
-} from './types.js'
-
-type Infer<T> = TSchemaLib<T>
-
-export type HttpReturn<TRes> =
-  TRes extends { body: infer B; headers: infer H } ? { body: Infer<B>; headers: Infer<H> }
-  : TRes extends { headers: infer H }              ? { headers: Infer<H> }
-  : TRes extends { body: infer B }                 ? Infer<B>
-  : void
-
-const PATH_PARAM_RE = /:([a-zA-Z_][a-zA-Z0-9_]*)/g
-
-function extractPathParamNames(path: string): string[] {
-  const matches = path.match(PATH_PARAM_RE)
-  return matches ? matches.map((m) => m.slice(1)) : []
-}
-
-export function checkPathParamConsistency(
-  procedureName: string,
-  path: string,
-  pathParamsSchema: Record<string, unknown> | undefined,
-  definitionInfo: ReturnType<typeof captureDefinitionInfo>,
-) {
-  const pathParamNames = extractPathParamNames(path)
-  const hasPathParams = pathParamNames.length > 0
-  const hasSchema = pathParamsSchema !== undefined
-
-  if (hasPathParams && !hasSchema) {
-    throw new ProcedureRegistrationError(
-      procedureName,
-      `Path "${path}" has path parameters [${pathParamNames.join(', ')}] but schema.req.pathParams is not defined.`,
-      definitionInfo,
-    )
-  }
-  if (!hasPathParams && hasSchema) {
-    throw new ProcedureRegistrationError(
-      procedureName,
-      `schema.req.pathParams is defined but path "${path}" has no path parameters.`,
-      definitionInfo,
-    )
-  }
-  if (hasPathParams && hasSchema) {
-    const schemaProperties = (pathParamsSchema as { properties?: Record<string, unknown> }).properties
-    if (schemaProperties) {
-      const schemaKeys = Object.keys(schemaProperties)
-      const missing = pathParamNames.filter((p) => !schemaKeys.includes(p))
-      const extra = schemaKeys.filter((k) => !pathParamNames.includes(k))
-      if (missing.length > 0 || extra.length > 0) {
-        const parts: string[] = []
-        if (missing.length > 0) parts.push(`path has [${missing.join(', ')}] missing from schema`)
-        if (extra.length > 0) parts.push(`schema has [${extra.join(', ')}] not in path`)
-        throw new ProcedureRegistrationError(
-          procedureName,
-          `Path param mismatch for "${procedureName}": ${parts.join('; ')}.`,
-          definitionInfo,
-        )
-      }
-    }
-  }
-}
-
-export function makeCreateHttp<TContext>(
-  procedures: Map<
-    string,
-    | TProcedureRegistration<TContext, any>
-    | TStreamProcedureRegistration<TContext, any>
-    | THttpProcedureRegistration<TContext>
-    | THttpStreamProcedureRegistration<TContext>
-  >,
-  builder?: { config?: TBuilderConfig; onCreate?: (procedure: any) => void },
-) {
-  return function CreateHttp<
-    TName extends string,
-    TReq extends Record<string, unknown> | undefined,
-    TRes extends { body?: unknown; headers?: unknown } | undefined = undefined,
-    TErrorKey extends string = string,
-  >(
-    name: TName,
-    config: TCreateHttpConfig<TReq, TRes, TErrorKey>,
-    handler: (
-      ctx: Prettify<TContext & TLocalContext>,
-      req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
-    ) => Promise<HttpReturn<TRes>>,
-  ) {
-    const definitionInfo = captureDefinitionInfo()
-
-    if (procedures.has(name)) {
-      throw new Error(`Procedure with name ${name} is already registered`)
-    }
-
-    if ((config.schema as any)?.params) {
-      throw new ProcedureRegistrationError(
-        name,
-        `Use schema.req.body (or schema.req.query) instead of schema.params on CreateHttp. Procedure: "${name}".`,
-        definitionInfo,
-      )
-    }
-
-    const { jsonSchema, validations } = computeSchema(
-      name,
-      {
-        req: config.schema.req as Record<string, unknown> | undefined,
-        res: config.schema.res as { body?: unknown; headers?: unknown } | undefined,
-      },
-      definitionInfo,
-    )
-
-    const pathParamsSchema = (jsonSchema.req as Record<string, unknown> | undefined)?.pathParams
-    checkPathParamConsistency(
-      name,
-      config.path,
-      pathParamsSchema as Record<string, unknown> | undefined,
-      definitionInfo,
-    )
-
-    const errorFactory = (message: string, meta?: object) =>
-      new ProcedureError(name, message, meta, definitionInfo)
-
-    const registeredProcedure: THttpProcedureRegistration<TContext> = {
-      name,
-      kind: 'http',
-      config: {
-        path: config.path,
-        method: config.method,
-        successStatus: config.successStatus,
-        scope: config.scope,
-        errors: config.errors as string[] | undefined,
-        description: config.description,
-        schema: jsonSchema as any,
-        validation: { req: validations.req },
-      },
-      handler: async (ctx: TContext, req: any) => {
-        try {
-          const skipValidation =
-            (ctx as { isPrevalidated?: boolean }).isPrevalidated ||
-            builder?.config?.noRuntimeValidation
-
-          if (validations?.req && !skipValidation) {
-            for (const [channel, validator] of Object.entries(validations.req)) {
-              const channelValue = (req as Record<string, unknown>)?.[channel]
-              const { errors } = validator(channelValue)
-              if (errors) {
-                throw new ProcedureValidationError(
-                  name,
-                  `Validation error for ${name} in req.${channel}`,
-                  errors,
-                  definitionInfo,
-                )
-              }
-            }
-          }
-
-          const localCtx: TLocalContext = { error: errorFactory }
-          return await handler({ ...ctx, ...localCtx } as any, req)
-        } 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
-          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 as any)
-    builder?.onCreate?.(registeredProcedure)
-
-    const info = { name, ...registeredProcedure.config }
-
-    return {
-      [name]: registeredProcedure.handler,
-      procedure: registeredProcedure.handler,
-      info,
-    } as {
-      [K in TName]: (
-        ctx: Prettify<TContext>,
-        req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
-      ) => Promise<HttpReturn<TRes>>
-    } & {
-      procedure: (
-        ctx: Prettify<TContext>,
-        req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
-      ) => Promise<HttpReturn<TRes>>
-      info: typeof info
-    }
-  }
-}

package/src/create-stream.ts

@@ -1,228 +0,0 @@
-import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError, ProcedureYieldValidationError } 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,
-  TStreamContext,
-  TProcedureRegistration,
-  TStreamProcedureRegistration,
-} from './types.js'
-
-export type CreateStreamBuilderArg<TContext, TExtendedConfig> = {
-  config?: TBuilderConfig
-  onCreate?: (
-    procedure:
-      | TProcedureRegistration<TContext, TExtendedConfig>
-      | TStreamProcedureRegistration<TContext, TExtendedConfig>
-  ) => void
-}
-
-export function makeCreateStream<TContext, TExtendedConfig>(
-  procedures: Map<
-    string,
-    | TProcedureRegistration<TContext, TExtendedConfig>
-    | TStreamProcedureRegistration<TContext, TExtendedConfig>
-    | THttpProcedureRegistration<TContext>
-    | THttpStreamProcedureRegistration<TContext>
-  >,
-  builder?: CreateStreamBuilderArg<TContext, TExtendedConfig>
-) {
-  return function CreateStream<TName extends string, TParams, TYieldType, TReturnType = void>(
-    name: TName,
-    config: {
-      description?: string
-      schema?: {
-        params?: TParams
-        yieldType?: TYieldType
-        returnType?: TReturnType
-      }
-      validateYields?: boolean
-    } & TExtendedConfig,
-    handler: (
-      ctx: Prettify<TContext & TStreamContext>,
-      params: TSchemaLib<TParams>
-    ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
-  ) {
-    // 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 CreateStream.`,
-        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) => {
-      return new ProcedureError(name, message, meta, definitionInfo)
-    }
-
-    const validateYields = config.validateYields ?? false
-
-    const registeredProcedure: TStreamProcedureRegistration<TContext, TExtendedConfig> = {
-      name,
-      kind: 'rpc-stream',
-      isStream: true,
-      config: {
-        ...config,
-        description: config.description,
-        schema: jsonSchema,
-        validation: {
-          params: validations.params,
-          yield: validations.yield,
-        },
-      },
-
-      handler: async function* wrappedHandler(
-        ctx: Prettify<TContext>,
-        params: TSchemaLib<TParams>
-      ) {
-        // Create abort controller for this stream
-        const abortController = new AbortController()
-
-        // Skip validation if caller has already validated (e.g., HonoAppBuilder) 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
-            )
-          }
-        }
-
-        // Combine with external signal (e.g., from HTTP request) if provided
-        const incomingSignal = (ctx as { signal?: AbortSignal }).signal
-        const signal = incomingSignal
-          ? AbortSignal.any([incomingSignal, abortController.signal])
-          : abortController.signal
-
-        const streamCtx: TStreamContext = {
-          error: errorFactory,
-          signal,
-        }
-
-        // params is correctly typed at the public API boundary via conditional type;
-        // cast here because TS cannot narrow conditional generics inside implementations
-        const userGenerator = handler(
-          {
-            ...ctx,
-            ...streamCtx,
-          } as Prettify<TContext & TStreamContext>,
-          params as any
-        )
-
-        const userIterator = userGenerator[Symbol.asyncIterator]()
-        try {
-          let userIterResult = await userIterator.next()
-
-          while (!userIterResult.done) {
-            const value = userIterResult.value
-
-            // Only validate if explicitly enabled via validateYields: true
-            if (validateYields && validations.yield) {
-              const { errors } = validations.yield(value)
-              if (errors) {
-                throw new ProcedureYieldValidationError(
-                  name,
-                  `Yield validation error for ${name}`,
-                  errors,
-                  definitionInfo
-                )
-              }
-            }
-
-            yield value
-            userIterResult = await userIterator.next()
-          }
-
-          // Propagate the generator's return value so consumers (e.g. HonoAppBuilder)
-          // can send it as a special 'return' SSE event
-          return userIterResult.value
-        } catch (error: any) {
-          // Preserve the original error class so HTTP builders' taxonomies and
-          // `onMidStreamError` callbacks see the actual thrown type — boxing
-          // user-defined errors inside ProcedureError defeats route-declared
-          // typed-error dispatch on the client. Augment the stack trace in
-          // place with the procedure's definition site when available.
-          if (definitionInfo.definedAt && error && typeof error.stack === 'string') {
-            const { file, line, column } = definitionInfo.definedAt
-            error.stack = `${error.stack}\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
-          }
-          throw error
-        } finally {
-          // Propagate `.return()` to the user generator so its `finally`
-          // blocks (and any `signal`-driven cleanup) run when the consumer
-          // closes the stream early. No-op when iteration already completed.
-          try {
-            await userIterator.return?.(undefined)
-          } catch {
-            // Swallow — cleanup must not mask the primary error path
-          }
-          abortController.abort('stream-completed')
-        }
-      } as (ctx: TContext, params?: any) => AsyncGenerator<any, any, unknown>,
-    }
-
-    procedures.set(name, registeredProcedure)
-    builder?.onCreate?.(registeredProcedure)
-
-    const info = {
-      name,
-      isStream: true as const,
-      ...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>
-      ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
-    } & {
-      procedure: (
-        ctx: Prettify<TContext>,
-        params: TSchemaLib<TParams>
-      ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
-      info: {
-        name: TName
-        isStream: true
-        description?: string
-        schema: {
-          params?: TParams
-          yieldType?: TYieldType
-          returnType?: TReturnType
-        }
-        validation?: {
-          params?: (params: any) => { errors?: any[] }
-          yield?: (value: any) => { errors?: any[] }
-        }
-      } & TExtendedConfig
-    }
-  }
-}