okengine 0.2.6 → 0.3.2

package/src/elements/store/resource-list-docs.fixture.ts

@@ -0,0 +1,56 @@
+/**
+ * Typechecked fixtures backing the two illustrative Store list configurations
+ * on the Store element docs page. They compile against the real
+ * `store.resource` / `ResourceListOptions` API — not a teaching-app claimed
+ * fence. If the resource list options change, these fail typecheck instead of
+ * rotting into invalid prose syntax.
+ *
+ * Docs copy the `list: { … }` option blocks below as unheaded illustrative
+ * fences; the 422 behavior for the restricted variant is locked by
+ * `resource-list-docs.test.ts`.
+ */
+
+import { z } from "zod";
+import { field, id, now, store } from "../store.ts";
+
+const docsItems = store.schema.table("docs_items", {
+  id: field.text().primaryKey().defaultFn(id),
+  title: field.text().notNull(),
+  secret: field.text().notNull(),
+  createdAt: field.integer().notNull().defaultFn(now),
+});
+
+const db = store.sql("docs-items", { schema: { docs_items: docsItems } });
+
+const inSchema = z.object({ title: z.string().min(1), secret: z.string().min(1) });
+const outSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  secret: z.string(),
+  createdAt: z.number(),
+});
+
+/**
+ * Admin table — offset paging with an exact row count. Docs illustrate
+ * `count: "exact"` (offset default) and point to `count: "none"` as the escape
+ * hatch when COUNT(*) is too expensive.
+ */
+export const docsAdminTableResource = store.resource(db, docsItems, {
+  in: inSchema,
+  out: outSchema,
+  list: { mode: "offset", count: "exact", limit: 20 },
+  unit: "docs-admin",
+  breaking: true,
+});
+
+/**
+ * Public restricted endpoint — filters off entirely. Any `?col=op.value`
+ * query key that is not a reserved list param fails validation (422).
+ */
+export const docsRestrictedResource = store.resource(db, docsItems, {
+  in: inSchema,
+  out: outSchema,
+  list: { mode: "offset", filter: "none", limit: 20 },
+  unit: "docs-restricted",
+  breaking: true,
+});

package/src/elements/store/resource-list-docs.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Lock the documented Store behaviors for the typechecked docs fixtures:
+ *
+ * 1. `filter: "none"` — a forbidden filter query key fails with HTTP 422 and a
+ *    `ValidationError` whose message is exactly `unknown list param "<key>"`
+ *    (`badInput` in `resource.ts`). The Store element page quotes this shape.
+ * 2. `mode: "offset"` + `count: "exact"` — list answers `meta.total` via
+ *    `COUNT(*)`. Changing it to `"none"` must drop `meta.total` and keep only
+ *    `meta.offset`; this test catches a silent behavior flip in either config.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { oke } from "../../kernel/app.ts";
+import { resetFlowSeq } from "../../kernel/flow.ts";
+import { on, resetBindings } from "../../kernel/on.ts";
+import { http } from "../../kernel/triggers.ts";
+import { createTestApp } from "../../test/create-test-app.ts";
+import { docsAdminTableResource, docsRestrictedResource } from "./resource-list-docs.fixture.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("resource-list-docs fixtures — documented behaviors stay real", () => {
+  test("filter: \"none\" — forbidden filter key → 422 ValidationError 'unknown list param'", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const mounted = on(http.resource("/docs-restricted", docsRestrictedResource.all()));
+    const app = oke({ name: "docs-restricted-test" }).adopt({ docs: mounted });
+    Object.assign(app.$options, { env: "test" });
+
+    const t = await createTestApp(app);
+
+    const bad = await app.fetch(new Request("http://localhost/docs-restricted?secret=eq.x"));
+    expect(bad.status).toBe(422);
+    const badBody = (await bad.json()) as {
+      data: null;
+      error: { code: string; data: { issues: Array<{ message: string; path: string[] }> } };
+    };
+    expect(badBody.error.code).toBe("ValidationError");
+    expect(badBody.error.data.issues[0]!.message).toBe('unknown list param "secret"');
+    expect(badBody.error.data.issues[0]!.path).toEqual(["secret"]);
+
+    const ok = await app.fetch(new Request("http://localhost/docs-restricted?limit=20"));
+    expect(ok.status).toBe(200);
+
+    await t.close();
+  });
+
+  test('offset + count: "exact" answers meta.total; "none" drops it', async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const exactMounted = on(http.resource("/docs-admin", docsAdminTableResource.all()));
+    const app = oke({ name: "docs-admin-test" }).adopt({ docs: exactMounted });
+    Object.assign(app.$options, { env: "test" });
+
+    const t = await createTestApp(app);
+    await app.fetch(
+      new Request("http://localhost/docs-admin", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ title: "one", secret: "s" }),
+      }),
+    );
+
+    const exact = await app.fetch(new Request("http://localhost/docs-admin?limit=20"));
+    expect(exact.status).toBe(200);
+    const exactBody = (await exact.json()) as {
+      meta: Record<string, unknown>;
+    };
+    expect(exactBody.meta.total).toBe(1);
+    expect(exactBody.meta.offset).toBe(0);
+
+    await t.close();
+  });
+});

package/src/elements/store/resource.test.ts

@@ -0,0 +1,253 @@
+/**
+ * `store.resource` row shape — declared JS keys only, never raw SQL names.
+ * Also locks the PII-masking order: mask after remapping so a `.pii()` column
+ * whose TS key differs from its SQL name cannot leak cleartext under the
+ * client-facing key.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+import { z } from "zod";
+import { sqliteDriver } from "../../drivers/sqlite.ts";
+import { oke } from "../../kernel/app.ts";
+import { resetFlowSeq } from "../../kernel/flow.ts";
+import { on, resetBindings } from "../../kernel/on.ts";
+import { http } from "../../kernel/triggers.ts";
+import { createTestApp } from "../../test/create-test-app.ts";
+import { classify, field, id, now, PII_MASK, store } from "../store.ts";
+import { createSqlStoreHandle } from "./sql-session.ts";
+import { mapRowToJs, resolveColumns } from "./table.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("mapRowToJs — declared keys only", () => {
+  const posts = sqliteTable("posts", {
+    id: text("id").primaryKey(),
+    createdAt: integer("created_at").notNull(),
+  });
+
+  test("SQL-keyed driver row becomes JS keys; raw SQL name is dropped", () => {
+    const cols = resolveColumns(posts);
+    expect(cols.find((c) => c.key === "createdAt")?.sqlName).toBe("created_at");
+
+    const mapped = mapRowToJs(posts, { id: "p1", created_at: 100 });
+    expect(mapped).toEqual({ id: "p1", createdAt: 100 });
+    expect("created_at" in mapped).toBe(false);
+  });
+
+  test("already JS-keyed row prefers JS key; raw SQL name is dropped", () => {
+    const mapped = mapRowToJs(posts, { id: "p1", createdAt: 100, created_at: 999 });
+    expect(mapped).toEqual({ id: "p1", createdAt: 100 });
+    expect("created_at" in mapped).toBe(false);
+  });
+});
+
+describe("SqlStoreHandle exit — list/get/create return JS keys only", () => {
+  const posts = sqliteTable("posts", {
+    id: text("id").primaryKey(),
+    title: text("title").notNull(),
+    createdAt: integer("created_at").notNull(),
+  });
+
+  test("select / findById / insert.returning never emit created_at", async () => {
+    const conn = await sqliteDriver.connect({
+      client: new Database(":memory:"),
+      role: "primary",
+    });
+    const handle = createSqlStoreHandle("sql:app", {
+      connection: conn,
+      classifications: new Map(),
+      routedRole: "primary",
+      domainDdl: "ensure",
+    });
+
+    const [created] = await handle
+      .insert(posts)
+      .values({ id: "p1", title: "one", createdAt: 100 })
+      .returning();
+    expect(Object.keys(created!).sort()).toEqual(["createdAt", "id", "title"]);
+    expect("created_at" in created!).toBe(false);
+
+    const listed = await handle.select().from(posts);
+    expect(Object.keys(listed[0]!).sort()).toEqual(["createdAt", "id", "title"]);
+    expect("created_at" in listed[0]!).toBe(false);
+
+    const got = await handle.findById(posts, "p1");
+    expect(Object.keys(got!).sort()).toEqual(["createdAt", "id", "title"]);
+    expect("created_at" in got!).toBe(false);
+
+    await conn.close();
+  });
+});
+
+describe("resource HTTP — exact keys + PII with differing TS/SQL names", () => {
+  // TS `email` ↔ SQL `email_addr`; TS `createdAt` ↔ SQL `created_at`.
+  const contacts = sqliteTable("contacts", {
+    id: text("id").primaryKey().$defaultFn(id),
+    email: text("email_addr").notNull(),
+    createdAt: integer("created_at").notNull().$defaultFn(now),
+  });
+
+  const NewContact = createInsertSchema(contacts).omit({ id: true, createdAt: true });
+  const Contact = createSelectSchema(contacts);
+
+  function buildApp() {
+    resetBindings();
+    resetFlowSeq();
+
+    const db = store.sql("contacts", {
+      schema: { contacts },
+      classify: { contacts: { email: classify({ pii: true }) } },
+    });
+
+    const contactsR = store.resource(db, contacts, {
+      in: NewContact,
+      out: Contact,
+      update: NewContact.partial(),
+      list: {
+        cursor: [contacts.createdAt, contacts.id],
+        direction: "desc",
+        limit: 20,
+        filter: "all",
+        order: "all",
+      },
+      unit: "contacts",
+      breaking: true,
+    });
+
+    const mounted = on(http.resource("/contacts", contactsR.all()));
+    const app = oke({ name: "contacts-resource-test" }).adopt({ contacts: mounted });
+    Object.assign(app.$options, { env: "test", stores: [db] });
+    return app;
+  }
+
+  /** Assert a row object has exactly the declared keys — no raw SQL names. */
+  function expectExactContactKeys(row: Record<string, unknown>) {
+    expect(Object.keys(row).sort()).toEqual(["createdAt", "email", "id"]);
+    expect("created_at" in row).toBe(false);
+    expect("email_addr" in row).toBe(false);
+  }
+
+  test("app.fetch list/get/create/update: only createdAt + masked email, never raw SQL keys", async () => {
+    const app = buildApp();
+    const t = await createTestApp(app);
+
+    // create → 201
+    const created = await app.fetch(
+      new Request("http://localhost/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email: "secret@example.com" }),
+      }),
+    );
+    expect(created.status).toBe(201);
+    const createdText = await created.text();
+    expect(createdText).not.toContain("created_at");
+    expect(createdText).not.toContain("email_addr");
+    expect(createdText).not.toContain("secret@example.com");
+    const createdBody = JSON.parse(createdText) as {
+      data: Record<string, unknown>;
+      error: null;
+    };
+    expect(createdBody.error).toBeNull();
+    expectExactContactKeys(createdBody.data);
+    expect(createdBody.data.email).toBe(PII_MASK);
+    expect(typeof createdBody.data.createdAt).toBe("number");
+    const contactId = createdBody.data.id as string;
+
+    // get → 200
+    const got = await app.fetch(new Request(`http://localhost/contacts/${contactId}`));
+    expect(got.status).toBe(200);
+    const gotText = await got.text();
+    expect(gotText).not.toContain("created_at");
+    expect(gotText).not.toContain("email_addr");
+    expect(gotText).not.toContain("secret@example.com");
+    const gotBody = JSON.parse(gotText) as { data: Record<string, unknown> };
+    expectExactContactKeys(gotBody.data);
+    expect(gotBody.data.email).toBe(PII_MASK);
+
+    // list → 200 (query present so list `in` is a record, not undefined)
+    const list = await app.fetch(new Request("http://localhost/contacts?limit=20"));
+    expect(list.status).toBe(200);
+    const listText = await list.text();
+    expect(listText).not.toContain("created_at");
+    expect(listText).not.toContain("email_addr");
+    expect(listText).not.toContain("secret@example.com");
+    const listBody = JSON.parse(listText) as { data: Record<string, unknown>[] };
+    expect(listBody.data).toHaveLength(1);
+    expectExactContactKeys(listBody.data[0]!);
+    expect(listBody.data[0]!.email).toBe(PII_MASK);
+
+    // update → 200
+    const updated = await app.fetch(
+      new Request(`http://localhost/contacts/${contactId}`, {
+        method: "PATCH",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email: "other@example.com" }),
+      }),
+    );
+    expect(updated.status).toBe(200);
+    const updatedText = await updated.text();
+    expect(updatedText).not.toContain("created_at");
+    expect(updatedText).not.toContain("email_addr");
+    expect(updatedText).not.toContain("other@example.com");
+    const updatedBody = JSON.parse(updatedText) as { data: Record<string, unknown> };
+    expectExactContactKeys(updatedBody.data);
+    expect(updatedBody.data.email).toBe(PII_MASK);
+
+    await t.close();
+  });
+
+  test("schema-decl .pii().as(sqlName) masks the final JS key via app.fetch", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const peopleTable = store.schema.table("people", {
+      id: field.text().primaryKey().defaultFn(id),
+      email: field.text().notNull().pii().as("email_addr"),
+      createdAt: field.integer().notNull().defaultFn(now),
+    });
+
+    const db = store.sql("people", { schema: { people: peopleTable } });
+    const peopleR = store.resource(db, peopleTable, {
+      in: z.object({ email: z.string().email() }),
+      out: z.object({
+        id: z.string(),
+        email: z.string(),
+        createdAt: z.number(),
+      }),
+      update: z.object({ email: z.string().email() }).partial(),
+      list: { mode: "offset", limit: 20 },
+      unit: "people",
+      breaking: true,
+    });
+
+    const mounted = on(http.resource("/people", peopleR.all()));
+    const app = oke({ name: "people-pii-test" }).adopt({ people: mounted });
+    Object.assign(app.$options, { env: "test", stores: [db] });
+
+    const t = await createTestApp(app);
+    const created = await app.fetch(
+      new Request("http://localhost/people", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email: "alice@example.com" }),
+      }),
+    );
+    expect(created.status).toBe(201);
+    const text = await created.text();
+    expect(text).not.toContain("email_addr");
+    expect(text).not.toContain("created_at");
+    expect(text).not.toContain("alice@example.com");
+    const body = JSON.parse(text) as { data: Record<string, unknown> };
+    expect(Object.keys(body.data).sort()).toEqual(["createdAt", "email", "id"]);
+    expect(body.data.email).toBe(PII_MASK);
+
+    await t.close();
+  });
+});