okengine 0.21.0 → 0.21.1

package/src/client/stream.ts

@@ -4,8 +4,17 @@
  * @module
  */
 
-import { iterateSse, sseError } from "./sse.ts";
-import type { ClientFetch, ClientHeaders, ClientOptions, ClientRouteMap } from "./types.ts";
+import { iterateSseFrames, sseError } from "./sse.ts";
+import type { ClientFetch, ClientOptions, ClientRouteMap } from "./types.ts";
+import {
+  applyAuthHeader,
+  applyHeaderBag,
+  interpolatePath,
+  methodAndPath,
+  resolveHeaders,
+  toQuery,
+  walkContracts,
+} from "./wire.ts";
 
 /** Flow id → REST route for stream-only (non-live) SSE. */
 export type StreamByFlow = Readonly<
@@ -19,20 +28,12 @@ export type StreamByFlow = Readonly<
  */
 export function flattenStreamRoutes($routes: ClientRouteMap | undefined): StreamByFlow {
   const out: Record<string, { readonly method: string; readonly path: string }> = {};
-  if (!$routes) return out;
-  for (const [unit, flows] of Object.entries($routes)) {
-    if (!flows || typeof flows !== "object") continue;
-    for (const [flow, contract] of Object.entries(flows)) {
-      if (!contract || typeof contract !== "object") continue;
-      if (!("stream" in contract) || contract.stream !== true) continue;
-      if ("live" in contract && typeof contract.live === "string") continue;
-      const method = "method" in contract ? contract.method : undefined;
-      const path = "path" in contract ? contract.path : undefined;
-      if (typeof method === "string" && typeof path === "string") {
-        out[`${unit}.${flow}`] = { method, path };
-      }
-    }
-  }
+  walkContracts($routes, (unit, flow, contract) => {
+    if (!("stream" in contract) || contract.stream !== true) return;
+    if ("live" in contract && typeof contract.live === "string") return;
+    const route = methodAndPath(contract);
+    if (route) out[`${unit}.${flow}`] = route;
+  });
   return out;
 }
 
@@ -51,36 +52,21 @@ export async function* openStream(
   opts: ClientOptions,
 ): AsyncGenerator<unknown> {
   const fetchFn: ClientFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  const signal = opts.signal ?? new AbortController().signal;
   let refreshed = false;
   for (;;) {
-    const ctrl = new AbortController();
-    const parent = opts.signal;
-    if (parent) {
-      if (parent.aborted) {
-        ctrl.abort();
-      } else {
-        parent.addEventListener("abort", () => ctrl.abort(), { once: true });
-      }
-    }
     const { url, method, body } = streamRequest(base, route.method, route.path, input);
     const headers = new Headers({ accept: "text/event-stream" });
-    const extra = typeof opts.headers === "function" ? await opts.headers() : opts.headers;
-    applyHeaders(headers, extra);
+    applyHeaderBag(headers, await resolveHeaders(opts));
     if (body !== undefined && !headers.has("content-type")) {
       headers.set("content-type", "application/json");
     }
-    const token =
-      opts.auth && "getToken" in opts.auth && typeof opts.auth.getToken === "function"
-        ? await opts.auth.getToken()
-        : undefined;
-    if (token && !headers.has("authorization")) {
-      headers.set("authorization", `Bearer ${token}`);
-    }
+    await applyAuthHeader(headers, opts);
     const res = await fetchFn(url, {
       method,
       headers,
       body,
-      signal: ctrl.signal,
+      signal,
       ...(opts.credentials !== undefined ? { credentials: opts.credentials } : {}),
     });
     if (
@@ -98,7 +84,7 @@ export async function* openStream(
       const text = await res.text().catch(() => "");
       throw sseError(res.status, text);
     }
-    yield* iterateSse(res, ctrl.signal);
+    for await (const frame of iterateSseFrames(res, signal)) yield frame.event;
     return;
   }
 }
@@ -109,39 +95,11 @@ function streamRequest(
   path: string,
   input: unknown,
 ): { url: string; method: string; body: string | undefined } {
-  const params =
-    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
-  let pathOut = path;
-  const rest: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(params)) {
-    const token = `:${k}`;
-    if (pathOut.includes(token)) {
-      pathOut = pathOut.replaceAll(token, encodeURIComponent(String(v)));
-    } else {
-      rest[k] = v;
-    }
-  }
+  const { path: pathOut, rest } = interpolatePath(path, input);
   const upper = method.toUpperCase();
-  let body: string | undefined;
   if (upper === "GET" || upper === "HEAD") {
-    const query: string[] = [];
-    for (const [k, v] of Object.entries(rest)) {
-      if (v !== undefined) {
-        query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
-      }
-    }
-    const qs = query.length ? `?${query.join("&")}` : "";
-    return { url: `${base}${pathOut}${qs}`, method: upper, body: undefined };
+    return { url: `${base}${pathOut}${toQuery(rest)}`, method: upper, body: undefined };
   }
-  body = JSON.stringify(Object.keys(rest).length > 0 ? rest : (input ?? {}));
+  const body = JSON.stringify(Object.keys(rest).length > 0 ? rest : (input ?? {}));
   return { url: `${base}${pathOut}`, method: upper, body };
 }
-
-function applyHeaders(headers: Headers, extra: ClientHeaders | undefined): void {
-  if (!extra) return;
-  if (Array.isArray(extra)) {
-    for (const [k, v] of extra) headers.set(k, v);
-  } else {
-    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
-  }
-}

package/src/client/transport.ts

@@ -12,6 +12,13 @@ import type {
   ClientHeaders,
   ClientOptions,
 } from "./types.ts";
+import {
+  applyAuthHeader,
+  applyHeaderBag,
+  interpolatePath,
+  resolveHeaders,
+  toQuery,
+} from "./wire.ts";
 
 /** Per-call transport options (binary decode, abort). */
 export interface TransportCallOptions {
@@ -102,7 +109,7 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
  * @param message - Human-readable failure text
  * @param status - Optional HTTP status
  */
-function transportEnvelope(message: string, status?: number): ClientEnvelope {
+export function transportEnvelope(message: string, status?: number): ClientEnvelope {
   return {
     data: null,
     error: {
@@ -154,37 +161,16 @@ async function once(
     : rpcRequest(base, key, input);
 
   const headers = new Headers();
-  const extra = typeof opts.headers === "function" ? await opts.headers() : opts.headers;
-  if (Array.isArray(extra)) {
-    for (const [k, v] of extra) headers.set(k, v);
-  } else if (extra) {
-    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
-  }
-  if (Array.isArray(callHeaders)) {
-    for (const [k, v] of callHeaders) headers.set(k, v);
-  } else if (callHeaders) {
-    for (const [k, v] of Object.entries(callHeaders)) headers.set(k, v);
-  }
+  applyHeaderBag(headers, await resolveHeaders(opts));
+  applyHeaderBag(headers, callHeaders);
   if (body !== undefined && !headers.has("content-type") && typeof body === "string") {
     headers.set("content-type", "application/json");
   }
+  await applyAuthHeader(headers, opts);
 
-  const token =
-    opts.auth && "getToken" in opts.auth && typeof opts.auth.getToken === "function"
-      ? await opts.auth.getToken()
-      : undefined;
-  if (token && !headers.has("authorization")) {
-    headers.set("authorization", `Bearer ${token}`);
-  }
-
-  const signals: AbortSignal[] = [];
-  if (opts.signal) signals.push(opts.signal);
-  if (opts.timeout !== undefined) {
-    const t = AbortSignal.timeout(opts.timeout);
-    signals.push(t);
-  }
+  const timeout = opts.timeout !== undefined ? AbortSignal.timeout(opts.timeout) : undefined;
   const signal =
-    signals.length === 0 ? undefined : signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+    opts.signal && timeout ? AbortSignal.any([opts.signal, timeout]) : (opts.signal ?? timeout);
 
   return await fetchFn(url, {
     method,
@@ -236,47 +222,32 @@ function restRequest(
   if (isRawBody(input)) {
     return { url: `${base}${path}`, method: method.toUpperCase(), body: input };
   }
-  const params =
-    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
-  let pathOut = path;
-  const query: string[] = [];
-  const rest: Record<string, unknown> = {};
-
-  for (const [k, v] of Object.entries(params)) {
-    const token = `:${k}`;
-    if (pathOut.includes(token)) {
-      pathOut = pathOut.replaceAll(token, encodeURIComponent(String(v)));
-    } else {
-      rest[k] = v;
-    }
-  }
+  const interpolated = interpolatePath(path, input);
+  const pathOut = interpolated.path;
+  const rest = interpolated.rest;
 
   const upper = method.toUpperCase();
+  const hasRest = Object.keys(rest).length > 0;
   let body: ClientBodyInit | undefined;
+  let qs = "";
   if (upper === "GET" || upper === "HEAD") {
-    for (const [k, v] of Object.entries(rest)) {
-      if (v !== undefined) {
-        query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
-      }
-    }
+    qs = toQuery(rest);
   } else if (upper === "QUERY") {
     // RFC 10008 QUERY always carries JSON content (empty object when only path params).
-    body = JSON.stringify(Object.keys(rest).length > 0 ? rest : {});
-  } else if (Object.keys(rest).length > 0 || path === pathOut) {
-    body = JSON.stringify(Object.keys(rest).length > 0 ? rest : (input ?? {}));
+    body = JSON.stringify(hasRest ? rest : {});
+  } else if (hasRest || path === pathOut) {
+    body = JSON.stringify(hasRest ? rest : (input ?? {}));
   }
 
-  const qs = query.length ? `?${query.join("&")}` : "";
   return { url: `${base}${pathOut}${qs}`, method: upper, body };
 }
 
 function isRawBody(input: unknown): input is ClientBodyInit {
-  if (input === null || input === undefined) return false;
-  if (typeof Blob !== "undefined" && input instanceof Blob) return true;
-  if (typeof FormData !== "undefined" && input instanceof FormData) return true;
-  if (typeof ArrayBuffer !== "undefined" && input instanceof ArrayBuffer) return true;
-  if (typeof ArrayBuffer !== "undefined" && ArrayBuffer.isView(input)) return true;
-  if (typeof ReadableStream !== "undefined" && input instanceof ReadableStream) return true;
+  if (input instanceof Blob) return true;
+  if (input instanceof FormData) return true;
+  if (input instanceof ArrayBuffer) return true;
+  if (ArrayBuffer.isView(input)) return true;
+  if (input instanceof ReadableStream) return true;
   return false;
 }
 
@@ -311,7 +282,7 @@ async function decode(res: Response): Promise<ClientEnvelope> {
 
 async function decodeBinary(res: Response, mode: "blob" | "arrayBuffer"): Promise<ClientEnvelope> {
   if (!res.ok) {
-    const structured = await decodeIfEnvelopeClone(res);
+    const structured = await decodeIfEnvelope(res);
     if (structured) return structured;
     return transportEnvelope(`HTTP ${res.status}`, res.status);
   }
@@ -319,22 +290,6 @@ async function decodeBinary(res: Response, mode: "blob" | "arrayBuffer"): Promis
   return { data, error: null };
 }
 
-/** Try JSON envelope from an error response without assuming the body is reusable. */
-async function decodeIfEnvelopeClone(res: Response): Promise<ClientEnvelope | null> {
-  const text = await res.text();
-  if (!text) return null;
-  let json: unknown;
-  try {
-    json = JSON.parse(text);
-  } catch {
-    return null;
-  }
-  if (json !== null && typeof json === "object" && "data" in json && "error" in json) {
-    return json as ClientEnvelope;
-  }
-  return null;
-}
-
 function isTransient(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
   if (err.name === "AbortError") return false;

package/src/client/wire.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared REST wire helpers for transport, live subscribe, and streams.
+ */
+
+import type { ClientHeaders, ClientOptions, ClientRouteMap, FlowContract } from "./types.ts";
+
+/**
+ * Visit every flow contract in `app.$routes`.
+ *
+ * @param $routes - Runtime route map
+ * @param visit - Called with unit, flow, and contract
+ */
+export function walkContracts(
+  $routes: ClientRouteMap | undefined,
+  visit: (unit: string, flow: string, contract: FlowContract) => void,
+): void {
+  if (!$routes) return;
+  for (const [unit, flows] of Object.entries($routes)) {
+    if (!flows || typeof flows !== "object") continue;
+    for (const [flow, contract] of Object.entries(flows)) {
+      if (!contract || typeof contract !== "object") continue;
+      visit(unit, flow, contract);
+    }
+  }
+}
+
+/**
+ * Read `method` and `path` when both are strings.
+ *
+ * @param contract - One flow contract
+ */
+export function methodAndPath(
+  contract: object,
+): { readonly method: string; readonly path: string } | undefined {
+  const method = "method" in contract ? contract.method : undefined;
+  const path = "path" in contract ? contract.path : undefined;
+  if (typeof method === "string" && typeof path === "string") return { method, path };
+  return undefined;
+}
+
+/**
+ * Replace `:param` tokens in `path`. Unmatched keys land in `rest`.
+ *
+ * @param path - Path template
+ * @param input - JSON object, or anything else (ignored)
+ */
+export function interpolatePath(
+  path: string,
+  input: unknown,
+): { readonly path: string; readonly rest: Record<string, unknown> } {
+  const params =
+    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
+  let pathOut = path;
+  const rest: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(params)) {
+    const token = `:${k}`;
+    if (pathOut.includes(token)) {
+      pathOut = pathOut.replaceAll(token, encodeURIComponent(String(v)));
+    } else {
+      rest[k] = v;
+    }
+  }
+  return { path: pathOut, rest };
+}
+
+/**
+ * Encode a query string, skipping `undefined` values.
+ *
+ * @param rest - Keys that were not path params
+ */
+export function toQuery(rest: Record<string, unknown>): string {
+  const query: string[] = [];
+  for (const [k, v] of Object.entries(rest)) {
+    if (v !== undefined) {
+      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+  }
+  return query.length > 0 ? `?${query.join("&")}` : "";
+}
+
+/**
+ * Copy a header bag onto `headers` (later keys win within the bag).
+ *
+ * @param headers - Target
+ * @param extra - Record or tuple list
+ */
+export function applyHeaderBag(headers: Headers, extra: ClientHeaders | undefined): void {
+  if (!extra) return;
+  if (Array.isArray(extra)) {
+    for (const [k, v] of extra) headers.set(k, v);
+  } else {
+    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
+  }
+}
+
+/**
+ * Resolve `opts.headers` when it is a function.
+ *
+ * @param opts - Client options
+ */
+export async function resolveHeaders(opts: ClientOptions): Promise<ClientHeaders | undefined> {
+  return typeof opts.headers === "function" ? await opts.headers() : opts.headers;
+}
+
+/**
+ * Set `Authorization` from `opts.auth.getToken` when the caller did not.
+ *
+ * @param headers - Target
+ * @param opts - Client options
+ */
+export async function applyAuthHeader(headers: Headers, opts: ClientOptions): Promise<void> {
+  const token =
+    opts.auth && "getToken" in opts.auth && typeof opts.auth.getToken === "function"
+      ? await opts.auth.getToken()
+      : undefined;
+  if (token && !headers.has("authorization")) {
+    headers.set("authorization", `Bearer ${token}`);
+  }
+}

package/src/compiler/aot.ts

@@ -6,30 +6,20 @@
  * {@link compileDynamic} / `aot: false` on edge runtimes that ban `eval`.
  */
 
-import type { FlowFailure } from "../kernel/errors.ts";
 import { validate, type SchemaInput } from "../validation/standard-schema.ts";
 import {
   assembleInput,
-  extractParts,
   parseBody,
   parseCookie,
   parseHeaders,
   parseQuery,
   type ContextInference,
-  type InputParts,
 } from "./http-parse.ts";
+import { createInterpretedParseValidate, type CompiledParseValidate } from "./interpret.ts";
 import { sucrose } from "./sucrose.ts";
 
-/** Result of parse + validate for one request. */
-export type ParseValidateResult =
-  | { readonly ok: true; readonly input: unknown }
-  | { readonly ok: false; readonly failure: FlowFailure };
-
-/** Compiled parse/validate function. */
-export type CompiledParseValidate = (
-  request: Request,
-  params: Readonly<Record<string, string>>,
-) => Promise<ParseValidateResult>;
+export type { CompiledParseValidate, ParseValidateResult } from "./interpret.ts";
+export { createInterpretedParseValidate };
 
 /** Options for {@link compileAot}. */
 export interface CompileRouteOptions {
@@ -152,25 +142,6 @@ function generateParseValidate(
   return factory(helpers);
 }
 
-/**
- * Interpreted parse/validate using the same helpers (AoT fallback).
- *
- * @param inference - Context flags
- * @param schema - Input schema
- */
-export function createInterpretedParseValidate(
-  inference: ContextInference,
-  schema: SchemaInput | undefined,
-): CompiledParseValidate {
-  return async (request, params) => {
-    const parts: InputParts = await extractParts(request, params, inference);
-    const raw = assembleInput(parts);
-    const result = await validate(schema, raw);
-    if (!result.ok) return { ok: false, failure: result.failure };
-    return { ok: true, input: result.value };
-  };
-}
-
 /**
  * Re-export sucrose for tests and tooling.
  */

package/src/compiler/dynamic.ts

@@ -7,15 +7,18 @@
  * a requirement). Produces byte-identical responses to {@link compileAot}.
  */
 
+import { lazyRequire } from "../kernel/lazy-require.ts";
 import type { SchemaInput } from "../validation/standard-schema.ts";
-import {
-  compileAot,
-  createInterpretedParseValidate,
-  type CompiledRoute,
-  type CompileRouteOptions,
-} from "./aot.ts";
+import type { CompiledRoute, CompileRouteOptions } from "./aot.ts";
 import { FULL_INFERENCE } from "./http-parse.ts";
-import { dynamicInference } from "./sucrose.ts";
+import { createInterpretedParseValidate } from "./interpret.ts";
+
+/**
+ * Load AoT codegen. Computed stem so the edge profile keeps the interpreted path only.
+ */
+function loadAot(): typeof import("./aot.ts") {
+  return lazyRequire(import.meta.dir, ["ao", "t"].join(""));
+}
 
 /**
  * Compile a route with the dynamic fallback (full context every request).
@@ -23,10 +26,9 @@ import { dynamicInference } from "./sucrose.ts";
  * @param options - Route metadata
  */
 export function compileDynamic(options: CompileRouteOptions): CompiledRoute {
-  const inference = dynamicInference();
   return {
-    inference,
-    parseValidate: createInterpretedParseValidate(inference, options.schema),
+    inference: FULL_INFERENCE,
+    parseValidate: createInterpretedParseValidate(FULL_INFERENCE, options.schema),
     aot: false,
   };
 }
@@ -39,7 +41,7 @@ export function compileDynamic(options: CompileRouteOptions): CompiledRoute {
  */
 export function compileRoute(options: CompileRouteOptions, aot: boolean = true): CompiledRoute {
   if (!aot) return compileDynamic(options);
-  return compileAot(options);
+  return loadAot().compileAot(options);
 }
 
 /**

package/src/compiler/interpret.ts

@@ -0,0 +1,45 @@
+/**
+ * Interpreted parse/validate — the edge path.
+ *
+ * AoT (`new Function`) lives in {@link compileAot} and is loaded only when
+ * requested, so eval-restricted runtimes do not carry the codegen.
+ */
+
+import type { FlowFailure } from "../kernel/errors.ts";
+import { validate, type SchemaInput } from "../validation/standard-schema.ts";
+import {
+  assembleInput,
+  extractParts,
+  type ContextInference,
+  type InputParts,
+} from "./http-parse.ts";
+
+/** Result of parse + validate for one request. */
+export type ParseValidateResult =
+  | { readonly ok: true; readonly input: unknown }
+  | { readonly ok: false; readonly failure: FlowFailure };
+
+/** Compiled parse/validate function. */
+export type CompiledParseValidate = (
+  request: Request,
+  params: Readonly<Record<string, string>>,
+) => Promise<ParseValidateResult>;
+
+/**
+ * Interpreted parse/validate using the shared HTTP helpers (AoT fallback).
+ *
+ * @param inference - Context flags
+ * @param schema - Input schema
+ */
+export function createInterpretedParseValidate(
+  inference: ContextInference,
+  schema: SchemaInput | undefined,
+): CompiledParseValidate {
+  return async (request, params) => {
+    const parts: InputParts = await extractParts(request, params, inference);
+    const raw = assembleInput(parts);
+    const result = await validate(schema, raw);
+    if (!result.ok) return { ok: false, failure: result.failure };
+    return { ok: true, input: result.value };
+  };
+}