@spinajs/orm 2.0.481 → 2.0.484

package/lib/cjs/subject.d.ts

@@ -0,0 +1,100 @@
+import { IModelDescriptor, IRelationDescriptor, OrphanPolicy } from './interfaces.js';
+import type { ModelBase } from './model.js';
+/**
+ * What `save()` will do with one model instance.
+ *
+ * There is no `delete` member: every row `save()` removes is removed because it was detached
+ * from a relation, and that is carried by `IOrphanDelta` keyed by primary key rather than by
+ * a subject over a model instance the caller no longer holds.
+ */
+export declare enum SubjectOperation {
+    Insert = "insert",
+    Update = "update",
+    None = "none"
+}
+/**
+ * A foreign-key column whose value is another model's primary key — which may not exist yet
+ * when the subject is built. Resolved by the executor immediately before the statement that
+ * needs it.
+ */
+export interface IPendingForeignKey {
+    /** Column on this subject's own row that receives the key. */
+    Column: string;
+    /** Model whose primary key is the value. */
+    Target: ModelBase;
+}
+/**
+ * The membership change of one hasMany relation on one owner, as of the snapshot diff.
+ *
+ * `Added` are members with no snapshot ( never in the database ). `Kept` are members that
+ * were already there or were re-parented in from elsewhere. `RemovedKeys` are primary keys
+ * that were in the snapshot and are not in the array any more.
+ */
+export interface IRelationDelta {
+    Descriptor: IRelationDescriptor;
+    Added: ModelBase[];
+    Kept: ModelBase[];
+    RemovedKeys: unknown[];
+}
+/**
+ * Junction rows to create and destroy for one manyToMany relation on one owner.
+ * `Added` holds target models because their keys may not exist yet; `RemovedKeys` holds
+ * plain keys because those models are gone from the array.
+ */
+export interface IJunctionDelta {
+    Descriptor: IRelationDescriptor;
+    JunctionDescriptor: IModelDescriptor;
+    Owner: ModelBase;
+    Added: ModelBase[];
+    RemovedKeys: unknown[];
+}
+/**
+ * Rows detached from a relation and the policy that decides their fate.
+ */
+export interface IOrphanDelta {
+    Descriptor: IRelationDescriptor;
+    TargetDescriptor: IModelDescriptor;
+    Policy: OrphanPolicy;
+    PrimaryKeys: unknown[];
+}
+/**
+ * One model instance and everything `save()` needs to know about it.
+ */
+export declare class Subject {
+    readonly Model: ModelBase;
+    readonly Descriptor: IModelDescriptor;
+    Operation: SubjectOperation;
+    /** Columns that differ from the snapshot. Empty for an insert, which writes everything. */
+    ChangedColumns: string[];
+    /** Foreign keys resolved just before this subject's own statement runs. */
+    PendingForeignKeys: IPendingForeignKey[];
+    /**
+     * Foreign keys that cannot be resolved before this subject's INSERT — a self-referencing
+     * cycle — and are applied by a follow-up UPDATE in the update phase instead.
+     */
+    DeferredForeignKeys: IPendingForeignKey[];
+    /** hasMany membership changes owned by this subject. Read by the orphan resolver. */
+    RelationDeltas: IRelationDelta[];
+    /** `Model#key`, or `Model#<new>` before the key exists. Diagnostics only — never a map key. */
+    get Identity(): string;
+    constructor(Model: ModelBase, Descriptor: IModelDescriptor, Operation: SubjectOperation);
+}
+/**
+ * Everything one `save()` will do, before ordering.
+ */
+export declare class SubjectSet {
+    readonly Subjects: Subject[];
+    readonly Junctions: IJunctionDelta[];
+    readonly Orphans: IOrphanDelta[];
+    private _byModel;
+    /**
+     * Registers `subject`, or returns the one already registered for the same model instance.
+     * Instance identity is the key — canonicalizing two instances of one row is the identity
+     * map's job, and it runs first.
+     */
+    add(subject: Subject): Subject;
+    find(model: ModelBase): Subject | undefined;
+    /** True when this set would emit no statements at all. */
+    get IsEmpty(): boolean;
+}
+//# sourceMappingURL=subject.d.ts.map

package/lib/cjs/subject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../src/subject.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;GAMG;AACH,oBAAY,gBAAgB;IAC1B,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,mBAAmB,CAAC;IAChC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,WAAW,EAAE,OAAO,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,mBAAmB,CAAC;IAChC,kBAAkB,EAAE,gBAAgB,CAAC;IACrC,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,EAAE,OAAO,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,mBAAmB,CAAC;IAChC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,MAAM,EAAE,YAAY,CAAC;IACrB,WAAW,EAAE,OAAO,EAAE,CAAC;CACxB;AAkBD;;GAEG;AACH,qBAAa,OAAO;aAqBU,KAAK,EAAE,SAAS;aAAkB,UAAU,EAAE,gBAAgB;IAAS,SAAS,EAAE,gBAAgB;IApB9H,2FAA2F;IACpF,cAAc,EAAE,MAAM,EAAE,CAAM;IAErC,2EAA2E;IACpE,kBAAkB,EAAE,kBAAkB,EAAE,CAAM;IAErD;;;OAGG;IACI,mBAAmB,EAAE,kBAAkB,EAAE,CAAM;IAEtD,qFAAqF;IAC9E,cAAc,EAAE,cAAc,EAAE,CAAM;IAE7C,+FAA+F;IAC/F,IAAW,QAAQ,IAAI,MAAM,CAE5B;gBAE2B,KAAK,EAAE,SAAS,EAAkB,UAAU,EAAE,gBAAgB,EAAS,SAAS,EAAE,gBAAgB;CAC/H;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,SAAgB,QAAQ,EAAE,OAAO,EAAE,CAAM;IACzC,SAAgB,SAAS,EAAE,cAAc,EAAE,CAAM;IACjD,SAAgB,OAAO,EAAE,YAAY,EAAE,CAAM;IAE7C,OAAO,CAAC,QAAQ,CAAiC;IAEjD;;;;OAIG;IACI,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAY9B,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS;IAIlD,0DAA0D;IAC1D,IAAW,OAAO,IAAI,OAAO,CAE5B;CACF"}

package/lib/cjs/subject.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubjectSet = exports.Subject = exports.SubjectOperation = void 0;
+/**
+ * What `save()` will do with one model instance.
+ *
+ * There is no `delete` member: every row `save()` removes is removed because it was detached
+ * from a relation, and that is carried by `IOrphanDelta` keyed by primary key rather than by
+ * a subject over a model instance the caller no longer holds.
+ */
+var SubjectOperation;
+(function (SubjectOperation) {
+    SubjectOperation["Insert"] = "insert";
+    SubjectOperation["Update"] = "update";
+    SubjectOperation["None"] = "none";
+})(SubjectOperation || (exports.SubjectOperation = SubjectOperation = {}));
+/**
+ * Renders a primary key for a diagnostic message. A composite key arrives as a tuple; a key
+ * with any part missing is not a key at all and reads as `<new>`, the same as an absent one.
+ */
+function describeKey(pk) {
+    if (pk === null || pk === undefined) {
+        return '<new>';
+    }
+    if (Array.isArray(pk)) {
+        return pk.some((p) => p === null || p === undefined) ? '<new>' : pk.map((p) => String(p)).join(',');
+    }
+    return String(pk);
+}
+/**
+ * One model instance and everything `save()` needs to know about it.
+ */
+class Subject {
+    /** `Model#key`, or `Model#<new>` before the key exists. Diagnostics only — never a map key. */
+    get Identity() {
+        return `${this.Descriptor.Name}#${describeKey(this.Model.PrimaryKeyValue)}`;
+    }
+    constructor(Model, Descriptor, Operation) {
+        this.Model = Model;
+        this.Descriptor = Descriptor;
+        this.Operation = Operation;
+        /** Columns that differ from the snapshot. Empty for an insert, which writes everything. */
+        this.ChangedColumns = [];
+        /** Foreign keys resolved just before this subject's own statement runs. */
+        this.PendingForeignKeys = [];
+        /**
+         * Foreign keys that cannot be resolved before this subject's INSERT — a self-referencing
+         * cycle — and are applied by a follow-up UPDATE in the update phase instead.
+         */
+        this.DeferredForeignKeys = [];
+        /** hasMany membership changes owned by this subject. Read by the orphan resolver. */
+        this.RelationDeltas = [];
+    }
+}
+exports.Subject = Subject;
+/**
+ * Everything one `save()` will do, before ordering.
+ */
+class SubjectSet {
+    constructor() {
+        this.Subjects = [];
+        this.Junctions = [];
+        this.Orphans = [];
+        this._byModel = new Map();
+    }
+    /**
+     * Registers `subject`, or returns the one already registered for the same model instance.
+     * Instance identity is the key — canonicalizing two instances of one row is the identity
+     * map's job, and it runs first.
+     */
+    add(subject) {
+        const existing = this._byModel.get(subject.Model);
+        if (existing) {
+            return existing;
+        }
+        this._byModel.set(subject.Model, subject);
+        this.Subjects.push(subject);
+        return subject;
+    }
+    find(model) {
+        return this._byModel.get(model);
+    }
+    /** True when this set would emit no statements at all. */
+    get IsEmpty() {
+        return this.Junctions.length === 0 && this.Orphans.length === 0 && this.Subjects.every((s) => s.Operation === SubjectOperation.None);
+    }
+}
+exports.SubjectSet = SubjectSet;
+//# sourceMappingURL=subject.js.map

package/lib/cjs/subject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.js","sourceRoot":"","sources":["../../src/subject.ts"],"names":[],"mappings":";;;AAIA;;;;;;GAMG;AACH,IAAY,gBAIX;AAJD,WAAY,gBAAgB;IAC1B,qCAAiB,CAAA;IACjB,qCAAiB,CAAA;IACjB,iCAAa,CAAA;AACf,CAAC,EAJW,gBAAgB,gCAAhB,gBAAgB,QAI3B;AAmDD;;;GAGG;AACH,SAAS,WAAW,CAAC,EAAW;IAC9B,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtG,CAAC;IAED,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAa,OAAO;IAgBlB,+FAA+F;IAC/F,IAAW,QAAQ;QACjB,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC;IAC9E,CAAC;IAED,YAA4B,KAAgB,EAAkB,UAA4B,EAAS,SAA2B;QAAlG,UAAK,GAAL,KAAK,CAAW;QAAkB,eAAU,GAAV,UAAU,CAAkB;QAAS,cAAS,GAAT,SAAS,CAAkB;QApB9H,2FAA2F;QACpF,mBAAc,GAAa,EAAE,CAAC;QAErC,2EAA2E;QACpE,uBAAkB,GAAyB,EAAE,CAAC;QAErD;;;WAGG;QACI,wBAAmB,GAAyB,EAAE,CAAC;QAEtD,qFAAqF;QAC9E,mBAAc,GAAqB,EAAE,CAAC;IAOoF,CAAC;CACnI;AAtBD,0BAsBC;AAED;;GAEG;AACH,MAAa,UAAU;IAAvB;QACkB,aAAQ,GAAc,EAAE,CAAC;QACzB,cAAS,GAAqB,EAAE,CAAC;QACjC,YAAO,GAAmB,EAAE,CAAC;QAErC,aAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;IA2BnD,CAAC;IAzBC;;;;OAIG;IACI,GAAG,CAAC,OAAgB;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE5B,OAAO,OAAO,CAAC;IACjB,CAAC;IAEM,IAAI,CAAC,KAAgB;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,0DAA0D;IAC1D,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvI,CAAC;CACF;AAhCD,gCAgCC"}

package/lib/cjs/unit-of-work.d.ts

@@ -0,0 +1,52 @@
+import { OrmDriver } from './driver.js';
+import { IIdentityMap, IModelDescriptor, ISaveOptions, ISaveResult } from './interfaces.js';
+import type { ModelBase } from './model.js';
+/**
+ * The `save()` entry point: one transaction, one identity map, one ordered plan.
+ */
+export declare class UnitOfWork {
+    /**
+     * Persists everything reachable from `root` atomically.
+     *
+     * @param root - the model `save()` was called on
+     * @param options - `reload` to diff against current database state; `chunk` to bound the row
+     *        count of the statements that ARE batched — junction inserts and the key lists of
+     *        orphan statements. It does not apply to model inserts: those run one statement per
+     *        row so each generated key can be read back exactly. See {@link ISaveOptions}.
+     */
+    static save(root: ModelBase, options?: ISaveOptions): Promise<ISaveResult>;
+    /**
+     * The identity map for this save. Reused across saves inside one transaction so a row
+     * touched by two of them is still one object; created fresh otherwise. Nothing survives
+     * the transaction ( decision D7 ).
+     */
+    protected static identityMapFor(driver: OrmDriver): IIdentityMap;
+    /**
+     * A graph spanning two connections cannot be persisted atomically — the transaction only
+     * covers one of them. Fail loudly rather than commit half of it.
+     */
+    protected static assertSingleConnection(models: ModelBase[], root: IModelDescriptor): void;
+    /**
+     * Re-reads every already-persisted model's row and rebases it on the database's current
+     * values, batched one SELECT per model class.
+     *
+     * This is a three-way merge between the hydration baseline, the model, and the row as it
+     * stands now. A column the caller edited keeps the caller's value and is rebased so it is
+     * written; a column the caller did not touch is reset to the current database value on the
+     * model *and* in the baseline, so it drops out of the diff and is not written at all.
+     *
+     * Moving only the baseline would do the exact opposite of the intent: the model would still
+     * hold the stale hydration value, the diff would report `current -> stale`, and the UPDATE
+     * would clobber whatever another process wrote. The model has to move too.
+     *
+     * This is a last-write-wins rebase, not conflict detection: two callers editing the same
+     * column still race, and neither is told.
+     */
+    protected static reloadSnapshots(models: ModelBase[]): Promise<void>;
+    /**
+     * Re-records every populated relation's member keys after a successful save, so a second
+     * `save()` on the same graph sees no membership change and emits nothing.
+     */
+    protected static resnapshotRelations(models: ModelBase[]): void;
+}
+//# sourceMappingURL=unit-of-work.d.ts.map

package/lib/cjs/unit-of-work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-of-work.d.ts","sourceRoot":"","sources":["../../src/unit-of-work.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,WAAW,EAAgB,MAAM,iBAAiB,CAAC;AAC1G,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAO5C;;GAEG;AACH,qBAAa,UAAU;IACrB;;;;;;;;OAQG;WACiB,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAkCvF;;;;OAIG;IACH,SAAS,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,YAAY;IAchE;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAU1F;;;;;;;;;;;;;;;OAeG;qBACoB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgE1E;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI;CAqBhE"}

package/lib/cjs/unit-of-work.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnitOfWork = void 0;
+/* eslint-disable prettier/prettier */
+const di_1 = require("@spinajs/di");
+const builders_js_1 = require("./builders.js");
+const descriptor_js_1 = require("./descriptor.js");
+const exceptions_js_1 = require("./exceptions.js");
+const identity_map_js_1 = require("./identity-map.js");
+const interfaces_js_1 = require("./interfaces.js");
+const primary_keys_js_1 = require("./primary-keys.js");
+const snapshot_js_1 = require("./snapshot.js");
+const subject_builder_js_1 = require("./subject-builder.js");
+const subject_executor_js_1 = require("./subject-executor.js");
+const subject_sorter_js_1 = require("./subject-sorter.js");
+/**
+ * The `save()` entry point: one transaction, one identity map, one ordered plan.
+ */
+class UnitOfWork {
+    /**
+     * Persists everything reachable from `root` atomically.
+     *
+     * @param root - the model `save()` was called on
+     * @param options - `reload` to diff against current database state; `chunk` to bound the row
+     *        count of the statements that ARE batched — junction inserts and the key lists of
+     *        orphan statements. It does not apply to model inserts: those run one statement per
+     *        row so each generated key can be read back exactly. See {@link ISaveOptions}.
+     */
+    static async save(root, options) {
+        const descriptor = (0, descriptor_js_1.extractModelDescriptor)(root.constructor);
+        if (!descriptor) {
+            throw new exceptions_js_1.OrmException(`model ${root.constructor.name} has no descriptor, use the @Model decorator`);
+        }
+        const driver = di_1.DI.resolve('OrmConnection', [descriptor.Connection]);
+        if (!driver) {
+            throw new exceptions_js_1.OrmException(`model ${descriptor.Name} has invalid connection ${descriptor.Connection}`);
+        }
+        return await driver.transaction(async () => {
+            const identityMap = UnitOfWork.identityMapFor(driver);
+            const builder = new subject_builder_js_1.SubjectBuilder(identityMap);
+            const models = builder.collect(root);
+            UnitOfWork.assertSingleConnection(models, descriptor);
+            if (options?.reload) {
+                await UnitOfWork.reloadSnapshots(models);
+            }
+            const set = builder.buildFrom(models);
+            const plan = new subject_sorter_js_1.SubjectSorter().sort(set);
+            const result = await new subject_executor_js_1.SubjectExecutor(options ?? {}).execute(plan);
+            UnitOfWork.resnapshotRelations(models);
+            return result;
+        });
+    }
+    /**
+     * The identity map for this save. Reused across saves inside one transaction so a row
+     * touched by two of them is still one object; created fresh otherwise. Nothing survives
+     * the transaction ( decision D7 ).
+     */
+    static identityMapFor(driver) {
+        const ctx = driver.CurrentTransaction;
+        if (!ctx) {
+            return new identity_map_js_1.IdentityMap();
+        }
+        if (!ctx.IdentityMap) {
+            ctx.IdentityMap = new identity_map_js_1.IdentityMap();
+        }
+        return ctx.IdentityMap;
+    }
+    /**
+     * A graph spanning two connections cannot be persisted atomically — the transaction only
+     * covers one of them. Fail loudly rather than commit half of it.
+     */
+    static assertSingleConnection(models, root) {
+        for (const model of models) {
+            const descriptor = (0, descriptor_js_1.extractModelDescriptor)(model.constructor);
+            if (descriptor && descriptor.Connection !== root.Connection) {
+                throw new exceptions_js_1.OrmException(`save() cannot span connections: ${root.Name} is on connection ${root.Connection} but ${descriptor.Name} is on ${descriptor.Connection}. Save each connection's graph separately.`);
+            }
+        }
+    }
+    /**
+     * Re-reads every already-persisted model's row and rebases it on the database's current
+     * values, batched one SELECT per model class.
+     *
+     * This is a three-way merge between the hydration baseline, the model, and the row as it
+     * stands now. A column the caller edited keeps the caller's value and is rebased so it is
+     * written; a column the caller did not touch is reset to the current database value on the
+     * model *and* in the baseline, so it drops out of the diff and is not written at all.
+     *
+     * Moving only the baseline would do the exact opposite of the intent: the model would still
+     * hold the stale hydration value, the diff would report `current -> stale`, and the UPDATE
+     * would clobber whatever another process wrote. The model has to move too.
+     *
+     * This is a last-write-wins rebase, not conflict detection: two callers editing the same
+     * column still race, and neither is told.
+     */
+    static async reloadSnapshots(models) {
+        const byConstructor = new Map();
+        for (const model of models) {
+            // A composite key is a tuple, and a tuple is ALWAYS truthy — check every part.
+            const pk = model.PrimaryKeyValue;
+            const missing = Array.isArray(pk) ? pk.some((v) => v === null || v === undefined) : pk === null || pk === undefined;
+            if (model.Snapshot === null || missing) {
+                continue;
+            }
+            const ctor = model.constructor;
+            const list = byConstructor.get(ctor) ?? [];
+            list.push(model);
+            byConstructor.set(ctor, list);
+        }
+        for (const [ctor, group] of byConstructor) {
+            const descriptor = (0, descriptor_js_1.extractModelDescriptor)(ctor);
+            const { query } = (0, builders_js_1.createQuery)(ctor, builders_js_1.SelectQueryBuilder);
+            const select = query.select('*');
+            (0, primary_keys_js_1.whereAnyPk)(select, descriptor, group.map((m) => m.PrimaryKeyValue));
+            const fresh = (await select.asRaw());
+            // Index by the flattened key so a composite key matches without a nested scan.
+            const byKey = new Map();
+            for (const row of fresh) {
+                byKey.set((0, primary_keys_js_1.pkKeyString)(row, descriptor), row);
+            }
+            for (const model of group) {
+                const row = byKey.get((0, primary_keys_js_1.pkKeyString)(model, descriptor));
+                if (!row) {
+                    // The row is gone. Clearing the snapshot reclassifies the model as an INSERT,
+                    // which re-creates it rather than emitting an UPDATE that matches nothing.
+                    model.clearSnapshot();
+                    continue;
+                }
+                const baseline = model.Snapshot.Columns;
+                const current = (0, snapshot_js_1.snapshotFromRow)(descriptor, row);
+                const converterOf = new Map((descriptor.Columns ?? []).map((c) => [c.Name, c.Converter]));
+                for (const [name, value] of current) {
+                    // eslint-disable-next-line security/detect-object-injection
+                    const callerEdited = !(0, snapshot_js_1.snapshotEquals)(baseline.get(name), model[name], converterOf.get(name));
+                    if (!callerEdited) {
+                        // Untouched by this caller: adopt the database's value so it is neither written
+                        // back stale nor reported as a change.
+                        // eslint-disable-next-line security/detect-object-injection
+                        model[name] = value;
+                    }
+                    baseline.set(name, value);
+                }
+            }
+        }
+    }
+    /**
+     * Re-records every populated relation's member keys after a successful save, so a second
+     * `save()` on the same graph sees no membership change and emits nothing.
+     */
+    static resnapshotRelations(models) {
+        for (const model of models) {
+            const descriptor = (0, descriptor_js_1.extractModelDescriptor)(model.constructor);
+            if (!descriptor) {
+                continue;
+            }
+            for (const [name, relation] of descriptor.Relations) {
+                if (relation.Type === interfaces_js_1.RelationType.Query || relation.Type === interfaces_js_1.RelationType.Virtual) {
+                    continue;
+                }
+                // eslint-disable-next-line security/detect-object-injection
+                const rel = model[name];
+                if (rel?.Populated === true || (relation.Type === interfaces_js_1.RelationType.One && rel?.Value)) {
+                    model.snapshotRelation(name);
+                }
+            }
+        }
+    }
+}
+exports.UnitOfWork = UnitOfWork;
+//# sourceMappingURL=unit-of-work.js.map

package/lib/cjs/unit-of-work.js.map

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

package/lib/mjs/bootstrap.js

@@ -1,5 +1,15 @@
 import { DI } from '@spinajs/di';
 import { ManyToManyRelationList, OneToManyRelationList } from './relation-objects.js';
+/**
+ * Pool telemetry needs no registration: the ORM publishes into the `Metrics` singleton from
+ * `@spinajs/telemetry-common`, which self-registers via its own `@Injectable()` and owns a private
+ * prom-client registry. `@spinajs/telemetry` re-exports that very class, so its `/metrics`
+ * endpoint renders the same registry the ORM writes to.
+ *
+ * The dependency runs orm -> telemetry-common and never orm -> telemetry: the latter pulls in
+ * `@spinajs/http`, and putting the HTTP stack underneath every database connection inverts the
+ * graph. Same reason `configuration-common` and `log-common` exist.
+ */
 /**
  * Register default relation type factory
  * for hasMany & hasManyToMany

package/lib/mjs/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,EAAE,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEtF;;;;;;;;;GASG;AACH,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAY,EAAE,IAA0B,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,mCAAmC,CAAC,CAAC;AAC3K,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAY,EAAE,IAA0B,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,2CAA2C,CAAC,CAAC"}
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,EAAE,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEtF;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAY,EAAE,IAA0B,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,mCAAmC,CAAC,CAAC;AAC3K,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAY,EAAE,IAA0B,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,2CAA2C,CAAC,CAAC"}