ts-procedures 7.3.0 → 8.1.0

package/src/create-stream.ts

@@ -0,0 +1,228 @@
+import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError, ProcedureYieldValidationError } from './errors.js'
+import { computeSchema } from './schema/compute-schema.js'
+import { Prettify, TSchemaLib } from './schema/types.js'
+import { captureDefinitionInfo } from './stack-utils.js'
+import {
+  TBuilderConfig,
+  THttpProcedureRegistration,
+  THttpStreamProcedureRegistration,
+  TStreamContext,
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+} from './types.js'
+
+export type CreateStreamBuilderArg<TContext, TExtendedConfig> = {
+  config?: TBuilderConfig
+  onCreate?: (
+    procedure:
+      | TProcedureRegistration<TContext, TExtendedConfig>
+      | TStreamProcedureRegistration<TContext, TExtendedConfig>
+  ) => void
+}
+
+export function makeCreateStream<TContext, TExtendedConfig>(
+  procedures: Map<
+    string,
+    | TProcedureRegistration<TContext, TExtendedConfig>
+    | TStreamProcedureRegistration<TContext, TExtendedConfig>
+    | THttpProcedureRegistration<TContext>
+    | THttpStreamProcedureRegistration<TContext>
+  >,
+  builder?: CreateStreamBuilderArg<TContext, TExtendedConfig>
+) {
+  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: TSchemaLib<TParams>
+    ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
+  ) {
+    // Capture definition location as first action
+    const definitionInfo = captureDefinitionInfo()
+
+    const HTTP_FIELDS = ['path', 'method', 'req', 'res', 'successStatus'] as const
+    const presentHttpFields = HTTP_FIELDS.filter((f) => (config as any)[f] !== undefined)
+    if (presentHttpFields.length > 0) {
+      throw new ProcedureRegistrationError(
+        name,
+        `HTTP fields require CreateHttp / CreateHttpStream. Procedure "${name}" has [${presentHttpFields.join(', ')}] which are not valid on CreateStream.`,
+        definitionInfo,
+      )
+    }
+
+    // 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,
+      kind: 'rpc-stream',
+      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()
+
+        // Skip validation if caller has already validated (e.g., HonoAppBuilder) or if builder config dictates noRuntimeValidation
+        const skipValidation =
+          (ctx as { isPrevalidated?: boolean }).isPrevalidated ||
+          builder?.config?.noRuntimeValidation
+
+        if (validations?.params && !skipValidation) {
+          const { errors } = validations.params(params)
+
+          if (errors) {
+            throw new ProcedureValidationError(
+              name,
+              `Validation error for ${name}`,
+              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
+        )
+
+        const userIterator = userGenerator[Symbol.asyncIterator]()
+        try {
+          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. HonoAppBuilder)
+          // can send it as a special 'return' SSE event
+          return userIterResult.value
+        } catch (error: any) {
+          // Preserve the original error class so HTTP builders' taxonomies and
+          // `onMidStreamError` callbacks see the actual thrown type — boxing
+          // user-defined errors inside ProcedureError defeats route-declared
+          // typed-error dispatch on the client. Augment the stack trace in
+          // place with the procedure's definition site when available.
+          if (definitionInfo.definedAt && error && typeof error.stack === 'string') {
+            const { file, line, column } = definitionInfo.definedAt
+            error.stack = `${error.stack}\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
+          }
+          throw error
+        } finally {
+          // Propagate `.return()` to the user generator so its `finally`
+          // blocks (and any `signal`-driven cleanup) run when the consumer
+          // closes the stream early. No-op when iteration already completed.
+          try {
+            await userIterator.return?.(undefined)
+          } catch {
+            // Swallow — cleanup must not mask the primary error path
+          }
+          abortController.abort('stream-completed')
+        }
+      } as (ctx: TContext, params?: any) => AsyncGenerator<any, any, unknown>,
+    }
+
+    procedures.set(name, registeredProcedure)
+    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
+    }
+  }
+}