ts-procedures 5.9.1 → 5.10.2

package/src/index.ts

@@ -0,0 +1,522 @@
+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
+}
+
+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 function Procedures<TContext = TNoContextProvided, TExtendedConfig = unknown>(
+  /**
+   * Optionally provided builder to register Procedures
+   */
+  builder?: {
+    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
+        >
+      }>
+    ) => void
+  }
+) {
+  const procedures: Map<
+    string,
+    | TProcedureRegistration<TContext, TExtendedConfig>
+    | TStreamProcedureRegistration<TContext, TExtendedConfig>
+  > = 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)
+          const isPrevalidated = (ctx as { isPrevalidated?: boolean }).isPrevalidated
+          if (validations?.params && !isPrevalidated) {
+            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 && !isPrevalidated) {
+            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)
+        const isPrevalidated = (ctx as { isPrevalidated?: boolean }).isPrevalidated
+        if (validations?.params && !isPrevalidated) {
+          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 && !isPrevalidated) {
+          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
+        )
+
+        try {
+          const userIterator = userGenerator[Symbol.asyncIterator]()
+          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) {
+          if (error instanceof ProcedureError) {
+            throw error
+          } else {
+            const err = new ProcedureError(
+              name,
+              `Error in streaming 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
+          }
+        } finally {
+          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
+    }
+  }
+
+  return {
+    /**
+     * Get all registered procedures
+     */
+    getProcedures: () => {
+      return Array.from(procedures.values())
+    },
+
+    /**
+     * Get a specific procedure by name
+     */
+    getProcedure: (name: string) => {
+      return procedures.get(name)
+    },
+
+    /**
+     * Remove a procedure by name
+     */
+    removeProcedure: (name: string) => {
+      return procedures.delete(name)
+    },
+
+    /**
+     * Clear all registered procedures
+     */
+    clear: () => {
+      procedures.clear()
+    },
+
+    Create,
+    CreateStream,
+  }
+}

package/src/schema/compute-schema.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest'
+import { Type } from 'typebox'
+import { v } from 'suretype'
+import { computeSchema } from './compute-schema.js'
+import { ProcedureRegistrationError } from '../errors.js'
+
+describe('computeSchema', () => {
+  it('should return empty schema and validations when no schema provided', () => {
+    const result = computeSchema('test-procedure')
+
+    expect(result).toEqual({
+      jsonSchema: { params: undefined, returnType: undefined },
+      validations: {}
+    })
+  })
+
+  describe('with Typebox schema', () => {
+    it('should correctly process params schema', () => {
+      const schema = {
+        params: Type.Object({
+          name: Type.String(),
+          age: Type.Number()
+        })
+      }
+
+      const result = computeSchema('test-procedure', schema)
+
+      expect(result.jsonSchema.params).toBeDefined()
+      expect(result.validations.params).toBeDefined()
+
+      // Test validation function
+      const validInput = { name: 'John', age: 30 }
+      expect(result.validations.params?.(validInput).errors).toBeUndefined()
+
+      // Test invalid input
+      const invalidInput = { name: 123, age: 'invalid' }
+      expect(result.validations.params?.(invalidInput).errors).toBeDefined()
+    })
+
+    it('should correctly process returnType schema', () => {
+      const schema = {
+        returnType: Type.Object({
+          result: Type.Boolean()
+        })
+      }
+
+      const result = computeSchema('test-procedure', schema)
+
+      expect(result.jsonSchema.returnType).toBeDefined()
+      expect(result.validations.params).toBeUndefined()
+    })
+  })
+
+  describe('with Suretype schema', () => {
+    it('should correctly process params schema', () => {
+      const schema = {
+        params: v.object({
+          name: v.string(),
+          age: v.number()
+        })
+      }
+
+      const result = computeSchema('test-procedure', schema)
+
+      expect(result.jsonSchema.params).toBeDefined()
+      expect(result.validations.params).toBeDefined()
+
+      // Test validation function
+      const validInput = { name: 'John', age: 30 }
+      expect(result.validations.params?.(validInput).errors).toBeUndefined()
+
+      // Test invalid input
+      const invalidInput = { name: 123, age: 'invalid' }
+      expect(result.validations.params?.(invalidInput).errors).toBeDefined()
+    })
+  })
+
+  describe('error handling', () => {
+    it('should throw ProcedureRegistrationError for invalid schema', () => {
+      const invalidSchema = {
+        params: {
+          type: 'invalid-schema-type'
+        }
+      }
+
+      expect(() => computeSchema('test-procedure', invalidSchema))
+        .toThrow(ProcedureRegistrationError)
+    })
+
+    it('should include procedure name in error message', () => {
+      const invalidSchema = {
+        params: {
+          type: 'invalid-schema-type'
+        }
+      }
+
+      try {
+        computeSchema('test-procedure', invalidSchema)
+      } catch (error: any) {
+        expect(error instanceof ProcedureRegistrationError).toBe(true)
+        expect(error.message).toContain('test-procedure')
+      }
+    })
+  })
+
+  describe('combined schemas', () => {
+    it('should handle both params and returnType schemas', () => {
+      const schema = {
+        params: Type.Object({
+          input: Type.String()
+        }),
+        returnType: Type.Object({
+          output: Type.Boolean()
+        })
+      }
+
+      const result = computeSchema('test-procedure', schema)
+
+      expect(result.jsonSchema.params).toBeDefined()
+      expect(result.jsonSchema.returnType).toBeDefined()
+      expect(result.validations.params).toBeDefined()
+
+      // Test params validation
+      const validInput = { input: 'test' }
+      expect(result.validations.params?.(validInput).errors).toBeUndefined()
+    })
+  })
+})