David Snelling
8f93add705
The COW version-control surface (fork, branches, checkout, commit,
getHistory/streamHistory, asOfCommit, brain.versions) is gone, along with
its subsystems: src/versioning/, the COW object store (CommitLog,
CommitObject, RefManager, TreeObject), HistoricalStorageAdapter, and the
TypeAwareHNSWIndex path it kept alive. The Db API (now/transact/asOf/
with/persist/restore) is the one versioning model in 8.0.
Survivors and replacements:
- BlobStorage survives (the VFS stores file content through it), relocated
to src/storage/blobStorage.ts with binaryDataCodec.ts; its adapter
interface is now BlobStoreAdapter, slimmed to the consumed surface
(write/read/has/delete/getMetadata + MIME-aware compression policy).
- brain.migrate() backup branches are replaced by persist-before-migrate:
MigrateOptions.backupTo persists a hard-link snapshot of the current
generation before any transform runs; MigrationResult.backupPath reports
it, and brain.restore(path) brings it back wholesale.
- CLI: cow.ts (fork/branch/checkout/history/migrate) is replaced by
snapshot.ts — snapshot <path>, restore <path>, history (tx-log),
generation.
- New public read API: brain.transactionLog({limit}) exposes the reified
tx-log (generation/timestamp/meta, newest first) that backs the CLI
history command; TxLogEntry is exported.
Tests: superseded suites deleted; fork/commit blocks excised from shared
suites; BlobStorage tests relocated + reworked against the slimmed store;
migration tests now prove the backupTo snapshot/restore round trip; new
transactionLog coverage in db-mvcc.
108 lines
3.6 KiB
TypeScript
108 lines
3.6 KiB
TypeScript
/**
|
|
* @module storage/storageFactory
|
|
* @description Storage adapter factory for Brainy 8.0.
|
|
*
|
|
* Brainy 8.0 ships **two storage adapters**:
|
|
* - `'filesystem'` (default) — Node.js + Bun + Deno; persistent on disk.
|
|
* - `'memory'` — in-memory; ephemeral; the right choice for tests + ephemeral
|
|
* workloads.
|
|
*
|
|
* Cloud-storage adapters (GCS, S3, R2, Azure) and the browser-only OPFS
|
|
* adapter were removed in 8.0 per `BR-BRAINY-80-STORAGE-SIMPLIFY`. The path
|
|
* forward for cloud backup is operator tooling: persist locally with
|
|
* `db.persist()`, sync the resulting on-disk artefact with `gsutil` /
|
|
* `aws s3 cp` / `rclone` / `azcopy`. This is the standard pattern every
|
|
* production database uses; bundling cloud SDKs into the library buys
|
|
* nothing and ships ~13 K LOC of code we don't maintain well.
|
|
*/
|
|
|
|
import type { StorageAdapter } from '../coreTypes.js'
|
|
import { MemoryStorage } from './adapters/memoryStorage.js'
|
|
import type { OperationConfig } from '../utils/operationUtils.js'
|
|
|
|
/**
|
|
* Options for creating a storage adapter (Brainy 8.0).
|
|
*/
|
|
export interface StorageOptions {
|
|
/**
|
|
* Storage backend to use.
|
|
* - `'auto'` (default) — `'filesystem'` on Node-like runtimes, `'memory'`
|
|
* in a browser.
|
|
* - `'memory'` — in-memory; ephemeral.
|
|
* - `'filesystem'` — persistent disk storage; Node-like runtimes only.
|
|
*/
|
|
type?: 'auto' | 'memory' | 'filesystem'
|
|
|
|
/** Force memory storage regardless of environment. */
|
|
forceMemoryStorage?: boolean
|
|
|
|
/** Force filesystem storage. Throws in a browser environment. */
|
|
forceFileSystemStorage?: boolean
|
|
|
|
/** Root directory for filesystem storage. */
|
|
rootDirectory?: string
|
|
|
|
/**
|
|
* Nested options block (backward-compat for `BrainyConfig.storage.options`).
|
|
* Recognized keys: `rootDirectory`, `path`.
|
|
*/
|
|
options?: {
|
|
rootDirectory?: string
|
|
path?: string
|
|
[key: string]: any
|
|
}
|
|
|
|
/** Operation tuning (timeouts, retry budgets) passed through to the adapter. */
|
|
operationConfig?: OperationConfig
|
|
}
|
|
|
|
/**
|
|
* Resolve `StorageOptions` to a concrete storage adapter.
|
|
*
|
|
* - `'auto'` (default) picks `FileSystemStorage`, falling back to
|
|
* `MemoryStorage` only if filesystem init fails (e.g. no write permission).
|
|
* - `forceMemoryStorage: true` returns `MemoryStorage` regardless.
|
|
* - `forceFileSystemStorage: true` returns `FileSystemStorage`.
|
|
*/
|
|
export async function createStorage(options: StorageOptions = {}): Promise<StorageAdapter> {
|
|
return pickAdapter(options)
|
|
}
|
|
|
|
async function pickAdapter(options: StorageOptions): Promise<StorageAdapter> {
|
|
if (options.forceMemoryStorage) {
|
|
return new MemoryStorage()
|
|
}
|
|
|
|
const requestedType = options.type ?? 'auto'
|
|
|
|
if (requestedType === 'memory') {
|
|
return new MemoryStorage()
|
|
}
|
|
|
|
if (requestedType === 'filesystem' || options.forceFileSystemStorage) {
|
|
return await createFilesystemStorage(options)
|
|
}
|
|
|
|
// 'auto': prefer filesystem, fall back to memory if init fails.
|
|
try {
|
|
return await createFilesystemStorage(options)
|
|
} catch {
|
|
return new MemoryStorage()
|
|
}
|
|
}
|
|
|
|
async function createFilesystemStorage(options: StorageOptions): Promise<StorageAdapter> {
|
|
const rootDir =
|
|
options.rootDirectory ??
|
|
options.options?.rootDirectory ??
|
|
options.options?.path ??
|
|
'./brainy-data'
|
|
|
|
// Dynamic import so browser bundles don't pull node:fs.
|
|
const { FileSystemStorage } = await import('./adapters/fileSystemStorage.js')
|
|
return new FileSystemStorage(rootDir) as unknown as StorageAdapter
|
|
}
|
|
|
|
// Re-export the surviving adapters for direct construction by callers
|
|
// that want to skip the factory.
|
|
export { MemoryStorage } from './adapters/memoryStorage.js'
|