ts-procedures 5.7.0 → 5.7.2

package/src/client/index.ts

@@ -0,0 +1,121 @@
+import { executeCall } from './call.js'
+import { executeStream, createTypedStream } from './stream.js'
+import type {
+  CreateClientConfig,
+  ClientInstance,
+  CallDescriptor,
+  StreamDescriptor,
+  ProcedureCallOptions,
+  TypedStream,
+} from './types.js'
+
+// ── createClient ──────────────────────────────────────────
+
+/**
+ * Creates a typed client from a config object.
+ *
+ * The `scopes` callback receives a `ClientInstance` and returns the typed
+ * scope bindings (e.g., `{ users: { getUser, createUser }, posts: { ... } }`).
+ * The return value of `createClient` is the scopes object.
+ *
+ * `client.stream()` must return `TypedStream` synchronously even though
+ * `executeStream` is async. We achieve this by creating a deferred TypedStream:
+ * - A deferred async generator awaits `executeStream` internally, then forwards
+ *   yields from the inner stream.
+ * - The outer `.result` is wired up to the inner stream's `.result`.
+ */
+export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TScopes {
+  const { adapter, basePath, hooks: globalHooks = {}, scopes } = config
+
+  const instance: ClientInstance = {
+    basePath,
+    adapter,
+    hooks: globalHooks,
+
+    call<TResponse>(
+      descriptor: CallDescriptor,
+      options?: ProcedureCallOptions
+    ): Promise<TResponse> {
+      return executeCall<TResponse>(descriptor, basePath, adapter, globalHooks, options)
+    },
+
+    stream<TYield, TReturn>(
+      descriptor: StreamDescriptor,
+      options?: ProcedureCallOptions
+    ): TypedStream<TYield, TReturn> {
+      // executeStream is async but stream() must be synchronous.
+      // Create a deferred TypedStream that wraps the async executeStream call.
+
+      let resolveResult: (value: TReturn) => void
+      let rejectResult: (reason: unknown) => void
+
+      const resultPromise = new Promise<TReturn>((resolve, reject) => {
+        resolveResult = resolve
+        rejectResult = reject
+      })
+
+      // The deferred async generator: awaits executeStream, then forwards
+      async function* deferredGenerator(): AsyncGenerator<TYield> {
+        let innerStream: TypedStream<TYield, TReturn>
+        try {
+          innerStream = await executeStream<TYield, TReturn>(
+            descriptor,
+            basePath,
+            adapter,
+            globalHooks,
+            options
+          )
+        } catch (err) {
+          rejectResult(err)
+          throw err
+        }
+
+        // Wire up .result from the inner stream
+        innerStream.result.then(resolveResult, rejectResult)
+
+        for await (const item of innerStream) {
+          yield item
+        }
+      }
+
+      const iterator = deferredGenerator()
+
+      return {
+        [Symbol.asyncIterator]() {
+          return iterator
+        },
+        result: resultPromise,
+      }
+    },
+  }
+
+  return scopes(instance)
+}
+
+// ── Barrel exports ────────────────────────────────────────
+
+export type {
+  ClientAdapter,
+  AdapterRequest,
+  AdapterResponse,
+  AdapterStreamResponse,
+  ClientHooks,
+  BeforeRequestContext,
+  AfterResponseContext,
+  ErrorContext,
+  CallDescriptor,
+  StreamDescriptor,
+  TypedStream,
+  ClientInstance,
+  ProcedureCallOptions,
+  CreateClientConfig,
+} from './types.js'
+
+export { ClientRequestError, ClientPathParamError, ClientStreamError } from './errors.js'
+
+export { createTypedStream } from './stream.js'
+export { executeCall } from './call.js'
+export { executeStream } from './stream.js'
+
+export { createFetchAdapter } from './fetch-adapter.js'
+export type { FetchAdapterConfig } from './fetch-adapter.js'

package/src/client/request-builder.ts

@@ -0,0 +1,73 @@
+import { ClientPathParamError } from './errors.js'
+import type { AdapterRequest, CallDescriptor } from './types.js'
+
+/**
+ * Replaces `:paramName` segments in `path` with URI-encoded values from `params`.
+ * Throws `ClientPathParamError` if a required segment is missing from `params`.
+ */
+export function interpolatePath(
+  path: string,
+  params: Record<string, unknown>,
+  procedureName: string
+): string {
+  return path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_match, key: string) => {
+    const value = params[key]
+    if (value === undefined || value === null) {
+      throw new ClientPathParamError(key, path, procedureName)
+    }
+    return encodeURIComponent(String(value))
+  })
+}
+
+/**
+ * Builds an `AdapterRequest` from a `CallDescriptor` and a base URL.
+ *
+ * - `kind === 'rpc'` or `kind === 'stream'`: params are flat — sent as the JSON body.
+ * - `kind === 'api'`: params are structured channels — `pathParams`, `query`, `body`, `headers`.
+ */
+export function buildAdapterRequest(descriptor: CallDescriptor, basePath: string): AdapterRequest {
+  const { name, path, method, kind, params } = descriptor
+
+  if (kind === 'rpc' || kind === 'stream') {
+    return {
+      url: `${basePath}${path}`,
+      method,
+      body: params,
+    }
+  }
+
+  // kind === 'api' — params are structured channels
+  const structured = (params ?? {}) as {
+    pathParams?: Record<string, unknown>
+    query?: Record<string, unknown>
+    body?: unknown
+    headers?: Record<string, string>
+  }
+
+  // Interpolate path params
+  const interpolatedPath = structured.pathParams
+    ? interpolatePath(path, structured.pathParams, name)
+    : path
+
+  // Build query string
+  let url = `${basePath}${interpolatedPath}`
+  if (structured.query && Object.keys(structured.query).length > 0) {
+    const searchParams = new URLSearchParams(
+      Object.entries(structured.query).map(([k, v]) => [k, String(v)])
+    )
+    url = `${url}?${searchParams.toString()}`
+  }
+
+  // Build headers
+  const headers =
+    structured.headers && Object.keys(structured.headers).length > 0
+      ? structured.headers
+      : undefined
+
+  return {
+    url,
+    method,
+    headers,
+    body: structured.body,
+  }
+}

package/src/client/stream.ts

@@ -0,0 +1,164 @@
+import { buildAdapterRequest } from './request-builder.js'
+import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
+import { ClientRequestError } from './errors.js'
+import type {
+  ClientAdapter,
+  ClientHooks,
+  StreamDescriptor,
+  TypedStream,
+  AdapterResponse,
+} from './types.js'
+
+// ── SSE item shape ────────────────────────────────────────
+
+interface SSEItem {
+  data: unknown
+  event?: string
+  id?: string
+}
+
+// ── createTypedStream ─────────────────────────────────────
+
+/**
+ * Wraps an AsyncIterable into a TypedStream.
+ *
+ * SSE mode: each item is `{ data, event?, id? }`.
+ *   - If `event === 'return'`, the data resolves `.result` and is NOT yielded.
+ *   - Otherwise, `data` is yielded.
+ *
+ * Text mode: each item is yielded as-is.
+ *   - `.result` resolves to `void` on completion.
+ *
+ * On error: `.result` rejects and the error is re-thrown from the async iterator.
+ */
+export function createTypedStream<TYield, TReturn = void>(
+  source: AsyncIterable<unknown>,
+  streamMode: 'sse' | 'text'
+): TypedStream<TYield, TReturn> {
+  let resolveResult: (value: TReturn) => void
+  let rejectResult: (reason: unknown) => void
+
+  const resultPromise = new Promise<TReturn>((resolve, reject) => {
+    resolveResult = resolve
+    rejectResult = reject
+  })
+
+  async function* generate(): AsyncGenerator<TYield> {
+    try {
+      if (streamMode === 'sse') {
+        let returnValue: TReturn | undefined
+        let hasReturn = false
+
+        for await (const item of source) {
+          const sseItem = item as SSEItem
+          if (sseItem.event === 'return') {
+            returnValue = sseItem.data as TReturn
+            hasReturn = true
+          } else {
+            yield sseItem.data as TYield
+          }
+        }
+
+        // Resolve result after iteration completes
+        if (hasReturn) {
+          resolveResult(returnValue as TReturn)
+        } else {
+          resolveResult(undefined as TReturn)
+        }
+      } else {
+        // text mode: yield each item as-is
+        for await (const item of source) {
+          yield item as TYield
+        }
+        resolveResult(undefined as TReturn)
+      }
+    } catch (err) {
+      rejectResult(err)
+      throw err
+    }
+  }
+
+  const iterator = generate()
+
+  return {
+    [Symbol.asyncIterator]() {
+      return iterator
+    },
+    result: resultPromise,
+  }
+}
+
+// ── executeStream ─────────────────────────────────────────
+
+/**
+ * Executes a streaming procedure call through the adapter.
+ *
+ * Flow:
+ * 1. Build AdapterRequest from descriptor
+ * 2. Run onBeforeRequest hooks
+ * 3. Call adapter.stream()
+ * 4. On adapter error: run onError hooks, re-throw
+ * 5. Run onAfterResponse immediately (before iteration), body is null
+ * 6. If non-2xx: throw ClientRequestError
+ * 7. Return createTypedStream(streamResponse.body, descriptor.streamMode)
+ */
+export async function executeStream<TYield, TReturn = void>(
+  descriptor: StreamDescriptor,
+  basePath: string,
+  adapter: ClientAdapter,
+  globalHooks: ClientHooks,
+  localHooks: ClientHooks | undefined
+): Promise<TypedStream<TYield, TReturn>> {
+  // 1. Build the initial request
+  let request = buildAdapterRequest(descriptor, basePath)
+
+  // 2. Run before-request hooks
+  const beforeCtx = await runBeforeRequest(
+    { procedureName: descriptor.name, scope: descriptor.scope, request },
+    globalHooks,
+    localHooks
+  )
+  request = beforeCtx.request
+
+  // 3. Call the adapter
+  let streamResponse
+  try {
+    streamResponse = await adapter.stream(request)
+  } catch (err) {
+    // 4. On adapter error: run error hooks, re-throw
+    await runOnError(
+      { procedureName: descriptor.name, scope: descriptor.scope, request, error: err },
+      globalHooks,
+      localHooks
+    )
+    throw err
+  }
+
+  // Build an AdapterResponse shape for the hooks (body is null for streams at this point)
+  const responseForHooks: AdapterResponse = {
+    status: streamResponse.status,
+    headers: streamResponse.headers,
+    body: null,
+  }
+
+  // 5. Run after-response hooks immediately (before iteration)
+  await runAfterResponse(
+    { procedureName: descriptor.name, scope: descriptor.scope, request, response: responseForHooks },
+    globalHooks,
+    localHooks
+  )
+
+  // 6. Check status after hooks (hooks may mutate responseForHooks.status)
+  if (responseForHooks.status < 200 || responseForHooks.status >= 300) {
+    throw new ClientRequestError({
+      status: responseForHooks.status,
+      headers: responseForHooks.headers,
+      body: responseForHooks.body,
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+    })
+  }
+
+  // 7. Return the typed stream
+  return createTypedStream<TYield, TReturn>(streamResponse.body, descriptor.streamMode)
+}

package/src/client/types.ts

@@ -0,0 +1,103 @@
+// ── Adapter ──────────────────────────────────────────────
+
+export interface ClientAdapter {
+  request(config: AdapterRequest): Promise<AdapterResponse>
+  stream(config: AdapterRequest): Promise<AdapterStreamResponse>
+}
+
+export interface AdapterRequest {
+  url: string
+  method: string
+  headers?: Record<string, string>
+  body?: unknown
+  signal?: AbortSignal
+}
+
+export interface AdapterResponse {
+  status: number
+  headers: Record<string, string>
+  body: unknown
+}
+
+export interface AdapterStreamResponse {
+  status: number
+  headers: Record<string, string>
+  body: AsyncIterable<unknown>
+}
+
+// ── Hooks ────────────────────────────────────────────────
+
+export interface ClientHooks {
+  onBeforeRequest?(context: BeforeRequestContext): BeforeRequestContext | Promise<BeforeRequestContext>
+  onAfterResponse?(context: AfterResponseContext): void | Promise<void>
+  onError?(context: ErrorContext): void | Promise<void>
+}
+
+export interface BeforeRequestContext {
+  procedureName: string
+  scope: string
+  request: AdapterRequest
+}
+
+export interface AfterResponseContext {
+  procedureName: string
+  scope: string
+  request: AdapterRequest
+  response: AdapterResponse
+}
+
+export interface ErrorContext {
+  procedureName: string
+  scope: string
+  request: AdapterRequest
+  error: unknown
+}
+
+// ── Descriptors ──────────────────────────────────────────
+
+export interface CallDescriptor {
+  name: string
+  scope: string
+  path: string
+  method: string
+  kind: 'rpc' | 'api' | 'stream'
+  params: unknown
+}
+
+export interface StreamDescriptor extends CallDescriptor {
+  kind: 'stream'
+  streamMode: 'sse' | 'text'
+}
+
+// ── TypedStream ──────────────────────────────────────────
+
+export interface TypedStream<TYield, TReturn = void> extends AsyncIterable<TYield> {
+  /**
+   * Resolves when the stream completes with the final return value.
+   * Rejects if the stream errors before completing.
+   * Note: iteration must begin (via for-await) for this promise to settle,
+   * since resolution depends on the async generator running to completion.
+   */
+  result: Promise<TReturn>
+}
+
+// ── Client Instance ──────────────────────────────────────
+
+export type ProcedureCallOptions = ClientHooks
+
+export interface ClientInstance {
+  basePath: string
+  adapter: ClientAdapter
+  hooks: ClientHooks
+  call<TResponse>(descriptor: CallDescriptor, options?: ProcedureCallOptions): Promise<TResponse>
+  stream<TYield, TReturn>(descriptor: StreamDescriptor, options?: ProcedureCallOptions): TypedStream<TYield, TReturn>
+}
+
+// ── createClient Config ──────────────────────────────────
+
+export interface CreateClientConfig<TScopes> {
+  adapter: ClientAdapter
+  basePath: string
+  scopes: (client: ClientInstance) => TScopes
+  hooks?: ClientHooks
+}