okengine 0.11.2 → 0.13.0

package/src/client/types.ts

@@ -120,25 +120,57 @@ export interface TransportError {
   readonly message?: string;
 }
 
+/** Next / previous list request — TanStack `pageParam` / URL bag. */
+export type ClientPagerLink = {
+  readonly cursor: string;
+};
+
 /**
- * Client call result — errors are values, never thrown for flow failures.
- * Success may carry an optional top-level `meta` (Stripe-style envelope,
- * e.g. paginated lists).
+ * Optional list pager on success `meta`. `next` / `prev` are request bags.
+ */
+export type ClientListMeta = {
+  readonly mode?: "offset" | "cursor";
+  readonly limit?: number;
+  readonly next?: ClientPagerLink | null;
+  readonly prev?: ClientPagerLink | null;
+  readonly total?: number;
+  readonly offset?: number;
+};
+
+/**
+ * Wire envelope — `{ data, error, meta? }` before pager methods attach.
  *
  * @typeParam O - Success data
  * @typeParam E - Declared error map
  */
-export type ClientResult<
+export type ClientEnvelope<
   O = unknown,
   E extends Record<string, unknown> = Record<string, unknown>,
 > =
   | {
       readonly data: O;
       readonly error: null;
-      readonly meta?: Record<string, unknown>;
+      readonly meta?: ClientListMeta;
     }
   | { readonly data: null; readonly error: ClientError<E> | TransportError };
 
+/**
+ * Client call result — envelope plus always-callable `next` / `prev`.
+ * Async-iterable: this page, then `next()`, stop when `meta.next` is null.
+ *
+ * @typeParam O - Success data
+ * @typeParam E - Declared error map
+ */
+export type ClientResult<
+  O = unknown,
+  E extends Record<string, unknown> = Record<string, unknown>,
+> = ClientEnvelope<O, E> & {
+  /** Next list page, or an empty success when there isn't one. */
+  readonly next: () => Promise<ClientResult<O, E>>;
+  /** Previous list page, or an empty success when there isn't one. */
+  readonly prev: () => Promise<ClientResult<O, E>>;
+} & AsyncIterable<ClientResult<O, E>>;
+
 /** Minimal fetch signature (avoids DOM `HeadersInit` / `preconnect` coupling). */
 export type ClientFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 
@@ -188,17 +220,33 @@ export interface ClientOptions {
 }
 
 /**
- * Call signature for one flow.
+ * `await list()` is one page; `for await (const page of list())` walks.
+ *
+ * @typeParam T - Page result
+ */
+export type ClientThenableIterable<T> = PromiseLike<T> & AsyncIterable<T>;
+
+/**
+ * Call signature for one flow — thenable (one page) and async-iterable (walk).
  *
  * @typeParam I - Input
  * @typeParam O - Output
  * @typeParam E - Errors
  */
-export type ClientCall<I, O, E extends Record<string, unknown>> = [I] extends [void]
-  ? () => Promise<ClientResult<O, E>>
+type ClientCallFn<I, O, E extends Record<string, unknown>> = [I] extends [void]
+  ? () => ClientThenableIterable<ClientResult<O, E>>
   : Partial<I> extends I
-    ? (input?: I) => Promise<ClientResult<O, E>>
-    : (input: I) => Promise<ClientResult<O, E>>;
+    ? (input?: I) => ClientThenableIterable<ClientResult<O, E>>
+    : (input: I) => ClientThenableIterable<ClientResult<O, E>>;
+
+/**
+ * Call signature for one flow. No `.pages()` — iterate the call or the page.
+ *
+ * @typeParam I - Input
+ * @typeParam O - Output
+ * @typeParam E - Errors
+ */
+export type ClientCall<I, O, E extends Record<string, unknown>> = ClientCallFn<I, O, E>;
 
 /**
  * Pull input from a contract shape (supports required or phantom-optional `in`).

package/src/compiler/aot.test.ts

@@ -1,6 +1,5 @@
 import { beforeEach, describe, expect, test } from "bun:test";
 import { z } from "zod";
-import { gate } from "../elements/gate.ts";
 import { oke } from "../kernel/app.ts";
 import { flow, resetFlowSeq } from "../kernel/flow.ts";
 import { on, resetBindings } from "../kernel/on.ts";
@@ -54,6 +53,17 @@ describe("sucrose — context inference", () => {
     expect(inference.params).toBe(true);
     expect(inference.body).toBe(false);
   });
+
+  test("QUERY enables body like POST", () => {
+    const inference = sucrose({
+      handler: ((input: { n: number }) => input) as never,
+      path: "/q",
+      method: "QUERY",
+      hasSchema: true,
+    });
+    expect(inference.body).toBe(true);
+    expect(inference.params).toBe(false);
+  });
 });
 
 describe("compileAot", () => {
@@ -119,7 +129,7 @@ describe("typed error narrowing end-to-end", () => {
     const FlightFull = z.object({ seatsLeft: z.number() });
 
     on(
-      http.post("/bookings").gate(gate.public),
+      http.post("/bookings").gate.public,
       flow("bookings.create", {
         in: Booking,
         out: z.object({ id: z.string() }),

package/src/compiler/effects-infer.ts

@@ -106,6 +106,7 @@ const READ_METHODS = new Set([
   "findFirst",
   "find",
   "list",
+  "ttlMs",
 ]);
 
 const WRITE_METHODS = new Set([
@@ -427,10 +428,18 @@ function tableFromStoreChain(
     if (!link || link.rootMethod !== "store") break;
     const leaf = link.methods[link.methods.length - 1]!;
     if (TABLE_ARG_METHODS.has(leaf)) {
-      const id = identifierName(c.arguments[0]);
-      if (id) {
-        const binding = bindings.get(id);
-        return binding?.kind === "table" ? binding.ref : id;
+      // KV / files / index take a key, not a table. Treating `delete(key)` as
+      // `delete(table)` stamps `kv:key` instead of `kv:drafts` and the runtime
+      // then throws OKE1002 on the real namespace.
+      const storeBinding = resolveBinding(link.rootCall.arguments[0], bindings);
+      if (storeBinding?.facet !== undefined && storeBinding.facet !== "sql") {
+        // keep walking — no table on this link
+      } else {
+        const id = identifierName(c.arguments[0]);
+        if (id) {
+          const binding = bindings.get(id);
+          return binding?.kind === "table" ? binding.ref : id;
+        }
       }
     }
     const callee = c.callee;

package/src/compiler/extract.test.ts

@@ -292,6 +292,8 @@ export const stripeKey = vault.secret("STRIPE_KEY", {
     });
     expect(manifest.stores?.embeddings?.description).toBe("Document embeddings");
     expect(manifest.stores?.sessions?.description).toBe("Session cache");
+    expect(manifest.stores?.sessions?.namespaces).toEqual(["sessions"]);
+    expect(manifest.stores?.sessions?.durable).toBeUndefined();
     expect(manifest.signals?.["order-placed"]?.description).toBe("Order placed event");
     expect(manifest.channels?.["booking-confirmed"]?.description).toBe(
       "Booking confirmation email",
@@ -300,6 +302,98 @@ export const stripeKey = vault.secret("STRIPE_KEY", {
     expect(manifest.gates?.member?.description).toBe("Verified members only");
     expect(manifest.vault?.STRIPE_KEY?.description).toBe("Payments gateway key");
   });
+
+  test("extracts store.kv durable onto the Manifest store", async () => {
+    const manifest = await extractFromSources({
+      "src/kv.ts": `
+import { store } from "okengine";
+export const sessions = store.kv("sessions", { description: "Session cache" });
+export const ledger = store.kv("ledger", { durable: true, description: "Idempotency keys" });
+`,
+    });
+    expect(manifest.stores?.sessions?.durable).toBeUndefined();
+    expect(manifest.stores?.ledger?.durable).toBe(true);
+    expect(manifest.stores?.ledger?.namespaces).toEqual(["ledger"]);
+  });
+});
+
+describe("extractManifest — bindNamedTableCrud(...)", () => {
+  test("expands the helper into unit-prefixed CRUD flows with table effects", async () => {
+    const source = `
+import { store } from "okengine";
+
+export const cycles = store.schema.table("cycles", {});
+
+export const { list, create, get, update, remove } = bindNamedTableCrud({
+  unit: "cycles",
+  path: "/cycles",
+  table: cycles,
+  liveList: true,
+});
+`;
+    const helper = `
+export function bindNamedTableCrud(spec) {
+  const unit = spec.unit;
+  const list = on(http.get("/x"), flow(\`\${unit}.list\`, { do: () => ({}) }));
+}
+`;
+    const manifest = await extractFromSources({
+      "src/lib/resource.ts": helper,
+      "src/flows/cycles/index.ts": source,
+    });
+
+    expect(manifest.flows?.["cycles.list"]?.trigger).toEqual({
+      http: { method: "GET", path: "/cycles" },
+    });
+    expect(manifest.flows?.["cycles.list"]?.live).toBe(true);
+    expect(manifest.flows?.["cycles.create"]?.trigger).toEqual({
+      http: { method: "POST", path: "/cycles" },
+    });
+    expect(manifest.flows?.["cycles.get"]?.trigger).toEqual({
+      http: { method: "GET", path: "/cycles/:id" },
+    });
+    expect(manifest.flows?.["cycles.update"]?.trigger).toEqual({
+      http: { method: "PATCH", path: "/cycles/:id" },
+    });
+    expect(manifest.flows?.["cycles.delete"]?.trigger).toEqual({
+      http: { method: "DELETE", path: "/cycles/:id" },
+    });
+    expect(manifest.flows?.["cycles.list"]?.effects?.reads).toEqual(["sql:cycles"]);
+    expect(manifest.flows?.["cycles.create"]?.effects?.writes).toEqual(["sql:cycles"]);
+    expect(manifest.flows?.list).toBeUndefined();
+  });
+
+  test("expands bindCrud the same as bindNamedTableCrud", async () => {
+    const source = `
+import { store } from "okengine";
+
+export const documents = store.schema.table("documents", {});
+
+export const { list, get, update, remove } = bindCrud({
+  unit: "documents",
+  path: "/documents",
+  table: documents,
+});
+`;
+    const helper = `
+export function bindCrud(spec) {
+  const unit = spec.unit;
+  const list = on(http.get("/x"), flow(\`\${unit}.list\`, { do: () => ({}) }));
+}
+`;
+    const manifest = await extractFromSources({
+      "src/lib/resource.ts": helper,
+      "src/flows/documents/index.ts": source,
+    });
+
+    expect(manifest.flows?.["documents.list"]?.effects?.reads).toEqual(["sql:documents"]);
+    expect(manifest.flows?.["documents.get"]?.effects?.reads).toEqual(["sql:documents"]);
+    expect(manifest.flows?.["documents.update"]?.effects).toEqual({
+      reads: ["sql:documents"],
+      writes: ["sql:documents"],
+    });
+    expect(manifest.flows?.list).toBeUndefined();
+  });
 });
 
 describe("extractManifest — on(http.resource(...))", () => {
@@ -309,7 +403,7 @@ import { on, http, store } from "okengine";
 
 export const db = store.sql("notes", { schema: {} });
 
-const notesR = store.resource(db, {}, { unit: "notes", breaking: true });
+const notesR = store.resource(db, {}, { breaking: true });
 
 const mounted = on(http.resource("/notes", notesR.all()));
 
@@ -340,6 +434,71 @@ export const remove = mounted.remove;
     expect(manifest.flows?.create?.effects?.writes).toEqual(["sql:notes"]);
     expect(manifest.flows?.list?.breaking).toBe(true);
   });
+
+  test("chains .gate(...) and .live() onto the five verbs", async () => {
+    const source = `
+import { on, http, store, gate } from "okengine";
+
+export const member = gate.policy("member", ({ auth }) => !!auth.verified);
+export const db = store.sql("notes", { schema: {} });
+
+const notesR = store.resource(db, {}, {});
+
+const mounted = on(http.resource("/notes", notesR.all()).gate(member).live());
+
+export const list = mounted.list;
+export const create = mounted.create;
+export const get = mounted.get;
+export const update = mounted.update;
+export const remove = mounted.remove;
+`;
+    const manifest = await extractFromSources({ "src/flows/notes.ts": source });
+
+    expect(manifest.flows?.list?.gates).toEqual(["member"]);
+    expect(manifest.flows?.create?.gates).toEqual(["member"]);
+    expect(manifest.flows?.get?.gates).toEqual(["member"]);
+    expect(manifest.flows?.update?.gates).toEqual(["member"]);
+    expect(manifest.flows?.remove?.gates).toEqual(["member"]);
+    expect(manifest.flows?.list?.live).toBe(true);
+    expect(manifest.flows?.get?.live).toBe(true);
+    expect(manifest.flows?.create?.live).toBeUndefined();
+    expect(manifest.flows?.update?.live).toBeUndefined();
+    expect(manifest.flows?.remove?.live).toBeUndefined();
+  });
+});
+
+describe("extractManifest — vault.config", () => {
+  test("fx.vault.get(config) infers the contract name, not the binding id", async () => {
+    const core = `
+export const publicAppUrl = vault.config("PUBLIC_APP_URL", {
+  description: "Public origin",
+  dev: "http://127.0.0.1:6530",
+});
+`;
+    const source = `
+import { publicAppUrl } from "@/core";
+
+export const list = on(
+  http.get("/issues").gate(member),
+  flow("issues.list", {
+    do: async (_input, fx) => {
+      await fx.vault.get(publicAppUrl);
+      return { items: [] };
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({
+      "src/core.ts": core,
+      "src/flows/issues/index.ts": source,
+    });
+
+    expect(manifest.vault?.PUBLIC_APP_URL).toMatchObject({
+      description: "Public origin",
+      sensitive: false,
+    });
+    expect(manifest.flows?.["issues.list"]?.effects?.secrets).toEqual(["PUBLIC_APP_URL"]);
+  });
 });
 
 describe("extractManifest — files-store write methods", () => {
@@ -350,7 +509,7 @@ import { on, flow, http, gate, store } from "okengine";
 export const files = store.files("uploads");
 
 export const attach = on(
-  http.post("/attach").gate(gate.public),
+  http.post("/attach").gate.public,
   flow("notes.attach", {
     do: async (input, fx) => {
       await fx.store(files).put("key", input.text);
@@ -371,7 +530,7 @@ import { on, flow, http, gate, store } from "okengine";
 export const files = store.files("uploads");
 
 export const attach = on(
-  http.post("/attach").gate(gate.public),
+  http.post("/attach").gate.public,
   flow("notes.attachImage", {
     do: async (input, fx) => {
       await fx.store(files).putImage("key", input.bytes);
@@ -407,6 +566,38 @@ export const sweep = on(
   });
 });
 
+describe("extractManifest — kv key methods", () => {
+  test("fx.store(kv).delete(key) writes kv:<namespace>, not kv:<identifier>", async () => {
+    const source = `
+import { on, flow, every, store, signal } from "okengine";
+
+export const draftsKv = store.kv("drafts");
+export const draftExpired = signal("draft-expired", { delivery: "broadcast", retries: 0, deadLetter: false });
+
+export const expire = on(
+  every("10m"),
+  flow("drafts.expire", {
+    do: async (_input, fx) => {
+      const keys = await fx.store(draftsKv).list();
+      for (const key of keys) {
+        const ttl = await fx.store(draftsKv).ttlMs(key);
+        if (ttl !== null && ttl <= 0) {
+          await fx.store(draftsKv).delete(key);
+          await fx.emit(draftExpired, { id: key });
+        }
+      }
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/drafts.ts": source });
+    const effects = manifest.flows?.["drafts.expire"]?.effects;
+    expect(effects?.reads).toEqual(["kv:drafts"]);
+    expect(effects?.writes).toEqual(["kv:drafts"]);
+    expect(effects?.emits).toEqual(["draft-expired"]);
+  });
+});
+
 describe("extractManifest — channel medium binder aliasing", () => {
   test("mail.template(...) resolves through `const mail = channel.email(...)`", async () => {
     const source = `
@@ -419,7 +610,7 @@ export const noteCreatedMail = mail.template("note-created", {
 });
 
 export const onCreated = on(
-  http.post("/hook").gate(gate.public),
+  http.post("/hook").gate.public,
   flow("notes.onCreated", {
     do: async (payload, fx) => {
       await fx.send(noteCreatedMail, { to: "you@localhost", data: payload });
@@ -442,7 +633,7 @@ const otp = channel.sms({});
 export const otpTemplate = otp.template("otp-code", {});
 
 export const send = on(
-  http.post("/otp").gate(gate.public),
+  http.post("/otp").gate.public,
   flow("notes.sendOtp", {
     do: async (payload, fx) => {
       await fx.send(otpTemplate, { to: "+10000000000", data: payload });
@@ -524,3 +715,64 @@ export const decoy = flow("checkout.realName", {
     expect(manifest.flows?.["checkout.decoyName"]).toBeUndefined();
   });
 });
+
+describe("extractManifest — .gate.public", () => {
+  test("reads the public sentinel from a member chain", async () => {
+    const source = `
+import { on, flow, http } from "okengine";
+
+export const health = on(
+  http.get("/health").gate.public,
+  flow("health.check", { do: () => ({ ok: true }) }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/health.ts": source });
+    expect(manifest.flows?.["health.check"]?.gates).toEqual(["public"]);
+  });
+});
+
+describe("extractManifest — gate.all", () => {
+  test("catalogues the handle and expands .gate(write) onto the flow", async () => {
+    const source = `
+import { on, flow, http, gate } from "okengine";
+
+export const member = gate.policy("member", ({ auth }) => !!auth.verified);
+export const canBook = gate.scope("booking:create");
+export const fair = gate.rate({ max: 60, per: "1m", keyBy: "ip" });
+export const write = gate.all(member, canBook, fair);
+
+export const create = on(
+  http.post("/bookings").gate(write),
+  flow("bookings.create", { do: () => ({ ok: true }) }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/bookings.ts": source });
+    expect(manifest.gates?.write).toEqual({
+      kind: "all",
+      members: ["member", "booking:create", "rate:sliding-window-counter:60/1m"],
+    });
+    expect(manifest.flows?.["bookings.create"]?.gates).toEqual([
+      "member",
+      "booking:create",
+      "rate:sliding-window-counter:60/1m",
+    ]);
+  });
+
+  test("expands .gate(...WRITE) from a const array", async () => {
+    const source = `
+import { on, flow, http, gate } from "okengine";
+
+export const member = gate.policy("member", ({ auth }) => !!auth.verified);
+export const canBook = gate.scope("booking:create");
+const WRITE = [member, canBook] as const;
+
+export const create = on(
+  http.post("/bookings").gate(...WRITE),
+  flow("bookings.create", { do: () => ({ ok: true }) }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/bookings.ts": source });
+    expect(manifest.flows?.["bookings.create"]?.gates).toEqual(["member", "booking:create"]);
+    expect(manifest.gates?.WRITE).toBeUndefined();
+  });
+});