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