esoul-sdk 0.3.0 → 0.6.0

package/dist/db/memory-client.d.ts

@@ -0,0 +1,136 @@
+/**
+ * THE IN-MEMORY CLIENT — an author's unit tests, and the workbench box.
+ *
+ * Storage is an array per model. Every DECISION — which keys may be filtered,
+ * what scope means, who may write which fields, what a new row is stamped
+ * with, when a ref crosses scope — comes from `./client-core`, which the
+ * Prisma client shares. What is left here is honest storage: evaluate a
+ * filter over JS values, sort, page, mutate arrays, snapshot for a rollback.
+ *
+ * The one behaviour that is this client's alone: a sealed field is stored in
+ * clear (there is nothing to protect in a test's memory) and BLANKED on read
+ * for anyone who may not unseal it. Production seals at rest and unseals for
+ * the same set of readers; the differential test holds the two to the same
+ * visible result.
+ */
+import { type CompiledRules, type RuleViewer } from "./compile-rules.js";
+import { type Refuse, type Row } from "./client-core.js";
+export type { Refuse, RefuseCode, Row } from "./client-core.js";
+export interface FindManyArgs {
+    where?: Record<string, unknown>;
+    orderBy?: Record<string, "asc" | "desc"> | Record<string, "asc" | "desc">[];
+    take?: number;
+    skip?: number;
+    cursor?: {
+        id: string;
+    };
+    includeDeleted?: boolean;
+}
+export interface AggregateArgs {
+    where?: Record<string, unknown>;
+    _count?: true;
+    _sum?: Record<string, true>;
+    _avg?: Record<string, true>;
+    _min?: Record<string, true>;
+    _max?: Record<string, true>;
+}
+export interface GroupByArgs extends AggregateArgs {
+    by: string[];
+}
+export interface Collection {
+    findMany(args?: FindManyArgs): Promise<Row[]>;
+    findFirst(args?: FindManyArgs): Promise<Row | null>;
+    findUnique(args: {
+        where: {
+            id: string;
+        };
+        includeDeleted?: boolean;
+    }): Promise<Row | null>;
+    count(args?: {
+        where?: Record<string, unknown>;
+        includeDeleted?: boolean;
+    }): Promise<number>;
+    aggregate(args?: AggregateArgs): Promise<Record<string, unknown>>;
+    groupBy(args: GroupByArgs): Promise<Record<string, unknown>[]>;
+    create(args: {
+        data: Row;
+    }): Promise<Row>;
+    createMany(args: {
+        data: Row[];
+    }): Promise<{
+        count: number;
+    }>;
+    update(args: {
+        where: {
+            id: string;
+        };
+        data: Row;
+    }): Promise<Row>;
+    updateMany(args: {
+        where?: Record<string, unknown>;
+        data: Row;
+    }): Promise<{
+        count: number;
+    }>;
+    upsert(args: {
+        where: {
+            id: string;
+        };
+        create: Row;
+        update: Row;
+    }): Promise<Row>;
+    delete(args: {
+        where: {
+            id: string;
+        };
+    }): Promise<Row>;
+    deleteMany(args?: {
+        where?: Record<string, unknown>;
+    }): Promise<{
+        count: number;
+    }>;
+}
+export interface PluginDbClient {
+    [model: string]: unknown;
+}
+/** Rows per model name. Shared by every client built over one store. */
+export interface MemoryStore {
+    rows: Record<string, Row[]>;
+    seq: number;
+}
+export declare function createStore(rules: CompiledRules): MemoryStore;
+export interface MemoryDbOptions {
+    rules: CompiledRules;
+    viewer: RuleViewer;
+    scope: {
+        workspaceId: string;
+        nodeId: string;
+    };
+    store?: MemoryStore;
+    /** Read across instances — owner-only / own-rows-only, never for writes. */
+    across?: "owned-instances" | "my-rows";
+    /** Workspaces this viewer owns, resolved by the PLATFORM, never by the app. */
+    ownedWorkspaceIds?: string[];
+    /** True when another app is reading this one through a binding. */
+    viaBinding?: boolean;
+    refuse?: Refuse;
+    now?: () => Date;
+    newId?: () => string;
+}
+export interface MemoryDb {
+    /**
+     * Model collections, keyed camelCase: `db.order`, `db.product`.
+     *
+     * `any` until the generator emits a per-app `.esoul/db.d.ts` (S5), which is
+     * what makes `where: { bogus: 1 }` a compile error. Typing it `unknown` here
+     * would only mean every author writes a cast in every test.
+     */
+    [model: string]: any;
+    /** The same store seen as somebody else — how a test checks isolation. */
+    as(viewer: RuleViewer, opts?: Partial<MemoryDbOptions>): MemoryDb;
+    $transaction<T>(fn: (tx: MemoryDb) => Promise<T>): Promise<T>;
+    $store: MemoryStore;
+}
+export declare function createMemoryDb(options: MemoryDbOptions): MemoryDb;
+/** Convenience: compile a manifest and hand back a client over a fresh store. */
+export declare function collectionKeys(rules: CompiledRules): string[];

package/dist/db/memory-client.js

@@ -0,0 +1,323 @@
+/**
+ * THE IN-MEMORY CLIENT — an author's unit tests, and the workbench box.
+ *
+ * Storage is an array per model. Every DECISION — which keys may be filtered,
+ * what scope means, who may write which fields, what a new row is stamped
+ * with, when a ref crosses scope — comes from `./client-core`, which the
+ * Prisma client shares. What is left here is honest storage: evaluate a
+ * filter over JS values, sort, page, mutate arrays, snapshot for a rollback.
+ *
+ * The one behaviour that is this client's alone: a sealed field is stored in
+ * clear (there is nothing to protect in a test's memory) and BLANKED on read
+ * for anyone who may not unseal it. Production seals at rest and unseals for
+ * the same set of readers; the differential test holds the two to the same
+ * visible result.
+ */
+import { camelKey } from "./compile-rules.js";
+import { assertFilterShape, assertFilterable, assertIncludeDeleted, assertNoInjectedKeys, assertRefTargets, assertUnique, checkWritableData, declaredValues, defaultRefuse, mayUnseal, orderTerms, ownerFilter, pageWindow, readPlan, scopeMatches, stampNewRow, writeGate, } from "./client-core.js";
+export function createStore(rules) {
+    const rows = {};
+    for (const name of Object.keys(rules.models))
+        rows[name] = [];
+    return { rows, seq: 0 };
+}
+/* ──────────────────────────── the client ──────────────────────────────── */
+export function createMemoryDb(options) {
+    const { rules, viewer, scope, across, ownedWorkspaceIds = [], viaBinding = false, refuse = defaultRefuse, } = options;
+    const store = options.store ?? createStore(rules);
+    const now = options.now ?? (() => new Date());
+    let idSeq = 0;
+    const newId = options.newId ?? (() => `row_${++idSeq}_${Math.random().toString(36).slice(2, 8)}`);
+    const db = {};
+    for (const model of Object.values(rules.models)) {
+        db[model.key] = makeCollection(model);
+    }
+    db.as = (v, opts) => createMemoryDb({ ...options, ...opts, viewer: v, store });
+    db.$store = store;
+    db.$transaction = async (fn) => {
+        // A snapshot restored on throw. Enough to prove all-or-nothing to an
+        // author; the real atomicity is the database's.
+        const snapshot = JSON.parse(JSON.stringify(store.rows));
+        try {
+            return await fn(db);
+        }
+        catch (err) {
+            store.rows = snapshot;
+            throw err;
+        }
+    };
+    return db;
+    /* ─────────────────────────── helpers ────────────────────────────── */
+    function coreFor(model) {
+        return { rules, model, viewer, scope, refuse, across, ownedWorkspaceIds, viaBinding };
+    }
+    /** Evaluate one `where` condition over a JS value — this client's half of filtering. */
+    function matchOne(value, cond) {
+        if (cond !== null && typeof cond === "object" && !(cond instanceof Date) && !Array.isArray(cond)) {
+            const c = cond;
+            for (const [op, operand] of Object.entries(c)) {
+                switch (op) {
+                    case "in":
+                        if (!Array.isArray(operand) || !operand.includes(value))
+                            return false;
+                        break;
+                    case "notIn":
+                        if (Array.isArray(operand) && operand.includes(value))
+                            return false;
+                        break;
+                    case "not":
+                        if (value === operand)
+                            return false;
+                        break;
+                    case "gt":
+                        if (!(cmp(value, operand) > 0))
+                            return false;
+                        break;
+                    case "gte":
+                        if (!(cmp(value, operand) >= 0))
+                            return false;
+                        break;
+                    case "lt":
+                        if (!(cmp(value, operand) < 0))
+                            return false;
+                        break;
+                    case "lte":
+                        if (!(cmp(value, operand) <= 0))
+                            return false;
+                        break;
+                    case "contains":
+                        if (typeof value !== "string" || !value.includes(String(operand)))
+                            return false;
+                        break;
+                    default:
+                        // Unreachable: `assertFilterShape` refused unknown operators first.
+                        return false;
+                }
+            }
+            return true;
+        }
+        return value === cond;
+    }
+    function cmp(a, b) {
+        const av = a instanceof Date ? a.getTime() : a;
+        const bv = b instanceof Date ? b.getTime() : b;
+        if (typeof av === "number" && typeof bv === "number")
+            return av - bv;
+        return String(av).localeCompare(String(bv));
+    }
+    /**
+     * Every read funnels through here: the caller's keys are validated, the read
+     * plan decides visibility, then scope → owner filter → soft-delete → the
+     * caller's own `where`. A row the caller may not see never reaches them, and
+     * never produces a refusal either — that is the whole point.
+     */
+    function visibleRows(c, args) {
+        const where = args?.where;
+        assertNoInjectedKeys(c, where, "where");
+        if (where)
+            assertFilterable(c, Object.keys(where), "where");
+        assertFilterShape(c, where);
+        assertIncludeDeleted(c, args?.includeDeleted);
+        const plan = readPlan(c);
+        if (!plan.visible)
+            return [];
+        let rows = (store.rows[c.model.name] ?? []).filter((r) => scopeMatches(c, r));
+        const own = ownerFilter(c, plan);
+        if (own)
+            rows = rows.filter((r) => r.ownerId && own.includes(String(r.ownerId)));
+        if (!args?.includeDeleted)
+            rows = rows.filter((r) => !r.deletedAt);
+        if (where)
+            rows = rows.filter((r) => Object.entries(where).every(([k, v]) => matchOne(r[k], v)));
+        return rows;
+    }
+    function sortRows(c, rows, orderBy) {
+        const terms = orderTerms(c, orderBy);
+        if (!terms.length)
+            return rows;
+        return [...rows].sort((a, b) => {
+            for (const t of terms) {
+                for (const [field, dir] of Object.entries(t)) {
+                    const d = cmp(a[field], b[field]);
+                    if (d !== 0)
+                        return dir === "desc" ? -d : d;
+                }
+            }
+            return 0;
+        });
+    }
+    /** Sealed fields are stored in clear here and BLANKED for anyone who may not unseal. */
+    function project(c, row) {
+        const out = { ...row };
+        if (!mayUnseal(c, row))
+            for (const f of c.model.sealed)
+                out[f] = null;
+        return out;
+    }
+    function page(c, rows, args) {
+        const { take, skip } = pageWindow(c, args);
+        let out = sortRows(c, rows, args?.orderBy);
+        if (args?.cursor) {
+            const at = out.findIndex((r) => r.id === args.cursor.id);
+            out = at >= 0 ? out.slice(at + 1) : [];
+        }
+        if (skip)
+            out = out.slice(skip);
+        return out.slice(0, take).map((r) => project(c, r));
+    }
+    /** The row a ref names, looked up RAW (rules do not apply to a scope check). */
+    async function lookupRaw(refModel, id) {
+        return (store.rows[refModel.name] ?? []).find((r) => r.id === id) ?? null;
+    }
+    function makeCollection(model) {
+        const c = coreFor(model);
+        const rowsOf = () => store.rows[model.name] ?? (store.rows[model.name] = []);
+        const bad = (detail) => refuse("invalid", "invalid", detail);
+        /** Update/delete find their target as a FILTER: not yours ⇒ not found, never "forbidden". */
+        const liveTarget = (id, ownerIn) => rowsOf().find((r) => r.id === id &&
+            scopeMatches(c, r) &&
+            !r.deletedAt &&
+            (!ownerIn || (r.ownerId && ownerIn.includes(String(r.ownerId)))));
+        return {
+            async findMany(args) {
+                return page(c, visibleRows(c, args), args);
+            },
+            async findFirst(args) {
+                return page(c, visibleRows(c, args), { ...args, take: 1 })[0] ?? null;
+            },
+            async findUnique(args) {
+                const rows = visibleRows(c, { where: { id: args.where.id }, includeDeleted: args.includeDeleted });
+                return rows[0] ? project(c, rows[0]) : null;
+            },
+            async count(args) {
+                return visibleRows(c, args).length;
+            },
+            async aggregate(args) {
+                const rows = visibleRows(c, args);
+                const out = {};
+                if (args?._count)
+                    out._count = rows.length;
+                const reduce = (spec, fn) => {
+                    if (!spec)
+                        return undefined;
+                    const res = {};
+                    for (const f of Object.keys(spec)) {
+                        if (!model.fields[f])
+                            bad(`${model.name}.aggregate: "${f}" is not a declared field`);
+                        const nums = rows.map((r) => Number(r[f])).filter((n) => !Number.isNaN(n));
+                        res[f] = nums.length ? fn(nums) : null;
+                    }
+                    return res;
+                };
+                const sum = reduce(args?._sum, (n) => n.reduce((a, b) => a + b, 0));
+                const avg = reduce(args?._avg, (n) => n.reduce((a, b) => a + b, 0) / n.length);
+                const min = reduce(args?._min, (n) => Math.min(...n));
+                const max = reduce(args?._max, (n) => Math.max(...n));
+                if (sum)
+                    out._sum = sum;
+                if (avg)
+                    out._avg = avg;
+                if (min)
+                    out._min = min;
+                if (max)
+                    out._max = max;
+                return out;
+            },
+            async groupBy(args) {
+                assertFilterable(c, args.by, "groupBy.by");
+                const rows = visibleRows(c, args);
+                const groups = new Map();
+                for (const r of rows) {
+                    const key = JSON.stringify(args.by.map((f) => r[f]));
+                    (groups.get(key) ?? groups.set(key, []).get(key)).push(r);
+                }
+                return [...groups.entries()].map(([key, rs]) => {
+                    const values = JSON.parse(key);
+                    const out = {};
+                    args.by.forEach((f, i) => (out[f] = values[i]));
+                    if (args._count)
+                        out._count = rs.length;
+                    for (const f of Object.keys(args._sum ?? {})) {
+                        out._sum = { ...out._sum, [f]: rs.reduce((a, r) => a + Number(r[f] ?? 0), 0) };
+                    }
+                    return out;
+                });
+            },
+            async create(args) {
+                const plan = writeGate(c, "create");
+                checkWritableData(c, args.data, plan.fields, "create");
+                const values = declaredValues(c, args.data);
+                await assertRefTargets(c, values, lookupRaw);
+                const row = { ...stampNewRow(c, now(), newId()), ...values };
+                await assertUnique(c, row, async (group, vals) => rowsOf().some((r) => scopeMatches(c, r) && !r.deletedAt && group.every((col, i) => r[col] === vals[i])));
+                rowsOf().push(row);
+                store.seq += 1;
+                return project(c, row);
+            },
+            async createMany(args) {
+                let count = 0;
+                for (const data of args.data) {
+                    await this.create({ data });
+                    count += 1;
+                }
+                return { count };
+            },
+            async update(args) {
+                const plan = writeGate(c, "update");
+                checkWritableData(c, args.data, plan.fields, "update");
+                await assertRefTargets(c, args.data, lookupRaw);
+                const target = liveTarget(args.where.id, plan.ownerIn);
+                if (!target)
+                    throw bad(`${model.name}.update: no row ${args.where.id}`);
+                Object.assign(target, args.data, { updatedAt: now() });
+                store.seq += 1;
+                return project(c, target);
+            },
+            async updateMany(args) {
+                const plan = writeGate(c, "update");
+                checkWritableData(c, args.data, plan.fields, "updateMany");
+                await assertRefTargets(c, args.data, lookupRaw);
+                const targets = visibleRows(c, { where: args.where }).filter((r) => !plan.ownerIn || (r.ownerId && plan.ownerIn.includes(String(r.ownerId))));
+                for (const t of targets)
+                    Object.assign(t, args.data, { updatedAt: now() });
+                store.seq += targets.length;
+                return { count: targets.length };
+            },
+            async upsert(args) {
+                const existing = await this.findUnique({ where: args.where });
+                if (existing)
+                    return this.update({ where: args.where, data: args.update });
+                return this.create({ data: args.create });
+            },
+            async delete(args) {
+                const plan = writeGate(c, "delete");
+                const target = liveTarget(args.where.id, plan.ownerIn);
+                if (!target)
+                    throw bad(`${model.name}.delete: no row ${args.where.id}`);
+                // A soft delete IS a modification: `updatedAt` moves. (The database
+                // would move it anyway through `@updatedAt`; the differential test
+                // caught the two clients disagreeing here, so both now say so.)
+                const at = now();
+                target.deletedAt = at;
+                target.updatedAt = at;
+                store.seq += 1;
+                return project(c, target);
+            },
+            async deleteMany(args) {
+                const plan = writeGate(c, "delete");
+                const targets = visibleRows(c, { where: args?.where }).filter((r) => !plan.ownerIn || (r.ownerId && plan.ownerIn.includes(String(r.ownerId))));
+                const at = now();
+                for (const t of targets) {
+                    t.deletedAt = at;
+                    t.updatedAt = at;
+                }
+                store.seq += targets.length;
+                return { count: targets.length };
+            },
+        };
+    }
+}
+/** Convenience: compile a manifest and hand back a client over a fresh store. */
+export function collectionKeys(rules) {
+    return Object.keys(rules.models).map(camelKey);
+}

package/dist/db/schema-gen.d.ts

@@ -0,0 +1,103 @@
+/**
+ * THE GENERATORS — a compiled `db` block turned into the two texts the
+ * platform needs from it: a Prisma schema fragment (the real tables) and a
+ * `.d.ts` (what the author's editor knows).
+ *
+ * Both are PURE and byte-deterministic: same `CompiledRules` in, same bytes
+ * out, every time. That is not tidiness. The fragment is committed for a
+ * vendored app and diffed on every install of a fetched one; the typings are
+ * what an author's `tsc` runs against. A generator that reordered a field or
+ * renamed an index between runs would produce a migration for nothing and a
+ * red build for nothing. Nothing here reads a clock, a random source, or the
+ * filesystem — it runs unchanged inside a workbench box.
+ *
+ * Decisions that are easy to undo by accident, so they are written down:
+ *
+ * - **A sealed field is always `String`.** Ciphertext at rest, whatever the
+ *   declared type. The declared type governs validation on write and the
+ *   parse on read; the column never sees plaintext.
+ * - **A `ref` is a `String`, not a relation.** It holds the target row's id.
+ *   No Prisma `@relation`: the target's SCOPE (same instance / same owner) is
+ *   what must be checked, and that is a client-side rule (spec Part C, S3),
+ *   not a foreign key — a foreign key would happily point at another shop's
+ *   row.
+ * - **A declared `unique` group is a plain `@@index`, not `@@unique`.**
+ *   Deletes are soft. A database-level unique would refuse re-creating a
+ *   SKU after its row was soft-deleted, and Prisma cannot express a partial
+ *   unique (`WHERE deletedAt IS NULL`). The client enforces uniqueness among
+ *   live rows. That leaves a race window between two concurrent creates — a
+ *   known v1 limitation, to be closed by a partial unique index emitted in the
+ *   DDL step, where raw SQL can say what Prisma's DSL cannot.
+ * - **Indexes lead with the scope column.** Every query the client issues is
+ *   narrowed to an instance (or workspace, or owner) FIRST, so every declared
+ *   index is emitted as `[scopeColumn, ...group]` — an index that does not
+ *   start with the scope column is one the planner cannot use for the query
+ *   the platform actually runs.
+ */
+import type { CompiledRules } from "./compile-rules.js";
+/** `ShipAddress` → `ship_address`; `Order` → `order`. */
+export declare function snakeCase(name: string): string;
+/** The Prisma model name: `plugin_shop_min__Order`. */
+export declare function prismaModelName(applicationType: string, model: string): string;
+/** The table it maps to: `plugin_shop_min__order`. */
+export declare function prismaTableName(applicationType: string, model: string): string;
+/**
+ * The Prisma schema fragment for one app — every model, platform columns
+ * first, scope-led indexes, mapped to a prefixed table. No datasource and no
+ * generator: this is a FRAGMENT that joins the platform's schema folder.
+ */
+export declare function prismaFragment(rules: CompiledRules, opts: {
+    applicationType: string;
+}): string;
+/**
+ * The `.esoul/db.d.ts` for one app: a `<Model>Row` and `<Model>Create` per
+ * model, a `<Model>Filterable` union that is exactly the compiled `filterable`
+ * list (so `where` and `orderBy` on an unindexed field are compile errors —
+ * the runtime rule, landed in the editor), and one `Collection` shape mirroring
+ * the memory client's method surface. Everything an author calls is typed with
+ * their own names; nothing here knows the table prefix.
+ */
+export declare function dbTypings(rules: CompiledRules, opts: {
+    typeName: string;
+}): string;
+/** The compiled artefact as the bytes `.esoul/rules.json` holds. */
+export declare function rulesJson(rules: CompiledRules): string;
+/**
+ * The SQL an app's tables need, emitted by us and not by Prisma's CLI: the
+ * install job runs where there is no CLI (an Inngest step on Vercel), and an
+ * UPDATE needs the difference between what is declared and what is LIVE, which
+ * only an introspection of the database can answer (the ledger records what
+ * was applied, not what the previous fragment was). So the declaration
+ * becomes table specs here; `lib/plugin-db/introspect.ts` reads the live
+ * tables and plans the additive difference; and a golden test pins these
+ * statements to Prisma's own `migrate diff` for the reference shop, so what
+ * we emit is what Prisma would.
+ */
+export interface TableColumn {
+    name: string;
+    /** Canonical Postgres type as Prisma spells it: TEXT, INTEGER, DOUBLE PRECISION, BOOLEAN, TIMESTAMP(3), JSONB, or one of those + `[]`. */
+    type: string;
+    nullable: boolean;
+    /** A SQL literal (`'new'`, `350`, `true`, `CURRENT_TIMESTAMP`) or null. */
+    default: string | null;
+}
+export interface TableIndex {
+    name: string;
+    columns: string[];
+}
+export interface TableSpec {
+    name: string;
+    columns: TableColumn[];
+    indexes: TableIndex[];
+}
+/** Prisma's index name: `<table>_<col>_<col>_idx`. */
+export declare function indexName(table: string, columns: string[]): string;
+/** Every table an app declares, as columns and indexes — the input to the planner and the emitter. */
+export declare function tableSpecs(rules: CompiledRules, opts: {
+    applicationType: string;
+}): TableSpec[];
+export declare function createTableSql(t: TableSpec): string;
+export declare function createIndexSql(table: string, idx: TableIndex): string;
+export declare function addColumnSql(table: string, c: TableColumn): string;
+/** The whole script for a fresh install: tables first, then every index — Prisma's order. */
+export declare function ddlStatements(specs: TableSpec[]): string[];