ts-procedures 7.3.0 → 8.1.0

package/src/index.ts

@@ -1,72 +1,29 @@
-import {
-  ProcedureError,
-  ProcedureValidationError,
-  ProcedureYieldValidationError,
-} from './errors.js'
-import { computeSchema } from './schema/compute-schema.js'
-import { Prettify, TJSONSchema, TSchemaLib } from './schema/types.js'
-import { captureDefinitionInfo } from './stack-utils.js'
-
-export type TNoContextProvided = unknown
-
-export type TLocalContext = {
-  error: (message: string, meta?: object) => ProcedureError
-  signal?: AbortSignal
-}
+import { Prettify, TJSONSchema } from './schema/types.js'
+import { makeCreate } from './create.js'
+import { makeCreateStream } from './create-stream.js'
+import { makeCreateHttp } from './create-http.js'
+import { makeCreateHttpStream } from './create-http-stream.js'
+
+export {
+  type TNoContextProvided,
+  type TLocalContext,
+  type TStreamContext,
+  type ProcedureKind,
+  type TProcedureRegistration,
+  type TStreamProcedureRegistration,
+  type THttpProcedureRegistration,
+  type THttpStreamProcedureRegistration,
+  type TBuilderConfig,
+} from './types.js'
 
-export type TStreamContext = TLocalContext & {
-  signal: AbortSignal
-}
-
-export type TProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
-  name: string
-  isStream?: false
-  config: {
-    description?: string
-    schema?: {
-      params?: TJSONSchema
-      returnType?: TJSONSchema
-      input?: Record<string, TJSONSchema>
-    }
-    validation?: {
-      params?: (params: any) => { errors?: any[] }
-      input?: Record<string, (value: any) => { errors?: any[] }>
-    }
-  } & TExtendedConfig
-
-  handler: (ctx: TContext, params?: any) => Promise<any>
-}
-
-export type TStreamProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
-  name: string
-  isStream: true
-  config: {
-    description?: string
-    schema?: {
-      params?: TJSONSchema
-      yieldType?: TJSONSchema
-      returnType?: TJSONSchema
-      input?: Record<string, TJSONSchema>
-    }
-    validation?: {
-      params?: (params: any) => { errors?: any[] }
-      yield?: (value: any) => { errors?: any[] }
-      input?: Record<string, (value: any) => { errors?: any[] }>
-    }
-  } & TExtendedConfig
-
-  handler: (ctx: TContext, params?: any) => AsyncGenerator<any, any, unknown>
-}
-
-export type TBuilderConfig = {
-  /**
-   * The default is to validate schema inputs at runtime, to disable pass `true` for this property.
-   *
-   * @Note: this is not recommended for public unknown data, only use for internal procedure
-   * factories with type-checking build steps.
-   */
-  noRuntimeValidation?: true
-}
+import {
+  TNoContextProvided,
+  TBuilderConfig,
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+  THttpProcedureRegistration,
+  THttpStreamProcedureRegistration,
+} from './types.js'
 
 export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unknown>(
   /**
@@ -74,30 +31,23 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
    */
   builder?: {
     config?: TBuilderConfig
+    /**
+     * Called once per registered procedure. Receives the full registration
+     * object for any of the four procedure kinds:
+     *   - `TProcedureRegistration`       (Create)
+     *   - `TStreamProcedureRegistration` (CreateStream)
+     *   - `THttpProcedureRegistration`   (CreateHttp)
+     *   - `THttpStreamProcedureRegistration` (CreateHttpStream)
+     *
+     * Use the `kind` discriminant to narrow to the specific shape.
+     */
     onCreate?: (
-      procedure: Prettify<{
-        name: string
-        isStream?: boolean
-        handler:
-          | ((ctx: Prettify<TContext>, params?: any) => Promise<any>)
-          | ((ctx: Prettify<TContext>, params?: any) => AsyncGenerator<any, any, unknown>)
-        config: Prettify<
-          {
-            description?: string
-            schema?: {
-              params?: TJSONSchema
-              yieldType?: TJSONSchema
-              returnType?: TJSONSchema
-              input?: Record<string, TJSONSchema>
-            }
-            validation?: {
-              params?: (params: any) => { errors?: any[] }
-              yield?: (value: any) => { errors?: any[] }
-              input?: Record<string, (value: any) => { errors?: any[] }>
-            }
-          } & TExtendedConfig
-        >
-      }>
+      procedure: Prettify<
+        | TProcedureRegistration<TContext, TExtendedConfig>
+        | TStreamProcedureRegistration<TContext, TExtendedConfig>
+        | THttpProcedureRegistration<TContext>
+        | THttpStreamProcedureRegistration<TContext>
+      >
     ) => void
   }
 ) {
@@ -105,402 +55,14 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
     string,
     | TProcedureRegistration<TContext, TExtendedConfig>
     | TStreamProcedureRegistration<TContext, TExtendedConfig>
+    | THttpProcedureRegistration<TContext>
+    | THttpStreamProcedureRegistration<TContext>
   > = new Map()
 
-  function Create<
-    TName extends string,
-    TParams,
-    TReturnType,
-    TInput extends Record<string, unknown> | undefined = undefined,
-  >(
-    name: TName,
-    config: {
-      description?: string
-      schema?: {
-        params?: TParams
-        returnType?: TReturnType
-        input?: TInput
-      }
-    } & TExtendedConfig,
-    handler: (
-      ctx: Prettify<TContext & TLocalContext>,
-      params: TInput extends Record<string, unknown>
-        ? Prettify<{ [K in keyof TInput]: TSchemaLib<TInput[K]> }>
-        : TSchemaLib<TParams>
-    ) => Promise<TSchemaLib<TReturnType>>
-  ) {
-    // Capture definition location as first action
-    const definitionInfo = captureDefinitionInfo()
-
-    // 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 registeredProcedure = {
-      name,
-      config: {
-        // ctx: config.hook, ??? why was this here
-        ...config,
-        description: config.description,
-        schema: jsonSchema,
-        validation: {
-          params: validations.params,
-          ...(validations.input && { input: validations.input }),
-        },
-      },
-
-      handler: async (ctx: Prettify<TContext>, params: TSchemaLib<TParams>) => {
-        try {
-          // Skip validation if caller has already validated (e.g., HonoStreamAppBuilder) 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
-              )
-            }
-          }
-
-          // Validate each input channel independently for better error messages.
-          // Double validation (per-channel + merged) is intentional for developer experience;
-          // the cost is negligible — revisit if validation becomes a performance bottleneck.
-          if (validations?.input && !skipValidation) {
-            for (const [channel, validator] of Object.entries(validations.input)) {
-              const channelValue = (params as Record<string, unknown>)?.[channel]
-              const { errors } = validator(channelValue)
-
-              if (errors) {
-                throw new ProcedureValidationError(
-                  name,
-                  `Validation error for ${name} in input.${channel}`,
-                  errors,
-                  definitionInfo
-                )
-              }
-            }
-          }
-
-          const localCtx: TLocalContext = {
-            error: errorFactory, // Reuse pre-created factory
-          }
-
-          // params is correctly typed at the public API boundary via conditional type;
-          // cast here because TS cannot narrow conditional generics inside implementations
-          return await handler(
-            {
-              ...ctx,
-              ...localCtx,
-            } as Prettify<TContext & TLocalContext>,
-            params as any
-          )
-        } catch (error: any) {
-          if (error instanceof ProcedureError) {
-            throw error
-          } else {
-            const err = new ProcedureError(
-              name,
-              `Error in handler for ${name} - ${error?.message}`,
-              undefined,
-              definitionInfo
-            )
-            err.cause = error // Preserve original 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)
-
-    if (builder?.onCreate) {
-      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: TInput extends Record<string, unknown>
-          ? Prettify<{ [K in keyof TInput]: TSchemaLib<TInput[K]> }>
-          : TSchemaLib<TParams>
-      ) => Promise<TSchemaLib<TReturnType>>
-    } & {
-      procedure: (
-        ctx: Prettify<TContext>,
-        params: TInput extends Record<string, unknown>
-          ? Prettify<{ [K in keyof TInput]: TSchemaLib<TInput[K]> }>
-          : TSchemaLib<TParams>
-      ) => Promise<TSchemaLib<TReturnType>>
-      info: {
-        name: TName
-        description?: string
-        schema: {
-          params?: TParams
-          returnType?: TReturnType
-          input?: TInput
-        }
-        validation?: {
-          params?: (params: any) => { errors?: any[] }
-          input?: Record<string, (value: any) => { errors?: any[] }>
-        }
-      } & TExtendedConfig
-    }
-  }
-
-  function CreateStream<
-    TName extends string,
-    TParams,
-    TYieldType,
-    TReturnType = void,
-    TInput extends Record<string, unknown> | undefined = undefined,
-  >(
-    name: TName,
-    config: {
-      description?: string
-      schema?: {
-        params?: TParams
-        yieldType?: TYieldType
-        returnType?: TReturnType
-        input?: TInput
-      }
-      validateYields?: boolean
-    } & TExtendedConfig,
-    handler: (
-      ctx: Prettify<TContext & TStreamContext>,
-      params: TInput extends Record<string, unknown>
-        ? Prettify<{ [K in keyof TInput]: TSchemaLib<TInput[K]> }>
-        : TSchemaLib<TParams>
-    ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
-  ) {
-    // Capture definition location as first action
-    const definitionInfo = captureDefinitionInfo()
-
-    // 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,
-      isStream: true,
-      config: {
-        ...config,
-        description: config.description,
-        schema: jsonSchema,
-        validation: {
-          params: validations.params,
-          yield: validations.yield,
-          ...(validations.input && { input: validations.input }),
-        },
-      },
-
-      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., HonoStreamAppBuilder) 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
-            )
-          }
-        }
-
-        // Validate each input channel independently (see Create for rationale)
-        if (validations?.input && !skipValidation) {
-          for (const [channel, validator] of Object.entries(validations.input)) {
-            const channelValue = (params as Record<string, unknown>)?.[channel]
-            const { errors } = validator(channelValue)
-
-            if (errors) {
-              throw new ProcedureValidationError(
-                name,
-                `Validation error for ${name} in input.${channel}`,
-                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. HonoStreamAppBuilder)
-          // 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)
-
-    if (builder?.onCreate) {
-      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: TInput extends Record<string, unknown>
-          ? Prettify<{ [K in keyof TInput]: TSchemaLib<TInput[K]> }>
-          : TSchemaLib<TParams>
-      ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
-    } & {
-      procedure: (
-        ctx: Prettify<TContext>,
-        params: TInput extends Record<string, unknown>
-          ? Prettify<{ [K in keyof TInput]: TSchemaLib<TInput[K]> }>
-          : TSchemaLib<TParams>
-      ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
-      info: {
-        name: TName
-        isStream: true
-        description?: string
-        schema: {
-          params?: TParams
-          yieldType?: TYieldType
-          returnType?: TReturnType
-          input?: TInput
-        }
-        validation?: {
-          params?: (params: any) => { errors?: any[] }
-          yield?: (value: any) => { errors?: any[] }
-          input?: Record<string, (value: any) => { errors?: any[] }>
-        }
-      } & TExtendedConfig
-    }
-  }
+  const Create = makeCreate<TContext, TExtendedConfig>(procedures, builder)
+  const CreateStream = makeCreateStream<TContext, TExtendedConfig>(procedures, builder)
+  const CreateHttp = makeCreateHttp<TContext>(procedures, builder)
+  const CreateHttpStream = makeCreateHttpStream<TContext>(procedures, builder)
 
   return {
     /**
@@ -533,5 +95,7 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
 
     Create,
     CreateStream,
+    CreateHttp,
+    CreateHttpStream,
   }
 }

package/src/migration.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest'
+import { Procedures } from './index.js'
+import { ProcedureRegistrationError } from './errors.js'
+import { Type } from 'typebox'
+
+describe('v7 → v8 migration errors', () => {
+  it('rejects schema.input on Create with v8 message', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.Create('Legacy', { schema: { input: { body: Type.Object({}) } } } as any, async () => undefined)
+    ).toThrow(ProcedureRegistrationError)
+    expect(() =>
+      procs.Create('Legacy2', { schema: { input: { body: Type.Object({}) } } } as any, async () => undefined)
+    ).toThrow(/schema.input was removed in v8/)
+  })
+
+  it('rejects schema.input on CreateStream with v8 message', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.CreateStream('Legacy', {
+        schema: { input: { body: Type.Object({}) }, yieldType: Type.Number() } as any,
+      }, async function* () {})
+    ).toThrow(/schema.input was removed in v8/)
+  })
+})
+
+describe('HTTP fields rejected on RPC creators', () => {
+  const HTTP_FIELDS = ['path', 'method', 'req', 'res', 'successStatus'] as const
+
+  for (const field of HTTP_FIELDS) {
+    it(`Create rejects ${field}`, () => {
+      const procs = Procedures()
+      expect(() =>
+        procs.Create('Foo', { [field]: 'x', schema: { params: Type.Object({}) } } as any, async () => undefined)
+      ).toThrow(/HTTP fields require CreateHttp/)
+    })
+
+    it(`CreateStream rejects ${field}`, () => {
+      const procs = Procedures()
+      expect(() =>
+        procs.CreateStream('Bar', {
+          [field]: 'x',
+          schema: { params: Type.Object({}), yieldType: Type.Number() },
+        } as any, async function* () {})
+      ).toThrow(/HTTP fields require CreateHttp/)
+    })
+  }
+})

package/src/schema/compute-schema.ts

@@ -17,7 +17,8 @@ export function computeSchema<TParamsSchemaType, TReturnTypeSchemaType, TYieldTy
     params?: TParamsSchemaType
     returnType?: TReturnTypeSchemaType
     yieldType?: TYieldTypeSchemaType
-    input?: Record<string, unknown>
+    req?: Record<string, unknown>
+    res?: { body?: unknown; headers?: unknown }
   },
   // Used for error stack trace details
   definitionInfo?: DefinitionInfo
@@ -26,44 +27,56 @@ export function computeSchema<TParamsSchemaType, TReturnTypeSchemaType, TYieldTy
     params?: TJSONSchema
     returnType?: TJSONSchema
     yieldType?: TJSONSchema
-    input?: Record<string, TJSONSchema>
+    req?: Record<string, TJSONSchema>
+    res?: { body?: TJSONSchema; headers?: TJSONSchema }
   }
   validations: {
     params?: (params?: any) => { errors?: TSchemaValidationError[] }
     yield?: (value?: any) => { errors?: TSchemaValidationError[] }
-    input?: Record<string, (value?: any) => { errors?: TSchemaValidationError[] }>
+    req?: Record<string, (value?: any) => { errors?: TSchemaValidationError[] }>
   }
 } {
   const jsonSchema: {
     params?: TJSONSchema
     returnType?: TJSONSchema
     yieldType?: TJSONSchema
-    input?: Record<string, TJSONSchema>
+    req?: Record<string, TJSONSchema>
+    res?: { body?: TJSONSchema; headers?: TJSONSchema }
   } = {
     params: undefined,
     returnType: undefined,
     yieldType: undefined,
-    input: undefined,
+    req: undefined,
+    res: undefined,
   }
 
   const validations: {
     params?: (params?: any) => { errors?: TSchemaValidationError[] }
     yield?: (value?: any) => { errors?: TSchemaValidationError[] }
-    input?: Record<string, (value?: any) => { errors?: TSchemaValidationError[] }>
+    req?: Record<string, (value?: any) => { errors?: TSchemaValidationError[] }>
   } = {}
 
-  // Mutual exclusivity: params and input cannot both be defined
-  if (schema?.params && schema?.input) {
+  // Migration guard: schema.input was removed in v8
+  if (schema && 'input' in schema && (schema as any).input !== undefined) {
     throw new ProcedureRegistrationError(
       name,
-      `schema.params and schema.input are mutually exclusive for procedure "${name}". Use schema.params for flat input or schema.input for structured multi-channel input.`,
+      `schema.input was removed in v8. Use CreateHttp / CreateHttpStream for per-channel HTTP validation. Procedure: "${name}".`,
+      definitionInfo,
+    )
+  }
+
+  // Mutual exclusivity: params and req cannot both be defined
+  if (schema?.params && schema?.req) {
+    throw new ProcedureRegistrationError(
+      name,
+      `schema.params and schema.req are mutually exclusive for procedure "${name}". Use schema.params for RPC procedures or schema.req for HTTP procedures.`,
       definitionInfo
     )
   }
 
   if (schema) {
     const {
-      jsonSchema: { params, returnType, yieldType, input },
+      jsonSchema: { params, returnType, yieldType, req, res },
       validation,
     } = schemaParser(schema, (errors) => {
       throw new ProcedureRegistrationError(
@@ -78,10 +91,11 @@ export function computeSchema<TParamsSchemaType, TReturnTypeSchemaType, TYieldTy
     jsonSchema.params = params
     jsonSchema.returnType = returnType
     jsonSchema.yieldType = yieldType
-    jsonSchema.input = input
+    jsonSchema.req = req
+    jsonSchema.res = res
     validations.params = validation.params
     validations.yield = validation.yield
-    validations.input = validation.input
+    validations.req = validation.req
   }
 
   return { jsonSchema, validations }