okengine 0.1.4

package/src/compiler/aot.test.ts

@@ -0,0 +1,248 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { oke } from "../kernel/app.ts";
+import { flow, resetFlowSeq } from "../kernel/flow.ts";
+import { on, resetBindings } from "../kernel/on.ts";
+import { http } from "../kernel/triggers.ts";
+import { VALIDATION_ERROR_CODE } from "../validation/standard-schema.ts";
+import { compileAot, sucrose } from "./aot.ts";
+import { compileDynamic } from "./dynamic.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("sucrose — context inference", () => {
+  test("POST enables body; path params enable params; skips unused slots", () => {
+    const inference = sucrose({
+      handler: ((input: { flightId: string }) => input) as never,
+      path: "/bookings",
+      method: "POST",
+      hasSchema: true,
+    });
+    expect(inference.body).toBe(true);
+    expect(inference.params).toBe(false);
+    expect(inference.query).toBe(false);
+    expect(inference.headers).toBe(false);
+    expect(inference.cookie).toBe(false);
+  });
+
+  test("detects context.body / query / headers access", () => {
+    const inference = sucrose({
+      handler: ((ctx: {
+        body: unknown;
+        query: unknown;
+        headers: unknown;
+      }) => ({
+        body: ctx.body,
+        q: ctx.query,
+        h: ctx.headers,
+      })) as never,
+      method: "GET",
+      path: "/",
+    });
+    expect(inference.body).toBe(true);
+    expect(inference.query).toBe(true);
+    expect(inference.headers).toBe(true);
+  });
+
+  test("GET /:id enables params only", () => {
+    const inference = sucrose({
+      handler: (({ id }: { id: string }) => ({ id })) as never,
+      path: "/notes/:id",
+      method: "GET",
+      hasSchema: true,
+    });
+    expect(inference.params).toBe(true);
+    expect(inference.body).toBe(false);
+  });
+});
+
+describe("compileAot", () => {
+  test("generates aot handler that validates JSON POST", async () => {
+    const schema = z.object({
+      flightId: z.string().min(1),
+      seats: z.number().int().min(1),
+    });
+    const compiled = compileAot({
+      method: "POST",
+      path: "/bookings",
+      handler: ((input: { flightId: string; seats: number }) => input) as never,
+      schema,
+    });
+    expect(compiled.aot).toBe(true);
+    expect(compiled.inference.body).toBe(true);
+
+    const ok = await compiled.parseValidate(
+      new Request("http://localhost/bookings", {
+        method: "POST",
+        body: JSON.stringify({ flightId: "SK1", seats: 2 }),
+        headers: { "content-type": "application/json" },
+      }),
+      {},
+    );
+    expect(ok).toEqual({
+      ok: true,
+      input: { flightId: "SK1", seats: 2 },
+    });
+
+    const bad = await compiled.parseValidate(
+      new Request("http://localhost/bookings", {
+        method: "POST",
+        body: JSON.stringify({ flightId: "SK1", seats: 0 }),
+      }),
+      {},
+    );
+    expect(bad.ok).toBe(false);
+    if (!bad.ok) {
+      expect(bad.failure.error.code).toBe(VALIDATION_ERROR_CODE);
+    }
+  });
+
+  test("dynamic path never uses new Function", () => {
+    const compiled = compileDynamic({
+      method: "POST",
+      path: "/x",
+      handler: (() => null) as never,
+      schema: z.object({ n: z.number() }),
+    });
+    expect(compiled.aot).toBe(false);
+    expect(compiled.inference.body).toBe(true);
+    expect(compiled.inference.headers).toBe(true);
+  });
+});
+
+describe("typed error narrowing end-to-end", () => {
+  test("declared FlightFull narrows by error.code; validation is not a throw", async () => {
+    const Booking = z.object({
+      flightId: z.string().min(1),
+      seats: z.number().int().min(1),
+    });
+    const FlightFull = z.object({ seatsLeft: z.number() });
+
+    on(
+      http.post("/bookings"),
+      flow({
+        name: "bookings.create",
+        in: Booking,
+        out: z.object({ id: z.string() }),
+        errors: { FlightFull },
+        do: (input: { flightId: string; seats: number }, fx) => {
+          if (input.seats > 2) {
+            return fx.fail("FlightFull", { seatsLeft: 2 });
+          }
+          return { id: "b_1" };
+        },
+      }),
+    );
+
+    const app = oke({ name: "bookings-e2e" });
+
+    const full = await app.fetch(
+      new Request("http://localhost/bookings", {
+        method: "POST",
+        body: JSON.stringify({ flightId: "SK1", seats: 5 }),
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    expect(full.status).toBe(400);
+    const fullBody = (await full.json()) as {
+      data: null;
+      error: { code: string; data: { seatsLeft: number } };
+    };
+    expect(fullBody.data).toBeNull();
+    if (fullBody.error.code === "FlightFull") {
+      expect(fullBody.error.data.seatsLeft).toBe(2);
+    } else {
+      throw new Error(`expected FlightFull, got ${fullBody.error.code}`);
+    }
+
+    const invalid = await app.fetch(
+      new Request("http://localhost/bookings", {
+        method: "POST",
+        body: JSON.stringify({ flightId: "SK1", seats: 0 }),
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    expect(invalid.status).toBe(422);
+    const invalidBody = (await invalid.json()) as {
+      data: null;
+      error: { code: string };
+    };
+    expect(invalidBody.error.code).toBe(VALIDATION_ERROR_CODE);
+
+    const ok = await app.fetch(
+      new Request("http://localhost/bookings", {
+        method: "POST",
+        body: JSON.stringify({ flightId: "SK1", seats: 1 }),
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    expect(ok.status).toBe(200);
+    expect(await ok.json()).toEqual({ data: { id: "b_1" }, error: null });
+  });
+});
+
+describe("AoT throughput ≥ 1.5× dynamic", () => {
+  test("validated JSON POST", async () => {
+    const schema = z.object({
+      flightId: z.string().min(1),
+      seats: z.number().int().min(1).max(9),
+      note: z.string().max(200).optional(),
+    });
+    const handler = ((input: {
+      flightId: string;
+      seats: number;
+    }) => input) as never;
+
+    const aot = compileAot({
+      method: "POST",
+      path: "/bookings",
+      handler,
+      schema,
+    });
+    const dyn = compileDynamic({
+      method: "POST",
+      path: "/bookings",
+      handler,
+      schema,
+    });
+    expect(aot.aot).toBe(true);
+    expect(dyn.aot).toBe(false);
+
+    const makeReq = () =>
+      new Request("http://localhost/bookings?utm=x", {
+        method: "POST",
+        body: JSON.stringify({ flightId: "SK1", seats: 2, note: "window" }),
+        headers: {
+          "content-type": "application/json",
+          cookie: "sid=abc",
+          "x-extra": "1",
+        },
+      });
+
+    // Warmup
+    for (let i = 0; i < 200; i++) {
+      await aot.parseValidate(makeReq(), {});
+      await dyn.parseValidate(makeReq(), {});
+    }
+
+    const iterations = 4_000;
+
+    const t0 = performance.now();
+    for (let i = 0; i < iterations; i++) {
+      await aot.parseValidate(makeReq(), {});
+    }
+    const aotMs = performance.now() - t0;
+
+    const t1 = performance.now();
+    for (let i = 0; i < iterations; i++) {
+      await dyn.parseValidate(makeReq(), {});
+    }
+    const dynMs = performance.now() - t1;
+
+    const speedup = dynMs / aotMs;
+    expect(speedup).toBeGreaterThanOrEqual(1.5);
+  });
+});

package/src/compiler/aot.ts

@@ -0,0 +1,182 @@
+/**
+ * AoT compiler — Sucrose analysis + `new Function()` per-route handlers.
+ *
+ * Generates a tailored parse/validate path that only touches context
+ * properties the handler uses (dead-code elimination). Opt out with
+ * {@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 { 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>;
+
+/** Options for {@link compileAot}. */
+export interface CompileRouteOptions {
+  /** HTTP method. */
+  readonly method: string;
+  /** HTTP path pattern. */
+  readonly path: string;
+  /** Flow handler (`do`). */
+  readonly handler: (...args: never[]) => unknown;
+  /** Optional lifecycle hooks included in sucrose. */
+  readonly hooks?: ReadonlyArray<(...args: never[]) => unknown>;
+  /** Input schema (Standard Schema when present). */
+  readonly schema?: SchemaInput | undefined;
+}
+
+/** Bundle returned by the compilers. */
+export interface CompiledRoute {
+  /** Inference used to generate / drive the handler. */
+  readonly inference: ContextInference;
+  /** Parse + validate only. */
+  readonly parseValidate: CompiledParseValidate;
+  /** `true` when generated via `new Function`. */
+  readonly aot: boolean;
+}
+
+/** Helpers injected into generated AoT functions. */
+interface AotHelpers {
+  readonly inference: ContextInference;
+  readonly schema: SchemaInput | undefined;
+  parseBody: typeof parseBody;
+  parseQuery: typeof parseQuery;
+  parseHeaders: typeof parseHeaders;
+  parseCookie: typeof parseCookie;
+  assembleInput: typeof assembleInput;
+  validate: typeof validate;
+}
+
+/**
+ * Compile a minimal per-route parse/validate handler via `new Function()`.
+ *
+ * Falls back to the interpreted path when codegen is unavailable.
+ *
+ * @param options - Route metadata
+ */
+export function compileAot(options: CompileRouteOptions): CompiledRoute {
+  const inference = sucrose({
+    handler: options.handler,
+    hooks: options.hooks,
+    path: options.path,
+    method: options.method,
+    hasSchema: options.schema !== undefined && options.schema !== null,
+  });
+
+  const helpers: AotHelpers = {
+    inference,
+    schema: options.schema,
+    parseBody,
+    parseQuery,
+    parseHeaders,
+    parseCookie,
+    assembleInput,
+    validate,
+  };
+
+  try {
+    const parseValidate = generateParseValidate(inference, helpers);
+    return { inference, parseValidate, aot: true };
+  } catch {
+    return {
+      inference,
+      parseValidate: createInterpretedParseValidate(inference, options.schema),
+      aot: false,
+    };
+  }
+}
+
+/**
+ * Generate a tailored async function that only parses inferred slots.
+ *
+ * @param inference - Context flags
+ * @param helpers - Bound runtime helpers
+ */
+function generateParseValidate(
+  inference: ContextInference,
+  helpers: AotHelpers,
+): CompiledParseValidate {
+  const lines: string[] = [];
+  lines.push("const parts = {};");
+
+  if (inference.params) {
+    lines.push("parts.params = Object.assign({}, params);");
+  }
+  if (inference.query) {
+    lines.push("parts.query = helpers.parseQuery(request);");
+  }
+  if (inference.headers) {
+    lines.push("parts.headers = helpers.parseHeaders(request);");
+  }
+  if (inference.cookie) {
+    lines.push("parts.cookie = helpers.parseCookie(request);");
+  }
+  if (inference.body) {
+    lines.push("parts.body = await helpers.parseBody(request);");
+  }
+
+  lines.push("const raw = helpers.assembleInput(parts);");
+  lines.push("if (helpers.schema === undefined || helpers.schema === null) {");
+  lines.push("  return { ok: true, input: raw };");
+  lines.push("}");
+  lines.push("const result = await helpers.validate(helpers.schema, raw);");
+  lines.push("if (!result.ok) return { ok: false, failure: result.failure };");
+  lines.push("return { ok: true, input: result.value };");
+
+  // new Function — the Bun/Node optimisation; banned on some edge runtimes
+  const factory = new Function(
+    "helpers",
+    `"use strict";\nreturn async function parseValidate(request, params) {\n${lines.map((l) => `  ${l}`).join("\n")}\n};`,
+  ) as (helpers: AotHelpers) => CompiledParseValidate;
+
+  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.
+ */
+export { sucrose } from "./sucrose.ts";
+export type { SucroseOptions } from "./sucrose.ts";
+export type { ContextInference } from "./http-parse.ts";

package/src/compiler/differential.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { compileAot } from "./aot.ts";
+import { compileDynamic } from "./dynamic.ts";
+import { encodeFailure, encodeSuccess } from "./response.ts";
+
+/** Deterministic PRNG for reproducible contracts. */
+function mulberry32(seed: number): () => number {
+  let t = seed >>> 0;
+  return () => {
+    t += 0x6d2b79f5;
+    let r = Math.imul(t ^ (t >>> 15), 1 | t);
+    r ^= r + Math.imul(r ^ (r >>> 7), 61 | r);
+    return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+interface GeneratedContract {
+  readonly name: string;
+  readonly method: "GET" | "POST";
+  readonly path: string;
+  readonly schema: z.ZodType;
+  readonly handler: (...args: never[]) => unknown;
+  readonly samples: ReadonlyArray<{
+    readonly label: string;
+    readonly url: string;
+    readonly init?: RequestInit;
+    readonly params: Record<string, string>;
+  }>;
+}
+
+function generateContracts(count: number, seed = 42): GeneratedContract[] {
+  const rand = mulberry32(seed);
+  const contracts: GeneratedContract[] = [];
+
+  for (let i = 0; i < count; i++) {
+    const kind = rand();
+    if (kind < 0.35) {
+      // POST object body
+      const minSeats = 1 + Math.floor(rand() * 3);
+      const schema = z.object({
+        flightId: z.string().min(1),
+        seats: z.number().int().min(minSeats).max(9),
+        cabin: z.enum(["economy", "business"]).optional(),
+      });
+      const path = `/c${i}/bookings`;
+      contracts.push({
+        name: `post-${i}`,
+        method: "POST",
+        path,
+        schema,
+        handler: ((input: {
+          flightId: string;
+          seats: number;
+          cabin?: string;
+        }) => ({
+          ok: true,
+          flightId: input.flightId,
+          seats: input.seats,
+          cabin: input.cabin ?? "economy",
+        })) as never,
+        samples: [
+          {
+            label: "valid",
+            url: `http://localhost${path}?ref=diff`,
+            init: {
+              method: "POST",
+              body: JSON.stringify({
+                flightId: `F${i}`,
+                seats: minSeats,
+                cabin: "economy",
+              }),
+              headers: {
+                "content-type": "application/json",
+                cookie: "a=1",
+              },
+            },
+            params: {},
+          },
+          {
+            label: "invalid-seats",
+            url: `http://localhost${path}`,
+            init: {
+              method: "POST",
+              body: JSON.stringify({ flightId: `F${i}`, seats: 0 }),
+              headers: { "content-type": "application/json" },
+            },
+            params: {},
+          },
+          {
+            label: "missing-flight",
+            url: `http://localhost${path}`,
+            init: {
+              method: "POST",
+              body: JSON.stringify({ seats: minSeats }),
+              headers: { "content-type": "application/json" },
+            },
+            params: {},
+          },
+        ],
+      });
+    } else if (kind < 0.7) {
+      // GET with path param
+      const schema = z.object({ id: z.string().min(1) });
+      const path = `/c${i}/notes/:id`;
+      const id = `n_${i}`;
+      contracts.push({
+        name: `get-${i}`,
+        method: "GET",
+        path,
+        schema,
+        handler: ((input: { id: string }) => ({ id: input.id, title: "t" })) as never,
+        samples: [
+          {
+            label: "valid",
+            url: `http://localhost/c${i}/notes/${id}`,
+            init: { method: "GET" },
+            params: { id },
+          },
+          {
+            label: "empty-id",
+            url: `http://localhost/c${i}/notes/`,
+            init: { method: "GET" },
+            params: { id: "" },
+          },
+        ],
+      });
+    } else {
+      // POST nested + array
+      const schema = z.object({
+        tags: z.array(z.string().min(1)).min(1).max(5),
+        meta: z.object({
+          source: z.string(),
+          n: z.number().int().nonnegative(),
+        }),
+      });
+      const path = `/c${i}/tags`;
+      contracts.push({
+        name: `nested-${i}`,
+        method: "POST",
+        path,
+        schema,
+        handler: ((input: {
+          tags: string[];
+          meta: { source: string; n: number };
+        }) => ({
+          count: input.tags.length,
+          source: input.meta.source,
+          n: input.meta.n,
+        })) as never,
+        samples: [
+          {
+            label: "valid",
+            url: `http://localhost${path}`,
+            init: {
+              method: "POST",
+              body: JSON.stringify({
+                tags: ["a", "b"],
+                meta: { source: "diff", n: i },
+              }),
+              headers: { "content-type": "application/json" },
+            },
+            params: {},
+          },
+          {
+            label: "empty-tags",
+            url: `http://localhost${path}`,
+            init: {
+              method: "POST",
+              body: JSON.stringify({
+                tags: [],
+                meta: { source: "diff", n: 0 },
+              }),
+              headers: { "content-type": "application/json" },
+            },
+            params: {},
+          },
+        ],
+      });
+    }
+  }
+
+  return contracts;
+}
+
+async function runSample(
+  parseValidate: (
+    request: Request,
+    params: Readonly<Record<string, string>>,
+  ) => Promise<
+    | { ok: true; input: unknown }
+    | { ok: false; failure: import("../kernel/errors.ts").FlowFailure }
+  >,
+  handler: (...args: never[]) => unknown,
+  sample: GeneratedContract["samples"][number],
+): Promise<{ status: number; body: string }> {
+  const request = new Request(sample.url, sample.init);
+  const parsed = await parseValidate(request, sample.params);
+  if (!parsed.ok) {
+    const res = encodeFailure(parsed.failure);
+    return { status: res.status, body: await res.text() };
+  }
+  const output = handler(parsed.input as never);
+  const res = encodeSuccess(output);
+  return { status: res.status, body: await res.text() };
+}
+
+describe("differential — AoT ≡ dynamic across 50 contracts", () => {
+  test("byte-identical responses for all samples", async () => {
+    const contracts = generateContracts(50);
+    expect(contracts).toHaveLength(50);
+
+    let compared = 0;
+    for (const contract of contracts) {
+      const aot = compileAot({
+        method: contract.method,
+        path: contract.path,
+        handler: contract.handler,
+        schema: contract.schema,
+      });
+      const dyn = compileDynamic({
+        method: contract.method,
+        path: contract.path,
+        handler: contract.handler,
+        schema: contract.schema,
+      });
+      expect(aot.aot).toBe(true);
+      expect(dyn.aot).toBe(false);
+
+      for (const sample of contract.samples) {
+        const a = await runSample(aot.parseValidate, contract.handler, sample);
+        const b = await runSample(dyn.parseValidate, contract.handler, sample);
+        expect(a.status).toBe(b.status);
+        expect(a.body).toBe(b.body);
+        compared += 1;
+      }
+    }
+
+    expect(compared).toBeGreaterThanOrEqual(100);
+  });
+});