ts-procedures 3.1.0 → 3.3.0

package/src/index.ts

@@ -1,6 +1,7 @@
-import { ProcedureError, ProcedureValidationError } from './errors.js'
+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
 
@@ -8,8 +9,13 @@ export type TLocalContext = {
   error: (message: string, meta?: object) => ProcedureError
 }
 
+export type TStreamContext = TLocalContext & {
+  signal: AbortSignal
+}
+
 export type TProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
   name: string
+  isStream?: false
   config: {
     description?: string
     schema?: {
@@ -24,6 +30,25 @@ export type TProcedureRegistration<TContext = unknown, TExtendedConfig = unknown
   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
+    }
+    validation?: {
+      params?: (params: any) => { errors?: any[] }
+      yield?: (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
@@ -32,16 +57,19 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
     onCreate?: (
       procedure: Prettify<{
         name: string
-        handler: (ctx: Prettify<TContext>, params?: any) => Promise<any>
+        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
             }
             validation?: {
               params?: (params: any) => { errors?: any[] }
+              yield?: (value: any) => { errors?: any[] }
             }
           } & TExtendedConfig
         >
@@ -51,7 +79,7 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
 ) {
   const procedures: Map<
     string,
-    TProcedureRegistration<TContext, TExtendedConfig>
+    TProcedureRegistration<TContext, TExtendedConfig> | TStreamProcedureRegistration<TContext, TExtendedConfig>
   > = new Map()
 
   function Create<TName extends string, TParams, TReturnType>(
@@ -68,16 +96,19 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
       params: 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)
+    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)
+      return new ProcedureError(name, message, meta, definitionInfo)
     }
 
     const registeredProcedure = {
@@ -101,7 +132,8 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
               throw new ProcedureValidationError(
                 name,
                 `Validation error for ${name} - ${errors.map((e) => e.message).join(', ')}`,
-                errors
+                errors,
+                definitionInfo
               )
             }
           }
@@ -121,9 +153,20 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
           if (error instanceof ProcedureError) {
             throw error
           } else {
-            const err = new ProcedureError(name, `Error in handler for ${name} - ${error?.message}`)
+            const err = new ProcedureError(
+              name,
+              `Error in handler for ${name} - ${error?.message}`,
+              undefined,
+              definitionInfo
+            )
             err.cause = error  // Preserve original error
-            err.stack = error.stack
+            // 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
           }
         }
@@ -164,6 +207,164 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
     }
   }
 
+  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()
+
+    // 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,
+        },
+      },
+
+      handler: async function* wrappedHandler(ctx: Prettify<TContext>, params: TSchemaLib<TParams>) {
+        // Create abort controller for this stream
+        const abortController = new AbortController()
+
+        // Validate params first
+        if (validations?.params) {
+          const { errors } = validations.params(params)
+
+          if (errors) {
+            throw new ProcedureValidationError(
+              name,
+              `Validation error for ${name} - ${errors.map((e) => e.message).join(', ')}`,
+              errors,
+              definitionInfo
+            )
+          }
+        }
+
+        const streamCtx: TStreamContext = {
+          error: errorFactory,
+          signal: abortController.signal,
+        }
+
+        const userGenerator = handler(
+          {
+            ...ctx,
+            ...streamCtx,
+          } as Prettify<TContext & TStreamContext>,
+          params
+        )
+
+        try {
+          for await (const value of userGenerator) {
+            // 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.map((e) => e.message).join(', ')}`,
+                  errors,
+                  definitionInfo
+                )
+              }
+            }
+
+            yield 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 {
+          // Signal abort on early termination
+          abortController.abort()
+        }
+      } 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: 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
+    }
+  }
+
   return {
     /**
      * Get all registered procedures
@@ -194,5 +395,6 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
     },
 
     Create,
+    CreateStream,
   }
 }

package/src/schema/compute-schema.ts

@@ -1,6 +1,7 @@
 import { schemaParser, TSchemaValidationError } from './parser.js'
 import { ProcedureRegistrationError } from '../errors.js'
 import { TJSONSchema } from './types.js'
+import { DefinitionInfo } from '../stack-utils.js'
 
 /**
  * This function is used to compute the JSON schema and validation functions
@@ -8,34 +9,42 @@ import { TJSONSchema } from './types.js'
  *
  * @param name The name of the procedure
  * @param schema Procedure schema
+ * @param definitionInfo Optional definition info for error reporting
  */
-export function computeSchema<TParamsSchemaType, TReturnTypeSchemaType>(
+export function computeSchema<TParamsSchemaType, TReturnTypeSchemaType, TYieldTypeSchemaType = unknown>(
   name: string,
   schema?: {
     params?: TParamsSchemaType
     returnType?: TReturnTypeSchemaType
+    yieldType?: TYieldTypeSchemaType
   },
+  // Used for error stack trace details
+  definitionInfo?: DefinitionInfo
 ): {
   jsonSchema: {
     params?: TJSONSchema
     returnType?: TJSONSchema
+    yieldType?: TJSONSchema
   }
   validations: {
     params?: (params?: any) => { errors?: TSchemaValidationError[] }
+    yield?: (value?: any) => { errors?: TSchemaValidationError[] }
   }
 } {
-  const jsonSchema: { params?: TJSONSchema; returnType?: TJSONSchema } = {
+  const jsonSchema: { params?: TJSONSchema; returnType?: TJSONSchema; yieldType?: TJSONSchema } = {
     params: undefined,
     returnType: undefined,
+    yieldType: undefined,
   }
 
   const validations: {
     params?: (params?: any) => { errors?: TSchemaValidationError[] }
+    yield?: (value?: any) => { errors?: TSchemaValidationError[] }
   } = {}
 
   if (schema) {
     const {
-      jsonSchema: { params, returnType },
+      jsonSchema: { params, returnType, yieldType },
       validation,
     } = schemaParser(schema, (errors) => {
       throw new ProcedureRegistrationError(
@@ -43,12 +52,15 @@ export function computeSchema<TParamsSchemaType, TReturnTypeSchemaType>(
         `Error parsing schema for ${name} - ${Object.entries(errors)
           .map(([key, error]) => `${key}: ${error}`)
           .join(', ')}`,
+        definitionInfo
       )
     })
 
     jsonSchema.params = params
     jsonSchema.returnType = returnType
+    jsonSchema.yieldType = yieldType
     validations.params = validation.params
+    validations.yield = validation.yield
   }
 
   return { jsonSchema, validations }

package/src/schema/parser.ts

@@ -4,8 +4,11 @@ import { extractJsonSchema } from './extract-json-schema.js'
 import { TJSONSchema } from './types.js'
 
 export type TSchemaParsed = {
-  jsonSchema: { params?: TJSONSchema; returnType?: TJSONSchema }
-  validation: { params?: (params: any) => { errors?: TSchemaValidationError[] } }
+  jsonSchema: { params?: TJSONSchema; returnType?: TJSONSchema; yieldType?: TJSONSchema }
+  validation: {
+    params?: (params: any) => { errors?: TSchemaValidationError[] }
+    yield?: (value: any) => { errors?: TSchemaValidationError[] }
+  }
 }
 
 export type TSchemaValidationError = AJV.ErrorObject
@@ -21,8 +24,8 @@ const ajv = addFormats(
 )
 
 export function schemaParser(
-  schema: { params?: unknown; returnType?: unknown },
-  onParseError: (errors: { params?: string; returnType?: string }) => void
+  schema: { params?: unknown; returnType?: unknown; yieldType?: unknown },
+  onParseError: (errors: { params?: string; returnType?: string; yieldType?: string }) => void
 ): TSchemaParsed {
   const jsonSchema: TSchemaParsed['jsonSchema'] = {}
   const validation: TSchemaParsed['validation'] = {}
@@ -93,5 +96,53 @@ export function schemaParser(
     }
   }
 
+  if (schema.yieldType) {
+    try {
+      const extracted = extractJsonSchema(schema.yieldType as TJSONSchema)
+
+      if (extracted) {
+        jsonSchema.yieldType = extracted
+      }
+    } catch (e: any) {
+      onParseError({
+        yieldType: `Error extracting json schema schema.yieldType - ${e.message}`,
+      })
+    }
+
+    if (!jsonSchema.yieldType) {
+      onParseError({
+        yieldType: `Error extracting json schema schema.yieldType - schema.yieldType might be empty or it is not a valid suretype or typebox type`,
+      })
+    } else {
+      let yieldValidator: AJV.ValidateFunction | undefined
+
+      try {
+        yieldValidator = ajv.compile(jsonSchema.yieldType as TJSONSchema)
+      } catch (e: any) {
+        onParseError({
+          yieldType: `Error compiling schema.yieldType for validator - ${e.message}`,
+        })
+      }
+
+      validation.yield = (value: any) => {
+        if (!yieldValidator) {
+          return { errors: [{ message: 'Validator not initialized', keyword: 'internal' } as TSchemaValidationError] }
+        }
+
+        const valid = yieldValidator(value)
+
+        if (!valid) {
+          const errors = yieldValidator.errors
+
+          return {
+            errors: errors?.length ? errors : undefined,
+          }
+        }
+
+        return {}
+      }
+    }
+  }
+
   return { jsonSchema, validation }
 }

package/src/schema/types.ts

@@ -9,6 +9,10 @@ export type TSchemaLib<SchemaLibType> =
       ? Static<SchemaLibType>
       : unknown
 
+// AsyncGenerator type extraction for streaming procedures
+export type TSchemaLibGenerator<TYield, TReturn = void> =
+  AsyncGenerator<TSchemaLib<TYield>, TSchemaLib<TReturn>, unknown>
+
 export type TJSONSchema = Record<string, any>
 
 export type Prettify<TObject> = {

package/src/stack-utils.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'vitest'
+import { captureDefinitionInfo, formatDefinitionInfo, DefinitionInfo } from './stack-utils.js'
+
+describe('Stack Utils', () => {
+  describe('captureDefinitionInfo', () => {
+    test('returns definition info with definedAt', () => {
+      const info = captureDefinitionInfo()
+
+      // Should capture the call site in this test file
+      expect(info).toBeDefined()
+      expect(info.definitionStack).toBeDefined()
+      expect(typeof info.definitionStack).toBe('string')
+    })
+
+    test('definedAt contains file, line, column when available', () => {
+      const info = captureDefinitionInfo()
+
+      // The definedAt should be present since we're calling from user code (test file)
+      if (info.definedAt) {
+        expect(info.definedAt.file).toBeDefined()
+        expect(typeof info.definedAt.file).toBe('string')
+        expect(info.definedAt.line).toBeDefined()
+        expect(typeof info.definedAt.line).toBe('number')
+        expect(info.definedAt.line).toBeGreaterThan(0)
+        expect(info.definedAt.column).toBeDefined()
+        expect(typeof info.definedAt.column).toBe('number')
+        expect(info.definedAt.column).toBeGreaterThan(0)
+        expect(info.definedAt.raw).toBeDefined()
+        expect(typeof info.definedAt.raw).toBe('string')
+      }
+    })
+
+    test('definitionStack contains Error stack trace', () => {
+      const info = captureDefinitionInfo()
+
+      expect(info.definitionStack).toContain('Error')
+      expect(info.definitionStack).toContain('at ')
+    })
+  })
+
+  describe('formatDefinitionInfo', () => {
+    test('returns undefined when definedAt is not present', () => {
+      const info: DefinitionInfo = {}
+      const result = formatDefinitionInfo(info, 'TestProcedure')
+
+      expect(result).toBeUndefined()
+    })
+
+    test('returns formatted string when definedAt is present', () => {
+      const info: DefinitionInfo = {
+        definedAt: {
+          file: '/app/procedures/test.ts',
+          line: 42,
+          column: 5,
+          raw: 'at Object.<anonymous> (/app/procedures/test.ts:42:5)',
+        },
+      }
+      const result = formatDefinitionInfo(info, 'TestProcedure')
+
+      expect(result).toBeDefined()
+      expect(result).toContain('--- Procedure "TestProcedure" defined at ---')
+      expect(result).toContain('/app/procedures/test.ts:42:5')
+    })
+
+    test('includes procedure name in formatted output', () => {
+      const info: DefinitionInfo = {
+        definedAt: {
+          file: '/path/to/file.ts',
+          line: 10,
+          column: 3,
+          raw: 'at /path/to/file.ts:10:3',
+        },
+      }
+      const result = formatDefinitionInfo(info, 'MyCustomProcedure')
+
+      expect(result).toContain('"MyCustomProcedure"')
+    })
+  })
+
+  describe('integration with procedure creation', () => {
+    test('captures location from calling code', () => {
+      // Helper to simulate what happens in Create()
+      function simulateCreate() {
+        return captureDefinitionInfo()
+      }
+
+      const info = simulateCreate()
+
+      // Should have captured the location of the simulateCreate() call
+      expect(info).toBeDefined()
+      expect(info.definitionStack).toBeDefined()
+    })
+  })
+})

package/src/stack-utils.ts

@@ -0,0 +1,129 @@
+/**
+ * Represents a specific location in source code where a procedure was defined.
+ */
+export type DefinitionLocation = {
+  file: string
+  line: number
+  column: number
+  raw: string
+}
+
+/**
+ * Contains information about where a procedure was defined.
+ */
+export type DefinitionInfo = {
+  definedAt?: DefinitionLocation
+  definitionStack?: string
+}
+
+/**
+ * Internal ts-procedures files that should be skipped when finding user code.
+ * Only skip the core library files, not test files or user code.
+ */
+const INTERNAL_FILES = [
+  '/index.ts',
+  '/index.js',
+  '/errors.ts',
+  '/errors.js',
+  '/stack-utils.ts',
+  '/stack-utils.js',
+  '/compute-schema.ts',
+  '/compute-schema.js',
+  '/parser.ts',
+  '/parser.js',
+]
+
+/**
+ * Captures the stack trace at the call site and extracts the definition location.
+ * Finds the first stack frame outside of ts-procedures internal files.
+ */
+export function captureDefinitionInfo(): DefinitionInfo {
+  const err = new Error()
+  const stack = err.stack
+
+  if (!stack) {
+    return {}
+  }
+
+  const lines = stack.split('\n')
+
+  // Find the first frame that's not from ts-procedures internals
+  // Skip the first line (Error message) and frames from this module
+  let userFrame: string | undefined
+
+  for (let i = 1; i < lines.length; i++) {
+    const rawLine = lines[i]
+    if (!rawLine) continue
+    const line = rawLine.trim()
+
+    // Skip empty or invalid frames
+    if (!line.startsWith('at ')) {
+      continue
+    }
+
+    // Skip frames from ts-procedures internal source files
+    const isInternalFile = INTERNAL_FILES.some(file => line.includes(file))
+    if (isInternalFile) {
+      continue
+    }
+
+    // Skip frames from ts-procedures in node_modules (when used as a dependency)
+    if (line.includes('/node_modules/ts-procedures/') || line.includes('\\node_modules\\ts-procedures\\')) {
+      continue
+    }
+
+    // Skip internal node frames
+    if (line.includes('node:') || line.startsWith('at Module.') || line.startsWith('at Object.<anonymous> (node:')) {
+      continue
+    }
+
+    userFrame = line
+    break
+  }
+
+  if (!userFrame) {
+    return { definitionStack: stack }
+  }
+
+  const definedAt = parseStackFrame(userFrame)
+
+  return {
+    definedAt,
+    definitionStack: stack,
+  }
+}
+
+/**
+ * Parses a V8 stack frame line to extract file, line, and column info.
+ * Handles formats like:
+ * - "at Object.<anonymous> (/path/to/file.ts:10:5)"
+ * - "at functionName (/path/to/file.ts:10:5)"
+ * - "at /path/to/file.ts:10:5"
+ */
+function parseStackFrame(frame: string): DefinitionLocation | undefined {
+  // Match patterns like "(path:line:column)" or just "path:line:column"
+  const match = frame.match(/\(([^)]+):(\d+):(\d+)\)$/) || frame.match(/at ([^:]+):(\d+):(\d+)$/)
+
+  if (match && match[1] && match[2] && match[3]) {
+    return {
+      file: match[1],
+      line: parseInt(match[2], 10),
+      column: parseInt(match[3], 10),
+      raw: frame,
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Formats definition info for appending to error stacks.
+ */
+export function formatDefinitionInfo(info: DefinitionInfo, procedureName: string): string | undefined {
+  if (!info.definedAt) {
+    return undefined
+  }
+
+  const { file, line, column } = info.definedAt
+  return `\n--- Procedure "${procedureName}" defined at ---\n    at ${file}:${line}:${column}`
+}