Class RelatedRecordCollection<T>

Number of retained related records.

Deliberately delegates to 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.

True when saving would produce work: any retained child is dirty or unsaved, or any removal is pending.

Whether reading Items right now will succeed — the guard for display-tier code.

A lazy collection's 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.

@if (action.Params.IsAvailable) {
  @for (p of action.Params.Items; track p.ID) { … }
}
Copy

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.

Whether this collection has been populated from the database.

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.

The retained children, in order.

Read-only by design — mutate through Add, Create and 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.

Alias for Count, so the collection reads like a collection in the places people expect length. Both go through Items, so both trigger a lazy fill and see a live cache view.

When this collection populates itself.

Stable identifier for this companion, unique within its owning entity.

This is the wire key: it appears in serialized payloads and is how the receiving tier finds the companion to deserialize into. Treat it as a published contract — renaming it breaks in-flight payloads and any persisted snapshot that captured them.

The OrderBy clause applied when loading, if declared.

The child field holding the foreign key back to the parent.

The child entity's name in MJ metadata.

What removal means for this collection.

Children removed since the last load or save, awaiting deletion on the next save.

Always empty when RemovalMode is 'orphan'.

Where this collection's records come from. Defaults to 'database'.

Iterates the retained records, so the collection works directly with for…of, spread and array destructuring:

for (const param of action.Params) { … }
const all = [...action.Params];
const [first, ...rest] = action.Params;
Copy

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 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.

Resets the companion to its post-save state — clearing pending removals, rebasing dirty tracking, and so on. Called after the graph commits successfully.

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 ContributeSaveWork.

Rebinds the provider used by this companion and its child entities. Subclasses with child entities override this to propagate the provider.

Removes every child.

Contributes this companion's work to the owner's delete plan.

Called before the owner's own node, because children must generally be removed before the parent row they point at. Implementations that rely on database-level cascade delete should contribute nothing.

Contributes this companion's work to the owner's save plan.

Called after the owner's own node has been added, so implementations may assume the parent node exists and order their nodes relative to it. Add nothing when there is no work — an empty contribution keeps the save on the fast single-row path.

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.

Restores this companion's state from a wire payload produced by Serialize on the other tier.

Implementations must be tolerant of payloads written by an older version of themselves — a companion is a wire contract, and rolling deploys mean both versions run at once.

Populates the collection from the database.

A no-op when the parent is unsaved (there is nothing to be a child of) or when LoadMode is 'never'.

Populates this companion from the database, when it is configured to load eagerly.

Called by BaseEntity.Load() after the record's own fields are populated. Never called from LoadFromData() — that is the row-materialization path for RunView(ResultType:'entity_object'), so loading children there turns one view into an N+1 storm. Set-oriented eager loading is handled by RunView's batched child loading instead.

Removes a child by instance or index.

A child that was already persisted is queued for deletion when RemovalMode is 'delete'; an unsaved child is simply dropped, since there is nothing to delete.

Replaces an existing item in the collection with another item (e.g. replacing a generic base entity with its hydrated polymorphic IS-A leaf entity instance).

Produces this companion's JSON-safe state for transport, or null when it has nothing to send.

Returning null keeps the companion out of the payload entirely, which matters: a save that touches only header fields should not ship an empty children array and pay for it on every request.

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.

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.

Synchronous, in-memory validation contributed by this companion.

Runs as part of the owner's Validate(), before any write, over the companion's complete state — including pending removals. That ordering is what lets cross-child invariants such as "debits must equal credits" be enforced correctly rather than after half the graph has landed.

Push errors onto result.Errors and set result.Success = false to fail the save.

Asynchronous validation contributed by this companion — anything that needs a round trip.