litedbmodel 2.0.2 → 2.2.0

package/dist/scp/limit-config.d.ts

@@ -0,0 +1,118 @@
+/**
+ * litedbmodel v2 SCP — hard-limit runaway prevention config (Phase E-2, epic #74; v1 parity —
+ * `DBModel.setLimitConfig` / `_limitConfig`).
+ *
+ * A read that forgot its WHERE clause, or a hasMany relation batch fanning out over an accidental
+ * cross-join, can load an unbounded result set. v1 guarded this with a global `findHardLimit` /
+ * `hasManyHardLimit` (plus a per-relation override); this module is the v2 SCP equivalent — the
+ * SHARED config surface the TS runtime reads at COMPILE time to bake the effective caps onto the
+ * portable artifacts (the {@link import('./makesql/static-bundle').ReadGraph} find-guard and each
+ * {@link import('./relation').RelationOp}). Because the caps are baked at compile, the native ports
+ * (#100-103) need NO config surface of their own: they read the resolved `hardLimit` off the JSON
+ * artifact and run the SAME post-fetch throw.
+ *
+ * ## Semantics (v1 parity — match precisely)
+ *
+ *  - `findHardLimit`     — a top-level read (find/read) exceeding this THROWS {@link
+ *    import('./errors').LimitExceededError} (`context: 'find'`). The read injects `LIMIT hardLimit +
+ *    1` when the author set no explicit limit, so the throw only asserts the total EXCEEDS the cap.
+ *  - `hasManyHardLimit`  — a hasMany relation batch whose TOTAL fetched rows exceed this THROWS
+ *    (`context: 'relation'`, EXACT count). A per-relation `hardLimit` override wins over the global.
+ *  - `null` DISABLES the check (a per-relation `hardLimit: null` disables it for that relation even
+ *    when the global is set); `undefined` on a relation means "use the global".
+ *  - A raw-SQL relation with an INTRINSIC per-parent `LIMIT` (a `hasMany` `RelationDecl.limit`) skips
+ *    the batch-total check — its fanout is already bounded per parent by the window.
+ *
+ * The config is a process-global singleton (v1 `DBModel._limitConfig`). `setLimitConfig` MERGES
+ * (v1 parity), `resetLimitConfig` clears it (test isolation). The defaults are BOTH disabled
+ * (`undefined` ⇒ no cap) so nothing changes for a caller who never opts in.
+ */
+/**
+ * Global hard-limit config (spec §E-2; v1 `LimitConfig`). Both caps default to disabled.
+ * This is the AUTHORING/config surface — the resolved caps are baked onto the compiled artifacts.
+ */
+export interface LimitConfig {
+    /**
+     * Hard cap for a top-level read (find/read). A read returning more than this THROWS
+     * {@link import('./errors').LimitExceededError}. `null` / `undefined` ⇒ disabled (no cap).
+     */
+    readonly findHardLimit?: number | null;
+    /**
+     * Hard cap for a hasMany relation batch TOTAL. A batch fetching more than this THROWS. A
+     * per-relation `hardLimit` override wins. `null` / `undefined` ⇒ disabled (no cap).
+     */
+    readonly hasManyHardLimit?: number | null;
+}
+/**
+ * MERGE `config` into the global hard-limit config (v1 `DBModel.setLimitConfig` parity — a partial
+ * update, not a replace). Call once at app start:
+ *   `setLimitConfig({ findHardLimit: 5000, hasManyHardLimit: 500 })`.
+ * Pass `null` for a key to explicitly DISABLE that check.
+ */
+export declare function setLimitConfig(config: LimitConfig): void;
+/** Read a shallow copy of the current global hard-limit config. */
+export declare function getLimitConfig(): LimitConfig;
+/** Clear the global hard-limit config back to the disabled default (test isolation). */
+export declare function resetLimitConfig(): void;
+/**
+ * Resolve the effective `findHardLimit`: the value passed in `override` (when the caller supplies a
+ * config explicitly, e.g. at compile) else the global. Returns `null` (disabled) or a non-negative
+ * integer cap. `undefined` normalizes to the global; an explicit `null` disables.
+ */
+export declare function resolveFindHardLimit(override?: number | null): number | null;
+/**
+ * Resolve the effective hasMany cap for ONE relation (v1 `_selectForRelation` precedence):
+ *   per-relation `perRelation` (`null` disables, a number overrides) wins over the `global`
+ *   `hasManyHardLimit`; `undefined` on the relation falls through to the global. Returns `null`
+ *   (disabled) or a non-negative integer cap.
+ */
+export declare function resolveHasManyHardLimit(perRelation?: number | null, global?: number | null): number | null;
+/**
+ * The find hard-limit READ-BOUNDARY check — the twin of {@link assertRelationHardLimit}. The emitter
+ * bakes `LIMIT cap + 1` into the capped read's static SQL (a BOUNDED fetch: at most `cap + 1` rows
+ * ever leave the DB), and this asserts the result: `cap + 1` rows means the true total EXCEEDS the
+ * cap, so it throws {@link LimitExceededError} with `context:'find'` and `count = rows.length` (the
+ * fetch size — the total is only known to exceed).
+ *
+ * It lives at the boundary because SCP has no throw: a generated module returns rows, and the caller
+ * that asked for the capped endpoint enforces the policy. `cap === undefined` ⇒ the endpoint baked no
+ * guard ⇒ no check.
+ */
+export declare function assertFindHardLimit(rows: readonly unknown[], cap: number | undefined, model: string): void;
+/**
+ * The RELATION runaway guard, resolved at compile onto a {@link import('./relation').RelationOp} and
+ * carried verbatim to whoever fetches that relation's child rows: the effective batch-total `limit`
+ * plus the identity the error reports (`model` = the child TABLE, `relation` = the relation name).
+ *
+ * It is a PLAIN JSON record on purpose. The compiled op is the SSoT, and the same record is what the
+ * emitter bakes into the generated relation child fetch (`leaf-transport.Db.executeSQL`'s `guard`
+ * port), so the codegen path and the typed-object/lazy path enforce ONE resolved cap — there is no
+ * second config surface anywhere downstream, in any language.
+ */
+export interface RelationGuard {
+    /** The effective batch-total row cap (per-relation override → global, resolved at compile). */
+    readonly limit: number;
+    /**
+     * The child (target) TABLE — what {@link LimitExceededError.model} reports in the relation context.
+     * Optional exactly as the error's own field is: an op compiled without a target table reports
+     * `unknown` rather than inventing a name.
+     */
+    readonly model?: string;
+    /** The relation NAME — what {@link LimitExceededError.relation} reports. */
+    readonly relation: string;
+}
+/**
+ * The relation hard-limit POST-FETCH check — the ONE `count > cap ⇒ throw` primitive for the relation
+ * context, shared by BOTH v2 read surfaces: the typed-object / lazy batch
+ * ({@link import('./relation').runRelationOp}) and the CODEGEN path, where the `executeSQL` leaf runs
+ * it on the raw child rows of a guarded relation fetch — the only place the raw child rows exist
+ * (past `group` the graph is nested, and SCP itself has no throw).
+ *
+ * Unlike the find twin the batch is fetched IN FULL (v1 `_selectForRelation` parity — no `LIMIT
+ * cap + 1` on a relation batch), so `count` is the EXACT batch total, exactly as
+ * {@link import('./errors').LimitExceededContext} declares and as the rust/go/python/php ports mirror.
+ * `guard == null` ⇒ the relation baked no cap (disabled, or an intrinsic per-parent `limit` window
+ * whose fanout is already bounded) ⇒ no check.
+ */
+export declare function assertRelationHardLimit(rows: readonly unknown[], guard: RelationGuard | null | undefined): void;
+//# sourceMappingURL=limit-config.d.ts.map

package/dist/scp/limit-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limit-config.d.ts","sourceRoot":"","sources":["../../src/scp/limit-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAKD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAExD;AAED,mEAAmE;AACnE,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAG5E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK1G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAG1G;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAK/G"}

package/dist/scp/limit-config.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — hard-limit runaway prevention config (Phase E-2, epic #74; v1 parity —
+ * `DBModel.setLimitConfig` / `_limitConfig`).
+ *
+ * A read that forgot its WHERE clause, or a hasMany relation batch fanning out over an accidental
+ * cross-join, can load an unbounded result set. v1 guarded this with a global `findHardLimit` /
+ * `hasManyHardLimit` (plus a per-relation override); this module is the v2 SCP equivalent — the
+ * SHARED config surface the TS runtime reads at COMPILE time to bake the effective caps onto the
+ * portable artifacts (the {@link import('./makesql/static-bundle').ReadGraph} find-guard and each
+ * {@link import('./relation').RelationOp}). Because the caps are baked at compile, the native ports
+ * (#100-103) need NO config surface of their own: they read the resolved `hardLimit` off the JSON
+ * artifact and run the SAME post-fetch throw.
+ *
+ * ## Semantics (v1 parity — match precisely)
+ *
+ *  - `findHardLimit`     — a top-level read (find/read) exceeding this THROWS {@link
+ *    import('./errors').LimitExceededError} (`context: 'find'`). The read injects `LIMIT hardLimit +
+ *    1` when the author set no explicit limit, so the throw only asserts the total EXCEEDS the cap.
+ *  - `hasManyHardLimit`  — a hasMany relation batch whose TOTAL fetched rows exceed this THROWS
+ *    (`context: 'relation'`, EXACT count). A per-relation `hardLimit` override wins over the global.
+ *  - `null` DISABLES the check (a per-relation `hardLimit: null` disables it for that relation even
+ *    when the global is set); `undefined` on a relation means "use the global".
+ *  - A raw-SQL relation with an INTRINSIC per-parent `LIMIT` (a `hasMany` `RelationDecl.limit`) skips
+ *    the batch-total check — its fanout is already bounded per parent by the window.
+ *
+ * The config is a process-global singleton (v1 `DBModel._limitConfig`). `setLimitConfig` MERGES
+ * (v1 parity), `resetLimitConfig` clears it (test isolation). The defaults are BOTH disabled
+ * (`undefined` ⇒ no cap) so nothing changes for a caller who never opts in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLimitConfig = setLimitConfig;
+exports.getLimitConfig = getLimitConfig;
+exports.resetLimitConfig = resetLimitConfig;
+exports.resolveFindHardLimit = resolveFindHardLimit;
+exports.resolveHasManyHardLimit = resolveHasManyHardLimit;
+exports.assertFindHardLimit = assertFindHardLimit;
+exports.assertRelationHardLimit = assertRelationHardLimit;
+const errors_1 = require("./errors");
+/** The process-global config singleton (v1 `DBModel._limitConfig`). Both caps disabled by default. */
+let globalLimitConfig = {};
+/**
+ * MERGE `config` into the global hard-limit config (v1 `DBModel.setLimitConfig` parity — a partial
+ * update, not a replace). Call once at app start:
+ *   `setLimitConfig({ findHardLimit: 5000, hasManyHardLimit: 500 })`.
+ * Pass `null` for a key to explicitly DISABLE that check.
+ */
+function setLimitConfig(config) {
+    globalLimitConfig = { ...globalLimitConfig, ...config };
+}
+/** Read a shallow copy of the current global hard-limit config. */
+function getLimitConfig() {
+    return { ...globalLimitConfig };
+}
+/** Clear the global hard-limit config back to the disabled default (test isolation). */
+function resetLimitConfig() {
+    globalLimitConfig = {};
+}
+/**
+ * Resolve the effective `findHardLimit`: the value passed in `override` (when the caller supplies a
+ * config explicitly, e.g. at compile) else the global. Returns `null` (disabled) or a non-negative
+ * integer cap. `undefined` normalizes to the global; an explicit `null` disables.
+ */
+function resolveFindHardLimit(override) {
+    const v = override !== undefined ? override : globalLimitConfig.findHardLimit;
+    return normalizeCap(v, 'findHardLimit');
+}
+/**
+ * Resolve the effective hasMany cap for ONE relation (v1 `_selectForRelation` precedence):
+ *   per-relation `perRelation` (`null` disables, a number overrides) wins over the `global`
+ *   `hasManyHardLimit`; `undefined` on the relation falls through to the global. Returns `null`
+ *   (disabled) or a non-negative integer cap.
+ */
+function resolveHasManyHardLimit(perRelation, global) {
+    // v1: `perRelationHardLimit === null ? null : perRelationHardLimit ?? globalHasManyHardLimit`.
+    const g = global !== undefined ? global : globalLimitConfig.hasManyHardLimit;
+    const raw = perRelation === null ? null : perRelation !== undefined ? perRelation : g;
+    return normalizeCap(raw, 'hasManyHardLimit');
+}
+/**
+ * The find hard-limit READ-BOUNDARY check — the twin of {@link assertRelationHardLimit}. The emitter
+ * bakes `LIMIT cap + 1` into the capped read's static SQL (a BOUNDED fetch: at most `cap + 1` rows
+ * ever leave the DB), and this asserts the result: `cap + 1` rows means the true total EXCEEDS the
+ * cap, so it throws {@link LimitExceededError} with `context:'find'` and `count = rows.length` (the
+ * fetch size — the total is only known to exceed).
+ *
+ * It lives at the boundary because SCP has no throw: a generated module returns rows, and the caller
+ * that asked for the capped endpoint enforces the policy. `cap === undefined` ⇒ the endpoint baked no
+ * guard ⇒ no check.
+ */
+function assertFindHardLimit(rows, cap, model) {
+    if (cap === undefined)
+        return;
+    if (rows.length > cap)
+        throw new errors_1.LimitExceededError(cap, rows.length, 'find', model);
+}
+/**
+ * The relation hard-limit POST-FETCH check — the ONE `count > cap ⇒ throw` primitive for the relation
+ * context, shared by BOTH v2 read surfaces: the typed-object / lazy batch
+ * ({@link import('./relation').runRelationOp}) and the CODEGEN path, where the `executeSQL` leaf runs
+ * it on the raw child rows of a guarded relation fetch — the only place the raw child rows exist
+ * (past `group` the graph is nested, and SCP itself has no throw).
+ *
+ * Unlike the find twin the batch is fetched IN FULL (v1 `_selectForRelation` parity — no `LIMIT
+ * cap + 1` on a relation batch), so `count` is the EXACT batch total, exactly as
+ * {@link import('./errors').LimitExceededContext} declares and as the rust/go/python/php ports mirror.
+ * `guard == null` ⇒ the relation baked no cap (disabled, or an intrinsic per-parent `limit` window
+ * whose fanout is already bounded) ⇒ no check.
+ */
+function assertRelationHardLimit(rows, guard) {
+    if (guard === null || guard === undefined)
+        return;
+    if (rows.length > guard.limit) {
+        throw new errors_1.LimitExceededError(guard.limit, rows.length, 'relation', guard.model, guard.relation);
+    }
+}
+/** Validate + normalize a cap: `null`/`undefined` ⇒ null (disabled); else a non-negative integer. */
+function normalizeCap(v, field) {
+    if (v === null || v === undefined)
+        return null;
+    if (!Number.isInteger(v) || v < 0) {
+        throw new Error(`limit-config: ${field} must be a non-negative integer or null (got ${String(v)})`);
+    }
+    return v;
+}
+//# sourceMappingURL=limit-config.js.map

package/dist/scp/limit-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limit-config.js","sourceRoot":"","sources":["../../src/scp/limit-config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;AA8BH,wCAEC;AAGD,wCAEC;AAGD,4CAEC;AAOD,oDAGC;AAQD,0DAKC;AAaD,kDAGC;AAsCD,0DAKC;AA1HD,qCAA8C;AAmB9C,sGAAsG;AACtG,IAAI,iBAAiB,GAAgB,EAAE,CAAC;AAExC;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,MAAmB;IAChD,iBAAiB,GAAG,EAAE,GAAG,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAAC;AAC1D,CAAC;AAED,mEAAmE;AACnE,SAAgB,cAAc;IAC5B,OAAO,EAAE,GAAG,iBAAiB,EAAE,CAAC;AAClC,CAAC;AAED,wFAAwF;AACxF,SAAgB,gBAAgB;IAC9B,iBAAiB,GAAG,EAAE,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,SAAgB,oBAAoB,CAAC,QAAwB;IAC3D,MAAM,CAAC,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,aAAa,CAAC;IAC9E,OAAO,YAAY,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,uBAAuB,CAAC,WAA2B,EAAE,MAAsB;IACzF,+FAA+F;IAC/F,MAAM,CAAC,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,gBAAgB,CAAC;IAC7E,MAAM,GAAG,GAAG,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACtF,OAAO,YAAY,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CAAC,IAAwB,EAAE,GAAuB,EAAE,KAAa;IAClG,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO;IAC9B,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG;QAAE,MAAM,IAAI,2BAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AACvF,CAAC;AAyBD;;;;;;;;;;;;GAYG;AACH,SAAgB,uBAAuB,CAAC,IAAwB,EAAE,KAAuC;IACvG,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAClD,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;QAC9B,MAAM,IAAI,2BAAkB,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClG,CAAC;AACH,CAAC;AAED,qGAAqG;AACrG,SAAS,YAAY,CAAC,CAA4B,EAAE,KAAa;IAC/D,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,iBAAiB,KAAK,gDAAgD,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/scp/makesql/compile-relation.d.ts

@@ -15,6 +15,12 @@
  *     MySQL/SQLite `SELECT … FROM t WHERE (k1, k2) IN ((?, ?), …)`
  *   composite-key, per-parent limit: PG LATERAL composite / others ROW_NUMBER composite.
  *
+ * The STATIC composite forms ({@link compileCompositeKeyStaticUnlimited} /
+ * {@link compileCompositeKeyStaticLimited}) deviate from those v1 texts on EVERY dialect: they bind
+ * the key set as ONE array-of-tuples param (RESULT parity, not byte-identity) so a composite batch
+ * rides the same three-leaf transport as everything else. The v1 texts stay proven by the
+ * value-expanding builders below.
+ *
  * The PG type text (`?::type[]`) comes from the ORIGINAL `inferPgArrayType` (sqlCast
  * wins, else element-type inference). The .rs regressions are NOT reproduced: PG
  * per-parent-limit is LATERAL (not ROW_NUMBER), and PG types are sqlCast-driven (not
@@ -26,6 +32,13 @@
 import { type ConditionObject } from '../../DBConditions';
 import type { MakeSQL } from './makesql';
 import type { Dialect } from './handler';
+/**
+ * The PG ELEMENT type of a value set — the ONE type inference every PG cast in this module is built
+ * on ({@link inferPgArrayType} appends `[]`; the composite key-row expansion casts each key column
+ * with it). Reproduces the ORIGINAL `LazyRelation.inferPgArrayType`'s element decision (the PG
+ * anchor — NOT the .rs coarse text-folding).
+ */
+export declare function inferPgElementType(values: unknown[]): string;
 /**
  * Reproduce the ORIGINAL `LazyRelation.inferPgArrayType`: sqlCast wins (`<cast>[]`);
  * otherwise infer the element type from the sample values. Byte-identical to the
@@ -71,20 +84,32 @@ export interface RelationCompileBase {
      */
     deferPgArrayCast?: boolean;
 }
+/** The STATIC composite-key builders' options: {@link RelationCompileBase} + the PG key-column types. */
+export interface CompositeStaticBase extends RelationCompileBase {
+    /**
+     * PostgreSQL only: the PG ELEMENT type of each key column, positional with `targetKeys`, derived
+     * from the model's DECLARED column type (the schema SoT — never from the values, which are unknown
+     * at compile and empty at call time often enough to matter; the SAME rule the composite `tupleIn`
+     * predicate follows, `json-array.ts` `pgElementTypes`). The key rows carry these types so the JOIN
+     * compares `int = int` / `bigint = bigint` against the child key columns instead of `… = text`.
+     */
+    readonly pgKeyTypes?: readonly string[];
+}
 /**
  * The STATIC composite-key batch forms (#47 item 1) — length-INDEPENDENT so the compiled `op.sql`
- * is fixed (one param per column on PG; ONE JSON param on MySQL/SQLite), the SAME static-op
- * property the single-key relation forms have. PG stays byte-identical to v1's `unnest`-JOIN
- * (`batchLoadWithUnnestJoin`), with the element-type cast DEFERRED (#46) to render from the real
- * keys. MySQL/SQLite use the single-JSON tuple form (the owner-approved deviation the single-key
- * IN-list and the batch UPDATE composite already use — RESULT parity, NOT byte-identity): a
- * `JSON_TABLE`/`json_each` subquery over one JSON array-of-tuples param. The v1 literal
- * `(k1,k2) IN ((?,?),…)` byte-form stays proven by the golden `compileCompositeKeyUnlimited`.
+ * is fixed (ONE JSON array-of-tuples param on EVERY dialect), the SAME static-op property the
+ * single-key relation forms have. Every dialect now consumes the SAME single key param the relation
+ * key set is produced as (`pluck` — one array of key TUPLES): MySQL/SQLite expand it with
+ * `JSON_TABLE`/`json_each`, PostgreSQL with {@link pgCompositeKeyRows} (#159). This is the
+ * owner-approved deviation the single-key IN-list and the batch UPDATE composite already use —
+ * RESULT parity, NOT byte-identity with v1; the v1 literal `(k1,k2) IN ((?,?),…)` /
+ * `unnest(?::t1[], ?::t2[])` byte-forms stay proven by the goldens
+ * {@link compileCompositeKeyUnlimited} / {@link compileCompositeKeyLimited}.
  *
  * The JSON tuple param is `[[k1a,k2a],[k1b,k2b],…]` (positional element arrays), read back by
  * ordinal path (`$[0]`, `$[1]`, …) so no per-column JSON key names are needed.
  */
-export declare function compileCompositeKeyStaticUnlimited(opts: RelationCompileBase & {
+export declare function compileCompositeKeyStaticUnlimited(opts: CompositeStaticBase & {
     targetKeys: string[];
 }): MakeSQL;
 /**
@@ -131,26 +156,27 @@ export declare function compileCompositeKeyLimited(opts: RelationCompileBase & {
 /**
  * The STATIC composite-key per-parent-LIMIT batch form (#47 last completeness gap) — the
  * length-INDEPENDENT sibling of {@link compileCompositeKeyLimited}, so the compiled `op.sql` is
- * FIXED (one array param per key column on PG; ONE JSON array-of-tuples param on MySQL/SQLite) and
- * can be a STATIC bundle op — exactly the property {@link compileSingleKeyLimited} and
- * {@link compileCompositeKeyStaticUnlimited} already have.
+ * FIXED (ONE JSON array-of-tuples param on every dialect) and can be a STATIC bundle op — exactly
+ * the property {@link compileSingleKeyLimited} and {@link compileCompositeKeyStaticUnlimited}
+ * already have.
  *
- * The per-parent window is IDENTICAL to the single-key-limited path:
- *   - **PG**: `CROSS JOIN LATERAL` over `unnest(?::t1[], ?::t2[])` — BYTE-identical to v1's
- *     `batchLoadWithLateralComposite` (the composite LATERAL is already structurally
- *     length-independent; only the element-type cast was value-derived, and that is DEFERRED (#46)
- *     to render from the real keys via {@link PG_ARRAY_CAST_TOKEN}). No deviation on PG.
+ * The per-parent window is IDENTICAL to the single-key-limited path, over the SAME single key param:
+ *   - **PG**: `CROSS JOIN LATERAL` over the typed key rows of {@link pgCompositeKeyRows} — v1's
+ *     `batchLoadWithLateralComposite` window verbatim, with its per-column `unnest(?::t1[], ?::t2[])`
+ *     key source replaced by the single-JSON-tuple expansion (#159), so the key set binds as the ONE
+ *     array `pluck` yields.
  *   - **MySQL/SQLite**: the SAME `ROW_NUMBER() OVER (PARTITION BY <keys> ORDER BY <order>)` CTE +
  *     `_rn <= limit` filter v1's `batchLoadWithRowNumberComposite` emits — but the CTE membership
  *     WHERE is the STATIC JSON-tuple predicate ({@link compositeJsonMembership}) instead of v1's
- *     value-dependent `(k1,k2) IN ((?,?),…)`. This is the owner-sanctioned static deviation the
- *     composite UNLIMITED form ({@link compileCompositeKeyStaticUnlimited}) and the single-key
- *     IN-list already use: the JSON subquery selects the SAME child rows the tuple-IN would, the
- *     window partitions/orders identically, so it is RESULT-parity to v1 (proven live). The v1
- *     literal `(k1,k2) IN ((?,?),…)` byte-form stays proven by the golden
- *     {@link compileCompositeKeyLimited}.
+ *     value-dependent `(k1,k2) IN ((?,?),…)`.
+ *
+ * Both are the owner-sanctioned static deviation the composite UNLIMITED form
+ * ({@link compileCompositeKeyStaticUnlimited}) and the single-key IN-list already use: the key rows
+ * select the SAME child rows the value-expanded form would and the window partitions/orders
+ * identically, so it is RESULT-parity to v1 (proven live). The v1 byte-forms stay proven by the
+ * golden {@link compileCompositeKeyLimited}.
  */
-export declare function compileCompositeKeyStaticLimited(opts: RelationCompileBase & {
+export declare function compileCompositeKeyStaticLimited(opts: CompositeStaticBase & {
     targetKeys: string[];
     limit: number;
 }): MakeSQL;

package/dist/scp/makesql/compile-relation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile-relation.d.ts","sourceRoot":"","sources":["../../../src/scp/makesql/compile-relation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAY5E;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAIzE;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,mBAAmB,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GACnD,OAAO,CAmCT;AA4BD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,mBAAmB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,GACnE,OAAO,CAyBT;AAMD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,mBAAmB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClF,OAAO,CAoCT;AAWD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAA;CAAE,GACxE,OAAO,CAuCT;AAMD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,mBAAmB,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvF,OAAO,CA+CT;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,mBAAmB,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClE,OAAO,CA6CT"}
+{"version":3,"file":"compile-relation.d.ts","sourceRoot":"","sources":["../../../src/scp/makesql/compile-relation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAW5D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAIzE;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAuBD,yGAAyG;AACzG,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AA+BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,mBAAmB,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GACnD,OAAO,CA0BT;AAeD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,mBAAmB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,GACnE,OAAO,CAyBT;AAMD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,mBAAmB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClF,OAAO,CAoCT;AAWD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAA;CAAE,GACxE,OAAO,CAuCT;AAMD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,mBAAmB,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvF,OAAO,CA+CT;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,mBAAmB,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClE,OAAO,CAuCT"}