Optionalopts: { onError?: (message: string) => void; saveReturnMode?: EntitySaveReturnMode }OptionalonError?: (message: string) => voidOptional handler for a failed save's diagnostic message. Defaults to the
global LogError. Consumers with structured logging (e.g. a category/metadata logger) pass
their own so failures stay in their log stream.
OptionalsaveReturnMode?: EntitySaveReturnModeOptional EntitySaveReturnMode forwarded to every queued
entity.Save(options) call (e.g. 'datestamps_only' for high-write execution log queues
whose wide JSON/text payload columns are already in memory).
Awaits all pending saves and returns failure diagnostics. Call at the run/goal finalize boundary.
Fire-and-forget INSERT of a freshly NewRecord()'d entity. The entity instance is the
serialization key, so a subsequent Update of the same instance waits for this to land.
Fire-and-forget INSERT that waits for dependency's pending tasks to settle first. Use this for
self-referencing foreign keys: a child entity whose FK points at dependency must not INSERT
until the dependency's own INSERT has landed in the database.
Fire-and-forget INSERT that runs only after ready resolves. Use this when the row has a foreign
key to a row that another queue is still writing: pass that queue's Settled for the
parent. The INSERT is queued at once (so Flush waits for it) and the caller never waits;
only the save itself is held back. (InsertAfter is the same wait when both rows share this
queue.)
Resolves once every save queued so far for entity has settled (at once when none is pending);
never rejects — a failed save is already logged here. For a caller that holds the entity's ID and
must write a dependent row (a foreign key to it) from a different queue: InsertAfter only
orders writes within this queue.
Fire-and-forget UPDATE chained after the entity's INSERT. applyMutation (if given) runs INSIDE
the post-INSERT task — after finalizeSave's reload — so its values always survive; the save is
force-persisted with IgnoreDirtyState. Pass no mutation only when the fields are already set
AND cannot race an in-flight INSERT.
OptionalapplyMutation: (entity: BaseEntity) => void
A per-entity-instance serial save queue. INSERT and UPDATE of the same
BaseEntityinstance are serialized (the UPDATE waits for the INSERT to land); different entities save concurrently. All saves are fire-and-forget and never throw outward — a failedSave()(returnedfalseor a thrown error) is logged and counted; call Flush at a run/goal boundary to await them and surface the failure count.