soulcraft/brainy
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

docs(8.0): consistency-model concept + snapshots guide — Db API replaces branching docs

Browse source
This commit is contained in:
David Snelling 2026-06-11 08:37:26 -07:00
parent e5feae4104
commit cc8037db10
23 changed files with 1053 additions and 1871 deletions
Download patch file Download diff file Expand all files Collapse all files

48
README.md
View file

@ -144,38 +144,34 @@ const results = await brain.find({
})
```
### Git-Style Branching
### Database as a Value
Fork your entire database in <100ms. Snowflake-style copy-on-write.
The whole database, pinned as an immutable value. Snapshot isolation, time travel, atomic transactions, instant hard-link snapshots.
```javascript
const experiment = await brain.fork('test-migration')
await experiment.add({ data: 'test data', type: NounType.Concept })
await experiment.commit({ message: 'Add test data', author: 'dev@co.com' })
await brain.checkout('test-migration')
const db = brain.now() // Pin current state — O(1)
// Time-travel: query at any past commit
const snapshot = await brain.asOf(commitId)
const pastResults = await snapshot.find({ query: 'historical data' })
await snapshot.close()
// Atomic multi-write transaction (all-or-nothing, with CAS)
await brain.transact([
{ op: 'update', id: orderId, metadata: { status: 'paid' } },
{ op: 'relate', from: invoiceId, to: orderId, type: VerbType.References, subtype: 'billing' }
], { meta: { author: 'billing-service' }, ifAtGeneration: db.generation })
await db.get(orderId) // Still 'pending' — pinned, forever
await brain.get(orderId) // 'paid' — live
// Time travel: full query surface at any past state
const yesterday = await brain.asOf(new Date(Date.now() - 86_400_000))
const past = await yesterday.find({ query: 'unpaid orders' })
// What-if: speculative writes, nothing touches disk
const whatIf = await db.with([{ op: 'remove', id: orderId }])
// Instant backup: hard-link snapshot, opens read-only with Brainy.load()
await brain.now().persist('/backups/today')
```
**[Branching Documentation](docs/features/instant-fork.md)**
### Entity Versioning
Save, restore, and compare entity snapshots.
```javascript
const userId = await brain.add({ data: 'Alice', type: NounType.Person })
await brain.versions.save(userId, { tag: 'v1.0' })
await brain.update(userId, { data: 'Alice Smith' })
await brain.versions.save(userId, { tag: 'v2.0' })
const diff = await brain.versions.compare(userId, 1, 2)
await brain.versions.restore(userId, 1)
```
**[Consistency Model](docs/concepts/consistency-model.md)** | **[Snapshots & Time Travel](docs/guides/snapshots-and-time-travel.md)**
### Virtual Filesystem