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

refactor: rename BackupData → PortableGraph (the type is interchange, not a backup)

Browse source 
Parity with the 8.0 rename, backported to the 7.x line. The brain.data()
export()/import() document type was BackupData, but it is the portable, versioned
interchange representation of a graph (entities + relations + optional vectors),
NOT a backup — exported for transport between instances, versions, and products.
The actual backup is the native snapshot, so "Backup*" mis-signalled.

Rename every developer-visible symbol, JSDoc, comment and doc:
- BackupData→PortableGraph, BackupEntity→PortableGraphEntity,
  BackupRelation→PortableGraphRelation, BACKUP_FORMAT[_VERSION]→
  PORTABLE_GRAPH_FORMAT[_VERSION], internal toBackup* helpers→toPortableGraph*.
- src/api/DataAPI.ts, src/index.ts, src/cli/commands/core.ts, docs, and the test
  (renamed data-backup.test.ts → data-portable-graph.test.ts).

The on-the-wire `format` tag is also renamed 'brainy-backup' → 'brainy-portable-graph':
the export/import format was introduced in 7.32.0 and has not been adopted by any
consumer, so there are no stored documents to stay compatible with — a clean rename
beats carrying a legacy tag forward. No deprecated aliases (nothing to alias).

1505 unit green; build clean; data-portable-graph.test.ts 20/20.
This commit is contained in:
David Snelling 2026-06-19 12:15:07 -07:00
parent 5e7379dc41
commit 89036deb20
9 changed files with 98 additions and 95 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/architecture/storage-architecture.md
View file

@ -457,14 +457,14 @@ await brain.storage.withLock('resource-id', async () => {
### Export Data
```typescript
// Export the whole brain to a portable BackupData document
const backup = await brain.data().then(d => d.export(undefined, { includeVectors: true }))
// Export the whole brain to a portable PortableGraph document
const graph = await brain.data().then(d => d.export(undefined, { includeVectors: true }))
```
### Import Data
```typescript
// Restore a BackupData document (dedup-by-id merge by default)
await brain.data().then(d => d.import(backup, { onConflict: 'merge' }))
// Restore a PortableGraph document (dedup-by-id merge by default)
await brain.data().then(d => d.import(graph, { onConflict: 'merge' }))
```
See the [Export & Import guide](../guides/export-and-import.md) for partial exports
@ -479,7 +479,7 @@ const newBrain = new Brainy({ storage: { type: 's3' } })
await oldBrain.init()
await newBrain.init()
// Transfer all data via a portable backup
// Transfer all data via a portable graph
const data = await oldBrain.data().then(d => d.export(undefined, { includeVectors: true }))
await newBrain.data().then(d => d.import(data))
```