litedbmodel 2.0.0 → 2.0.2

package/dist/scp/write-runtime.js

@@ -1,167 +0,0 @@
-"use strict";
-/**
- * litedbmodel v2 SCP — write-time transaction runtime (WS5, #25; spec §6 / §3 / §11).
- *
- * Executes a derived {@link TransactionPlan} against REAL SQLite as ONE transaction with
- * gate-first short-circuit (spec §6). It renders each ordered statement with the SAME normative
- * {@link renderOperation} the read path uses (fragment tree + Expression-IR param slots), and
- * drives an explicit `BEGIN` / `COMMIT` / `ROLLBACK` envelope through the SAME synchronous
- * driver seam ({@link SqliteDb}) the WS3 runtime uses — no mock, no separate interpreter.
- *
- * ## The transaction envelope (spec §6) — Tx is derived, not authored
- *
- *   BEGIN;
- *     for each ordered statement:
- *       render (input + accumulated $.entity row) → execute REAL SQL
- *       if it is a GATE and its rule FAILS  → ROLLBACK and stop (remaining SQL never runs)
- *   COMMIT;   (or ROLLBACK on a driver failure / gate fail)
- *
- * The body write's RETURNING row is captured and exposed to the derive/edges/emits stages under
- * `$.entity.*` ({@link ENTITY_ROOT}) — the §6 example's `$.entity.id`.
- *
- * ## Gate-first is a REAL behavior (spec §6 "Gate First"), proven, not textual
- *
- * A gate statement's {@link GateRule} is evaluated on its actual driver result:
- *   - `existsElseRollback` — `SELECT 1 …` returned ZERO rows ⇒ the required row is absent ⇒
- *     ROLLBACK; the body + all later statements are NEVER prepared/executed (a real query-count
- *     drop, observable via a counting driver, and the DB is unchanged).
- *   - `insertedElseRollback` — a `unique` guard `INSERT … ON CONFLICT DO NOTHING` affected ZERO
- *     rows ⇒ a collision ⇒ ROLLBACK.
- *   - `insertedElseNoop` — an `idempotency` token INSERT affected ZERO rows ⇒ a DUPLICATE request
- *     ⇒ short-circuit as a no-op: ROLLBACK the (empty-so-far) transaction, so a duplicate
- *     `request_id` performs NO double write (idempotent).
- *
- * A short-circuit returns a structured {@link TransactionResult} (`committed:false`) rather than
- * throwing — the caller distinguishes a legitimate gate outcome (absent requires / unique
- * collision / duplicate) from a driver Failure (which IS mapped + thrown, spec §11 item 5).
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.executeTransaction = executeTransaction;
-exports.countingDriver = countingDriver;
-const render_1 = require("./render");
-const errors_1 = require("./errors");
-const writes_1 = require("./writes");
-const dialect_1 = require("./dialect");
-/** bc evaluates ints to bigint; convert a rendered param to a driver-bindable value. */
-function toDriverParam(v) {
-    if (typeof v === 'bigint') {
-        if (v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER))
-            return Number(v);
-        return v;
-    }
-    // An emit payload evaluates to a plain object (`{obj:{…}}`); serialize it to the outbox JSON
-    // text column. Arrays are IN-list elements (not used in the write path); pass through.
-    if (v !== null && typeof v === 'object' && !Array.isArray(v))
-        return JSON.stringify(v);
-    return v;
-}
-/**
- * Execute one statement's compiled op against the driver in the given scope, returning the
- * rows (SELECT / RETURNING) plus the affected-row count (non-returning writes). A driver error
- * is mapped and thrown (the caller ROLLBACKs). This is the SAME render→bind→execute pipeline as
- * the WS3 read/write handlers; only the transaction envelope + gate interpretation is new.
- */
-function execStatement(db, op, scope, dialect) {
-    const rendered = (0, render_1.renderOperation)(op, scope, dialect);
-    const params = rendered.params.map(toDriverParam);
-    const stmt = db.prepare(rendered.sql);
-    const hasReturn = op.component === 'Select' || /\breturning\b/i.test(rendered.sql);
-    if (hasReturn) {
-        const rows = stmt.all(...params);
-        return { rows, changes: rows.length };
-    }
-    const info = stmt.run(...params);
-    return { rows: [], changes: info.changes };
-}
-/** Evaluate a gate rule on a statement result → the short-circuit reason, or null to continue. */
-function gateShortCircuit(gate, result) {
-    switch (gate) {
-        case 'existsElseRollback':
-            return result.rows.length === 0 ? 'requires_absent' : null;
-        case 'insertedElseRollback':
-            return result.changes === 0 ? 'unique_collision' : null;
-        case 'insertedElseNoop':
-            return result.changes === 0 ? 'idempotent_duplicate' : null;
-    }
-}
-/**
- * Execute a derived {@link TransactionPlan} as ONE real SQLite transaction with gate-first
- * short-circuit (spec §6). Statements run in the plan's fixed order (requires → idempotency →
- * unique → body → derive → edges → emits); a failing gate ROLLBACKs and the remaining statements
- * are never executed. On success COMMITs and returns the `$.entity` RETURNING row.
- *
- * @param db     the synchronous SQLite driver (better-sqlite3 `Database`), supporting `BEGIN` /
- *               `COMMIT` / `ROLLBACK` via `prepare(...).run()`.
- * @param plan   the derived transaction plan (pure JSON; from `deriveTransactionPlan` or the bundle).
- * @param input  the Command input scope (`$.input.*` = bc flat scope).
- * @throws {SqlFailure} a mapped driver failure (the transaction is ROLLBACKed first, spec §11).
- */
-function executeTransaction(db, plan, input, dialect = dialect_1.SQLITE) {
-    db.prepare('BEGIN').run();
-    const executed = [];
-    // The evolving scope: input names at the top level (bc flat scope) + the body RETURNING row
-    // exposed under `__entity` once the body runs. Defaults live in the declaration/schema, so no
-    // ad-hoc code default is injected here.
-    const scope = { ...input };
-    let entity = null;
-    try {
-        for (const stmt of plan.statements) {
-            const result = runOne(db, stmt, scope, executed, dialect);
-            // Gate-first: a failing gate short-circuits — ROLLBACK and STOP (tail never executes).
-            if (stmt.gate !== undefined) {
-                const reason = gateShortCircuit(stmt.gate, result);
-                if (reason !== null) {
-                    db.prepare('ROLLBACK').run();
-                    return { committed: false, shortCircuit: { statementId: stmt.id, reason }, entity: null, executed };
-                }
-            }
-            // Capture the SOLE body RETURNING row as `$.entity` (WS5 single-write back-compat).
-            if (stmt.id === plan.entityFrom) {
-                entity = result.rows.length > 0 ? result.rows[0] : null;
-                if (entity !== null)
-                    scope[writes_1.ENTITY_ROOT] = entity;
-            }
-            // Composite (WS8a): bind THIS statement's RETURNING row under its `binds` name so a later
-            // `$.ref.<binds>.<field>` resolves against it (the DAG's data-dependency edge). Self-
-            // describing: the runtime just binds the row the plan told it to — no re-derivation.
-            if (stmt.binds !== undefined && result.rows.length > 0) {
-                scope[stmt.binds] = result.rows[0];
-            }
-        }
-        db.prepare('COMMIT').run();
-        return { committed: true, entity, executed };
-    }
-    catch (e) {
-        // A driver failure: ROLLBACK, then map + re-throw the structured SqlFailure (spec §11).
-        try {
-            db.prepare('ROLLBACK').run();
-        }
-        catch {
-            /* ROLLBACK best-effort; surface the original failure below */
-        }
-        throw (0, errors_1.mapSqliteError)(e);
-    }
-}
-/** Render + execute one statement, recording it as executed. */
-function runOne(db, stmt, scope, executed, dialect) {
-    const result = execStatement(db, stmt.op, scope, dialect);
-    executed.push(stmt.id);
-    return result;
-}
-/**
- * A counting {@link SqliteDb} wrapper: forwards every call to the wrapped driver but records
- * each PREPARED SQL string. Tests use it to PROVE gate-first short-circuit — after an absent
- * `requires`, the body/derive/edges/emits SQL is never prepared (a real, observable query-count
- * drop), not merely absent from a text list. This is a test aid living beside the runtime.
- */
-function countingDriver(db) {
-    const prepared = [];
-    const wrapped = {
-        prepare(sql) {
-            prepared.push(sql);
-            return db.prepare(sql);
-        },
-    };
-    return { db: wrapped, prepared };
-}
-//# sourceMappingURL=write-runtime.js.map

package/dist/scp/write-runtime.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"write-runtime.js","sourceRoot":"","sources":["../../src/scp/write-runtime.ts"],"names":[],"mappings":"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"}