litedbmodel 2.0.2 → 2.2.0

package/dist/scp/dbmodel-runtime.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — the DBModel ActiveRecord ↔ SCP RUNTIME bridge (Phase F-2, epic #74, issue #105).
+ *
+ * The runtime glue that puts `DBModel`'s pooled execution on the Phase A-E substrate
+ * (`exec-context.ts` / `connection-routing.ts` / `middleware.ts` / `tx-options.ts`). It owns two
+ * concerns:
+ *
+ *  1. **Connection wiring** ({@link buildContextFromConfig}) — a v1 `DBConfig` (+ `writerConfig` /
+ *     writer-sticky options) → a {@link PooledAsyncContext} over REAL pg / mysql2 pools (via
+ *     `pgPoolFactory` / `mysqlPoolFactory` + `buildRoutingConfig`) and a `close()`. This is the C3
+ *     `setConfig → ConnectionRegistry → pool` path. Every statement DBModel issues — a v1-built SELECT
+ *     as much as a compiled write bundle — goes through this ONE ctx, so routing, middleware and an
+ *     ambient transaction pin apply uniformly.
+ *
+ *  2. **Write execution** ({@link executeWriteAsync}) — run a compiled write bundle's transaction plan
+ *     on the writer through the SCP tx runtime (write=tx guard).
+ *
+ * There is NO runtime read-compile here. A read whose SHAPE is fixed is declared on the `@behavior` /
+ * `@leaf` authoring surface and lowered by `bc generate`; a read whose shape is only known per request
+ * (`find({where:{age:{gt:x}}})`) runs the v1 imperative builder — compile-free — and reaches the DB
+ * through the SAME ctx seam via `DBModel.execute`.
+ *
+ * The public API + README code are UNCHANGED: `DBModel`'s method signatures / return shapes are
+ * identical; this module is an INTERNAL execution substrate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileDeleteBundle = exports.compileUpdateBundle = exports.compileCreateBundle = void 0;
+exports.buildContextFromConfig = buildContextFromConfig;
+exports.scpRuntimeGeneration = scpRuntimeGeneration;
+exports.closeAllScpRuntimes = closeAllScpRuntimes;
+exports.executeWriteAsync = executeWriteAsync;
+exports.renderRawSql = renderRawSql;
+require("reflect-metadata");
+const connection_routing_1 = require("./connection-routing");
+const exec_context_1 = require("./exec-context");
+const pool_executor_1 = require("./makesql/pool-executor");
+const tx_1 = require("./makesql/tx");
+const decorator_adapter_1 = require("./decorator-adapter");
+Object.defineProperty(exports, "compileCreateBundle", { enumerable: true, get: function () { return decorator_adapter_1.compileCreateBundle; } });
+Object.defineProperty(exports, "compileUpdateBundle", { enumerable: true, get: function () { return decorator_adapter_1.compileUpdateBundle; } });
+Object.defineProperty(exports, "compileDeleteBundle", { enumerable: true, get: function () { return decorator_adapter_1.compileDeleteBundle; } });
+const handler_1 = require("./makesql/handler");
+/** Map a {@link RuntimeDbConfig} to the C3 {@link ConnectionConfig} pool-construction knobs. */
+function toConnectionConfig(config) {
+    return {
+        ...(config.host !== undefined ? { host: config.host } : {}),
+        ...(config.port !== undefined ? { port: config.port } : {}),
+        ...(config.database !== undefined ? { database: config.database } : {}),
+        ...(config.user !== undefined ? { user: config.user } : {}),
+        ...(config.password !== undefined ? { password: config.password } : {}),
+        ...(config.max !== undefined ? { maxPool: config.max } : {}),
+        ...(config.keepAlive !== undefined ? { keepAlive: config.keepAlive } : {}),
+        ...(config.keepAliveInitialDelayMillis !== undefined ? { keepAliveInitialDelayMillis: config.keepAliveInitialDelayMillis } : {}),
+    };
+}
+/** Lazily `require` the pg module (optional peer dep). */
+function requirePg() {
+    return require('pg');
+}
+/** Lazily `require` the mysql2/promise module (optional peer dep). */
+function requireMysql2() {
+    return require('mysql2/promise');
+}
+/**
+ * A {@link PoolFactory} that builds the reader pool from the primary config and (when the setup asks
+ * for `separateWriter`) the writer pool from `writerConfig` — a genuine reader/writer replica split on
+ * distinct hosts. `buildRoutingConfig` calls this with the resolved config so sizing/keepAlive/de-box
+ * options land at pool construction; the writer role overlays the `writerConfig` connection params.
+ */
+function splitPoolFactory(baseFactory, writerConfig) {
+    return (resolved, role) => {
+        if (role === 'writer' && writerConfig !== undefined) {
+            const overlaid = { ...resolved, ...toConnectionConfig(writerConfig) };
+            return baseFactory(overlaid, 'writer');
+        }
+        return baseFactory(resolved, role);
+    };
+}
+/**
+ * Build a Phase A-E {@link PooledAsyncContext} + reader executor from a v1 `DBConfig` (the
+ * `setConfig → ConnectionRegistry → pool` wiring). Constructs a REAL pg / mysql2 pool via
+ * `buildRoutingConfig` + the driver pool factory (sizing/keepAlive applied at pool construction), wires
+ * the default connection, and — when `writerConfig` is present — a distinct writer pool (reader/writer
+ * replica split). The writer-sticky clock is armed per `useWriterAfterTransaction` / `writerStickyDuration`.
+ *
+ * `sqlite` is NOT routed here (it keeps the v1 in-proc path). Throws for an unsupported driver.
+ */
+function buildContextFromConfig(config, options = {}) {
+    const driver = config.driver ?? 'postgres';
+    if (driver === 'sqlite') {
+        throw new Error('scp dbmodel-runtime: the sqlite dialect is not routed through the async SCP runtime (v1 in-proc path).');
+    }
+    const dialect = driver === 'mysql' ? 'mysql' : 'postgres';
+    const stickyOpts = {
+        ...(options.useWriterAfterTransaction !== undefined ? { useWriterAfterTransaction: options.useWriterAfterTransaction } : {}),
+        ...(options.writerStickyDuration !== undefined ? { writerStickyDuration: options.writerStickyDuration } : {}),
+    };
+    const baseFactory = dialect === 'mysql' ? (0, pool_executor_1.mysqlPoolFactory)(requireMysql2()) : (0, pool_executor_1.pgPoolFactory)(requirePg());
+    const hasWriter = options.writerConfig !== undefined;
+    const built = (0, connection_routing_1.buildRoutingConfig)([{
+            config: toConnectionConfig(config),
+            poolFactory: hasWriter ? splitPoolFactory(baseFactory, options.writerConfig) : baseFactory,
+            separateWriter: hasWriter,
+        }], stickyOpts);
+    const ctx = new exec_context_1.PooledAsyncContext(built.routing);
+    // The `ctx` (PooledAsyncContext) IS the async read/write seam — there is no separate reader executor.
+    // The closer is REGISTERED as well as returned: a caller that drops its `RuntimeContext` without
+    // awaiting `close()` (which `DBModel.setConfig` does on every reconfigure) would otherwise leak the
+    // pools with no handle left to reach them. `closeAllScpRuntimes` is the drain.
+    const runtime = {
+        ctx,
+        dialect,
+        close: async () => {
+            liveClosers.delete(built.close);
+            await built.close();
+        },
+    };
+    liveClosers.add(built.close);
+    return runtime;
+}
+/**
+ * Every pool set this module has constructed and not yet closed.
+ *
+ * The same shape `src/drivers/mysql.ts` uses for the v1 pools: the module that CREATES the pools owns
+ * the registry that can close them. Without it, `closeAllPools()` closed the v1 caches only and the
+ * routed SCP pools stayed open — `closeAllPools()` resolved in 0ms with three live sockets, and a
+ * consumer process could not exit.
+ */
+const liveClosers = new Set();
+/**
+ * Bumped every time {@link closeAllScpRuntimes} closes the pools. `DBModel` caches its `RuntimeContext`
+ * per (sub)class; that cache holds pools this generation counter invalidates — after a `closeAllPools()`,
+ * a cached runtime points at a CLOSED pool, and the next op must rebuild rather than reuse it (#182). The
+ * counter is the seam: the closer lives here (this module owns the pools), the cache lives on `DBModel`,
+ * and they agree through this monotonically increasing token.
+ */
+let scpRuntimeGen = 0;
+/** The current SCP-runtime generation; a cached runtime built at an older generation is stale (#182). */
+function scpRuntimeGeneration() {
+    return scpRuntimeGen;
+}
+/**
+ * Close every pool set {@link buildContextFromConfig} has constructed — including runtimes their owner
+ * discarded without closing. Part of the v1 `closeAllPools()` teardown, alongside the per-driver caches.
+ * Bumps {@link scpRuntimeGeneration} so `DBModel`'s cached runtimes rebuild instead of reusing a now-closed
+ * pool (#182).
+ */
+async function closeAllScpRuntimes() {
+    const closers = [...liveClosers];
+    liveClosers.clear();
+    scpRuntimeGen++;
+    for (const close of closers)
+        await close();
+}
+// ── 2. Write execution (bundle → executeTransactionAsync) ───────────────────────────────────────
+/** Run a write bundle's transaction plan on the writer through the SCP tx runtime (write=tx guard). */
+function executeWriteAsync(bundle, input, ctx, options = {}) {
+    if (bundle.transaction === undefined) {
+        throw new Error(`scp dbmodel-runtime: write bundle '${bundle.name}' carries no transaction plan`);
+    }
+    return (0, tx_1.executeTransactionAsync)(ctx.ctx, bundle.transaction, input, ctx.dialect, options);
+}
+/**
+ * Render a v1-built raw SQL string (with `?` placeholders) to the ctx dialect's placeholder form for
+ * the escape-hatch seam path: `postgres` renumbers `?`→`$N` (string-literal-aware, via the SAME
+ * `renderPlaceholders` the makesql render uses); `mysql` keeps `?`. v1's DBHandler did this `?`→`$N`
+ * conversion on the imperative path — the SCP seam passes SQL verbatim to the driver, so the raw path
+ * must renumber here to stay byte-equivalent. Phase F-2 (#105).
+ */
+function renderRawSql(sql, dialect) {
+    return (0, handler_1.renderPlaceholders)(sql, dialect === 'postgres' ? 'postgres' : dialect === 'mysql' ? 'mysql' : 'sqlite');
+}
+//# sourceMappingURL=dbmodel-runtime.js.map

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

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

package/dist/scp/decorator-adapter.d.ts

@@ -0,0 +1,196 @@
+/**
+ * litedbmodel v2 SCP — the decorator METADATA adapter (Phase F-1, epic #74, issue #104).
+ *
+ * litedbmodel's decorators are metadata-only COLLECTORS: `@column` / `@hasMany` / … record
+ * `ColumnMeta` / `RelationMeta` / `TABLE_NAME` on the class (`src/decorators.ts`, via `reflect-metadata`
+ * + `_columnMeta` / `_relationMeta`). This module READS that registry and translates it into the SCP-level
+ * facts the rest of the stack consumes, plus the write bundles a decorated model compiles to. It builds
+ * NO SQL structure of its own and holds NO authoring vocabulary — the decorator never emits IR, and the
+ * adapter never re-implements composition.
+ *
+ * ## What the adapter translates
+ *
+ *  1. **Columns** (the one real translation): `@column.*` `ColumnMeta` (the decorator already knows the
+ *     type family — bigint / date / boolean / uuid / json / array / …) → the SCP column SoT
+ *     ({@link ModelColumns}: the SQL-type token per column, validated by `coltype.ts`). See
+ *     {@link deriveModelColumns} + {@link COLUMN_FAMILY_SQL_TYPE}. The typed-read `outType` and the
+ *     relation key-array element type both resolve against exactly this SoT.
+ *  2. **Relations**: `@hasMany` / `@belongsTo` / `@hasOne` `RelationMeta` → {@link RelationDecl} →
+ *     `compileRelationOp` (single + composite keys, per-parent `limit` window + `hardLimit`).
+ *  3. **Write bundles**: `createMany` (and a `create` WITH `onConflict`) / `updateMany` / `deleteMany` →
+ *     `compileCreateManyBundle` / `compileUpdateManyBundle` / `compileDeleteManyBundle`, with the
+ *     model's column SoT threaded as the write de-box resolver.
+ *
+ * READS are NOT compiled here. A read endpoint is DECLARED on the `@behavior` / `@leaf` authoring
+ * surface and lowered by `bc generate`; an ad-hoc runtime-shaped query runs the v1 imperative path.
+ */
+import { type SqlBundle } from './write-bundle';
+import { type RelationDecl, type RelationOp } from './relation';
+import { type BcScalar, type ColumnTypeResolver } from './coltype';
+import type { DialectName } from './dialect';
+import type { InsertManyBuildOptions } from './makesql/compile-crud';
+import type { UpdateManyBuildOptions } from '../drivers/types';
+import { type ColumnMeta, type RelationMeta } from '../decorators';
+/**
+ * The model's inline typed-column declaration: `table → (column → SQL type token)` — the consumer-inline
+ * column-type SoT (bc never infers types; the author annotates them). SQL type tokens are the §4.1
+ * vocabulary (`INTEGER`/`INT`/`BIGINT`/`REAL`/`DOUBLE`/`DECIMAL(…)`/`TEXT`/`VARCHAR(…)`/`BOOLEAN`/
+ * `DATE`/`TIMESTAMP`/`JSON`/`JSONB`/`UUID`/…).
+ */
+export type ModelColumns = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/**
+ * Resolve the de-box bc element scalar of a relation's parent-key column ((table, column) → bc scalar),
+ * so a relation key array carries the type the READ-materialized key value actually holds
+ * (INT→`float` / BIGINT→`string` / text/uuid→`string`) — see {@link keyArrayElemScalar}.
+ */
+export type KeyTypeResolver = (table: string, column: string) => BcScalar;
+/**
+ * The decorator's `ColumnMeta.sqlCast` type-family token → the canonical §4.1 SQL-type token the SCP
+ * `static columns` SoT carries (validated by `coltype.ts`). The decorator ALREADY knows the family
+ * (it set `sqlCast` from the `@column.*` variant / the `design:type` inference — `src/decorators.ts`),
+ * so this is a pure token normalization, no inference. `coltype.ts` accepts every RHS here:
+ * BOOLEAN/BIGINT/TIMESTAMP/DATE/UUID/JSONB are scalar; the array tokens de-box as `passthrough`
+ * (`sqlTypeToMaterializeClass`).
+ *
+ * The RHS matches the decorator families 1:1:
+ *  - `boolean`    → `BOOLEAN`     (`@column.boolean()` / auto `Boolean`)
+ *  - `bigint`     → `BIGINT`      (`@column.bigint()` / auto `BigInt` — read de-box: exact string)
+ *  - `timestamp`  → `TIMESTAMP`   (`@column.datetime()` / auto `Date` — read de-box: TZ string)
+ *  - `date`       → `DATE`        (`@column.date()` — read de-box: YYYY-MM-DD string)
+ *  - `uuid`       → `UUID`        (`@column.uuid()`)
+ *  - `jsonb`      → `JSONB`       (`@column.json()`)
+ *  - `text[]` / `int[]` / `numeric[]` / `boolean[]` → the array token (`@column.*Array()`)
+ */
+export declare const COLUMN_FAMILY_SQL_TYPE: Readonly<Record<string, string>>;
+/**
+ * The LAST-RESORT SQL type for a column that carries NO `sqlCast` family, NO `baseSqlType` (its
+ * `design:type` is absent — no `emitDecoratorMetadata` — or is an Array/Object family), and NO
+ * `columnTypes` override. Phase F-2 (#105 option B) made {@link columnSqlType} consult the decorator's
+ * `baseSqlType` (derived from the field's TS `design:type`: String→TEXT / Number→INTEGER / Boolean→
+ * BOOLEAN / Date→TIMESTAMP / BigInt→BIGINT) BEFORE this default, so a bare `@column() name: string`
+ * types as `TEXT` (not `INTEGER`) — the fix for F1's blanket-INTEGER read-de-box defect (it threw
+ * `materialize int32` on a live string column). This default now only applies when `design:type` is
+ * genuinely unavailable; a REAL/DECIMAL column (a `Number` that is not INT) is pinned via
+ * {@link DeriveColumnsOptions.columnTypes} (the escape hatch, unchanged from F1).
+ */
+export declare const DEFAULT_UNCAST_SQL_TYPE = "INTEGER";
+/** Options for {@link deriveModelColumns}. */
+export interface DeriveColumnsOptions {
+    /**
+     * Per-column SQL-type OVERRIDES (property name → §4.1 SQL type token), for columns whose decorator
+     * family is ambiguous (a bare `Number` that is actually REAL/DECIMAL) or that need a non-default
+     * width. Takes precedence over the family-derived token. The escape hatch for the no-INT-vs-REAL
+     * decorator gap — no assumption is baked into the engine.
+     */
+    readonly columnTypes?: Readonly<Record<string, string>>;
+}
+/**
+ * Translate ONE column's {@link ColumnMeta} to its §4.1 SQL-type token. Precedence (Phase F-2 / #105
+ * option B):
+ *   1. an explicit `columnTypes` override (the REAL/DECIMAL/width escape hatch) wins;
+ *   2. else the family token from {@link COLUMN_FAMILY_SQL_TYPE} (an explicit `@column.*` `sqlCast`);
+ *   3. else the decorator's `baseSqlType` — derived from the field's TS `design:type` (String→TEXT /
+ *      Number→INTEGER / Boolean→BOOLEAN / Date→TIMESTAMP / BigInt→BIGINT), so a bare `@column()` types
+ *      correctly for the SCP typed-read de-box (the fix for F1's blanket-INTEGER default);
+ *   4. else {@link DEFAULT_UNCAST_SQL_TYPE} (only when `design:type` is unavailable).
+ * Fail-closed: a family token the mapping does not know, or a produced token `coltype.ts` rejects,
+ * THROWS (naming the column) — never a silent skip (no-assume, no-fallback).
+ */
+export declare function columnSqlType(propKey: string, meta: ColumnMeta, override?: string): string;
+/**
+ * Derive the SCP `static columns` ({@link ModelColumns}) for a decorated model class from its
+ * `@column` `ColumnMeta` registry (the decorator IS the type SoT for v1/v2's decorator surface). The
+ * table is the model's `TABLE_NAME` (or the model-name lowercased, matching the decorator's
+ * `effectiveTableName`). Each column keys by its DB `columnName` (what a SELECT projects), mapping to
+ * its §4.1 SQL type. A model with no `@column` declarations yields no table entry.
+ *
+ * This is the ONE real translation in the adapter — the read-path de-box (INT→number / BIGINT→string /
+ * DATE→string / BOOLEAN→boolean) and the codegen `outType` both consult exactly this SoT.
+ */
+export declare function deriveModelColumns(modelClass: ModelClassLike, options?: DeriveColumnsOptions): ModelColumns;
+/** The decorated model class shape the adapter reads (a `@model`-decorated `DBModel` subclass). */
+export interface ModelClassLike {
+    readonly name: string;
+    readonly TABLE_NAME?: string;
+}
+/** The effective table name (v1 `@model` rule): explicit `TABLE_NAME`, else the model name lowercased. */
+export declare function tableNameOf(modelClass: ModelClassLike): string;
+/**
+ * Compile a decorated model's `createMany` — and a `create` WITH `onConflict` (upsert) — into a batch
+ * write {@link SqlBundle} via `compileCreateManyBundle`. This is the UPSERT carry: `onConflict` /
+ * `onConflictUpdate` / `onConflictIgnore` are `compileInsertMany` BUILD options (not authored ports),
+ * so they carry end-to-end here with NO SCP authoring addition — exactly as v1's `create` and
+ * `createMany` share the ONE `DBModel._insert` grouping path (`buildInsert` handles ON CONFLICT for
+ * both a single record and a batch). A single-record `records` array is a one-group createMany that
+ * emits the SAME statement `_insert` does for a single upsert.
+ *
+ * Parity scope (the v1/v2 SQL-parity rule, per dialect — NOT a blanket "byte-identical to v1"): on
+ * **Postgres** the emitted upsert INSERT is byte-identical to v1 (`compileInsertMany` copies the v1
+ * `buildInsert` verbatim; PG stays base-class tuple/placeholder form). On **MySQL / SQLite** the v2
+ * form is the JSON-array single-param shape (`json_each` / `JSON_TABLE`), which is DELIBERATELY NOT
+ * byte-identical to v1's per-row placeholder expansion — it is the established v2 shape the conformance
+ * corpus freezes (#64/#65), executing to the same rows. So: pg = v1-byte-identical; mysql/sqlite = the
+ * v2 JSON-array form (equivalent result, distinct text).
+ *
+ * @param options the `compileCreateManyBundle` options (records / rawRecords / sqlCastMap / onConflict /
+ *   onConflictUpdate / onConflictIgnore / returning / pk) — already serialized as `DBModel._insert`
+ *   holds them.
+ */
+export declare function compileCreateBundle(modelClass: ModelClassLike, name: string, options: InsertManyBuildOptions & {
+    pk?: {
+        columns: readonly string[];
+        autoInc: string | null;
+    };
+}, dialect?: DialectName, columnsOptions?: DeriveColumnsOptions): SqlBundle;
+/** Compile a decorated model's `updateMany` into a batch write {@link SqlBundle} (`compileUpdateManyBundle`). */
+export declare function compileUpdateBundle(name: string, options: UpdateManyBuildOptions, dialect?: DialectName): SqlBundle;
+/**
+ * Compile a decorated model's `deleteMany` into a batch write {@link SqlBundle} (`compileDeleteManyBundle`):
+ * a PK-set IN-list DELETE (single key) or one DELETE per composite-key group. `keyColumns` +
+ * `returning` carry straight through.
+ */
+export declare function compileDeleteBundle(name: string, options: {
+    tableName: string;
+    keyColumns: string[];
+    keys: Record<string, unknown>[];
+    returning?: string;
+}, dialect?: DialectName): SqlBundle;
+/**
+ * Build a {@link KeyTypeResolver} from a decorated model's `static columns` SoT — `(table, column) →`
+ * the de-box bc scalar of that key column ({@link import('./coltype').keyArrayElemScalar}). Threaded into
+ * {@link relationReadAuthoring} so each relation's `pluck` key array is stamped with the type its
+ * READ-materialized key value carries. Returns `undefined` when the model declares no columns.
+ */
+export declare function relationKeyTypeResolver(modelClass: ModelClassLike, columnsOptions?: DeriveColumnsOptions): KeyTypeResolver | undefined;
+/** The fail-closed column-type resolver for a decorated model (its `static columns` SoT), or `undefined` if it has no columns. */
+export declare function modelColumnResolver(modelClass: ModelClassLike, columnsOptions?: DeriveColumnsOptions): ColumnTypeResolver | undefined;
+/**
+ * Translate a decorated model's `@hasMany` / `@belongsTo` / `@hasOne` {@link RelationMeta} registry
+ * into SCP {@link RelationDecl}s. Single AND composite keys are supported: the decorator's
+ * `keysFactory` resolves lazily (forward refs) to `[srcCol, tgtCol]` (single) or `[[…],[…]]`
+ * (composite); the target table + projection come from the target model's `@column` metadata (the
+ * relation projects the child's OWN columns). Per-parent `order` / `limit` (hasMany window) and
+ * `hardLimit` carry from the decorator `options`.
+ *
+ * @param modelClass the parent (source) `@model` class.
+ * @param resolveTargetModel model NAME → the target `@model` class (the decorator records the target
+ *   model NAME on the key column; the caller supplies the registry — same lazy-resolution shape v1's
+ *   `_loadRelation` uses).
+ */
+export declare function deriveRelationDecls(modelClass: ModelClassLike, resolveTargetModel: (modelName: string) => ModelClassLike, dialect?: DialectName): RelationDecl[];
+/**
+ * Translate ONE {@link RelationMeta} → a {@link RelationDecl} (single or composite key) AND the
+ * resolved target model (so a caller can bake the child's de-box materializers from the TARGET
+ * model's `static columns` — the relation projects the child's own columns).
+ */
+export declare function relationDeclOf(rel: RelationMeta, resolveTargetModel: (modelName: string) => ModelClassLike, dialect?: DialectName): {
+    decl: RelationDecl;
+    targetModel: ModelClassLike;
+};
+/**
+ * Compile a decorated model's relation registry into ready {@link RelationOp}s (one per relation). Each
+ * op's child-column de-box materializers are baked from the TARGET model's `static columns` (the same
+ * resolution the primary read uses) — ZERO per-read introspection.
+ */
+export declare function compileRelationOps(modelClass: ModelClassLike, resolveTargetModel: (modelName: string) => ModelClassLike, dialect?: DialectName, columnsOptions?: DeriveColumnsOptions): Record<string, RelationOp>;
+//# sourceMappingURL=decorator-adapter.d.ts.map

package/dist/scp/decorator-adapter.d.ts.map

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