@zmdb/orm 1.0.0-beta.1

package/dist/outbox/index.js

@@ -0,0 +1,323 @@
+import {} from '@zmdb/schema';
+import { schemaFromIR } from '@zmdb/schema/ir';
+import {} from '@zmdb/schema/tags';
+import { createQueryCompiler } from '@zmdb/sql';
+import {} from '../index.js';
+import {} from '../transactions/index.js';
+import { outboxCandidatesQuery, outboxClaimQuery, outboxMarkDeadQuery, outboxMarkDeliveredQuery, outboxMarkRetryQuery, outboxReadBackQuery, } from './sql.js';
+function requiredDialect(dialect, owner) {
+    if (dialect === undefined)
+        throw new TypeError(`${owner} requires an explicit database dialect object`);
+    return dialect;
+}
+export * from './sql.js';
+const EMPTY_COLUMN = {
+    primaryKey: false,
+    serial: false,
+    unique: false,
+    sensitive: false,
+    constraints: {},
+    rules: [],
+};
+/**
+ * The built-in physical declaration applications include in schema snapshots.
+ *
+ * The public row type uses app-facing camelCase, while this value names the
+ * snake_case columns emitted by `outboxMigration` and used by the dispatcher.
+ */
+export const OutboxSchema = schemaFromIR({
+    table: 'zmdb_outbox',
+    physicalTable: 'zmdb_outbox',
+    primaryKey: ['id'],
+    relations: [],
+    foreignKeys: [],
+    columns: [
+        {
+            ...EMPTY_COLUMN,
+            name: 'id',
+            physicalName: 'id',
+            sql: 'text',
+            nullable: false,
+            primaryKey: true,
+            hasDefault: false,
+        },
+        {
+            ...EMPTY_COLUMN,
+            name: 'topic',
+            physicalName: 'topic',
+            sql: 'text',
+            nullable: false,
+            hasDefault: false,
+        },
+        {
+            ...EMPTY_COLUMN,
+            name: 'payload',
+            physicalName: 'payload',
+            sql: 'text',
+            nullable: false,
+            hasDefault: false,
+        },
+        {
+            ...EMPTY_COLUMN,
+            name: 'status',
+            physicalName: 'status',
+            sql: 'jsonEnum',
+            nullable: false,
+            hasDefault: true,
+            enum: ['dead', 'delivered', 'pending'],
+        },
+        {
+            ...EMPTY_COLUMN,
+            name: 'attempts',
+            physicalName: 'attempts',
+            sql: 'integer',
+            nullable: false,
+            hasDefault: true,
+        },
+        {
+            ...EMPTY_COLUMN,
+            name: 'created_at',
+            physicalName: 'created_at',
+            sql: 'timestamp',
+            nullable: false,
+            hasDefault: true,
+        },
+        {
+            ...EMPTY_COLUMN,
+            name: 'lease_owner',
+            physicalName: 'lease_owner',
+            sql: 'text',
+            nullable: false,
+            hasDefault: true,
+        },
+        {
+            ...EMPTY_COLUMN,
+            name: 'lease_until',
+            physicalName: 'lease_until',
+            sql: 'timestamp',
+            nullable: false,
+            hasDefault: true,
+        },
+        {
+            ...EMPTY_COLUMN,
+            name: 'delivered_at',
+            physicalName: 'delivered_at',
+            sql: 'timestamp',
+            nullable: true,
+            hasDefault: false,
+        },
+        {
+            ...EMPTY_COLUMN,
+            name: 'last_error',
+            physicalName: 'last_error',
+            sql: 'text',
+            nullable: true,
+            hasDefault: false,
+        },
+    ],
+});
+export function outboxWriter(tx) {
+    const dialect = requiredDialect(tx.dialect, 'outboxWriter');
+    return {
+        async write(topic, payload) {
+            const id = globalThis.crypto.randomUUID();
+            await tx.execute(createQueryCompiler(dialect)
+                .insertInto('zmdb_outbox')
+                .values({
+                id,
+                topic,
+                payload,
+                status: 'pending',
+                attempts: 0,
+                created_at: new Date(),
+                lease_owner: '',
+                lease_until: new Date(0),
+                delivered_at: null,
+                last_error: null,
+            })
+                .compile());
+            return id;
+        },
+    };
+}
+function claimedRow(row) {
+    const { id, topic, payload, attempts } = row;
+    if (typeof id !== 'string' ||
+        typeof topic !== 'string' ||
+        typeof payload !== 'string' ||
+        typeof attempts !== 'number' ||
+        !Number.isInteger(attempts) ||
+        attempts < 0) {
+        throw new Error('@zmdb/orm: invalid outbox row returned by the driver');
+    }
+    return { id, topic, payload, attempts };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function deadRowFromInvalid(raw, attempts, lastError) {
+    return {
+        id: typeof raw['id'] === 'string' ? raw['id'] : String(raw['id']),
+        topic: typeof raw['topic'] === 'string' ? raw['topic'] : String(raw['topic']),
+        payload: typeof raw['payload'] === 'string' ? raw['payload'] : String(raw['payload']),
+        attempts,
+        lastError,
+    };
+}
+function positiveInteger(name, value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`@zmdb/orm: ${name} must be a positive safe integer`);
+    }
+    return value;
+}
+const MAX_TIMER_MS = 2_147_483_647;
+function timerDelay(name, value) {
+    const delay = positiveInteger(name, value);
+    if (delay > MAX_TIMER_MS) {
+        throw new Error(`@zmdb/orm: ${name} must not exceed ${MAX_TIMER_MS}`);
+    }
+    return delay;
+}
+export function createOutboxDispatcher(options) {
+    const dialect = requiredDialect(options.driver.dialect, 'createOutboxDispatcher');
+    const batch = positiveInteger('batch', options.batch ?? 100);
+    const leaseMs = positiveInteger('leaseMs', options.leaseMs ?? 30_000);
+    const idleMs = timerDelay('idleMs', options.idleMs ?? 1_000);
+    const maxIdleMs = timerDelay('maxIdleMs', options.maxIdleMs ?? 30_000);
+    const maxAttempts = positiveInteger('maxAttempts', options.maxAttempts ?? 10);
+    if (maxIdleMs < idleMs) {
+        throw new Error('@zmdb/orm: maxIdleMs must be greater than or equal to idleMs');
+    }
+    const backoffMs = options.backoffMs ?? (attempts => Math.min(2 ** attempts * 1_000, 300_000));
+    let stopped = false;
+    let started = false;
+    let timer;
+    const activePasses = new Set();
+    let nextIdleMs = idleMs;
+    const runPass = async () => {
+        const now = new Date();
+        const candidates = await options.driver.execute(outboxCandidatesQuery(dialect, { now, batch }));
+        const ids = candidates.flatMap(row => (typeof row['id'] === 'string' ? [row['id']] : []));
+        if (ids.length === 0)
+            return { claimed: 0, delivered: 0, failed: 0 };
+        const token = globalThis.crypto.randomUUID();
+        const leaseUntil = new Date(now.getTime() + leaseMs);
+        await options.driver.execute(outboxClaimQuery(dialect, { now, token, leaseUntil, ids }));
+        const candidateOrder = new Map(ids.map((id, index) => [id, index]));
+        const rows = (await options.driver.execute(outboxReadBackQuery(dialect, { token }))).toSorted((left, right) => {
+            const leftIndex = typeof left['id'] === 'string' ? candidateOrder.get(left['id']) : undefined;
+            const rightIndex = typeof right['id'] === 'string' ? candidateOrder.get(right['id']) : undefined;
+            return (leftIndex ?? ids.length) - (rightIndex ?? ids.length);
+        });
+        let delivered = 0;
+        let failed = 0;
+        for (const raw of rows) {
+            let row;
+            try {
+                row = claimedRow(raw);
+            }
+            catch (error) {
+                failed += 1;
+                const id = raw['id'];
+                const previousAttempts = raw['attempts'];
+                if (typeof id !== 'string' || typeof previousAttempts !== 'number' || !Number.isInteger(previousAttempts)) {
+                    throw error;
+                }
+                const attempts = previousAttempts + 1;
+                const lastError = errorMessage(error);
+                await options.driver.execute(outboxMarkDeadQuery(dialect, { id, token, attempts, lastError }));
+                await options.onDead?.(deadRowFromInvalid(raw, attempts, lastError));
+                continue;
+            }
+            const attempts = row.attempts + 1;
+            let publishError;
+            try {
+                await options.publish(row.topic, row.payload);
+            }
+            catch (error) {
+                publishError = error;
+            }
+            if (publishError === undefined) {
+                await options.driver.execute(outboxMarkDeliveredQuery(dialect, {
+                    id: row.id,
+                    token,
+                    deliveredAt: new Date(),
+                    attempts,
+                }));
+                delivered += 1;
+            }
+            else {
+                failed += 1;
+                const lastError = errorMessage(publishError);
+                if (attempts >= maxAttempts) {
+                    await options.driver.execute(outboxMarkDeadQuery(dialect, { id: row.id, token, attempts, lastError }));
+                    await options.onDead?.({ ...row, attempts, lastError });
+                }
+                else {
+                    const delay = backoffMs(attempts);
+                    if (!Number.isFinite(delay) || delay < 0) {
+                        throw new Error('@zmdb/orm: backoffMs must return a finite non-negative number');
+                    }
+                    await options.driver.execute(outboxMarkRetryQuery(dialect, {
+                        id: row.id,
+                        token,
+                        attempts,
+                        lastError,
+                        leaseUntil: new Date(Date.now() + delay),
+                    }));
+                }
+            }
+        }
+        return { claimed: rows.length, delivered, failed };
+    };
+    const runOnce = () => {
+        if (stopped)
+            return Promise.resolve({ claimed: 0, delivered: 0, failed: 0 });
+        const pass = runPass();
+        activePasses.add(pass);
+        void pass.then(() => activePasses.delete(pass), () => activePasses.delete(pass));
+        return pass;
+    };
+    const schedule = (delay) => {
+        timer = setTimeout(() => {
+            if (stopped)
+                return;
+            const pass = runOnce();
+            void pass.then(report => {
+                if (stopped)
+                    return;
+                if (report.claimed > 0) {
+                    nextIdleMs = idleMs;
+                    schedule(report.claimed >= batch ? 0 : nextIdleMs);
+                }
+                else {
+                    nextIdleMs = Math.min(nextIdleMs * 2, maxIdleMs);
+                    schedule(nextIdleMs);
+                }
+            }, () => {
+                if (!stopped)
+                    schedule(nextIdleMs);
+            });
+        }, delay);
+    };
+    const start = () => {
+        if (started || stopped)
+            return;
+        started = true;
+        schedule(idleMs);
+    };
+    return {
+        runOnce,
+        start,
+        onModuleInit: start,
+        async onShutdown() {
+            stopped = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            while (activePasses.size > 0) {
+                await Promise.allSettled(activePasses);
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/outbox/index.js.map

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

package/dist/outbox/sql.d.ts

@@ -0,0 +1,52 @@
+import { type CompiledQuery, type DialectTarget } from '@zmdb/sql';
+export declare const OUTBOX_TABLE = "zmdb_outbox";
+export type OutboxStatus = 'pending' | 'delivered' | 'dead';
+export interface OutboxMigration {
+    readonly version: number;
+    readonly name: string;
+    readonly up: string;
+    readonly down: string;
+}
+/**
+ * Most dialects index only pending rows. Dialects that cannot represent the
+ * predicate use the full composite index with `status` first to preserve a
+ * useful pending-row prefix instead of degrading to an unindexed scan.
+ */
+export declare function outboxPendingIndexDdl(dialect: DialectTarget): string;
+/** The declared outbox table's migration DDL, including the defaults its type tags cannot carry. */
+export declare function outboxTableDdl(dialect: DialectTarget): string;
+/** A normal migration value applications can place in their ordered migration list. */
+export declare function outboxMigration(version: number, dialect: DialectTarget): OutboxMigration;
+export declare function outboxCandidatesQuery(dialect: DialectTarget, args: {
+    readonly now: Date;
+    readonly batch: number;
+}): CompiledQuery;
+export declare function outboxClaimQuery(dialect: DialectTarget, args: {
+    readonly now: Date;
+    readonly token: string;
+    readonly leaseUntil: Date;
+    readonly ids: readonly string[];
+}): CompiledQuery;
+export declare function outboxReadBackQuery(dialect: DialectTarget, args: {
+    readonly token: string;
+}): CompiledQuery;
+export declare function outboxMarkDeliveredQuery(dialect: DialectTarget, args: {
+    readonly id: string;
+    readonly token: string;
+    readonly deliveredAt: Date;
+    readonly attempts: number;
+}): CompiledQuery;
+export declare function outboxMarkRetryQuery(dialect: DialectTarget, args: {
+    readonly id: string;
+    readonly token: string;
+    readonly attempts: number;
+    readonly lastError: string;
+    readonly leaseUntil: Date;
+}): CompiledQuery;
+export declare function outboxMarkDeadQuery(dialect: DialectTarget, args: {
+    readonly id: string;
+    readonly token: string;
+    readonly attempts: number;
+    readonly lastError: string;
+}): CompiledQuery;
+//# sourceMappingURL=sql.d.ts.map

package/dist/outbox/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/outbox/sql.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAElB,KAAK,aAAa,EACnB,MAAM,WAAW,CAAC;AAEnB,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAC1C,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAI5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAepE;AASD,oGAAoG;AACpG,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAyB7D;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,eAAe,CAOxF;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD,aAAa,CASf;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE;IACJ,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,GACA,aAAa,CAQf;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAM3G;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE;IACJ,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GACA,aAAa,CAOf;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE;IACJ,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CAC3B,GACA,aAAa,CAOf;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE;IACJ,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GACA,aAAa,CAOf"}

package/dist/outbox/sql.js

@@ -0,0 +1,115 @@
+import { createQueryCompiler, dialectTraits, quoteIdentifier, } from '@zmdb/sql';
+export const OUTBOX_TABLE = 'zmdb_outbox';
+const PENDING = 'pending';
+/**
+ * Most dialects index only pending rows. Dialects that cannot represent the
+ * predicate use the full composite index with `status` first to preserve a
+ * useful pending-row prefix instead of degrading to an unindexed scan.
+ */
+export function outboxPendingIndexDdl(dialect) {
+    const definition = {
+        name: 'zmdb_outbox_pending',
+        table: OUTBOX_TABLE,
+        columns: ['status', 'lease_until', 'created_at'],
+        ...(outboxDialect(dialect).pendingIndex === 'full' ? {} : { where: "status = 'pending'" }),
+    };
+    const statements = dialect.migrations.emitSchemaObject({
+        kind: 'create_index',
+        definition,
+    });
+    if (statements.length !== 1 || statements[0] === undefined) {
+        throw new TypeError(`${dialect.name} outbox index emission must return exactly one statement`);
+    }
+    return statements[0];
+}
+function outboxDialect(dialect) {
+    if (dialect.outbox === undefined) {
+        throw new TypeError(`${dialect.name} does not provide an outbox DDL strategy`);
+    }
+    return dialect.outbox;
+}
+/** The declared outbox table's migration DDL, including the defaults its type tags cannot carry. */
+export function outboxTableDdl(dialect) {
+    const q = (name) => quoteIdentifier(dialect, name);
+    const traits = dialectTraits(dialect);
+    const outbox = outboxDialect(dialect);
+    const timestamp = traits.types.timestamp;
+    // MySQL refuses TEXT primary keys and TEXT columns in an index without a prefix
+    // length. These three values are bounded by construction, so the migration uses
+    // bounded storage there while the application type remains string.
+    const text = traits.types.text;
+    const idType = outbox.boundedTextType(36);
+    const statusType = outbox.boundedTextType(16);
+    const leaseOwnerType = outbox.boundedTextType(36);
+    return (`${outbox.createTable} ${q(OUTBOX_TABLE)} (` +
+        `${q('id')} ${idType} PRIMARY KEY, ` +
+        `${q('topic')} ${text} NOT NULL, ` +
+        `${q('payload')} ${text} NOT NULL, ` +
+        `${q('status')} ${statusType} NOT NULL DEFAULT 'pending', ` +
+        `${q('attempts')} ${traits.types.integer} NOT NULL DEFAULT 0, ` +
+        `${q('created_at')} ${timestamp} NOT NULL DEFAULT ${outbox.createdAtDefault}, ` +
+        `${q('lease_owner')} ${leaseOwnerType} NOT NULL DEFAULT '', ` +
+        `${q('lease_until')} ${timestamp} NOT NULL DEFAULT ${outbox.epochLiteral}, ` +
+        `${q('delivered_at')} ${timestamp}, ` +
+        `${q('last_error')} ${text})`);
+}
+/** A normal migration value applications can place in their ordered migration list. */
+export function outboxMigration(version, dialect) {
+    return {
+        version,
+        name: 'create_zmdb_outbox',
+        up: `${outboxTableDdl(dialect)}; ${outboxPendingIndexDdl(dialect)}`,
+        down: `DROP TABLE ${quoteIdentifier(dialect, OUTBOX_TABLE)}`,
+    };
+}
+export function outboxCandidatesQuery(dialect, args) {
+    return createQueryCompiler(dialect)
+        .selectFrom(OUTBOX_TABLE)
+        .select(['id'])
+        .where('status', '=', PENDING)
+        .where('lease_until', '<', args.now)
+        .orderBy('created_at', 'asc')
+        .limit(args.batch)
+        .compile();
+}
+export function outboxClaimQuery(dialect, args) {
+    return createQueryCompiler(dialect)
+        .updateTable(OUTBOX_TABLE)
+        .set({ lease_owner: args.token, lease_until: args.leaseUntil })
+        .where('status', '=', PENDING)
+        .where('lease_until', '<', args.now)
+        .whereIn('id', args.ids)
+        .compile();
+}
+export function outboxReadBackQuery(dialect, args) {
+    return createQueryCompiler(dialect)
+        .selectFrom(OUTBOX_TABLE)
+        .select(['id', 'topic', 'payload', 'attempts'])
+        .where('lease_owner', '=', args.token)
+        .compile();
+}
+export function outboxMarkDeliveredQuery(dialect, args) {
+    return createQueryCompiler(dialect)
+        .updateTable(OUTBOX_TABLE)
+        .set({ status: 'delivered', delivered_at: args.deliveredAt, attempts: args.attempts })
+        .where('id', '=', args.id)
+        .where('lease_owner', '=', args.token)
+        .compile();
+}
+export function outboxMarkRetryQuery(dialect, args) {
+    return createQueryCompiler(dialect)
+        .updateTable(OUTBOX_TABLE)
+        .set({ attempts: args.attempts, last_error: args.lastError, lease_until: args.leaseUntil })
+        .where('id', '=', args.id)
+        .where('lease_owner', '=', args.token)
+        .compile();
+}
+export function outboxMarkDeadQuery(dialect, args) {
+    return createQueryCompiler(dialect)
+        .updateTable(OUTBOX_TABLE)
+        .set({ status: 'dead', attempts: args.attempts, last_error: args.lastError })
+        .where('id', '=', args.id)
+        .where('lease_owner', '=', args.token)
+        .compile();
+}
+//# sourceMappingURL=sql.js.map

package/dist/outbox/sql.js.map

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

package/dist/relations/index.d.ts

@@ -0,0 +1,38 @@
+import type { SchemaIR } from '@zmdb/schema/ir';
+import { type ComparisonPredicate, type DialectTarget } from '@zmdb/sql';
+export type PopulateDialect = DialectTarget;
+export interface PopulateQuery {
+    readonly kind: 'join' | 'batched';
+    readonly sql: string;
+    readonly parameters: readonly unknown[];
+}
+/**
+ * Compile a populate hint into SQL: a to-one becomes an `INNER JOIN`, a to-many a batched
+ * `IN (…)` select over the parent keys.
+ *
+ * Takes the declaring table's IR and a relation name rather than a relation object, which is
+ * what makes the two spellings one: the columns on either side of the `ON` come out of
+ * `resolveRelation`, the same call `@zmdb/orm`'s `populate` makes.
+ */
+export declare function compilePopulate(ir: SchemaIR, relationName: string, dialect: PopulateDialect, parentIds?: readonly unknown[], targetFilters?: readonly ComparisonPredicate[], schemas?: readonly SchemaIR[]): PopulateQuery;
+/**
+ * Attach a populated relation to a parent row, without mutating it.
+ *
+ * The type widening is `Populated<T, K>` in `../derive/query.ts`, which reads the declared
+ * relation property; this only puts the value there.
+ */
+export declare function attachPopulated<P extends Record<string, unknown>, N extends string, V>(parent: P, name: N, value: V): P & {
+    [K in N]: V;
+};
+/**
+ * A row from a join written against two tables directly. LEFT: the joined columns may be
+ * absent, so they come back optional.
+ *
+ * `../derive/query.ts` has a `JoinRow<T, K, Kind>` that names the joined side by relation
+ * key instead; this is the form for a join whose target is not a declared relation of the
+ * base table.
+ */
+export type JoinRow<Base, Joined, Kind extends 'inner' | 'left' = 'left'> = Kind extends 'inner' ? Base & Joined : Base & Partial<Joined>;
+/** Rename aliased columns per a { alias: outKey } map (stable, non-mutating). */
+export declare function aliasRow<Row extends Record<string, unknown>>(row: Row, map: Readonly<Record<string, string>>): Record<string, unknown>;
+//# sourceMappingURL=index.d.ts.map

package/dist/relations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/relations/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAOL,KAAK,mBAAmB,EACxB,KAAK,aAAa,EACnB,MAAM,WAAW,CAAC;AAEnB,MAAM,MAAM,eAAe,GAAG,aAAa,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,CAAC;CACzC;AA6CD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,EACZ,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,eAAe,EACxB,SAAS,GAAE,SAAS,OAAO,EAAO,EAClC,aAAa,GAAE,SAAS,mBAAmB,EAAO,EAClD,OAAO,GAAE,SAAS,QAAQ,EAAO,GAChC,aAAa,CAiGf;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,EACpF,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,CAAC,GACP,CAAC,GAAG;KAAG,CAAC,IAAI,CAAC,GAAG,CAAC;CAAE,CAKrB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,OAAO,GAAG,MAAM,GAAG,MAAM,IAAI,IAAI,SAAS,OAAO,GAC5F,IAAI,GAAG,MAAM,GACb,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE3B,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB"}