litedbmodel 2.1.0 → 2.2.0

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

@@ -1,196 +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 } from 'behavior-contracts';
-import type { ComponentGraphIR, ComponentRefNode, MapNode, BehaviorModelContract } from '../authoring';
-import { type Dialect } from './handler';
-import { type FindFilterSource } from '../find-filter-guard';
-import { type ColumnTypeResolver, type MaterializeClass } 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 (#12 de-surrogated): `compileBehaviors`'
- * REAL `ComponentGraphIR` — the authored `Select`/`Count`/map nodes with their own ports (only
- * additively annotated with read `outType`/`outputType`), NOT a hand-built `__makeSqlNode`/`__scope`
- * surrogate — plus the per-node static `makeSQL` statement templates (opaque, v1-`DBConditions`-
- * sourced SQL TEXT) keyed by the real body-node id, and the optional heads. Pure JSON —
- * `JSON.stringify` round-trips, so every language runtime walks this real-node IR natively (topology
- * from the real nodes, SQL from `statementsById`) with a SQL driver — never bc `runBehavior`.
- */
-export interface ReadGraph {
-    readonly dialect: Dialect;
-    readonly name: string;
-    /** `compileBehaviors`' real `ComponentGraphIR` (real `Select`/`Count`/map nodes; outType-annotated). */
-    readonly ir: ComponentGraphIR;
-    /** Per-node static `makeSQL` statement templates (v1-sourced SQL text), keyed by real 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[];
-    /**
-     * TS read-path MATERIALIZERS (issue #59), per Select node: `column → MaterializeClass`. Present
-     * ONLY when a column-type resolver was supplied at compile (same gate as the `outType`
-     * annotations) — without it the read stays un-materialized (raw driver values), identical to the
-     * pre-#59 behavior. When present, the read handler coerces each raw row cell to the JS form the
-     * SQL column type declares (BIGINT→bigint, INT→number, DATE→string, BOOLEAN→boolean), consistent
-     * across sqlite/pg/mysql.
-     */
-    readonly materializersByNode?: Record<string, Record<string, MaterializeClass>>;
-}
-/**
- * Compile a READ behavior method into a portable {@link ReadGraph} (#12 de-surrogated): keep
- * `compileBehaviors`' REAL `Select`/`Count`/map body nodes (only additively annotate each with its
- * read `outType`), and compile each node's static `makeSQL` statements ONCE into the `statementsById`
- * sidecar (keyed by the real body-node id). SYMBOLIC — no concrete input. The native walker
- * ({@link executeReadGraph}) owns map iteration / wire binding / Φ output at execute time, rendering
- * each node's statements against the walk scope — never bc `runBehavior`, never a `__scope` surrogate.
- */
-export declare function compileReadGraph(contract: BehaviorModelContract, dialect: Dialect, entry?: string, findFilterModel?: FindFilterSource, resolveColumnType?: ColumnTypeResolver): ReadGraph;
-/**
- * Execute a compiled {@link ReadGraph} via the NATIVE walker (#12): walk `compileBehaviors`' REAL
- * `Select`/`Count`/map node IR in `plan.groups` stage order — computing each node's rows from its
- * `statementsById` fragments (rendered against the walk scope) and committing `(nodeId → value)` —
- * then evaluate the component's `output` Φ expression. NO bc `runBehavior`, NO `__makeSqlNode`
- * surrogate; litedbmodel owns map iteration / wire binding / Φ output. This is the SAME native
- * orchestration model the rust/go/py/php runtimes follow — one shape, all 5 languages, interpreter-free.
- */
-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 live PG / MySQL execution model (#40). Byte-identical
- * composition (SAME real-node IR, SAME per-node SQL text + params, SAME Φ output); within a plan stage
- * the INDEPENDENT sibling nodes are dispatched concurrently against the pooled async executor (each
- * `exec` resolving on its own pooled connection), and a map node's per-element queries fan out in
- * bounded parallel. The result is deterministic (stage outcomes commit in declaration order), so it
- * equals the serial `executeReadGraph` output exactly; only the wall-clock changes.
- */
-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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"}