ts-procedures 3.1.0 → 3.3.0

package/src/index.test.ts

@@ -3,10 +3,7 @@ import { describe, expect, test } from 'vitest'
 import { Procedures } from './index.js'
 import { v } from 'suretype'
 import { Type } from 'typebox'
-import {
-  ProcedureError,
-  ProcedureValidationError,
-} from './errors.js'
+import { ProcedureError, ProcedureValidationError } from './errors.js'
 
 describe('Procedures', () => {
   test('Procedures', () => {
@@ -31,7 +28,7 @@ describe('Procedures', () => {
 
     const { Create } = Procedures<CustomContext, ExtendedConfig>()
 
-    const {info} = Create(
+    const { info } = Create(
       'TestProcedure',
       {
         // should not throw type errors
@@ -40,7 +37,7 @@ describe('Procedures', () => {
       async (ctx) => {
         // should not throw type errors
         return ctx.authToken
-      },
+      }
     )
 
     expect(info.customProp).toEqual('customProp')
@@ -48,20 +45,12 @@ describe('Procedures', () => {
   })
 
   test('Create Single Procedures', () => {
-    const { procedure: procedure1, info: info1 } = Procedures().Create(
-      'test1',
-      {},
-      async () => {
-        return '1'
-      },
-    )
-    const { procedure: procedure2, info: info2 } = Procedures().Create(
-      'test2',
-      {},
-      async () => {
-        return '2'
-      },
-    )
+    const { procedure: procedure1, info: info1 } = Procedures().Create('test1', {}, async () => {
+      return '1'
+    })
+    const { procedure: procedure2, info: info2 } = Procedures().Create('test2', {}, async () => {
+      return '2'
+    })
 
     expect(procedure1).toBeDefined()
     expect(info1).toBeDefined()
@@ -91,7 +80,7 @@ describe('Procedures', () => {
           expect(params).toEqual({ name: 'name' })
           done()
           return 'name'
-        },
+        }
       )
 
       mockHttpCall({}, { name: 'name' })
@@ -119,7 +108,7 @@ describe('Procedures', () => {
           expect(params).toEqual({ name: 'name' })
           done()
           return 'name'
-        },
+        }
       )
 
       mockHttpCall({}, { name: 'name' })
@@ -144,7 +133,7 @@ describe('Procedures', () => {
       },
       async (ctx, params) => {
         return params.number
-      },
+      }
     )
 
     expect(NamedExportHandler).toBeDefined()
@@ -200,7 +189,7 @@ describe('Procedures', () => {
         },
         async () => {
           done()
-        },
+        }
       )
 
       mockHttpCall()
@@ -243,7 +232,7 @@ describe('Procedures', () => {
         },
         async () => {
           return
-        },
+        }
       )
 
       mockHttpCall({})
@@ -272,13 +261,9 @@ describe('Procedures', () => {
   test('Procedure handler can throw local ctx error and is caught', async () => {
     const { Create } = Procedures()
 
-    const { TestProcedureHandlerError } = Create(
-      'TestProcedureHandlerError',
-      {},
-      async (ctx) => {
-        throw ctx.error( 'Local context error')
-      },
-    )
+    const { TestProcedureHandlerError } = Create('TestProcedureHandlerError', {}, async (ctx) => {
+      throw ctx.error('Local context error')
+    })
 
     try {
       await TestProcedureHandlerError({}, {})
@@ -307,11 +292,11 @@ describe('Procedures', () => {
       },
       async () => {
         return 'test-docs'
-      },
+      }
     )
 
     const procedures = getProcedures()
-    const testDocsProcedure = procedures.find(p => p.name === 'test-docs')
+    const testDocsProcedure = procedures.find((p) => p.name === 'test-docs')
     expect(testDocsProcedure).toBeDefined()
     expect(testDocsProcedure?.config?.schema).toEqual({
       params: {
@@ -353,15 +338,15 @@ describe('Procedures', () => {
         }
 
         return 'User authentication is valid'
-      },
+      }
     )
 
-    await expect(
-      CheckIsAuthenticated({ authToken: 'valid-token' }, {}),
-    ).resolves.toEqual('User authentication is valid')
-    await expect(
-      CheckIsAuthenticated({ authToken: 'not-valid-token' }, {}),
-    ).rejects.toThrowError(ProcedureError)
+    await expect(CheckIsAuthenticated({ authToken: 'valid-token' }, {})).resolves.toEqual(
+      'User authentication is valid'
+    )
+    await expect(CheckIsAuthenticated({ authToken: 'not-valid-token' }, {})).rejects.toThrowError(
+      ProcedureError
+    )
   })
 
   test('Procedures - duplicate registration throws before schema computation', () => {
@@ -447,3 +432,502 @@ describe('Procedures', () => {
     }
   })
 })
+
+describe('Procedures - Definition Location in Errors', () => {
+  test('ProcedureValidationError includes definition location', async () => {
+    const { Create } = Procedures()
+
+    const { TestValidation } = Create(
+      'TestValidation',
+      {
+        schema: {
+          params: v.object({ name: v.string().required() }),
+        },
+      },
+      async (ctx, params) => {
+        return params.name
+      }
+    )
+
+    try {
+      // @ts-expect-error - intentionally passing invalid params
+      await TestValidation({}, {}) // Missing required 'name' param
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureValidationError)
+      expect(e.definedAt).toBeDefined()
+      expect(e.definedAt.file).toContain('index.test.ts')
+      expect(e.definedAt.line).toBeGreaterThan(0)
+      expect(e.definedAt.column).toBeGreaterThan(0)
+      expect(e.stack).toContain('--- Procedure "TestValidation" defined at ---')
+    }
+  })
+
+  test('ctx.error() includes definition location', async () => {
+    const { Create } = Procedures()
+
+    const { TestCtxError } = Create('TestCtxError', {}, async (ctx) => {
+      throw ctx.error('Custom error')
+    })
+
+    try {
+      await TestCtxError({}, {})
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.definedAt).toBeDefined()
+      expect(e.definedAt.file).toContain('index.test.ts')
+      expect(e.getDefinitionLocation()).toBeDefined()
+      expect(e.stack).toContain('--- Procedure "TestCtxError" defined at ---')
+    }
+  })
+
+  test('wrapped errors include definition location', async () => {
+    const { Create } = Procedures()
+
+    const { TestWrappedError } = Create('TestWrappedError', {}, async () => {
+      throw new Error('Original error')
+    })
+
+    try {
+      await TestWrappedError({}, {})
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.definedAt).toBeDefined()
+      expect(e.definedAt.file).toContain('index.test.ts')
+      expect(e.message).toContain('Error in handler for TestWrappedError')
+      expect(e.cause).toBeInstanceOf(Error)
+      expect(e.cause.message).toBe('Original error')
+    }
+  })
+
+  test('getDefinitionLocation returns formatted string', async () => {
+    const { Create } = Procedures()
+
+    const { TestGetLocation } = Create(
+      'TestGetLocation',
+      {
+        schema: {
+          params: v.object({ id: v.number().required() }),
+        },
+      },
+      async (ctx, params) => {
+        return params.id
+      }
+    )
+
+    try {
+      // @ts-expect-error - intentionally passing invalid params
+      await TestGetLocation({}, {}) // Missing required 'id' param
+    } catch (e: any) {
+      const location = e.getDefinitionLocation()
+      expect(location).toBeDefined()
+      expect(location).toMatch(/index\.test\.ts:\d+:\d+/)
+    }
+  })
+
+  test('error stack shows procedure definition location at the end', async () => {
+    const { Create } = Procedures()
+
+    const { TestStackFormat } = Create(
+      'TestStackFormat',
+      {
+        schema: {
+          params: v.object({ value: v.string().required() }),
+        },
+      },
+      async (ctx, params) => {
+        return params.value
+      }
+    )
+
+    try {
+      // @ts-expect-error - intentionally passing invalid params
+      await TestStackFormat({}, {})
+    } catch (e: any) {
+      // Verify it's a validation error
+      expect(e.name).toBe('ProcedureValidationError')
+      expect(e).toBeInstanceOf(ProcedureValidationError)
+      // Stack should contain the error message and definition location
+      expect(e.stack).toContain('Validation error for TestStackFormat')
+      expect(e.stack).toContain('--- Procedure "TestStackFormat" defined at ---')
+      // The definition section should be at the end of the stack
+      const stackLines = e.stack.split('\n')
+      const definitionIndex = stackLines.findIndex((line: string) =>
+        line.includes('--- Procedure "TestStackFormat" defined at ---')
+      )
+      expect(definitionIndex).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe('Streaming Procedures - CreateStream', () => {
+  test('CreateStream creates a streaming procedure', async () => {
+    const { CreateStream } = Procedures()
+
+    const { StreamTest, procedure, info } = CreateStream(
+      'StreamTest',
+      {
+        description: 'Test streaming procedure',
+        schema: {
+          params: v.object({ count: v.number().required() }),
+          yieldType: v.object({ value: v.number().required() }),
+        },
+      },
+      async function* (ctx, params) {
+        for (let i = 0; i < params.count; i++) {
+          yield { value: i }
+        }
+      }
+    )
+
+    expect(StreamTest).toBeDefined()
+    expect(procedure).toBeDefined()
+    expect(info.isStream).toBe(true)
+    expect(info.name).toBe('StreamTest')
+    expect(info.description).toBe('Test streaming procedure')
+    expect(info.schema.params).toEqual({
+      type: 'object',
+      properties: { count: { type: 'number' } },
+      required: ['count'],
+    })
+    expect(info.schema.yieldType).toEqual({
+      type: 'object',
+      properties: { value: { type: 'number' } },
+      required: ['value'],
+    })
+
+    // Collect yielded values
+    const values: { value: number }[] = []
+    for await (const val of StreamTest({}, { count: 3 })) {
+      values.push(val)
+    }
+
+    expect(values).toEqual([{ value: 0 }, { value: 1 }, { value: 2 }])
+  })
+
+  test('CreateStream validates params', async () => {
+    const { CreateStream } = Procedures()
+
+    const { StreamWithParams } = CreateStream(
+      'StreamWithParams',
+      {
+        schema: {
+          params: v.object({ name: v.string().required() }),
+          yieldType: v.string(),
+        },
+      },
+      async function* (ctx, params) {
+        yield params.name
+      }
+    )
+
+    // Missing required param should throw ProcedureValidationError
+    try {
+      // @ts-expect-error - intentionally passing invalid params
+      for await (const _val of StreamWithParams({}, {})) {
+        // Should not reach here
+      }
+      expect.fail('Should have thrown')
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureValidationError)
+      expect(e.message).toContain('Validation error for StreamWithParams')
+    }
+  })
+
+  test('CreateStream with validateYields validates each yielded value', async () => {
+    const { CreateStream } = Procedures()
+    const { ProcedureYieldValidationError } = await import('./errors.js')
+
+    const { StreamValidateYields } = CreateStream(
+      'StreamValidateYields',
+      {
+        schema: {
+          yieldType: v.object({ id: v.number().required() }),
+        },
+        validateYields: true,
+      },
+      async function* () {
+        yield { id: 1 } // Valid
+        yield { id: 'not-a-number' } as any // Invalid - should throw
+      }
+    )
+
+    const values: any[] = []
+    try {
+      for await (const val of StreamValidateYields({}, {})) {
+        values.push(val)
+      }
+      expect.fail('Should have thrown on invalid yield')
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureYieldValidationError)
+      expect(e.message).toContain('Yield validation error for StreamValidateYields')
+      expect(values).toEqual([{ id: 1 }]) // First value was valid
+    }
+  })
+
+  test('CreateStream without validateYields does not validate yields', async () => {
+    const { CreateStream } = Procedures()
+
+    const { StreamNoValidate } = CreateStream(
+      'StreamNoValidate',
+      {
+        schema: {
+          yieldType: v.object({ id: v.number().required() }),
+        },
+        // validateYields defaults to false
+      },
+      async function* () {
+        yield { id: 1 }
+        yield { id: 'not-a-number' } as any // Invalid but won't throw
+      }
+    )
+
+    const values: any[] = []
+    for await (const val of StreamNoValidate({}, {})) {
+      values.push(val)
+    }
+
+    expect(values).toEqual([{ id: 1 }, { id: 'not-a-number' }])
+  })
+
+  test('CreateStream ctx.error throws ProcedureError', async () => {
+    const { CreateStream } = Procedures()
+
+    const { StreamError } = CreateStream('StreamError', {}, async function* (ctx) {
+      yield 'first'
+      throw ctx.error('Custom stream error', { code: 'STREAM_ERR' })
+    })
+
+    const values: any[] = []
+    try {
+      for await (const val of StreamError({}, {})) {
+        values.push(val)
+      }
+      expect.fail('Should have thrown')
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.message).toBe('Custom stream error')
+      expect(e.procedureName).toBe('StreamError')
+      expect(e.meta).toEqual({ code: 'STREAM_ERR' })
+      expect(values).toEqual(['first'])
+    }
+  })
+
+  test('CreateStream provides ctx.signal for abort handling', async () => {
+    const { CreateStream } = Procedures()
+    let signalReceived = false
+
+    const { StreamWithSignal } = CreateStream('StreamWithSignal', {}, async function* (ctx) {
+      expect(ctx.signal).toBeDefined()
+      expect(ctx.signal).toBeInstanceOf(AbortSignal)
+      signalReceived = true
+      yield 'value'
+    })
+
+    for await (const _val of StreamWithSignal({}, {})) {
+      // consume
+    }
+
+    expect(signalReceived).toBe(true)
+  })
+
+  test('CreateStream appears in getProcedures with isStream flag', () => {
+    const { Create, CreateStream, getProcedures } = Procedures()
+
+    Create('RegularProc', {}, async () => 'regular')
+
+    CreateStream('StreamProc', {}, async function* () {
+      yield 'stream'
+    })
+
+    const procs = getProcedures()
+    expect(procs.length).toBe(2)
+
+    const regular = procs.find((p) => p.name === 'RegularProc')
+    const stream = procs.find((p) => p.name === 'StreamProc')
+
+    expect(regular?.isStream).toBeUndefined()
+    expect(stream?.isStream).toBe(true)
+  })
+
+  test('CreateStream onCreate callback receives isStream flag', () =>
+    new Promise<void>((done) => {
+      let receivedProc: any
+
+      const { CreateStream } = Procedures({
+        onCreate: (proc) => {
+          receivedProc = proc
+        },
+      })
+
+      CreateStream('OnCreateStream', {}, async function* () {
+        yield 'test'
+      })
+
+      expect(receivedProc).toBeDefined()
+      expect(receivedProc.isStream).toBe(true)
+      expect(receivedProc.name).toBe('OnCreateStream')
+      done()
+    }))
+
+  test('CreateStream duplicate registration throws', () => {
+    const { CreateStream } = Procedures()
+
+    CreateStream('DuplicateStream', {}, async function* () {
+      yield 'first'
+    })
+
+    expect(() => {
+      CreateStream('DuplicateStream', {}, async function* () {
+        yield 'second'
+      })
+    }).toThrow('Procedure with name DuplicateStream is already registered')
+  })
+
+  test('CreateStream error includes definition location', async () => {
+    const { CreateStream } = Procedures()
+
+    const { StreamErrorLocation } = CreateStream(
+      'StreamErrorLocation',
+      {
+        schema: {
+          params: v.object({ id: v.number().required() }),
+        },
+      },
+      async function* () {
+        yield 'test'
+      }
+    )
+
+    try {
+      // @ts-expect-error - intentionally passing invalid params
+      for await (const _val of StreamErrorLocation({}, {})) {
+        // consume
+      }
+      expect.fail('Should have thrown')
+    } catch (e: any) {
+      expect(e.definedAt).toBeDefined()
+      expect(e.definedAt.file).toContain('index.test.ts')
+      expect(e.stack).toContain('--- Procedure "StreamErrorLocation" defined at ---')
+    }
+  })
+
+  test('CreateStream with Typebox schema', async () => {
+    const { CreateStream } = Procedures()
+
+    const { TypeboxStream } = CreateStream(
+      'TypeboxStream',
+      {
+        schema: {
+          params: Type.Object({ limit: Type.Number() }),
+          yieldType: Type.Object({ data: Type.String() }),
+        },
+      },
+      async function* (ctx, params) {
+        for (let i = 0; i < params.limit; i++) {
+          yield { data: `item-${i}` }
+        }
+      }
+    )
+
+    const values: any[] = []
+    for await (const val of TypeboxStream({}, { limit: 2 })) {
+      values.push(val)
+    }
+
+    expect(values).toEqual([{ data: 'item-0' }, { data: 'item-1' }])
+  })
+
+  test('CreateStream with context type', async () => {
+    interface StreamContext {
+      userId: string
+    }
+
+    const { CreateStream } = Procedures<StreamContext>()
+
+    const { ContextStream } = CreateStream('ContextStream', {}, async function* (ctx) {
+      // ctx should have both userId and error
+      expect(ctx.userId).toBe('user-123')
+      expect(ctx.error).toBeDefined()
+      expect(ctx.signal).toBeDefined()
+      yield ctx.userId
+    })
+
+    const values: any[] = []
+    for await (const val of ContextStream({ userId: 'user-123' }, {})) {
+      values.push(val)
+    }
+
+    expect(values).toEqual(['user-123'])
+  })
+
+  test('CreateStream wrapped errors preserve cause', async () => {
+    const { CreateStream } = Procedures()
+    const originalError = new Error('Stream underlying error')
+    ;(originalError as any).code = 'STREAM_FAIL'
+
+    const { StreamCause } = CreateStream(
+      'StreamCause',
+      {},
+      // eslint-disable-next-line require-yield
+      async function* () {
+        throw originalError
+      }
+    )
+
+    try {
+      for await (const _val of StreamCause({}, {})) {
+        // consume
+      }
+      expect.fail('Should have thrown')
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.cause).toBe(originalError)
+      expect(e.cause.code).toBe('STREAM_FAIL')
+    }
+  })
+
+  test('CreateStream with extended config', () => {
+    interface ExtConfig {
+      scope: string
+      version: number
+    }
+
+    const { CreateStream } = Procedures<unknown, ExtConfig>()
+
+    const { info } = CreateStream(
+      'ExtendedStream',
+      {
+        scope: 'api',
+        version: 1,
+        description: 'Extended config stream',
+      },
+      async function* () {
+        yield 'data'
+      }
+    )
+
+    expect(info.scope).toBe('api')
+    expect(info.version).toBe(1)
+    expect(info.description).toBe('Extended config stream')
+    expect(info.isStream).toBe(true)
+  })
+
+  test('CreateStream signal.aborted becomes true after generator completes', async () => {
+    const { CreateStream } = Procedures()
+    let capturedSignal: AbortSignal | null = null
+
+    const { AbortStream } = CreateStream('AbortStream', {}, async function* (ctx) {
+      capturedSignal = ctx.signal
+      yield 'value'
+    })
+
+    // Consume the generator
+    for await (const _val of AbortStream({}, {})) {
+      // consume
+    }
+
+    // After generator completes, signal should be aborted
+    expect(capturedSignal).not.toBeNull()
+    expect(capturedSignal!.aborted).toBe(true)
+  })
+})