@memberjunction/core 6.1.0-edge.0 → 6.1.0-edge.1

package/dist/generic/relatedRecordCollection.d.ts

@@ -0,0 +1,578 @@
+/**
+ * @fileoverview `RelatedRecordCollection<T>` — a typed, transportable collection of child records that
+ * loads, validates and persists as one unit with its parent.
+ *
+ * ## The problem it replaces
+ *
+ * Three MemberJunction applications independently hand-rolled this same pattern, and each got a
+ * different subset of it right:
+ *
+ * | | Order | PaymentHeader | JournalEntry |
+ * |---|---|---|---|
+ * | Typed | ✓ | ✗ (`BaseEntity[]`) | ✓ |
+ * | Loads children | ✗ | ✗ | ✓ |
+ * | Tracks removals | ✗ | ✗ | ✓ |
+ * | Add/remove API | raw setter | raw setter | ✓ |
+ * | Re-sequences | ✗ | ✗ | ✓ |
+ *
+ * All three were server-only classes, because each cast the provider to `DatabaseProviderBase` to
+ * reach `BeginTransaction()`. `RelatedRecordCollection` is tier-neutral: it never touches a provider
+ * transaction itself, it only contributes nodes to an {@link EntitySavePlan}, and `BaseEntity`
+ * decides where that plan runs.
+ *
+ * @module @memberjunction/core
+ */
+import type { BaseEntity } from './baseEntity.js';
+import { EntityCompanion, EntityCompanionDeserializeMode } from './entityCompanion.js';
+import type { EntitySavePlan } from './entitySavePlan.js';
+import { ValidationResult } from './entityInfo.js';
+import type { EntitySaveOptions } from './interfaces.js';
+/**
+ * When a child collection populates itself from the database.
+ *
+ * - `'explicit'` — **the default.** Nothing loads until the caller awaits `Load()`. Chosen as the
+ *   default because the alternative is a performance trap: an eager collection on a widely-listed
+ *   entity turns every grid into an N+1 storm.
+ * - `'immediate'` — populated automatically by `BaseEntity.Load()`. **Never** by `LoadFromData()`,
+ *   which is the per-row materialization path for `RunView(ResultType:'entity_object')`. That
+ *   exclusion is deliberate and is the structural fix for a live N+1 in production accounting code,
+ *   where a `LoadFromData` override issued one child query per row of every view.
+ * - `'lazy'` — populated on first read of {@link RelatedRecordCollection.Items}. Requires
+ *   {@link RelatedRecordSource} `'cache'`: a property getter cannot await, so a lazy *database*
+ *   load could only ever silently fail to fill, and CodeGen refuses that combination. A cache
+ *   lookup is synchronous, so lazy works there — reproducing exactly the hand-written memoized
+ *   getters this mechanism replaces.
+ * - `'never'` — the collection is a write-only staging buffer; `Load()` is a no-op. Matches how
+ *   order lines are actually used: built up in memory and pushed down, never read back through the
+ *   collection.
+ */
+export type RelatedRecordLoadMode = 'explicit' | 'immediate' | 'lazy' | 'never';
+/**
+ * Where a collection's records come from.
+ *
+ * - `'database'` — a `RunView` filtered by the join field. Always fresh, costs a query. Correct for
+ *   transactional data where staleness is unacceptable.
+ * - `'cache'` — taken from whichever loaded `BaseEngine` already holds the entity, discovered
+ *   generically via `BaseEngineRegistry.FindCachedEntity()`. Costs **zero queries**, and falls back
+ *   to `'database'` when no loaded engine offers it, so a miss degrades rather than fails.
+ *
+ * Deliberately not `'query'`: in MemberJunction a *Query* is a stored, named artifact
+ * (`MJ: Queries`, `RunQuery`), so that word already means something else.
+ */
+export type RelatedRecordSource = 'database' | 'cache';
+/**
+ * What happens to a child that is removed from the collection.
+ *
+ * - `'delete'` — the row is deleted when the parent saves. Correct for true composition, where a
+ *   child has no meaning without its parent (order lines, journal entry lines).
+ * - `'orphan'` — the row is left in place, foreign key untouched. Correct for aggregation, where
+ *   the child outlives the relationship.
+ * - `'refuse'` — removal throws. For collections where detaching a child is always a bug.
+ */
+export type RelatedRecordRemovalMode = 'delete' | 'orphan' | 'refuse';
+/**
+ * Automatic sequence numbering for a child collection.
+ */
+export type RelatedRecordSequence = {
+    /** The child field holding the sequence number (e.g. `'LineNumber'`). */
+    Field: string;
+    /** The value assigned to the first child. Defaults to 1. */
+    From?: number;
+};
+/**
+ * Declaration for a {@link RelatedRecordCollection}, supplied to `BaseEntity.DeclareRelatedRecords()`.
+ *
+ * @remarks
+ * **This shape deliberately mirrors `EntityRelationship` metadata**, so a declaration can be
+ * hand-written today and code-generated tomorrow from exactly the same information:
+ *
+ * | Option | Metadata source |
+ * |---|---|
+ * | {@link RelatedEntity} | `EntityRelationship.RelatedEntity` (column) |
+ * | {@link RelatedEntityJoinField} | `EntityRelationship.RelatedEntityJoinField` (column) |
+ * | everything else | `EntityRelationship.RelatedRecordCollection` (JSONType, `IRelatedRecordCollectionConfig`) |
+ *
+ * The two column-backed options are **not** repeated inside the JSON blob — one source of truth
+ * each. Keep this type and `metadata/entities/JSONType-interfaces/IRelatedRecordCollectionConfig.ts`
+ * in step when adding an option.
+ */
+export type RelatedRecordCollectionOptions = {
+    /**
+     * The companion's stable name, and the property name callers will use. Also the wire key —
+     * see {@link EntityCompanion.Name}.
+     */
+    Name: string;
+    /**
+     * The related entity's name in MJ metadata, e.g. `'MJ_BizApps_Orders: Order Lines'`.
+     * Mirrors `EntityRelationship.RelatedEntity`.
+     */
+    RelatedEntity: string;
+    /**
+     * The related entity's field holding the foreign key back to this record, e.g.
+     * `'OrderHeaderID'`. Mirrors `EntityRelationship.RelatedEntityJoinField`.
+     */
+    RelatedEntityJoinField: string;
+    /** `OrderBy` clause used when loading. Strongly recommended for sequenced collections. */
+    OrderBy?: string;
+    /** When the collection populates itself. Defaults to `'explicit'`. */
+    Load?: RelatedRecordLoadMode;
+    /** Where records come from. Defaults to `'database'`. */
+    Source?: RelatedRecordSource;
+    /**
+     * Whether the collection refuses mutation. Defaults to `false` — but to `true` when
+     * {@link Source} is `'cache'`, because a cache-sourced collection hands out the engine's own
+     * entity instances.
+     */
+    ReadOnly?: boolean;
+    /** What removal means. Defaults to `'delete'`. */
+    OnRemove?: RelatedRecordRemovalMode;
+    /** Automatic sequence numbering, if the child has a sequence field. */
+    Sequence?: RelatedRecordSequence;
+    /**
+     * Whether the collection clears itself after a successful save.
+     *
+     * `true` matches the order-line staging pattern, where the collection is a buffer for pending
+     * inserts rather than a live view of persisted rows. Defaults to `false`, which keeps the
+     * saved children in memory with fresh primary keys — the behavior most callers expect.
+     */
+    ClearAfterSave?: boolean;
+};
+/**
+ * One retained child on the wire.
+ */
+export type RelatedRecordCollectionWireItem = {
+    /** The child's field values, as produced by `GetAll()`. */
+    Fields: Record<string, unknown>;
+    /**
+     * Whether this child is a pending insert rather than an edit of an existing row.
+     *
+     * Carried **explicitly** rather than inferred from primary-key presence, because `NewRecord()`
+     * generates a UUID for `uniqueidentifier` keys — so a brand-new child already has a populated
+     * primary key and is indistinguishable from an existing one by inspection. Inferring would make
+     * the server try to load a row that does not exist for every client-created child.
+     */
+    IsNew: boolean;
+};
+/**
+ * The wire shape of a serialized child collection.
+ */
+export type RelatedRecordCollectionWire = {
+    /** Each retained child. */
+    Items: RelatedRecordCollectionWireItem[];
+    /** Primary-key field maps for children removed since load, when removal means deletion. */
+    Removed: Record<string, unknown>[];
+};
+/**
+ * A typed collection of child records that travels, validates and persists with its parent.
+ *
+ * Obtain one via `BaseEntity.DeclareRelatedRecords()` in a subclass constructor or field initialiser —
+ * do not construct it directly, or it will not be registered as a companion and will be silently
+ * ignored by load, validation and save.
+ *
+ * @typeParam T - The child entity type.
+ *
+ * @example Declaring a collection on a shared (client + server) entity subclass
+ * ```typescript
+ * @RegisterClass(BaseEntity, 'MJ_BizApps_Accounting: Journal Entries')
+ * export class JournalEntryEntity extends mjBizAppsAccountingJournalEntryEntity {
+ *     public readonly Lines = this.DeclareRelatedRecords<JournalEntryLineEntity>({
+ *         Name: 'Lines',
+ *         RelatedEntity: 'MJ_BizApps_Accounting: Journal Entry Lines',
+ *         RelatedEntityJoinField: 'JournalEntryID',
+ *         OrderBy: 'LineNumber ASC',
+ *         Load: 'explicit',
+ *         OnRemove: 'delete',
+ *         Sequence: { Field: 'LineNumber', From: 1 },
+ *     });
+ *
+ *     public override Validate(): ValidationResult {
+ *         const result = super.Validate();          // fans out to companions
+ *         assertBalanced(this.Lines.Items, result); // runs on BOTH tiers
+ *         return result;
+ *     }
+ * }
+ * ```
+ */
+export declare class RelatedRecordCollection<T extends BaseEntity = BaseEntity> extends EntityCompanion<RelatedRecordCollectionWire> {
+    private items;
+    private removed;
+    private loaded;
+    private readonly options;
+    /**
+     * @param owner - The parent entity.
+     * @param options - The collection declaration.
+     */
+    constructor(owner: BaseEntity, options: RelatedRecordCollectionOptions);
+    /**
+     * Rejects declarations whose combination of options cannot work, at declaration time.
+     *
+     * CodeGen already refuses these combinations for metadata-declared collections; enforcing them
+     * here as well means a hand-written declaration fails immediately with an accurate message,
+     * instead of at first read with a misleading one (`populateFromCache` bails on `!IsReadOnly`
+     * before ever consulting the donor, so a writable lazy collection used to throw "engine is not
+     * loaded yet" even when the engine was fully loaded).
+     */
+    private assertDeclarationInvariants;
+    /** @inheritdoc */
+    get Name(): string;
+    /** The child entity's name in MJ metadata. */
+    get RelatedEntityName(): string;
+    /** The child field holding the foreign key back to the parent. */
+    get RelatedEntityJoinField(): string;
+    /** The `OrderBy` clause applied when loading, if declared. */
+    get OrderByClause(): string | undefined;
+    /** When this collection populates itself. */
+    get LoadMode(): RelatedRecordLoadMode;
+    /** What removal means for this collection. */
+    get RemovalMode(): RelatedRecordRemovalMode;
+    /** Where this collection's records come from. Defaults to `'database'`. */
+    get Source(): RelatedRecordSource;
+    /**
+     * Whether this collection refuses mutation.
+     *
+     * Defaults to `false`, **except for a cache-sourced collection**, which defaults to `true`
+     * because its records are the engine's own shared instances. An explicit `ReadOnly: false`
+     * still wins — and switches the cache path to copying, so the engine's objects stay untouched.
+     */
+    get IsReadOnly(): boolean;
+    /**
+     * The retained children, in order.
+     *
+     * Read-only by design — mutate through {@link Add}, {@link Create} and {@link Remove} so that
+     * removals are tracked, sequence numbers stay correct, and the parent's `Dirty` flag reflects
+     * reality. Handing out a mutable array would make all three impossible to guarantee.
+     */
+    get Items(): readonly T[];
+    /**
+     * Iterates the retained records, so the collection works directly with `for…of`, spread and
+     * array destructuring:
+     *
+     * ```typescript
+     * for (const param of action.Params) { … }
+     * const all = [...action.Params];
+     * const [first, ...rest] = action.Params;
+     * ```
+     *
+     * This is the standard ES2015 iterable protocol — the same one `Map`, `Set` and `NodeList`
+     * implement — deliberately chosen over extending `Array`. Subclassing `Array` would inherit
+     * `push`, `splice`, `sort` and index assignment, every one of which bypasses the removal
+     * tracking, foreign-key stamping and sequence renumbering this class exists to guarantee; and
+     * `Symbol.species` would hand `map`/`filter` this constructor, which takes an owner and options
+     * rather than a length. Iterability adds the ergonomics without any of that.
+     *
+     * Use {@link Items} when you want the array itself — `map`, `filter`, `find` and indexing.
+     * It is `readonly`, which is what keeps a caller from mutating around the collection's back.
+     *
+     * @returns An iterator over the retained records, in collection order.
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Alias for {@link Count}, so the collection reads like a collection in the places people expect
+     * `length`. Both go through {@link Items}, so both trigger a lazy fill and see a live cache view.
+     */
+    get length(): number;
+    /**
+     * Children removed since the last load or save, awaiting deletion on the next save.
+     *
+     * Always empty when {@link RemovalMode} is `'orphan'`.
+     */
+    get Removed(): readonly T[];
+    /**
+     * Number of retained related records.
+     *
+     * Deliberately delegates to {@link Items} rather than reading the backing array: for a `'lazy'`
+     * collection `Items` is what triggers population, so reading the raw array here would report 0
+     * for a collection that has simply not been touched yet — and `Count === 0` while
+     * `Items.length === 2` is the kind of inconsistency nobody debugs quickly. Same reason it picks
+     * up a live cache view's refresh.
+     */
+    get Count(): number;
+    /** Whether this collection has been populated from the database. */
+    get IsLoaded(): boolean;
+    /**
+     * True when saving would produce work: any retained child is dirty or unsaved, or any removal
+     * is pending.
+     */
+    get Dirty(): boolean;
+    /**
+     * Appends an existing child entity to the collection.
+     *
+     * The foreign key is *not* set here — it is stamped at save time, because when the parent is
+     * itself new its primary key does not exist yet. See {@link ContributeSaveWork}.
+     *
+     * @param item - The child to append.
+     * @returns The same child, for chaining.
+     */
+    Add(item: T): T;
+    /**
+     * Creates a new, empty child entity, appends it, and returns it.
+     *
+     * Uses the owner's provider so the child resolves to the right registered subclass on whichever
+     * tier this runs — the server subclass on the server, the shared subclass in the browser.
+     *
+     * @returns The newly created child.
+     */
+    Create(): Promise<T>;
+    /**
+     * Removes a child by instance or index.
+     *
+     * A child that was already persisted is queued for deletion when {@link RemovalMode} is
+     * `'delete'`; an unsaved child is simply dropped, since there is nothing to delete.
+     *
+     * @param itemOrIndex - The child instance, or its index in {@link Items}.
+     * @throws When {@link RemovalMode} is `'refuse'`.
+     */
+    Remove(itemOrIndex: T | number): void;
+    /** Removes every child. */
+    Clear(): void;
+    /**
+     * Populates the collection from the database.
+     *
+     * A no-op when the parent is unsaved (there is nothing to be a child of) or when
+     * {@link LoadMode} is `'never'`.
+     *
+     * @remarks
+     * A failed load **throws** rather than yielding an empty collection. Silently returning no
+     * children makes a populated parent look empty, and anything derived from that — a reversal, a
+     * total, a validation decision — is then wrong in a way nothing downstream can detect. Only
+     * saves use the boolean-return convention.
+     *
+     * @param force - Reload even if already loaded.
+     */
+    Load(force?: boolean): Promise<void>;
+    /** @inheritdoc */
+    LoadEager(): Promise<void>;
+    /**
+     * Replaces the collection's contents with rows already fetched elsewhere.
+     *
+     * Used by `RunView`'s batched child loading, which issues one `WHERE fk IN (...)` for an entire
+     * result set and distributes the rows — turning what would be N+1 queries into 1 + K.
+     *
+     * @param items - The children belonging to this parent.
+     */
+    SetLoadedItems(items: T[]): void;
+    /**
+     * Throws when the collection is read-only. Called by every mutating entry point.
+     *
+     * @param operation - The attempted operation, named in the error.
+     */
+    private assertMutable;
+    /**
+     * Attempts to populate this collection from a `BaseEngine` cache without touching the database.
+     *
+     * Used by `BaseEntity.LoadRelatedRecords()` to resolve the free collections before batching
+     * whatever is left into a database round trip.
+     *
+     * @returns True when the collection was populated from a cache; false when the caller must load
+     *          it from the database.
+     */
+    TryLoadFromCache(): Promise<boolean>;
+    /**
+     * Fills the collection from whichever loaded engine already caches the related entity.
+     *
+     * Synchronous by nature — a registry walk plus a `filter` — which is what makes `'lazy'`
+     * possible at all. Returns `false` when no loaded engine offers the entity, leaving the
+     * collection unloaded so `Load()` can fall back to a query.
+     *
+     * @returns True when the collection was populated from a cache.
+     */
+    /**
+     * Re-reads a live cache view when the donor engine has moved on.
+     *
+     * Only applies to a read-only cache-sourced collection — the case where the records belong to
+     * the engine rather than to this collection. A writable cache collection holds COPIES the caller
+     * owns, so silently replacing them would discard their edits; and a database-sourced collection
+     * is a point-in-time load by definition, which is what callers expect of one.
+     *
+     * The check is two reference comparisons in the common case, so this stays cheap enough to run
+     * on every read.
+     */
+    private refreshCacheViewIfStale;
+    /**
+     * Populates a `'lazy'` collection from cache, or throws explaining why it could not.
+     *
+     * **A lazy declaration is an assertion.** Writing `Load: 'lazy'` says "an engine caches this
+     * entity"; there is no async fallback available from a getter, so if the assertion is wrong the
+     * only alternatives are a hard error or a silently empty array. Silence is how
+     * `MJAIAgentEntityExtended.Actions` returned `[]` to three call sites indefinitely without
+     * anyone noticing — exactly the failure this mechanism exists to end.
+     *
+     * A donor holding **zero rows** is a perfectly good answer and does not throw; the collection is
+     * simply empty. Only the absence of a donor is an error, and the message distinguishes the two
+     * ways that happens, because they need opposite fixes.
+     */
+    private populateLazyOrThrow;
+    /**
+     * Whether reading {@link Items} right now will succeed — the guard for display-tier code.
+     *
+     * A lazy collection's {@link Items} getter **throws** when its donor engine is not available,
+     * deliberately: a silently empty array is how the bug this feature replaced went unnoticed for
+     * years. That is the right default for business logic, but a template or widget rendering
+     * during bootstrap (before anything has awaited the engine's `Config()`) wants "not yet",
+     * not an aborted render — and the null-check templates reach for (`@if (entity.Params && …)`)
+     * cannot help, because the collection property itself is never null; it is the *read* that
+     * throws.
+     *
+     * ```html
+     * @if (action.Params.IsAvailable) {
+     *   @for (p of action.Params.Items; track p.ID) { … }
+     * }
+     * ```
+     *
+     * **This is a predicate, not a second way to read.** There is exactly one accessor — `Items` —
+     * so there is no `null`-versus-`[]` ambiguity for a caller to get wrong, and no quiet path that
+     * can drift into business logic and re-create the silent-empty bug. `true` here means the very
+     * next `Items` read is safe *and already populated*, because deciding the answer requires
+     * consulting the donor, and consulting it is what fills the collection.
+     *
+     * Never triggers a database load, and never throws.
+     */
+    get IsAvailable(): boolean;
+    /**
+     * The engine and property this collection last read from, plus enough about that array to tell
+     * cheaply whether it has moved on.
+     *
+     * A cache-sourced read-only collection is a **live view**, not a snapshot. `.claude/rules/data-access.md`
+     * spells out why: an engine responds to entity events either by mutating its array in place or —
+     * for ordered configs — by REASSIGNING the property wholesale, so a captured reference silently
+     * goes stale. The documented remedy is to resolve per-access from the engine plus the config's
+     * property name, which is what this records.
+     *
+     * Revalidation is deliberately cheap: identity catches a reassignment, length catches an
+     * in-place push or splice, and field-level edits need no detection at all because a read-only
+     * collection hands out the engine's own instances — the caller is already looking at them.
+     */
+    private cacheDonor;
+    private populateFromCache;
+    /**
+     * Finds this record's related rows in whichever loaded engine already caches the related entity.
+     *
+     * @returns The matching records in declared order, or `null` when no loaded engine offers the
+     *          entity — in which case the caller falls back to a database load.
+     */
+    private findCachedRecords;
+    /**
+     * Applies the declared `OrderBy` to cache-sourced records.
+     *
+     * Only single-field `FIELD [ASC|DESC]` clauses are honored — the common case, and all that can
+     * be done in memory without reimplementing SQL. Anything more complex is left in donor order
+     * rather than half-applied, because a silently mis-ordered sequenced collection would renumber
+     * itself into that wrong order on the next mutation.
+     *
+     * @param records - The filtered records.
+     * @returns A new, ordered array.
+     */
+    private sortLikeOrderBy;
+    /**
+     * Parses the declared `OrderBy` into comparable terms.
+     *
+     * Handles `FIELD [ASC|DESC]` lists — `'Priority ASC, Name DESC'`. Anything beyond that (an
+     * expression, a function call, a CASE) is refused wholesale rather than partially applied,
+     * because a *silently* mis-ordered sequenced collection renumbers itself into that wrong order
+     * on the next mutation. This is in-memory ordering for cache-sourced collections only; a
+     * database-sourced load passes the clause to SQL untouched.
+     *
+     * @returns One term per field, or an empty array when the clause cannot be honored in memory.
+     */
+    private parseOrderBy;
+    /**
+     * Copies cached records into fresh entity instances, so a writable collection never hands out —
+     * or mutates — the engine's own objects. Saving a copy fires the ordinary `BaseEntity` save
+     * event that the engines already subscribe to, so their caches refresh themselves.
+     *
+     * @param records - The engine's cached records.
+     * @returns Detached copies carrying the same field values.
+     */
+    private copyRecords;
+    /** @inheritdoc */
+    Validate(result: ValidationResult): void;
+    /** @inheritdoc */
+    ValidateAsync(result: ValidationResult): Promise<void>;
+    /**
+     * Prefixes child validation errors with the collection and index they came from.
+     *
+     * Without this a failing order line reports "Quantity is required" with no indication of *which*
+     * line, which is close to useless on a twenty-line order.
+     *
+     * @param errors - The child's raw validation errors.
+     * @param index - The child's position in the collection.
+     * @returns Re-labeled errors.
+     */
+    private prefixErrors;
+    /** @inheritdoc */
+    ContributeSaveWork(plan: EntitySavePlan, options?: EntitySaveOptions): void;
+    /**
+     * Leaves the exact breadcrumb a developer debugging "my edit vanished" needs.
+     *
+     * Mutating a record obtained from a read-only collection and then saving the PARENT succeeds
+     * while persisting nothing — the collection contributes no save work by design, and `Dirty`
+     * deliberately excludes it. That is correct, documented behavior, but it emits no runtime
+     * signal at all; this verbose-mode log is the one witness. Save the record directly
+     * (`record.Save()`), or declare the collection writable, to persist such edits.
+     */
+    private warnIfReadOnlyHoldsDirtyItems;
+    /** @inheritdoc */
+    ContributeDeleteWork(plan: EntitySavePlan): void;
+    /** @inheritdoc */
+    AcceptChanges(): void;
+    /** @inheritdoc */
+    Serialize(): Promise<RelatedRecordCollectionWire | null>;
+    /** @inheritdoc */
+    Deserialize(data: RelatedRecordCollectionWire, mode?: EntityCompanionDeserializeMode): Promise<void>;
+    /**
+     * Rebuilds retained child entity objects from the wire.
+     *
+     * Each child is created through the provider, so it resolves to whatever subclass is registered
+     * on **this** tier. That is what makes a graph assembled in the browser execute server-side
+     * business logic: the server rebuilds the same records as their server subclasses.
+     *
+     * @param provider - The provider to create entity objects from.
+     * @param rows - Wire items.
+     * @returns Rehydrated child entities.
+     */
+    private rehydrateItems;
+    /**
+     * Rebuilds the children queued for deletion. Only identity is carried, so these are loaded from
+     * their primary keys — a delete needs the real row, not the sender's view of its fields.
+     *
+     * A removal whose row has already vanished is skipped rather than failing the graph: the intent
+     * ("this should not exist") is already satisfied.
+     *
+     * @param provider - The provider to create entity objects from.
+     * @param rows - Primary-key maps.
+     * @returns Loaded child entities to delete.
+     */
+    private rehydrateRemovals;
+    /**
+     * Extracts just the primary-key fields of a child, for the `Removed` payload.
+     *
+     * Removals only need identity — shipping the whole row would waste bandwidth and invite the
+     * server to act on stale field values for a record it is about to delete.
+     *
+     * @param child - The removed child.
+     * @returns A map of primary-key field names to values.
+     */
+    private primaryKeyOf;
+    /**
+     * Copies the parent's primary key into every retained record's foreign-key field.
+     *
+     * Called at add time, at validation time and again immediately before each record is written.
+     * Doing it early keeps the in-memory graph coherent — `line.OrderHeaderID` is populated as soon
+     * as the line is added, which is what a caller inspecting the object expects, and what lets a
+     * `NOT NULL` foreign key pass validation on a create. Doing it again at execution time covers
+     * identity/auto-increment parents, whose key genuinely does not exist until their row is
+     * inserted.
+     *
+     * A parent with no key yet is skipped rather than stamping `undefined` over a value that may
+     * already be correct.
+     */
+    private stampParentKey;
+    /**
+     * Renumbers retained children when the collection declares a sequence field.
+     *
+     * Runs on every add and remove so the sequence is always contiguous and gap-free, which is what
+     * callers assume when they display or reference "line 3".
+     */
+    private applySequence;
+}
+//# sourceMappingURL=relatedRecordCollection.d.ts.map

package/dist/generic/relatedRecordCollection.d.ts.map

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