@spinajs/orm 2.0.480 → 2.0.482

package/lib/mjs/subject-builder.js

@@ -0,0 +1,292 @@
+/* eslint-disable prettier/prettier */
+import { extractModelDescriptor } from './descriptor.js';
+import { identityKey } from './identity-map.js';
+import { OrphanPolicy, RelationType } from './interfaces.js';
+import { resolveOrphanPolicy } from './orphan.js';
+import { SingleRelation } from './relation-objects.js';
+import { OrmException } from './exceptions.js';
+import { Subject, SubjectOperation, SubjectSet } from './subject.js';
+/**
+ * Turns a mutated object graph into a `SubjectSet` — the complete, unordered description of
+ * what one `save()` must do.
+ *
+ * Traversal rules:
+ *
+ * - a `belongsTo` is followed whenever its `Value` is set, populated or not, because
+ *   attaching a model to it is an explicit act;
+ * - a `hasMany` or `manyToMany` is followed **only when `Populated` is true**, so a relation
+ *   the caller never loaded is invisible and `Items: OrderItem[] = []` on a freshly
+ *   constructed model deletes nothing;
+ * - `Query` and `Virtual` relations are read-only projections and are never followed.
+ */
+export class SubjectBuilder {
+    constructor(identityMap) {
+        this.identityMap = identityMap;
+        this._visited = new Set();
+    }
+    build(root) {
+        return this.buildFrom(this.collect(root));
+    }
+    /**
+     * Walks the graph breadth-first from `root`, canonicalizing every model through the
+     * identity map so a row reached by two paths yields one instance.
+     *
+     * @param root - the model `save()` was called on
+     */
+    collect(root) {
+        this._visited = new Set();
+        const ordered = [];
+        const queue = [this.identityMap.add(root)];
+        while (queue.length > 0) {
+            const model = queue.shift();
+            if (this._visited.has(model)) {
+                continue;
+            }
+            this._visited.add(model);
+            ordered.push(model);
+            for (const related of this.relatedOf(model)) {
+                const canonical = this.identityMap.add(related);
+                if (!this._visited.has(canonical)) {
+                    queue.push(canonical);
+                }
+            }
+        }
+        return ordered;
+    }
+    /**
+     * Models directly reachable from `model` under the traversal rules.
+     */
+    relatedOf(model) {
+        const descriptor = extractModelDescriptor(model.constructor);
+        if (!descriptor) {
+            return [];
+        }
+        const out = [];
+        for (const [name, relation] of descriptor.Relations) {
+            // eslint-disable-next-line security/detect-object-injection
+            const value = model[name];
+            if (value === null || value === undefined) {
+                continue;
+            }
+            switch (relation.Type) {
+                case RelationType.One:
+                    if (value instanceof SingleRelation && value.Value) {
+                        out.push(value.Value);
+                    }
+                    break;
+                case RelationType.Many:
+                case RelationType.ManyToMany:
+                    if (value.Populated === true) {
+                        out.push(...[...value]);
+                    }
+                    break;
+                case RelationType.Query:
+                case RelationType.Virtual:
+                default:
+                    break;
+            }
+        }
+        return out;
+    }
+    /**
+     * Diffs each collected model against its snapshot and records its `belongsTo` foreign keys.
+     * hasMany, manyToMany and orphan handling are layered on by later passes.
+     *
+     * @param models - output of `collect()`
+     */
+    buildFrom(models) {
+        const set = new SubjectSet();
+        for (const model of models) {
+            const descriptor = extractModelDescriptor(model.constructor);
+            if (!descriptor) {
+                continue;
+            }
+            const subject = new Subject(model, descriptor, classify(model));
+            // Only an UPDATE needs a column list: an INSERT writes every column, and a no-op
+            // writes none. Reading the diff again here is cheap and keeps `classify` pure.
+            if (subject.Operation === SubjectOperation.Update) {
+                subject.ChangedColumns = model.changedColumns();
+            }
+            set.add(subject);
+        }
+        for (const subject of set.Subjects) {
+            this.buildBelongsTo(subject);
+            this.buildHasMany(subject, set);
+            this.buildManyToMany(subject, set);
+        }
+        this.buildOrphans(set);
+        return set;
+    }
+    /**
+     * Records, for every `belongsTo` with a `Value`, that this subject's foreign-key column
+     * takes the target's primary key. The value is *not* read here — the target may not have
+     * been inserted yet; the executor resolves it immediately before the statement.
+     */
+    buildBelongsTo(subject) {
+        for (const [name, relation] of subject.Descriptor.Relations) {
+            if (relation.Type !== RelationType.One) {
+                continue;
+            }
+            // eslint-disable-next-line security/detect-object-injection
+            const rel = subject.Model[name];
+            if (!(rel instanceof SingleRelation) || !rel.Value) {
+                continue;
+            }
+            subject.PendingForeignKeys.push({ Column: relation.ForeignKey, Target: rel.Value });
+        }
+    }
+    /**
+     * Diffs each populated `hasMany` on `subject` against the owner's relation snapshot and
+     * records the owner's foreign key as pending on every member that stays.
+     *
+     * A relation with `Populated === false` is skipped entirely — that is the anti-footgun
+     * guarantee, and it is why a freshly constructed model with `Items: OrderItem[] = []`
+     * deletes nothing.
+     *
+     * Both new *and* kept members get the pending foreign key. That is what makes re-parenting
+     * work: a clean child moved to another owner has its key rewritten and is promoted from a
+     * no-op to an UPDATE, instead of keeping its old owner id in the database ( B20 ).
+     */
+    buildHasMany(subject, set) {
+        for (const [name, relation] of subject.Descriptor.Relations) {
+            if (relation.Type !== RelationType.Many) {
+                continue;
+            }
+            // eslint-disable-next-line security/detect-object-injection
+            const rel = subject.Model[name];
+            if (!rel || rel.Populated !== true) {
+                continue;
+            }
+            const members = [...rel];
+            const snapshotKeys = subject.Model.Snapshot?.Relations.get(name) ?? [];
+            const presentKeys = new Set(members.map((m) => identityKey(m.PrimaryKeyValue)).filter((k) => k !== null));
+            const delta = {
+                Descriptor: relation,
+                Added: members.filter((m) => m.Snapshot === null),
+                Kept: members.filter((m) => m.Snapshot !== null),
+                RemovedKeys: snapshotKeys.filter((k) => !presentKeys.has(identityKey(k))),
+            };
+            subject.RelationDeltas.push(delta);
+            for (const member of members) {
+                const memberSubject = set.find(member);
+                if (memberSubject) {
+                    memberSubject.PendingForeignKeys.push({ Column: relation.ForeignKey, Target: subject.Model });
+                }
+            }
+        }
+    }
+    /**
+     * Diffs each populated `manyToMany` against the owner's relation snapshot into junction
+     * rows to create and destroy.
+     *
+     * Only the *junction* row is created or destroyed. A target that is new gets its own insert
+     * subject from `collect()` so its key exists before the junction row references it; a target
+     * that is merely unlinked is left completely alone — removing a tag from an order must
+     * never delete the tag.
+     */
+    buildManyToMany(subject, set) {
+        for (const [name, relation] of subject.Descriptor.Relations) {
+            if (relation.Type !== RelationType.ManyToMany) {
+                continue;
+            }
+            // eslint-disable-next-line security/detect-object-injection
+            const rel = subject.Model[name];
+            if (!rel || rel.Populated !== true) {
+                continue;
+            }
+            if (!relation.JunctionModel) {
+                throw new OrmException(`manyToMany relation ${relation.Name} on ${subject.Descriptor.Name} has no junction model`);
+            }
+            const junctionDescriptor = extractModelDescriptor(relation.JunctionModel);
+            if (!junctionDescriptor) {
+                throw new OrmException(`junction model ${relation.JunctionModel.name} for relation ${relation.Name} has no model descriptor`);
+            }
+            const members = [...rel];
+            const snapshotKeys = subject.Model.Snapshot?.Relations.get(name) ?? [];
+            const snapshotSet = new Set(snapshotKeys.map((k) => identityKey(k)).filter((k) => k !== null));
+            const presentKeys = new Set(members.map((m) => identityKey(m.PrimaryKeyValue)).filter((k) => k !== null));
+            const delta = {
+                Descriptor: relation,
+                JunctionDescriptor: junctionDescriptor,
+                Owner: subject.Model,
+                // A member with no key yet cannot have been linked before, so it is always an add.
+                Added: members.filter((m) => {
+                    const key = identityKey(m.PrimaryKeyValue);
+                    return key === null || !snapshotSet.has(key);
+                }),
+                RemovedKeys: snapshotKeys.filter((k) => !presentKeys.has(identityKey(k))),
+            };
+            set.Junctions.push(delta);
+        }
+    }
+    /**
+     * Turns every `hasMany` removal recorded during the diff into an orphan action.
+     *
+     * Runs once over the whole set rather than per relation, because the decision needs global
+     * information: a child removed from one owner and pushed onto another is a re-parent, not
+     * an orphan, and only a set-wide view can tell the two apart. Every key that has a live
+     * subject of the same target model in this graph is therefore subtracted.
+     */
+    buildOrphans(set) {
+        // Primary keys, per target model, that are alive somewhere in this graph. Keyed on
+        // TableName rather than on the constructor: a discrimination map can produce several
+        // constructors for one table, and a subclass instance is still the same row.
+        const alive = new Map();
+        for (const subject of set.Subjects) {
+            const key = identityKey(subject.Model.PrimaryKeyValue);
+            if (key === null) {
+                continue;
+            }
+            const table = subject.Descriptor.TableName;
+            if (!alive.has(table)) {
+                alive.set(table, new Set());
+            }
+            alive.get(table).add(key);
+        }
+        for (const subject of set.Subjects) {
+            for (const delta of subject.RelationDeltas) {
+                if (delta.RemovedKeys.length === 0) {
+                    continue;
+                }
+                const targetDescriptor = extractModelDescriptor(delta.Descriptor.TargetModel);
+                if (!targetDescriptor) {
+                    throw new OrmException(`relation ${delta.Descriptor.Name} on ${subject.Descriptor.Name} has an unresolved target model`);
+                }
+                const policy = resolveOrphanPolicy(delta.Descriptor, targetDescriptor);
+                if (policy === OrphanPolicy.Disable) {
+                    continue;
+                }
+                const survivors = alive.get(targetDescriptor.TableName) ?? new Set();
+                const keys = delta.RemovedKeys.filter((k) => {
+                    const key = identityKey(k);
+                    return key !== null && !survivors.has(key);
+                });
+                // Drop an empty list rather than emitting a statement with `IN ()`.
+                if (keys.length === 0) {
+                    continue;
+                }
+                const orphan = {
+                    Descriptor: delta.Descriptor,
+                    TargetDescriptor: targetDescriptor,
+                    Policy: policy,
+                    PrimaryKeys: keys,
+                };
+                set.Orphans.push(orphan);
+            }
+        }
+    }
+}
+/**
+ * `Insert` when the model has never been hydrated from the database, `Update` when its
+ * snapshot diff is non-empty, `None` otherwise.
+ *
+ * Deliberately not keyed on the primary key: `setDefaults()` pre-fills @Uuid keys on
+ * construction, so a brand-new UUID-keyed model already has one.
+ */
+function classify(model) {
+    if (model.Snapshot === null) {
+        return SubjectOperation.Insert;
+    }
+    return model.changedColumns().length > 0 ? SubjectOperation.Update : SubjectOperation.None;
+}
+//# sourceMappingURL=subject-builder.js.map

package/lib/mjs/subject-builder.js.map

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

package/lib/mjs/subject-executor.d.ts

@@ -0,0 +1,122 @@
+import { ISaveOptions, ISaveResult, OrphanPolicy } from './interfaces.js';
+import { ISortedPlan } from './subject-sorter.js';
+import { IJunctionDelta, IOrphanDelta, Subject } from './subject.js';
+/** Rows per batched statement when the caller does not say. */
+export declare const DEFAULT_SAVE_CHUNK = 100;
+/**
+ * Runs a sorted plan.
+ *
+ * Every statement is built through `createQuery`, so table naming, schema qualification and
+ * identifier escaping are the same as on the ActiveRecord paths. No connection is threaded by
+ * hand: `OrmDriver.transaction()` carries it in `AsyncLocalStorage` and the builders resolved
+ * from that driver pick it up automatically.
+ *
+ * The executor does **not** open the transaction — `UnitOfWork` does — so that a caller can
+ * drive it directly in a test and so that nested saves inside one transaction fold into
+ * savepoints rather than each opening their own.
+ */
+export declare class SubjectExecutor {
+    protected options: ISaveOptions;
+    constructor(options: ISaveOptions);
+    execute(plan: ISortedPlan): Promise<ISaveResult>;
+    /**
+     * Inserts every insert subject in the order the sorter produced, reading each generated key
+     * back before moving on so the next subject's foreign keys can be resolved.
+     *
+     * One statement per row, deliberately, and NOT subject to `options.chunk`: a batched
+     * multi-row INSERT can only return keys where the dialect supports RETURNING or where
+     * `insertIdIsFirstOfBatch` holds, and a subject's key is needed by the very next subject in
+     * the order. Batching here is a real feature — it has to carry the per-dialect key-backfill
+     * rules with it — not something to fold into the chunking used for junction and orphan rows.
+     */
+    protected runInserts(plan: ISortedPlan, result: ISaveResult): Promise<void>;
+    /**
+     * One INSERT, with the key read back.
+     *
+     * Mirrors `ModelBase.insert()`'s key handling rather than inventing a second one: client-side
+     * keys are generated first, `assigned` keys are asserted before anything touches the database,
+     * and RETURNING is requested when an `auto` key needs to come back and the dialect supports it.
+     */
+    protected insertOne(subject: Subject): Promise<void>;
+    /**
+     * Runs every update, including the follow-up updates that carry deferred self-referencing
+     * foreign keys.
+     *
+     * A subject whose payload comes out empty emits nothing. This is the single place that
+     * decides whether a row actually changed: pending foreign keys are written onto the model
+     * first and `changedColumns()` is read afterwards, so a re-parented child that was clean
+     * when the subjects were built is caught here and nowhere else.
+     */
+    protected runUpdates(plan: ISortedPlan, result: ISaveResult): Promise<void>;
+    /**
+     * The column payload for one UPDATE, or `null` when there is nothing to write.
+     *
+     * The primary key columns are excluded: writing them is a no-op at best and, for a model
+     * whose key column differs from its snapshot for any other reason, a silent identity change.
+     *
+     * @param subject - an update subject, or an insert subject with deferred foreign keys
+     */
+    protected updatePayload(subject: Subject): Record<string, unknown> | null;
+    /**
+     * The column payload for one INSERT.
+     *
+     * Starts from the model's own serialization, drops every column whose foreign key is
+     * deferred to a follow-up UPDATE, then writes every pending foreign key from its target's
+     * now-known primary key. The overwrite matters: `StandardModelToSqlConverter` already wrote
+     * that column from the relation object, and for a target inserted moments ago that value was
+     * `undefined` when the model was serialized.
+     */
+    protected insertPayload(subject: Subject): Record<string, unknown>;
+    /**
+     * Writes a generated key onto the model.
+     *
+     * Uses `setPkValue` — the primary-keys helper that assigns the key columns and nothing else —
+     * rather than the `PrimaryKeyValue` setter, whose `RelationType.One` branch also writes the
+     * new key onto the owner's `SingleRelation` wrapper, which persists nothing. The executor
+     * resolves foreign keys itself and does not want that side effect.
+     *
+     * A key the caller already supplied ( uuid / assigned strategies ) is never overwritten.
+     */
+    protected backfillKey(subject: Subject, returning: any[], lastInsertId: number, needsKeyBack: boolean): void;
+    /**
+     * Creates and destroys junction rows.
+     *
+     * Rows are written column-first rather than through the junction model, so a junction model
+     * is not required to declare `@BelongsTo` on both sides — `ManyToManyRelationList.update()`
+     * does require that, and none of the existing junction fixtures satisfy it.
+     *
+     * Inserts run before deletes so that re-linking the same pair inside one save cannot
+     * momentarily violate a unique constraint on the junction table in the other order.
+     */
+    protected runJunctions(plan: ISortedPlan, result: ISaveResult): Promise<void>;
+    protected insertJunctionRows(delta: IJunctionDelta, result: ISaveResult): Promise<void>;
+    protected deleteJunctionRows(delta: IJunctionDelta, result: ISaveResult): Promise<void>;
+    /**
+     * Applies the orphan policy to every detached row.
+     *
+     * `nullify` and `soft-delete` run first as UPDATEs, then `delete` runs as DELETEs, and the
+     * deltas arrive from the sorter already ordered children-before-parents so a delete cannot
+     * strand a foreign key.
+     *
+     * `createQuery` only adds the default `DeletedAt IS NULL` filter to a SelectQueryBuilder, so
+     * these builders are unfiltered — which is what stamping an already-soft-deleted row needs.
+     */
+    protected runOrphans(plan: ISortedPlan, result: ISaveResult): Promise<void>;
+    /**
+     * The policy actually applied to `delta`.
+     *
+     * `delete` on a model that declares `@SoftDelete` degrades to `soft-delete`, so orphaning a
+     * row and calling `destroy()` on it mean the same thing. `ModelBase.destroy()` has always
+     * stamped `DeletedAt` rather than issuing a DELETE for such a model; an orphan taking the
+     * other branch made "delete this row" depend on which code path reached it, and hard-erased
+     * rows the model had declared should never be hard-erased.
+     */
+    protected effectivePolicy(delta: IOrphanDelta): OrphanPolicy;
+    protected updateOrphans(delta: IOrphanDelta, result: ISaveResult): Promise<void>;
+    protected deleteOrphans(delta: IOrphanDelta, result: ISaveResult): Promise<void>;
+    /** Rows per batched statement. */
+    protected get chunkSize(): number;
+    /** Splits `items` into runs of at most `chunkSize`. */
+    protected chunked<T>(items: T[]): T[][];
+}
+//# sourceMappingURL=subject-executor.d.ts.map

package/lib/mjs/subject-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject-executor.d.ts","sourceRoot":"","sources":["../../src/subject-executor.ts"],"names":[],"mappings":"AAKA,OAAO,EAAiB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAwB,MAAM,iBAAiB,CAAC;AAE/G,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAErE,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe;IACd,SAAS,CAAC,OAAO,EAAE,YAAY;gBAArB,OAAO,EAAE,YAAY;IAE9B,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAkB7D;;;;;;;;;OASG;cACa,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjF;;;;;;OAMG;cACa,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB1D;;;;;;;;OAQG;cACa,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBjF;;;;;;;OAOG;IACH,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAyBzE;;;;;;;;OAQG;IACH,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAkBlE;;;;;;;;;OASG;IACH,SAAS,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,IAAI;IA+B5G;;;;;;;;;OASG;cACa,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;cAOnE,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;cA2B7E,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB7F;;;;;;;;;OASG;cACa,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAajF;;;;;;;;OAQG;IACH,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY;cAQ5C,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;cAkBtE,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtF,kCAAkC;IAClC,SAAS,KAAK,SAAS,IAAI,MAAM,CAGhC;IAED,uDAAuD;IACvD,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE;CAOxC"}