okengine 0.1.4

package/src/client/create.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Typed client — same-repo `<App>`, narrowing, transport behaviours.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createClient } from "./create.ts";
+import { isErrorCode, isOk, isTransportError } from "./errors.ts";
+import type { AppOf, ClientError, ClientResult } from "./types.ts";
+
+/** Fixture App matching Notes / bookings (`FlightFull`). */
+type BookingsApp = AppOf<{
+  bookings: {
+    create: {
+      in: { flightId: string; seats: number };
+      out: { id: string; flightId: string; seats: number };
+      errors: { FlightFull: { seatsLeft: number } };
+    };
+  };
+  notes: {
+    get: {
+      in: { id: string };
+      out: { id: string; title: string };
+      errors: { NotFound: Record<string, never> };
+    };
+  };
+}>;
+
+/** Compile-time equality. */
+type Eq<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+    ? true
+    : false;
+type Assert<T extends true> = T;
+
+describe("createClient — same-repo <App>", () => {
+  test("success envelope is typed", async () => {
+    const api = createClient<BookingsApp>("http://app.test", {
+      fetch: async () =>
+        Response.json({
+          data: { id: "b_1", flightId: "SK1", seats: 1 },
+          error: null,
+        }),
+    });
+
+    const result = await api.bookings.create({
+      flightId: "SK1",
+      seats: 1,
+    });
+    expect(result.error).toBeNull();
+    expect(result.data?.id).toBe("b_1");
+    expect(isOk(result)).toBe(true);
+  });
+
+  test('error.code === "FlightFull" narrows error.data', async () => {
+    const api = createClient<BookingsApp>("http://app.test", {
+      fetch: async () =>
+        Response.json(
+          {
+            data: null,
+            error: { code: "FlightFull", data: { seatsLeft: 2 } },
+          },
+          { status: 400 },
+        ),
+    });
+
+    const { data, error } = await api.bookings.create({
+      flightId: "SK1",
+      seats: 9,
+    });
+    expect(data).toBeNull();
+    expect(error?.code).toBe("FlightFull");
+
+    if (error?.code === "FlightFull") {
+      // Runtime + type-level: seatsLeft is number, not unknown.
+      expect(error.data.seatsLeft).toBe(2);
+      type _Narrow = Assert<
+        Eq<typeof error.data, { seatsLeft: number }>
+      >;
+      const _keep: _Narrow = true;
+      expect(_keep).toBe(true);
+    } else {
+      throw new Error("expected FlightFull");
+    }
+
+    expect(isErrorCode(error, "FlightFull")).toBe(true);
+    if (isErrorCode(error, "FlightFull")) {
+      expect(error.data.seatsLeft).toBe(2);
+    }
+  });
+
+  test("RPC path is POST /_oke/{unit}/{flow}", async () => {
+    let seen = "";
+    const api = createClient<BookingsApp>("http://app.test/", {
+      fetch: async (input) => {
+        seen = String(input);
+        return Response.json({
+          data: { id: "n_1", title: "Hi" },
+          error: null,
+        });
+      },
+    });
+    await api.notes.get({ id: "n_1" });
+    expect(seen).toBe("http://app.test/_oke/notes/get");
+  });
+
+  test("REST routes map substitutes path params", async () => {
+    let method = "";
+    let url = "";
+    const api = createClient<BookingsApp>("http://app.test", {
+      routes: {
+        "notes.get": { method: "GET", path: "/notes/:id" },
+      },
+      fetch: async (input, init) => {
+        url = String(input);
+        method = String(init?.method ?? "GET");
+        return Response.json({
+          data: { id: "n_1", title: "Hi" },
+          error: null,
+        });
+      },
+    });
+    await api.notes.get({ id: "n_1" });
+    expect(method).toBe("GET");
+    expect(url).toBe("http://app.test/notes/n_1");
+  });
+});
+
+describe("createClient — type helpers", () => {
+  test("ClientError discriminated union is exhaustive on code", () => {
+    type E = ClientError<{
+      FlightFull: { seatsLeft: number };
+      NotFound: Record<string, never>;
+    }>;
+    type _Codes = Assert<Eq<E["code"], "FlightFull" | "NotFound">>;
+    const ok: _Codes = true;
+    expect(ok).toBe(true);
+
+    const sample: ClientResult<{ id: string }, { FlightFull: { seatsLeft: number } }> =
+      {
+        data: null,
+        error: { code: "FlightFull", data: { seatsLeft: 0 } },
+      };
+    if (sample.error?.code === "FlightFull") {
+      type _D = Assert<Eq<typeof sample.error.data, { seatsLeft: number }>>;
+      const d: _D = true;
+      expect(d).toBe(true);
+    }
+  });
+
+  test("isTransportError", () => {
+    expect(
+      isTransportError({
+        code: "TransportError",
+        data: { message: "boom" },
+      }),
+    ).toBe(true);
+    expect(isTransportError({ code: "FlightFull", data: {} })).toBe(false);
+  });
+});

package/src/client/create.ts

@@ -0,0 +1,152 @@
+/**
+ * `createClient<App>(url, opts)` — typed client, zero runtime codegen.
+ *
+ * Modes:
+ * 1. Same-repo: `createClient<App>(url)` with `typeof app` after
+ *    `.adopt({ notes })`, or `createClient(app, url)` to also wire REST from
+ *    `app.$routes` at runtime
+ * 2. Local dev: `createClient(url)` — types from ambient {@link Register}
+ * 3. Separate repo: same as (2) after `oke client add <url>`
+ *
+ * Wire: HTTP triggers use REST (`method` + `path` from the bound trigger).
+ * Untriggered flows fall back to `POST /_oke/{unit}/{flow}` RPC.
+ */
+
+import { createTransport, type Transport } from "./transport.ts";
+import type {
+  Client,
+  ClientOptions,
+  ClientRouteMap,
+  ResolveApp,
+} from "./types.ts";
+
+/** App-shaped value that carries a runtime `$routes` table from typed adopt. */
+export interface AppWithRoutes {
+  readonly $routes: ClientRouteMap;
+}
+
+/**
+ * Create a fully typed client from an adopted app value (types + REST).
+ *
+ * @typeParam App - `typeof app` after `.adopt({ notes })`
+ * @param app - Application instance with `$routes`
+ * @param url - App base URL (port 6530 in dev)
+ * @param opts - Transport options (retry, timeout, auth)
+ */
+export function createClient<App extends AppWithRoutes>(
+  app: App,
+  url: string,
+  opts?: ClientOptions,
+): Client<App>;
+
+/**
+ * Create a fully typed client from an App type argument / ambient Register.
+ *
+ * Pass `opts.$routes` (usually `app.$routes`) so HTTP triggers issue REST
+ * instead of RPC.
+ *
+ * @typeParam App - `typeof app`, {@link AppOf} route map, or omit for {@link Register}
+ * @param url - App base URL (port 6530 in dev)
+ * @param opts - Transport options (retry, timeout, auth, `$routes`)
+ */
+export function createClient<App = never>(
+  url: string,
+  opts?: ClientOptions,
+): Client<ResolveApp<App>>;
+
+/**
+ * @param appOrUrl - App instance or base URL
+ * @param urlOrOpts - Base URL (when app given) or options
+ * @param maybeOpts - Options when app + url form is used
+ */
+export function createClient(
+  appOrUrl: AppWithRoutes | string,
+  urlOrOpts?: string | ClientOptions,
+  maybeOpts?: ClientOptions,
+): Client {
+  if (typeof appOrUrl === "string") {
+    return buildClient(appOrUrl, urlOrOpts as ClientOptions | undefined);
+  }
+  const url = typeof urlOrOpts === "string" ? urlOrOpts : "";
+  const opts = typeof urlOrOpts === "string" ? maybeOpts : urlOrOpts;
+  return buildClient(url, {
+    ...opts,
+    $routes: opts?.$routes ?? appOrUrl.$routes,
+  });
+}
+
+/**
+ * Shared constructor — flattens `$routes` into the transport REST table.
+ *
+ * @param url - Base URL
+ * @param opts - Client options
+ */
+function buildClient(url: string, opts: ClientOptions = {}): Client {
+  const base = url.replace(/\/+$/, "");
+  const routes = opts.routes ?? flattenRoutes(opts.$routes);
+  const transport = createTransport(base, { ...opts, routes });
+  return proxy(transport, []) as Client;
+}
+
+/**
+ * Flatten `app.$routes` into the transport REST table (`unit.flow` → method/path).
+ * Entries without both method and path are omitted (RPC fallback).
+ *
+ * @param $routes - Runtime route map from typed adopt
+ */
+export function flattenRoutes(
+  $routes: ClientRouteMap | undefined,
+): ClientOptions["routes"] | undefined {
+  if (!$routes) return undefined;
+  const out: Record<string, { readonly method: string; readonly path: string }> =
+    {};
+  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;
+      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 };
+      }
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Build a nested Proxy: `api.notes.get(input)` → REST or RPC from routes.
+ *
+ * @param transport - HTTP transport
+ * @param path - Accumulated property path
+ */
+function proxy(transport: Transport, path: readonly string[]): unknown {
+  const call = (input?: unknown) => {
+    if (path.length < 2) {
+      return Promise.resolve({
+        data: null,
+        error: {
+          code: "TransportError" as const,
+          data: {
+            message: `Incomplete path: api.${path.join(".") || "?"}(…)`,
+          },
+        },
+      });
+    }
+    // `api.bookings.create` → unit `bookings`, flow `create`
+    const unit = path[0]!;
+    const flow = path.slice(1).join(".");
+    return transport.call(`${unit}/${flow}`, input);
+  };
+
+  return new Proxy(call, {
+    get(_target, prop, receiver) {
+      if (typeof prop === "symbol") {
+        return Reflect.get(_target, prop, receiver);
+      }
+      // Prevent `await api.notes` from treating the proxy as a Thenable.
+      if (prop === "then") return undefined;
+      return proxy(transport, [...path, prop]);
+    },
+  });
+}

package/src/client/errors.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed error narrowing for the client result envelope.
+ *
+ * Flow failures are values (`{ data: null, error }`). Narrow with
+ * `error.code === "FlightFull"` — TypeScript then knows `error.data`.
+ */
+
+import type { ClientResult, TransportError } from "./types.ts";
+
+/**
+ * True when `error` is a transport / protocol failure.
+ *
+ * @param error - Client error value
+ */
+export function isTransportError(
+  error: { readonly code: string; readonly data?: unknown } | null | undefined,
+): error is TransportError {
+  return error?.code === "TransportError";
+}
+
+/**
+ * Narrow a client error to one declared code.
+ *
+ * Prefer `error?.code === "FlightFull"` for inference; use this when
+ * you need a type predicate in a helper.
+ *
+ * @param error - Error value from a {@link ClientResult}
+ * @param code - Declared error code
+ */
+export function isErrorCode<
+  Err extends { readonly code: string; readonly data: unknown },
+  C extends Err["code"],
+>(
+  error: Err | null | undefined,
+  code: C,
+): error is Extract<Err, { readonly code: C }> {
+  return error != null && error.code === code;
+}
+
+/**
+ * True when the result is a failure (flow or transport).
+ *
+ * @param result - Client call result
+ */
+export function isFail<O, E extends Record<string, unknown>>(
+  result: ClientResult<O, E>,
+): result is Extract<ClientResult<O, E>, { readonly data: null }> {
+  return result.error !== null;
+}
+
+/**
+ * True when the result is a success.
+ *
+ * @param result - Client call result
+ */
+export function isOk<O, E extends Record<string, unknown>>(
+  result: ClientResult<O, E>,
+): result is Extract<ClientResult<O, E>, { readonly error: null }> {
+  return result.error === null;
+}

package/src/client/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Typed client (+ live). Subpath: `okengine/client`.
+ *
+ * First Manifest derivation: `type App` → fully typed client, zero codegen.
+ */
+
+export { createClient, flattenRoutes } from "./create.ts";
+export type { AppWithRoutes } from "./create.ts";
+export {
+  isErrorCode,
+  isFail,
+  isOk,
+  isTransportError,
+} from "./errors.ts";
+export { createTransport } from "./transport.ts";
+export type { Transport } from "./transport.ts";
+export type {
+  AppOf,
+  Client,
+  ClientApp,
+  ClientCall,
+  ClientDescriptor,
+  ClientError,
+  ClientFetch,
+  ClientFromRoutes,
+  ClientHeaders,
+  ClientOptions,
+  ClientResult,
+  ClientRouteMap,
+  FlowContract,
+  Register,
+  ResolveApp,
+  RoutesOf,
+  TransportError,
+} from "./types.ts";

package/src/client/notes-contract.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Notes contract — `typeof app` → typed client (Prompt 8.1).
+ *
+ * Proves: adopt accumulates routes · REST from trigger · error narrowing ·
+ * removing a flow from adopt removes it from the client type.
+ */
+
+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 { createClient } from "./create.ts";
+import type { Client } from "./types.ts";
+
+beforeEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+/** Compile-time equality. */
+type Eq<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+    ? true
+    : false;
+type Assert<T extends true> = T;
+
+const NoteId = z.object({ id: z.string() });
+const Note = z.object({
+  id: z.string(),
+  title: z.string(),
+  body: z.string(),
+});
+const NewNote = z.object({
+  title: z.string(),
+  body: z.string(),
+});
+const NotFound = z.object({});
+
+const create = on(
+  http.post("/notes"),
+  flow({
+    in: NewNote,
+    out: NoteId,
+    do: (input) => ({ id: `n_${input.title}` }),
+  }),
+);
+
+const get = on(
+  http.get("/notes/:id"),
+  flow({
+    in: NoteId,
+    out: Note,
+    errors: { NotFound },
+    do: ({ id }, fx) =>
+      id === "missing"
+        ? fx.fail("NotFound", {})
+        : { id, title: "First", body: "Hello" },
+  }),
+);
+
+const notes = { create, get } as const;
+
+describe("Notes — typeof app carries contracts", () => {
+  test("four-applications client block typechecks without AppOf<>", () => {
+    const app = oke({ name: "notes" }).adopt({ notes });
+    type App = typeof app;
+
+    // Exactly the Notes client shape — types from App alone, no AppOf.
+    const api = createClient<App>("http://localhost:6530");
+
+    type GetResult = Awaited<ReturnType<typeof api.notes.get>>;
+    type GetError = NonNullable<GetResult["error"]>;
+    type NotFoundData = Extract<GetError, { code: "NotFound" }>["data"];
+    type SuccessTitle = Extract<GetResult, { error: null }>["data"]["title"];
+
+    type _Err = Assert<Eq<NotFoundData, Record<string, never>>>;
+    type _Title = Assert<Eq<SuccessTitle, string>>;
+    const ok: [_Err, _Title] = [true, true];
+    expect(ok).toEqual([true, true]);
+    expect(typeof api.notes.get).toBe("function");
+    expect(typeof api.notes.create).toBe("function");
+  });
+
+  test("Notes client block: createClient<App> narrows data and NotFound", async () => {
+    const app = oke({ name: "notes" }).adopt({ notes });
+    type App = typeof app;
+
+    // four-applications client shape — App from typeof app, no AppOf<>.
+    const api = createClient<App>("http://localhost:6530", {
+      $routes: app.$routes,
+      fetch: async (input, init) => {
+        const url = String(input);
+        const method = String(init?.method ?? "GET");
+        if (method === "GET" && url.endsWith("/notes/n_1")) {
+          return Response.json({
+            data: { id: "n_1", title: "First", body: "Hello" },
+            error: null,
+          });
+        }
+        if (method === "GET" && url.endsWith("/notes/missing")) {
+          return Response.json(
+            { data: null, error: { code: "NotFound", data: {} } },
+            { status: 404 },
+          );
+        }
+        return Response.json(
+          {
+            data: null,
+            error: {
+              code: "TransportError",
+              data: { message: `${method} ${url}` },
+            },
+          },
+          { status: 500 },
+        );
+      },
+    });
+
+    {
+      const { data, error } = await api.notes.get({ id: "n_1" });
+      if (error?.code === "NotFound") {
+        type _Empty = Assert<
+          Eq<typeof error.data, Record<string, never>>
+        >;
+        const keep: _Empty = true;
+        expect(keep).toBe(true);
+        throw new Error("unexpected NotFound");
+      } else if (error) {
+        throw new Error(`unexpected ${error.code}`);
+      } else {
+        // Notes: else data.title — narrowed success
+        expect(data.title).toBe("First");
+        type _Title = Assert<Eq<typeof data.title, string>>;
+        const t: _Title = true;
+        expect(t).toBe(true);
+      }
+    }
+
+    {
+      const { error } = await api.notes.get({ id: "missing" });
+      if (error?.code === "NotFound") {
+        type _D = Assert<Eq<typeof error.data, Record<string, never>>>;
+        const d: _D = true;
+        expect(d).toBe(true);
+      } else {
+        throw new Error("expected NotFound");
+      }
+    }
+  });
+
+  test("api.notes.get issues GET /notes/n_1, not RPC POST", async () => {
+    const app = oke({ name: "notes" }).adopt({ notes });
+    type App = typeof app;
+
+    let method = "";
+    let url = "";
+    const api = createClient<App>("http://app.test", {
+      $routes: app.$routes,
+      fetch: async (input, init) => {
+        url = String(input);
+        method = String(init?.method ?? "GET");
+        return Response.json({
+          data: { id: "n_1", title: "First", body: "Hello" },
+          error: null,
+        });
+      },
+    });
+
+    await api.notes.get({ id: "n_1" });
+    expect(method).toBe("GET");
+    expect(url).toBe("http://app.test/notes/n_1");
+  });
+
+  test("createClient(app, url) wires REST from app.$routes", async () => {
+    const app = oke({ name: "notes" }).adopt({ notes });
+
+    let method = "";
+    let url = "";
+    const api = createClient(app, "http://app.test", {
+      fetch: async (input, init) => {
+        url = String(input);
+        method = String(init?.method ?? "GET");
+        return Response.json({
+          data: { id: "n_1", title: "Hi", body: "" },
+          error: null,
+        });
+      },
+    });
+
+    await api.notes.get({ id: "n_1" });
+    expect(method).toBe("GET");
+    expect(url).toBe("http://app.test/notes/n_1");
+  });
+
+  test("POST create uses REST /notes from trigger", async () => {
+    const app = oke({ name: "notes" }).adopt({ notes });
+    let method = "";
+    let url = "";
+    let body = "";
+    const api = createClient(app, "http://app.test", {
+      fetch: async (input, init) => {
+        url = String(input);
+        method = String(init?.method ?? "GET");
+        body = String(init?.body ?? "");
+        return Response.json({ data: { id: "n_1" }, error: null });
+      },
+    });
+
+    await api.notes.create({ title: "First", body: "Hello" });
+    expect(method).toBe("POST");
+    expect(url).toBe("http://app.test/notes");
+    expect(JSON.parse(body)).toEqual({ title: "First", body: "Hello" });
+  });
+
+  test("runtime $routes carries method/path literals from triggers", () => {
+    const app = oke({ name: "notes" }).adopt({ notes });
+    expect(app.$routes.notes.get).toEqual({
+      method: "GET",
+      path: "/notes/:id",
+    });
+    expect(app.$routes.notes.create).toEqual({
+      method: "POST",
+      path: "/notes",
+    });
+
+    type App = typeof app;
+    type GetMethod = App["$routes"]["notes"]["get"]["method"];
+    type GetPath = App["$routes"]["notes"]["get"]["path"];
+    type _M = Assert<Eq<GetMethod, "GET">>;
+    type _P = Assert<Eq<GetPath, "/notes/:id">>;
+    const ok: [_M, _P] = [true, true];
+    expect(ok).toEqual([true, true]);
+  });
+
+  test("removing a flow from adopt removes it from the client type", () => {
+    const full = oke({ name: "notes" }).adopt({ notes });
+    const createOnly = oke({ name: "notes" }).adopt({
+      notes: { create: notes.create },
+    });
+
+    type FullClient = Client<typeof full>;
+    type PartialClient = Client<typeof createOnly>;
+
+    type FullHasGet = "get" extends keyof FullClient["notes"] ? true : false;
+    type PartialHasGet = "get" extends keyof PartialClient["notes"]
+      ? true
+      : false;
+
+    type _Full = Assert<Eq<FullHasGet, true>>;
+    type _Part = Assert<Eq<PartialHasGet, false>>;
+    const checks: [_Full, _Part] = [true, true];
+    expect(checks).toEqual([true, true]);
+
+    // Runtime table matches.
+    expect("get" in full.$routes.notes).toBe(true);
+    expect("get" in createOnly.$routes.notes).toBe(false);
+  });
+
+  test("untriggered adopted flow is RPC-only on the client", async () => {
+    const stats = flow({
+      name: "notes.stats",
+      in: NoteId,
+      out: z.object({ clicks: z.number() }),
+      do: () => ({ clicks: 7 }),
+    });
+
+    const app = oke({ name: "notes" }).adopt({
+      notes: { create, get, stats },
+    });
+
+    expect(app.$routes.notes.stats).toEqual({});
+
+    let url = "";
+    let method = "";
+    const api = createClient(app, "http://app.test", {
+      fetch: async (input, init) => {
+        url = String(input);
+        method = String(init?.method ?? "GET");
+        return Response.json({ data: { clicks: 7 }, error: null });
+      },
+    });
+
+    await api.notes.stats({ id: "n_1" });
+    expect(method).toBe("POST");
+    expect(url).toBe("http://app.test/_oke/notes/stats");
+  });
+});