litedbmodel 2.0.2 → 2.2.0

package/dist/scp/makesql/static-bundle.d.ts

@@ -1,187 +0,0 @@
-/**
- * litedbmodel v2 SCP — the STATIC, PORTABLE `makeSQL` bundle + its runtime (epic #43/#45
- * Phase B; design #45 owner-confirmed static-bundle decision).
- *
- * This is the SOLE read/compile path of the makeSQL SCP model, expressed as a compile step
- * that is **symbolic** (no concrete input needed) and a runtime that evaluates value-specs +
- * skip PER-INPUT via behavior-contracts. It REPLACES the reduced-spine `../runtime.ts`
- * `SqlBundle`/`compileBundle`/`executeBundle` for the read path.
- *
- * ## The static bundle shape (design #45)
- *
- * A compiled behavior method is a bundle of ordered {@link StaticStatement} — each a
- * `makeSQL` TEMPLATE:
- *   - `sql`    — tuned dialect SQL text (`?` placeholders), COMPLETE and value-independent
- *                (compiled ONCE; the single-JSON-param array forms + PG `= ANY`/UNNEST keep
- *                the text fixed regardless of the runtime array length — no per-input text).
- *   - `params` — value-specs = bc Expression IR (`{ref:[…]}` / small ops / literals), 1:1 with
- *                the top-level `?`, evaluated AT RUNTIME by bc `evaluateExpression`.
- *   - `skip?`  — a bc presence expression, evaluated at runtime; when truthy the whole
- *                statement (its `sql` and `params`) drops (contributes NOTHING).
- *
- * So the compile step emits a reusable portable artifact; the runtime (this module's
- * {@link executeStaticBundle}) evaluates skip + params per-input via bc, assembles present
- * fragments, renders placeholders, and executes. This unifies read/write/codegen on ONE
- * `SqlBundle` shape and enables multi-language IR-reference execution.
- *
- * ## Symbolic compile — reuses `authoring-compile`'s port decoding, defers evaluation
- *
- * Phase A's `authoring-compile.ts` compiled per-input EAGERLY (it called `evaluateExpression`
- * on every value slot to produce concrete `{sql, params}`). Here we keep the SAME closed-set
- * port decoding (`../bridge.ts` operators, IN-sentinel, SKIP-`cond` collapse) but DEFER the
- * value/skip evaluation to the runtime: a where-member's value operand stays as its raw bc
- * Expression IR, a SKIP-`cond` guard becomes the statement's `skip` expression, and the SQL
- * text is emitted once.
- */
-import { type Scope, type Value, type ComponentGraphIR } from 'behavior-contracts';
-import type { ComponentRefNode, MapNode, BehaviorModelContract } from '../authoring';
-import { type Dialect } from './handler';
-import { type FindFilterSource } from '../find-filter-guard';
-import type { ColumnTypeResolver } from '../coltype';
-/** A closed-set bc Expression IR node used as a deferred value-spec or a skip expression. */
-export type ValueSpec = unknown;
-/**
- * One statement of a static bundle — a `makeSQL` TEMPLATE. `sql` is the complete tuned SQL
- * text (`?` placeholders, value-independent); `params` are deferred value-specs (bc
- * Expression IR) evaluated at runtime; `skip`, when present, is a bc presence expression
- * evaluated at runtime (truthy ⇒ drop the whole statement).
- */
-export interface StaticStatement {
-    /** Complete tuned SQL text (`?` placeholders). */
-    readonly sql: string;
-    /** Deferred value-specs — closed-set bc Expression IR, 1:1 with the top-level `?`. */
-    readonly params: readonly ValueSpec[];
-    /** Optional bc presence expression; truthy ⇒ the whole statement drops. */
-    readonly skip?: ValueSpec;
-    /**
-     * A WHERE-clause fragment: its `sql` is a bare predicate body (no leading connector). The
-     * runtime prepends ` WHERE ` to the FIRST present fragment and ` AND ` to each later one, so
-     * a skipped fragment never leaves a dangling connector. A statement WITHOUT this flag emits
-     * its `sql` verbatim.
-     */
-    readonly whereFragment?: true;
-}
-/**
- * The static, portable compiled artifact of ONE authored behavior method (the read path).
- * Pure JSON — every statement's `sql` is fixed text and its `params`/`skip` are bc Expression
- * IR, so `JSON.stringify` round-trips losslessly and a per-language runtime can execute it
- * with bc + a SQL driver alone.
- */
-export interface StaticBundle {
-    readonly dialect: Dialect;
-    /** The behavior (component) name. */
-    readonly name: string;
-    /** Ordered `makeSQL` statement templates composed into the read query. */
-    readonly statements: readonly StaticStatement[];
-    /** Input heads normalized to present-as-null (absent-key SKIP; SSoT-driven). */
-    readonly optionalHeads: readonly string[];
-}
-type RefLike = ComponentRefNode | MapNode;
-/**
- * Compile ONE authored `Select` node into its static `makeSQL` statement templates:
- * the head `SELECT … FROM t` fragment plus one guarded WHERE fragment per member, then the
- * trailing GROUP BY / ORDER BY / LIMIT / OFFSET tail. The head + GROUP BY + ORDER BY TEXT is
- * produced by the ORIGINAL `compileSelect` (which reproduces `_buildSelectSQL` byte-for-byte),
- * never a v2 hand-roll. LIMIT/OFFSET are INLINE literals in v1; for the static bundle they are
- * deferred value-specs bound as `?` (a portable equivalent a per-language runtime renders
- * identically) — evaluated at runtime.
- */
-export declare function compileSelectNode(node: RefLike, dialect: Dialect): StaticStatement[];
-/**
- * Compile the primary CRUD query of an authored behavior method into a {@link StaticBundle}.
- * Relation `.map` nodes are NOT part of the primary bundle (they are the read-relations concern
- * — step 3, still on the reduced spine). The compile is SYMBOLIC (no concrete input); the runtime
- * ({@link executeStaticBundle} for reads / {@link executeStaticWrite} for writes) evaluates skip +
- * value-specs per-input.
- */
-export declare function compileStaticBundle(contract: BehaviorModelContract, dialect: Dialect, entry?: string): StaticBundle;
-/** The minimal synchronous SQLite driver surface (better-sqlite3 `Database`). */
-export interface SqliteDb {
-    prepare(sql: string): {
-        all(...params: unknown[]): unknown[];
-        run(...params: unknown[]): {
-            changes: number;
-            lastInsertRowid: number | bigint;
-        };
-    };
-}
-/**
- * Execute a {@link StaticBundle} read query end-to-end against real SQLite: normalize optional
- * heads, evaluate skip + value-specs per-input, assemble present fragments, render, and run the
- * SELECT. Returns the row list.
- */
-export declare function executeStaticBundle(bundle: StaticBundle, input: Scope, db: SqliteDb): Record<string, unknown>[];
-/**
- * Execute a single-statement WRITE {@link StaticBundle} (Insert/Update/Delete) against real
- * SQLite: evaluate the deferred value-specs per-input, render, and run the statement. A statement
- * with a RETURNING tail returns its rows; a non-returning write returns a single-row summary
- * `[{ changes, lastInsertRowid }]`. A driver error maps to a {@link SqlFailure} at the boundary.
- * (A Command with write-time relations rides the tx-DAG plan of `./tx`, not this path.)
- */
-export declare function executeStaticWrite(bundle: StaticBundle, input: Scope, db: SqliteDb): Record<string, unknown>[];
-/**
- * The compiled, portable READ graph of a behavior method: the surrogate bc `ComponentGraphIR`
- * (each SQL node → a `makeSQL` node with one `__scope` port; wiring / map / Φ output preserved)
- * plus the per-node static statement templates and the optional heads. Pure JSON —
- * `JSON.stringify` round-trips, so a per-language runtime executes it with bc + a SQL driver.
- */
-export interface ReadGraph {
-    readonly dialect: Dialect;
-    readonly name: string;
-    /** The surrogate bc IR (catalog nodes → `makeSQL` `__scope`-port nodes). */
-    readonly ir: ComponentGraphIR;
-    /** Per-node static `makeSQL` statement templates, keyed by body node id. */
-    readonly statementsById: Record<string, readonly StaticStatement[]>;
-    /** Input heads normalized to present-as-null (absent-key SKIP; SSoT-driven). */
-    readonly optionalHeads: readonly string[];
-}
-/**
- * Compile a READ behavior method into a portable {@link ReadGraph}: rewrite each authored SQL
- * body node to a `makeSQL` node carrying a synthetic `__scope` port (bc evaluates it in-scope),
- * and compile each node's static statements ONCE. SYMBOLIC — no concrete input. bc will own map
- * iteration / wire binding / Φ output at execute time; the handler renders each node's statements.
- */
-export declare function compileReadGraph(contract: BehaviorModelContract, dialect: Dialect, entry?: string, findFilterModel?: FindFilterSource, resolveColumnType?: ColumnTypeResolver): ReadGraph;
-/**
- * Execute a compiled {@link ReadGraph} via bc `runBehavior` + a makeSQL handler: bc drives map
- * iteration / wire binding / Φ output; the handler renders each node's static statements against
- * the evaluated `__scope` and runs REAL SQLite. Returns the component's Φ output. This is the
- * design's "bc composes, makeSQL executes" — the SAME path a per-language runtime follows.
- */
-export declare function executeReadGraph(graph: ReadGraph, input: Scope, db: SqliteDb): Value;
-/** An async driver seam: run a rendered `{ sql, params }` and resolve to result rows (#40). */
-export type SqlExecutorAsync = (sql: string, params: unknown[]) => Promise<Record<string, unknown>[]>;
-/**
- * Async twin of {@link executeReadGraph} — the PG / MySQL execution model (#40).
- *
- * Byte-identical composition (SAME IR, SAME per-node SQL text + params, SAME Φ output), but bc's
- * `runBehaviorAsync` drives it: the makeSQL handler returns a Promise, and bc dispatches the
- * INDEPENDENT sibling nodes of a plan stage on `runPlanAsync`'s bounded-parallel path (bc#23),
- * bounded by the plan's `concurrency` (default 16). Against a pooled async driver (`pg` / `mysql2`,
- * each `exec` call resolving on its own pooled connection), that becomes REAL parallel read-relation
- * DB I/O — the plan's declared concurrency finally cashes out as concurrent dispatch. The result is
- * deterministic (bc commits stage outcomes in declaration order), so it equals the serial
- * `executeReadGraph` output exactly; only the wall-clock changes.
- *
- * The conformance bar stays on the SYNC in-proc better-sqlite3 path (`executeReadGraph`); this async
- * path is the live PG/MySQL execution model and is proven by the latency-injecting concurrency test.
- */
-export declare function executeReadGraphAsync(graph: ReadGraph, input: Scope, exec: SqlExecutorAsync): Promise<Value>;
-/**
- * Convenience: compile + execute a READ behavior method whose output may be a Φ-merge of SQL
- * nodes (including relation `.map` nodes). Equivalent to `executeReadGraph(compileReadGraph(...))`.
- */
-export declare function executeReadBehavior(contract: BehaviorModelContract, input: Scope, dialect: Dialect, db: SqliteDb, entry?: string): Value;
-/**
- * Render the PRIMARY read node's statements of a {@link ReadGraph} against an input scope to its
- * dialect SQL text + bound params (the render axis for conformance golden). The primary node is
- * the first non-map body node (the root SELECT the relations map over). Optional heads are
- * normalized to present-as-null first (absent-key SKIP), so an omitted optional head renders the
- * SAME text a runtime would produce.
- */
-export declare function renderReadPrimary(graph: ReadGraph, input: Scope): {
-    sql: string;
-    params: unknown[];
-};
-export {};
-//# sourceMappingURL=static-bundle.d.ts.map

package/dist/scp/makesql/static-bundle.d.ts.map

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