feat(database): add atomic single-record mutations - #23
Merged
Merged
Conversation
Upd4ting
marked this pull request as ready for review
September 14, 2026 16:10
Retain native acknowledgements, declared-field and Date regressions. Preparation only: do not push this removal until a published interface release includes atomic_mutation_operations.test.js and the dependency minimum and lockfile have been updated to that release.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Outcome
Implements the published atomic mutation contract from AntelopeJS/interface-database#15 for revision-conditional update/delete and scalar
deleteIfEqualcleanup. The native single-primary-keyreplacefunction checks existence, instance, and condition together, uses hard durability, and never upserts or retries. Supplied nested fields replace their entire previous value.Normal database write atoms reject
errors/first_error, including duplicate primary keys. Scopedgetretains its instance filter for reads and ordinary writes. It is not advertised as compare-and-set; only the dedicated atomic primitive supplies that guarantee.Published prerequisite
This PR requires
@antelopejs/interface-database >=0.1.6 <1.0.0and locks registry 0.1.6. Its 13 shared real-backend atomic conformance tests are discovered automatically by Antelope. Five duplicate local cases were removed; backend-specific acknowledgement, storage, and fault coverage remains. No local overlays are required.Verification
pnpm install --frozen-lockfile: passed.pnpm build,pnpm typecheck,pnpm lint,pnpm knip,pnpm format:check: passed locally against the published interface. Lint retains three existingstream.tsmax-params warnings; Knip retains configuration hints.pnpm testpassed 198 tests, including shared conformance, against the disposable RethinkDB 2.4 service with published interface 0.1.6. Build, lint, format, Knip, and typecheck also passed.Tests cover competing unequal patches, conditional deletion/update races with alternating submission order, absent versus null revision, no upsert, wrong instance, default instance, literal nested replacement/Date, duplicate insert rejection, scalar/Date equality cleanup versus refresh, malformed stages/results, and uncertainty without retry.
Acknowledgement loss uses deterministic fault injection after a real write completes, plus typed transport/indeterminate error injection. It does not simulate physical network partition or multi-node failover.
Limits
Uncertain acknowledgements and untyped write-result failures return
unknown, nevernot-applied. Input validation and definitive typed query errors throw. Callers must reconcile unknown outcomes and never reuse revision tokens or immutable identities across incarnations.deleteIfEqualis field equality, not revision-based no-ABA protection. Ordinary multi-record writes can partially succeed before reporting errors.No merge, release, deployment, draft-state change, or shared-database writes were performed.