ts-procedures 8.5.0 → 9.0.0

package/src/{create-stream.test.ts → core/create-stream.test.ts}

@@ -1,21 +1,23 @@
- 
-import { describe, expect, it, test } from 'vitest'
-import { Procedures } from './index.js'
-import { v } from 'suretype'
+import { describe, expect, test } from 'vitest'
+import { Procedures } from './procedures.js'
 import { Type } from 'typebox'
-import { ProcedureError, ProcedureValidationError } from './errors.js'
+import {
+  ProcedureError,
+  ProcedureValidationError,
+  ProcedureYieldValidationError,
+} from './errors.js'
 
 describe('Streaming Procedures - CreateStream', () => {
   test('CreateStream creates a streaming procedure', async () => {
-    const { CreateStream } = Procedures()
+    const procs = Procedures()
 
-    const { StreamTest, procedure, info } = CreateStream(
+    const { StreamTest, procedure, info } = procs.CreateStream(
       'StreamTest',
       {
         description: 'Test streaming procedure',
         schema: {
-          params: v.object({ count: v.number().required() }),
-          yieldType: v.object({ value: v.number().required() }),
+          params: Type.Object({ count: Type.Number() }),
+          yieldType: Type.Object({ value: Type.Number() }),
         },
       },
       async function* (ctx, params) {
@@ -27,7 +29,7 @@ describe('Streaming Procedures - CreateStream', () => {
 
     expect(StreamTest).toBeDefined()
     expect(procedure).toBeDefined()
-    expect(info.isStream).toBe(true)
+    expect(procs.getProcedure('StreamTest')?.kind).toBe('rpc-stream')
     expect(info.name).toBe('StreamTest')
     expect(info.description).toBe('Test streaming procedure')
     expect(info.schema.params).toEqual({
@@ -57,8 +59,8 @@ describe('Streaming Procedures - CreateStream', () => {
       'StreamWithParams',
       {
         schema: {
-          params: v.object({ name: v.string().required() }),
-          yieldType: v.string(),
+          params: Type.Object({ name: Type.String() }),
+          yieldType: Type.String(),
         },
       },
       async function* (ctx, params) {
@@ -81,13 +83,12 @@ describe('Streaming Procedures - CreateStream', () => {
 
   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() }),
+          yieldType: Type.Object({ id: Type.Number() }),
         },
         validateYields: true,
       },
@@ -117,7 +118,7 @@ describe('Streaming Procedures - CreateStream', () => {
       'StreamNoValidate',
       {
         schema: {
-          yieldType: v.object({ id: v.number().required() }),
+          yieldType: Type.Object({ id: Type.Number() }),
         },
         // validateYields defaults to false
       },
@@ -176,7 +177,7 @@ describe('Streaming Procedures - CreateStream', () => {
     expect(signalReceived).toBe(true)
   })
 
-  test('CreateStream onCreate callback receives isStream flag', () =>
+  test('CreateStream onCreate callback receives kind: rpc-stream', () =>
     new Promise<void>((done) => {
       let receivedProc: any
 
@@ -191,7 +192,7 @@ describe('Streaming Procedures - CreateStream', () => {
       })
 
       expect(receivedProc).toBeDefined()
-      expect(receivedProc.isStream).toBe(true)
+      expect(receivedProc.kind).toBe('rpc-stream')
       expect(receivedProc.name).toBe('OnCreateStream')
       done()
     }))
@@ -217,7 +218,7 @@ describe('Streaming Procedures - CreateStream', () => {
       'StreamErrorLocation',
       {
         schema: {
-          params: v.object({ id: v.number().required() }),
+          params: Type.Object({ id: Type.Number() }),
         },
       },
       async function* () {
@@ -294,7 +295,7 @@ describe('Streaming Procedures - CreateStream', () => {
     // user's class). Stack annotation is added in place; class identity and
     // custom properties are preserved.
     class MyDomainError extends Error {
-      readonly name = 'MyDomainError'
+      override readonly name = 'MyDomainError'
       readonly code = 'STREAM_FAIL'
     }
 
@@ -373,7 +374,6 @@ describe('Streaming Procedures - CreateStream', () => {
     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 () => {
@@ -444,7 +444,7 @@ describe('isPrevalidated context property', () => {
       'StreamSkipValidation',
       {
         schema: {
-          params: v.object({ count: v.number().required() }),
+          params: Type.Object({ count: Type.Number() }),
         },
       },
       async function* (ctx, params) {
@@ -468,7 +468,7 @@ describe('isPrevalidated context property', () => {
       'StreamValidate',
       {
         schema: {
-          params: v.object({ count: v.number().required() }),
+          params: Type.Object({ count: Type.Number() }),
         },
       },
       async function* (ctx, params) {
@@ -494,7 +494,7 @@ describe('isPrevalidated context property', () => {
       'StreamValidateUndefined',
       {
         schema: {
-          params: v.object({ value: v.string().required() }),
+          params: Type.Object({ value: Type.String() }),
         },
       },
       async function* (ctx, params) {
@@ -514,9 +514,9 @@ describe('isPrevalidated context property', () => {
   })
 })
 
-describe('builder.config.noRuntimeValidation', () => {
-  test('CreateStream skips params validation when noRuntimeValidation is true', async () => {
-    const { CreateStream } = Procedures({ config: { noRuntimeValidation: true } })
+describe('Procedures({ validation: false })', () => {
+  test('CreateStream skips params validation when validation is false', async () => {
+    const { CreateStream } = Procedures({ validation: false })
 
     const { StreamSkipParams } = CreateStream(
       'StreamSkipParams',
@@ -538,11 +538,8 @@ describe('builder.config.noRuntimeValidation', () => {
     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: {} })
+  test('CreateStream still validates when validation is omitted', async () => {
+    const { CreateStream } = Procedures({})
 
     const { StreamValidateDefault } = CreateStream(
       'StreamValidateDefault',

package/src/core/create-stream.ts

@@ -0,0 +1,142 @@
+import { ProcedureError } from './errors.js'
+import { computeSchema } from '../schema/compute-schema.js'
+import type { Infer, Prettify } from '../schema/json-schema.js'
+import { captureDefinitionInfo } from './definition-site.js'
+import {
+  assertNoHttpFields,
+  assertNotDuplicate,
+  combineSignals,
+  iterateWithGuards,
+  shouldSkipValidation,
+  validateParams,
+} from './internal.js'
+import type { FactoryRuntime } from './internal.js'
+import type { ProcedureResult, TStreamContext, TStreamProcedureRegistration } from './types.js'
+import type { Validate } from '../schema/compile.js'
+
+export function makeCreateStream<TContext, TExtendedConfig>(runtime: FactoryRuntime<TContext, TExtendedConfig>) {
+  /**
+   * Defines a streaming RPC procedure (async generator).
+   *
+   * - `ctx.signal` is ALWAYS present: it aborts on client disconnect, and with
+   *   reason `'stream-completed'` on normal completion.
+   * - Yields are validated only with `validateYields: true` + a `yieldType`
+   *   schema.
+   * - The generator's return value propagates to consumers (it becomes the
+   *   `event: 'return'` SSE payload over HTTP).
+   */
+  return 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: Infer<TParams>,
+    ) => AsyncGenerator<Infer<TYieldType>, Infer<TReturnType> | void, unknown>,
+  ) {
+    // Capture definition location as first action
+    const definitionInfo = captureDefinitionInfo()
+
+    assertNoHttpFields('CreateStream', name, config as Record<string, unknown>, definitionInfo)
+    assertNotDuplicate(runtime.registry, name, definitionInfo)
+
+    const { jsonSchema, validations } = computeSchema(name, config.schema, {
+      adapters: runtime.adapters,
+      compile: runtime.compile,
+      definitionInfo,
+    })
+
+    // Create error factory once at registration time (outside handler)
+    const errorFactory = (message: string, meta?: object) =>
+      new ProcedureError(name, message, meta, definitionInfo)
+
+    const validateYields = config.validateYields ?? false
+
+    const registeredProcedure: TStreamProcedureRegistration<TContext, TExtendedConfig> = {
+      name,
+      kind: 'rpc-stream',
+      config: {
+        ...config,
+        description: config.description,
+        schema: jsonSchema,
+        validation: {
+          params: validations.params,
+          yield: validations.yield,
+        },
+      },
+
+      handler: async function* wrappedHandler(ctx: Prettify<TContext>, params: Infer<TParams>) {
+        // Per-stream controller: aborts on completion ('stream-completed') so
+        // handlers can distinguish completion from client disconnect
+        const abortController = new AbortController()
+
+        if (!shouldSkipValidation(ctx, runtime)) {
+          validateParams(name, validations.params, params, definitionInfo)
+        }
+
+        const incomingSignal = (ctx as { signal?: AbortSignal }).signal
+        const streamCtx: TStreamContext = {
+          error: errorFactory,
+          signal: combineSignals(incomingSignal, abortController.signal),
+        }
+
+        // params is correctly typed at the public API boundary via conditional
+        // type; cast here because TS cannot narrow generics inside implementations
+        const userGenerator = handler(
+          { ...ctx, ...streamCtx } as Prettify<TContext & TStreamContext>,
+          params as any,
+        )
+
+        return yield* iterateWithGuards(userGenerator[Symbol.asyncIterator](), {
+          name,
+          validateYields,
+          validateYield: validations.yield,
+          abortController,
+          definitionInfo,
+        })
+      } as (ctx: TContext, params?: any) => AsyncGenerator<any, any, unknown>,
+    }
+
+    runtime.registry.set(name, registeredProcedure)
+    runtime.onCreate?.(registeredProcedure)
+
+    const info = {
+      name,
+      kind: 'rpc-stream' as const,
+      ...registeredProcedure.config,
+    }
+
+    type Handler = (
+      ctx: Prettify<TContext>,
+      params: Infer<TParams>,
+    ) => AsyncGenerator<Infer<TYieldType>, Infer<TReturnType> | void, unknown>
+    type Info = {
+      name: TName
+      kind: 'rpc-stream'
+      description?: string
+      schema: {
+        params?: TParams
+        yieldType?: TYieldType
+        returnType?: TReturnType
+      }
+      validation?: {
+        params?: Validate
+        yield?: Validate
+      }
+    } & TExtendedConfig
+
+    // return so the procedure can be called directly (e.g. unit tests)
+    return {
+      [name]: registeredProcedure.handler,
+      procedure: registeredProcedure.handler,
+      info,
+    } as ProcedureResult<TName, Handler, Info>
+  }
+}

package/src/{create.test.ts → core/create.test.ts}

@@ -1,7 +1,5 @@
- 
-import { describe, expect, it, test } from 'vitest'
-import { Procedures } from './index.js'
-import { v } from 'suretype'
+import { describe, expect, test } from 'vitest'
+import { Procedures } from './procedures.js'
 import { Type } from 'typebox'
 import { ProcedureError, ProcedureValidationError } from './errors.js'
 
@@ -48,40 +46,12 @@ describe('Procedures', () => {
     expect(info2).toBeDefined()
   })
 
-  test('Procedures - Create call', () =>
-    new Promise<void>((done) => {
-      let mockHttpCall: any
-
-      const { Create } = Procedures({
-        onCreate: ({ handler }) => {
-          mockHttpCall = handler
-        },
-      })
-
-      Create(
-        'Handler',
-        {
-          schema: {
-            params: v.object({ name: v.string() }),
-            returnType: v.string(),
-          },
-        },
-        async (ctx, params) => {
-          expect(params).toEqual({ name: 'name' })
-          done()
-          return 'name'
-        }
-      )
-
-      mockHttpCall({}, { name: 'name' })
-    }))
-
   test('Procedures - Create call w/ Typebox', () =>
     new Promise<void>((done) => {
       let mockHttpCall: any
 
       const { Create } = Procedures({
-        onCreate: ({ handler, config, name }) => {
+        onCreate: ({ handler }) => {
           mockHttpCall = handler
         },
       })
@@ -118,7 +88,7 @@ describe('Procedures', () => {
       {
         description: 'Handler description',
         schema: {
-          params: v.object({ number: v.number() }),
+          params: Type.Object({ number: Type.Number() }),
         },
       },
       async (ctx, params) => {
@@ -143,6 +113,7 @@ describe('Procedures', () => {
     expect(info.schema.params).toEqual({
       type: 'object',
       properties: { number: { type: 'number' } },
+      required: ['number'],
     })
     expect(info).toHaveProperty('description')
     expect(info.description).toEqual('Handler description')
@@ -153,7 +124,7 @@ describe('Procedures', () => {
       let mockHttpCall: any
 
       const { Create } = Procedures({
-        onCreate: ({ handler, config, name }) => {
+        onCreate: ({ handler, config }) => {
           mockHttpCall = (callParams: any) => {
             const validation = (config as any).validation
             if (validation?.params) {
@@ -175,7 +146,7 @@ describe('Procedures', () => {
         'test',
         {
           schema: {
-            params: v.object({}),
+            params: Type.Object({}),
           },
         },
         async () => {
@@ -191,7 +162,7 @@ describe('Procedures', () => {
       let mockHttpCall: any
 
       const { Create } = Procedures({
-        onCreate: async ({ handler, config, name }) => {
+        onCreate: ({ handler, config }) => {
           mockHttpCall = async (callParams: any) => {
             const validation = (config as any).validation
             if (validation?.params) {
@@ -215,10 +186,10 @@ describe('Procedures', () => {
         'test',
         {
           schema: {
-            params: v.object({
-              name: v.string().required(),
-              id: v.number().required(),
-              email: v.string(),
+            params: Type.Object({
+              name: Type.String(),
+              id: Type.Number(),
+              email: Type.Optional(Type.String()),
             }),
           },
         },
@@ -242,7 +213,7 @@ describe('Procedures', () => {
         },
       })
 
-      Create('test', {}, async (ctx, params) => {
+      Create('test', {}, async (ctx) => {
         expect(ctx.testCtx).toEqual('testCtx')
         done()
       })
@@ -282,7 +253,7 @@ describe('Procedures', () => {
       'CheckIsAuthenticated',
       {
         schema: {
-          returnType: v.string(),
+          returnType: Type.String(),
         },
       },
       async (ctx) => {
@@ -401,7 +372,7 @@ describe('Procedures - Definition Location in Errors', () => {
       'TestValidation',
       {
         schema: {
-          params: v.object({ name: v.string().required() }),
+          params: Type.Object({ name: Type.String() }),
         },
       },
       async (ctx, params) => {
@@ -466,7 +437,7 @@ describe('Procedures - Definition Location in Errors', () => {
       'TestGetLocation',
       {
         schema: {
-          params: v.object({ id: v.number().required() }),
+          params: Type.Object({ id: Type.Number() }),
         },
       },
       async (ctx, params) => {
@@ -491,7 +462,7 @@ describe('Procedures - Definition Location in Errors', () => {
       'TestStackFormat',
       {
         schema: {
-          params: v.object({ value: v.string().required() }),
+          params: Type.Object({ value: Type.String() }),
         },
       },
       async (ctx, params) => {
@@ -527,7 +498,7 @@ describe('isPrevalidated context property', () => {
       'SkipValidation',
       {
         schema: {
-          params: v.object({ name: v.string().required() }),
+          params: Type.Object({ name: Type.String() }),
         },
       },
       async (ctx, params) => {
@@ -548,7 +519,7 @@ describe('isPrevalidated context property', () => {
       'ValidateParams',
       {
         schema: {
-          params: v.object({ name: v.string().required() }),
+          params: Type.Object({ name: Type.String() }),
         },
       },
       async (ctx, params) => {
@@ -572,7 +543,7 @@ describe('isPrevalidated context property', () => {
       'ValidateUndefined',
       {
         schema: {
-          params: v.object({ id: v.number().required() }),
+          params: Type.Object({ id: Type.Number() }),
         },
       },
       async (ctx, params) => {
@@ -600,9 +571,9 @@ describe('isPrevalidated context property', () => {
   })
 })
 
-describe('builder.config.noRuntimeValidation', () => {
-  test('Create skips params validation when noRuntimeValidation is true', async () => {
-    const { Create } = Procedures({ config: { noRuntimeValidation: true } })
+describe('Procedures({ validation: false })', () => {
+  test('Create skips params validation when validation is false', async () => {
+    const { Create } = Procedures({ validation: false })
 
     const { SkipParams } = Create(
       'SkipParams',
@@ -619,11 +590,8 @@ describe('builder.config.noRuntimeValidation', () => {
     expect(result).toEqual({})
   })
 
-  // migrated to schema.req in Phase 3+
-  test.todo('Create skips input channel validation when noRuntimeValidation is true')
-
-  test('Create still validates when noRuntimeValidation is omitted', async () => {
-    const { Create } = Procedures({ config: {} })
+  test('Create still validates when validation is omitted', async () => {
+    const { Create } = Procedures({})
 
     const { ValidateDefault } = Create(
       'ValidateDefault',

package/src/core/create.ts

@@ -0,0 +1,121 @@
+import { ProcedureError } from './errors.js'
+import { computeSchema } from '../schema/compute-schema.js'
+import type { Infer, Prettify } from '../schema/json-schema.js'
+import { captureDefinitionInfo } from './definition-site.js'
+import {
+  assertNoHttpFields,
+  assertNotDuplicate,
+  shouldSkipValidation,
+  toProcedureError,
+  validateParams,
+} from './internal.js'
+import type { FactoryRuntime } from './internal.js'
+import type { ProcedureResult, TLocalContext, TProcedureRegistration } from './types.js'
+import type { Validate } from '../schema/compile.js'
+
+export function makeCreate<TContext, TExtendedConfig>(runtime: FactoryRuntime<TContext, TExtendedConfig>) {
+  /**
+   * Defines a unary RPC procedure.
+   *
+   * - `schema.params` is validated at runtime; `schema.returnType` is
+   *   documentation/codegen only.
+   * - The handler receives `(ctx, params)` where ctx adds `error()` and an
+   *   optional `signal` on top of the factory context.
+   * - Returns `{ [name]: handler, procedure: handler, info }` so the procedure
+   *   is directly callable in tests and introspectable via `info`.
+   */
+  return function Create<TName extends string, TParams, TReturnType>(
+    name: TName,
+    config: {
+      description?: string
+      schema?: {
+        params?: TParams
+        returnType?: TReturnType
+      }
+    } & TExtendedConfig,
+    handler: (
+      ctx: Prettify<TContext & TLocalContext>,
+      params: Infer<TParams>,
+    ) => Promise<Infer<TReturnType>>,
+  ) {
+    // Capture definition location as first action
+    const definitionInfo = captureDefinitionInfo()
+
+    assertNoHttpFields('Create', name, config as Record<string, unknown>, definitionInfo)
+    assertNotDuplicate(runtime.registry, name, definitionInfo)
+
+    const { jsonSchema, validations } = computeSchema(name, config.schema, {
+      adapters: runtime.adapters,
+      compile: runtime.compile,
+      definitionInfo,
+    })
+
+    // Create error factory once at registration time (outside handler)
+    const errorFactory = (message: string, meta?: object) =>
+      new ProcedureError(name, message, meta, definitionInfo)
+
+    const registeredProcedure: TProcedureRegistration<TContext, TExtendedConfig> = {
+      name,
+      kind: 'rpc',
+      config: {
+        ...config,
+        description: config.description,
+        schema: jsonSchema,
+        validation: {
+          params: validations.params,
+        },
+      },
+
+      handler: async (ctx: Prettify<TContext>, params: Infer<TParams>) => {
+        try {
+          if (!shouldSkipValidation(ctx, runtime)) {
+            validateParams(name, validations.params, params, definitionInfo)
+          }
+
+          const localCtx: TLocalContext = {
+            error: errorFactory,
+          }
+
+          // params is correctly typed at the public API boundary;
+          // cast here because TS cannot narrow generics inside implementations
+          return await handler(
+            { ...ctx, ...localCtx } as Prettify<TContext & TLocalContext>,
+            params as any,
+          )
+        } catch (error: any) {
+          throw toProcedureError(name, definitionInfo, error)
+        }
+      },
+    }
+
+    runtime.registry.set(name, registeredProcedure)
+    runtime.onCreate?.(registeredProcedure)
+
+    const info = {
+      name,
+      kind: 'rpc' as const,
+      ...registeredProcedure.config,
+    }
+
+    type Handler = (ctx: Prettify<TContext>, params: Infer<TParams>) => Promise<Infer<TReturnType>>
+    type Info = {
+      name: TName
+      kind: 'rpc'
+      description?: string
+      schema: {
+        params?: TParams
+        returnType?: TReturnType
+      }
+      validation?: {
+        params?: Validate
+      }
+    } & TExtendedConfig
+
+    // return so the procedure can be called directly (e.g. unit tests)
+    return {
+      [name]: registeredProcedure.handler,
+      procedure: registeredProcedure.handler,
+      info,
+    } as ProcedureResult<TName, Handler, Info>
+  }
+}

package/src/{stack-utils.test.ts → core/definition-site.test.ts}

@@ -1,8 +1,8 @@
 import { describe, expect, test } from 'vitest'
-import type { DefinitionInfo } from './stack-utils.js';
-import { captureDefinitionInfo, formatDefinitionInfo } from './stack-utils.js'
+import type { DefinitionInfo } from './definition-site.js'
+import { captureDefinitionInfo, formatDefinitionInfo } from './definition-site.js'
 
-describe('Stack Utils', () => {
+describe('Definition Site', () => {
   describe('captureDefinitionInfo', () => {
     test('returns definition info with definedAt', () => {
       const info = captureDefinitionInfo()
@@ -91,5 +91,16 @@ describe('Stack Utils', () => {
       expect(info).toBeDefined()
       expect(info.definitionStack).toBeDefined()
     })
+
+    test('skips v9 library-internal frames, not this test file', () => {
+      // v9's internal-file list covers procedures.ts / internal.ts / compile.ts
+      // (etc.) — but must never swallow user/test frames whose names merely
+      // resemble internal files (e.g. this `definition-site.test.ts` file is
+      // NOT matched by the `/definition-site.ts` entry).
+      const info = captureDefinitionInfo()
+
+      expect(info.definedAt).toBeDefined()
+      expect(info.definedAt?.file).toContain('definition-site.test.ts')
+    })
   })
 })