ts-procedures 5.7.0 → 5.7.1

package/src/client/fetch-adapter.ts

@@ -0,0 +1,191 @@
+import type { ClientAdapter, AdapterRequest, AdapterResponse, AdapterStreamResponse } from './types.js'
+
+// ── Config ────────────────────────────────────────────────
+
+export interface FetchAdapterConfig {
+  headers?: Record<string, string>
+}
+
+// ── SSE parser ────────────────────────────────────────────
+
+interface SSEEvent {
+  data: unknown
+  event?: string
+  id?: string
+}
+
+/**
+ * Parses an SSE message block (the text between double-newlines).
+ * Returns null if there is no data field (e.g., comment-only blocks).
+ */
+function parseSSEBlock(block: string): SSEEvent | null {
+  const lines = block.split('\n')
+  let event: string | undefined
+  let id: string | undefined
+  const dataParts: string[] = []
+
+  for (const line of lines) {
+    if (line.startsWith('event:')) {
+      event = line.slice('event:'.length).trim()
+    } else if (line.startsWith('data:')) {
+      dataParts.push(line.slice('data:'.length).trimStart())
+    } else if (line.startsWith('id:')) {
+      id = line.slice('id:'.length).trim()
+    }
+    // Lines starting with ':' are comments — skip them
+  }
+
+  if (dataParts.length === 0) {
+    return null
+  }
+
+  const dataStr = dataParts.join('\n')
+  let data: unknown
+  try {
+    data = JSON.parse(dataStr)
+  } catch {
+    data = dataStr
+  }
+
+  return { data, event, id }
+}
+
+/**
+ * Async generator that reads a ReadableStream<Uint8Array>, buffers text,
+ * splits on double-newline SSE boundaries, and yields parsed SSE events.
+ */
+async function* parseSseStream(
+  readableStream: ReadableStream<Uint8Array>
+): AsyncGenerator<SSEEvent> {
+  const reader = readableStream.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+
+      if (value) {
+        buffer += decoder.decode(value, { stream: !done })
+      }
+
+      // Process all complete SSE message blocks (split on \n\n)
+      let boundary: number
+      while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+        const block = buffer.slice(0, boundary).trim()
+        buffer = buffer.slice(boundary + 2)
+
+        if (block.length > 0) {
+          const event = parseSSEBlock(block)
+          if (event !== null) {
+            yield event
+          }
+        }
+      }
+
+      if (done) break
+    }
+
+    // Handle any remaining buffer content (no trailing \n\n)
+    const remaining = buffer.trim()
+    if (remaining.length > 0) {
+      const event = parseSSEBlock(remaining)
+      if (event !== null) {
+        yield event
+      }
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+// ── Adapter ───────────────────────────────────────────────
+
+/**
+ * Extracts response headers as a plain Record<string, string>.
+ */
+function extractHeaders(response: Response): Record<string, string> {
+  const headers: Record<string, string> = {}
+  response.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+  return headers
+}
+
+/**
+ * Attempts to parse the response body as JSON, then as text, then returns null.
+ */
+async function parseResponseBody(response: Response): Promise<unknown> {
+  // Clone so we can attempt multiple reads
+  const clone = response.clone()
+  try {
+    return await clone.json()
+  } catch {
+    try {
+      const text = await response.text()
+      return text || null
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * Creates a fetch-based ClientAdapter.
+ *
+ * - `config.headers` are default headers applied to every request.
+ * - Per-request headers override config headers (spread order).
+ * - Works in Node.js 18+ and browsers (uses standard fetch + ReadableStream).
+ */
+export function createFetchAdapter(config?: FetchAdapterConfig): ClientAdapter {
+  const configHeaders = config?.headers ?? {}
+
+  return {
+    async request(req: AdapterRequest): Promise<AdapterResponse> {
+      const mergedHeaders: Record<string, string> = {
+        ...configHeaders,
+        ...(req.headers ?? {}),
+      }
+
+      const response = await fetch(req.url, {
+        method: req.method,
+        headers: mergedHeaders,
+        body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
+        signal: req.signal,
+      })
+
+      const headers = extractHeaders(response)
+      const body = await parseResponseBody(response)
+
+      return { status: response.status, headers, body }
+    },
+
+    async stream(req: AdapterRequest): Promise<AdapterStreamResponse> {
+      const mergedHeaders: Record<string, string> = {
+        ...configHeaders,
+        ...(req.headers ?? {}),
+      }
+
+      const response = await fetch(req.url, {
+        method: req.method,
+        headers: mergedHeaders,
+        body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
+        signal: req.signal,
+      })
+
+      const headers = extractHeaders(response)
+
+      if (!response.body) {
+        // No body — return an empty async iterable
+        const emptyBody: AsyncIterable<unknown> = {
+          [Symbol.asyncIterator]: async function* () {},
+        }
+        return { status: response.status, headers, body: emptyBody }
+      }
+
+      const body = parseSseStream(response.body as ReadableStream<Uint8Array>)
+
+      return { status: response.status, headers, body }
+    },
+  }
+}

package/src/client/hooks.ts

@@ -0,0 +1,65 @@
+import type {
+  BeforeRequestContext,
+  AfterResponseContext,
+  ErrorContext,
+  ClientHooks,
+} from './types.js'
+
+/**
+ * Runs `onBeforeRequest` hooks: global first, then per-procedure.
+ * Each hook receives the (possibly mutated) context from the previous hook.
+ * Returns the final context.
+ */
+export async function runBeforeRequest(
+  ctx: BeforeRequestContext,
+  globalHooks: ClientHooks,
+  localHooks: ClientHooks | undefined
+): Promise<BeforeRequestContext> {
+  let current = ctx
+
+  if (globalHooks.onBeforeRequest) {
+    current = await globalHooks.onBeforeRequest(current)
+  }
+
+  if (localHooks?.onBeforeRequest) {
+    current = await localHooks.onBeforeRequest(current)
+  }
+
+  return current
+}
+
+/**
+ * Runs `onAfterResponse` hooks: global first, then per-procedure.
+ * Returns void.
+ */
+export async function runAfterResponse(
+  ctx: AfterResponseContext,
+  globalHooks: ClientHooks,
+  localHooks: ClientHooks | undefined
+): Promise<void> {
+  if (globalHooks.onAfterResponse) {
+    await globalHooks.onAfterResponse(ctx)
+  }
+
+  if (localHooks?.onAfterResponse) {
+    await localHooks.onAfterResponse(ctx)
+  }
+}
+
+/**
+ * Runs `onError` hooks: global first, then per-procedure.
+ * Returns void.
+ */
+export async function runOnError(
+  ctx: ErrorContext,
+  globalHooks: ClientHooks,
+  localHooks: ClientHooks | undefined
+): Promise<void> {
+  if (globalHooks.onError) {
+    await globalHooks.onError(ctx)
+  }
+
+  if (localHooks?.onError) {
+    await localHooks.onError(ctx)
+  }
+}

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)
+}