ts-procedures 7.3.0 → 8.0.0

package/src/create-stream.test.ts

@@ -0,0 +1,565 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { describe, expect, it, test } from 'vitest'
+import { Procedures } from './index.js'
+import { v } from 'suretype'
+import { Type } from 'typebox'
+import { ProcedureError, ProcedureValidationError } from './errors.js'
+
+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 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('create-stream.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 rethrows the original error preserving class identity', async () => {
+    // The streaming wrapper must NOT box user errors inside ProcedureError —
+    // doing so would defeat route-declared typed-error dispatch on the client
+    // (the HTTP builder's taxonomy would see `ProcedureError` instead of the
+    // user's class). Stack annotation is added in place; class identity and
+    // custom properties are preserved.
+    class MyDomainError extends Error {
+      readonly name = 'MyDomainError'
+      readonly code = 'STREAM_FAIL'
+    }
+
+    const { CreateStream } = Procedures()
+    const originalError = new MyDomainError('Stream underlying error')
+
+    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).toBe(originalError)
+      expect(e).toBeInstanceOf(MyDomainError)
+      expect(e.code).toBe('STREAM_FAIL')
+    }
+  })
+
+  test('CreateStream propagates .return() to the user generator', async () => {
+    // Consumers that close a stream early (via `iterator.return()` or breaking
+    // out of for-await) must trigger the user generator's `finally` block so
+    // cleanup (db handles, subscriptions, signal-driven teardown) runs.
+    const { CreateStream } = Procedures()
+    let finallyRan = false
+
+    const { EarlyClose } = CreateStream(
+      'EarlyClose',
+      {},
+      async function* () {
+        try {
+          yield 1
+          yield 2
+          yield 3
+        } finally {
+          finallyRan = true
+        }
+      }
+    )
+
+    const iter = EarlyClose({}, {})
+    const first = await iter.next()
+    expect(first.value).toBe(1)
+    await iter.return!(undefined)
+    expect(finallyRan).toBe(true)
+  })
+
+  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)
+  })
+
+  test('CreateStream signal.reason is stream-completed after normal completion', async () => {
+    const { CreateStream } = Procedures()
+    let capturedSignal: AbortSignal | null = null
+
+    const { ReasonStream } = CreateStream('ReasonStream', {}, async function* (ctx) {
+      capturedSignal = ctx.signal
+      yield 'value'
+    })
+
+    for await (const _val of ReasonStream({}, {})) {
+      // consume
+    }
+
+    expect(capturedSignal!.reason).toBe('stream-completed')
+  })
+
+  test('CreateStream combines external signal with internal signal', async () => {
+    const { CreateStream } = Procedures<{ signal: AbortSignal }>()
+    const externalAc = new AbortController()
+    let capturedSignal: AbortSignal | null = null
+
+    const { CombinedStream } = CreateStream('CombinedStream', {}, async function* (ctx) {
+      capturedSignal = ctx.signal
+      // Combined signal is a new object, not the raw external signal
+      expect(ctx.signal).not.toBe(externalAc.signal)
+      yield 'value'
+    })
+
+    // Abort external before consuming — combined signal should reflect it
+    externalAc.abort('client-disconnected')
+
+    for await (const _val of CombinedStream({ signal: externalAc.signal }, {})) {
+      // consume
+    }
+
+    expect(capturedSignal!.aborted).toBe(true)
+    // Reason comes from external abort, not internal 'stream-completed'
+    expect(capturedSignal!.reason).toBe('client-disconnected')
+  })
+})
+
+describe('isPrevalidated context property', () => {
+  test('CreateStream skips validation when ctx.isPrevalidated is true', async () => {
+    const { CreateStream } = Procedures()
+
+    const { StreamSkipValidation } = CreateStream(
+      'StreamSkipValidation',
+      {
+        schema: {
+          params: v.object({ count: v.number().required() }),
+        },
+      },
+      async function* (ctx, params) {
+        yield { received: params }
+      }
+    )
+
+    // With isPrevalidated: true, validation is skipped even with invalid params
+    const values: any[] = []
+    for await (const val of StreamSkipValidation({ isPrevalidated: true }, {} as any)) {
+      values.push(val)
+    }
+
+    expect(values).toEqual([{ received: {} }])
+  })
+
+  test('CreateStream validates when ctx.isPrevalidated is false', async () => {
+    const { CreateStream } = Procedures()
+
+    const { StreamValidate } = CreateStream(
+      'StreamValidate',
+      {
+        schema: {
+          params: v.object({ count: v.number().required() }),
+        },
+      },
+      async function* (ctx, params) {
+        yield { received: params }
+      }
+    )
+
+    // With isPrevalidated: false, validation should run
+    try {
+      for await (const _val of StreamValidate({ isPrevalidated: false }, {} as any)) {
+        // consume
+      }
+      expect.fail('Should have thrown validation error')
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureValidationError)
+    }
+  })
+
+  test('CreateStream validates when ctx.isPrevalidated is undefined', async () => {
+    const { CreateStream } = Procedures()
+
+    const { StreamValidateUndefined } = CreateStream(
+      'StreamValidateUndefined',
+      {
+        schema: {
+          params: v.object({ value: v.string().required() }),
+        },
+      },
+      async function* (ctx, params) {
+        yield params
+      }
+    )
+
+    // Without isPrevalidated property, validation should run
+    try {
+      for await (const _val of StreamValidateUndefined({}, {} as any)) {
+        // consume
+      }
+      expect.fail('Should have thrown validation error')
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureValidationError)
+    }
+  })
+})
+
+describe('builder.config.noRuntimeValidation', () => {
+  test('CreateStream skips params validation when noRuntimeValidation is true', async () => {
+    const { CreateStream } = Procedures({ config: { noRuntimeValidation: true } })
+
+    const { StreamSkipParams } = CreateStream(
+      'StreamSkipParams',
+      {
+        schema: {
+          params: Type.Object({ count: Type.Number() }),
+        },
+      },
+      async function* (_ctx, params) {
+        yield { received: params }
+      }
+    )
+
+    const values: any[] = []
+    for await (const val of StreamSkipParams({}, {} as any)) {
+      values.push(val)
+    }
+
+    expect(values).toEqual([{ received: {} }])
+  })
+
+  // migrated to schema.req in Phase 3+ (CreateHttpStream)
+  test.todo('CreateStream skips input channel validation when noRuntimeValidation is true')
+
+  test('CreateStream still validates when noRuntimeValidation is omitted', async () => {
+    const { CreateStream } = Procedures({ config: {} })
+
+    const { StreamValidateDefault } = CreateStream(
+      'StreamValidateDefault',
+      {
+        schema: {
+          params: Type.Object({ count: Type.Number() }),
+        },
+      },
+      async function* (_ctx, params) {
+        yield params
+      }
+    )
+
+    await expect(async () => {
+      for await (const _v of StreamValidateDefault({}, {} as any)) {
+        // consume
+      }
+    }).rejects.toBeInstanceOf(ProcedureValidationError)
+  })
+})