@barry-rocks/sdk/stores

Per-bag SQLite stores: openBagStore opens (and migrates) a bag’s store, migrateStore and Migration run ordered migrations, and the registry types describe where each store lives. The machine or an identity owns each store, as bag.yaml declares.

import { … } from "@barry-rocks/sdk/stores";

API

Classes

AmbiguousSessionLocation

Extends

• Error

Constructors

Constructor

new AmbiguousSessionLocation(): AmbiguousSessionLocation

Returns

AmbiguousSessionLocation

Overrides

Error.constructor

---

StoreRegistry

Providers are installed locally. Snapshot metadata never supplies executable code.

Constructors

Constructor

new StoreRegistry(nodeId, root?): StoreRegistry

Parameters

Parameter	Type
nodeId	string
root	string

Returns

StoreRegistry

Properties

Property	Modifier	Type
nodeId	readonly	string
root	readonly	string

Methods

declarationsFor()

declarationsFor(scope?): object[]

Parameters

Parameter	Type
scope?	StoreScope

Returns

object[]

forRoot()

forRoot(root): StoreRegistry

Parameters

Parameter	Type
root	string

Returns

StoreRegistry

hasRestoreAdapter()

hasRestoreAdapter(bag, name): boolean

Parameters

Parameter	Type
bag	string
name	string

Returns

boolean

hasSnapshotAdapter()

hasSnapshotAdapter(bag, name): boolean

Parameters

Parameter	Type
bag	string
name	string

Returns

boolean

open()

open(ref, readonly?): Promise<RegistryStoreHandle>

Parameters

Parameter	Type	Default value
ref	StoreRef	undefined
readonly	boolean	false

Returns

Promise<RegistryStoreHandle>

prepareRestore()

prepareRestore(snapshot, destination): Promise<void>

Parameters

Parameter	Type
snapshot	StoreSnapshot
destination	string

Returns

Promise<void>

register()

register(bag, name, declaration, provider): void

Parameters

Parameter	Type
bag	string
name	string
declaration	StoreDeclaration
provider	StoreProvider

Returns

void

registerRestoreAdapter()

registerRestoreAdapter(bag, name, adapter): void

Parameters

Parameter	Type
bag	string
name	string
adapter	StoreRestoreAdapter

Returns

void

registerSnapshotAdapter()

registerSnapshotAdapter(bag, name, adapter): void

Parameters

Parameter	Type
bag	string
name	string
adapter	StoreSnapshotAdapter

Returns

void

snapshot()

snapshot(ref, directory): Promise<StoreSnapshot>

Parameters

Parameter	Type
ref	StoreRef
directory	string

Returns

Promise<StoreSnapshot>

validateDatabase()

validateDatabase(ref, path): Promise<void>

Parameters

Parameter	Type
ref	StoreRef
path	string

Returns

Promise<void>

Interfaces

BagStore

Type Parameters

Type Parameter
D extends StoreHandle

Methods

close()

close(): void

Close every handle; the next use opens again.

Returns

void

db()

db(): D

The handle for the current store context, opened on first use.

Returns

D

path()

path(): string

The path the current store context’s handle opens.

Returns

string

replace()

replace(db): void

Use this handle instead (a test); it is migrated, and the previous one closed.

Parameters

Parameter	Type
db	D

Returns

void

---

BagStoreOptions

Type Parameters

Type Parameter
D extends StoreHandle

Properties

Property	Type	Description
adopt?	(db) => void	Run on each newly opened handle before its migrations: adopting a store from before it had any.
connect	(path) => D	Open the file with the bag’s driver: (path) => new Database(path).
file	string	The store’s file name, as migrations and errors name it: events.db.
foreignKeys?	boolean	On by default.
identityScoped?	boolean	Keep a handle per identity when the store context names one.
migrations	readonly Migration[]	-
onOpen?	(db, path) => void	Run on each newly opened handle, after its migrations.
path	() => string	Where the store is for the current store context; asked on every open.
scratchGuard?	string	Refuse a path outside a scratch directory under test, naming this label.
synchronous?	"FULL" | "NORMAL"	-

---

MigratableDatabase

The part of a SQLite handle this needs. better-sqlite3 and node:sqlite both fit.

Extended by

• StoreHandle

Methods

exec()

exec(sql): unknown

Parameters

Parameter	Type
sql	string

Returns

unknown

prepare()

prepare(sql): object

Parameters

Parameter	Type
sql	string

Returns

object

Name	Type
all()	(…params) => unknown
get()	(…params) => unknown
run()	(…params) => unknown

---

Migration

One forward schema change loaded from SQL or a generated migration catalog.

Properties

Property	Type
name	string
sql	string

---

MigrationResult

Properties

Property	Type	Description
from	number	The version the store was at when opened.
to	number	The version it is at now.

---

RegistryStoreHandle

Methods

close()

close(): void

Returns

void

revision()

revision(): string

Returns

string

schemaVersion()

schemaVersion(): number

Returns

number

snapshot()

snapshot(destination): Promise<void | object[]>

Parameters

Parameter	Type
destination	string

Returns

Promise<void | object[]>

---

SnapshotManifest

Extends

• StoreRef

Properties

Property	Type	Inherited from
bag	string	StoreRef.bag
bytes	number	-
capturedAt	string	-
checksum	string	-
format	1	-
identity?	string	StoreRef.identity
node	string	StoreRef.node
resources?	object[]	-
revision	string	-
schemaVersion	number	-
store	string	StoreRef.store

---

StoreBagConfiguration

Properties

Property	Type
overrides?	Readonly<Record<string, { app_url?: string; engine?: "sqlite"; filepath?: string; url?: string; }>>
remoteProtocols?	readonly string[]
stores	Readonly<Record<string, StoreDeclaration>>

---

StoreContext

Properties

Property	Type
bags?	Readonly<Record<string, StoreBagConfiguration>>
execution?	ExecutionContext
identity?	string
node?	string
root?	string
workflowActor?	(path, body?) => string | Promise<string>

---

StoreDeclaration

Properties

Property	Type
engine	"sqlite"
migrations	string
owned_by	StoreScope

---

StoreHandle

The part of a SQLite handle a bag store needs. better-sqlite3 and node:sqlite both fit.

Extends

• MigratableDatabase

Methods

close()

close(): unknown

Returns

unknown

exec()

exec(sql): unknown

Parameters

Parameter	Type
sql	string

Returns

unknown

Inherited from

MigratableDatabase.exec

prepare()

prepare(sql): object

Parameters

Parameter	Type
sql	string

Returns

object

Name	Type
all()	(…params) => unknown
get()	(…params) => unknown
run()	(…params) => unknown

Inherited from

MigratableDatabase.prepare

---

StoreProvider

Properties

Property	Type
migrations	readonly Migration[]

Methods

open()

open(path, options): RegistryStoreHandle | Promise<RegistryStoreHandle>

Parameters

Parameter	Type
path	string
options	{ readonly: boolean; }
options.readonly	boolean

Returns

RegistryStoreHandle | Promise<RegistryStoreHandle>

---

StoreRef

Extended by

• SnapshotManifest

Properties

Property	Type
bag	string
identity?	string
node	string
store	string

---

StoreResolution

Properties

Property	Type
identity?	string
name?	string
node	string
overrides?	Readonly<Record<string, { app_url?: string; engine?: "sqlite"; filepath?: string; url?: string; }>>
remoteProtocols?	readonly string[]
root?	string

---

StoreSnapshot

Properties

Property	Type
manifest	SnapshotManifest
path	string

Type Aliases

SnapshotResource

SnapshotResource = z.infer<typeof SnapshotResourceSchema>

---

StoreOptions

StoreOptions = z.infer<typeof StoreOptionsSchema>

---

StoreRestoreAdapter

StoreRestoreAdapter = (snapshot, ref, destination) => Promise<void>

Parameters

Parameter	Type
snapshot	StoreSnapshot
ref	StoreRef
destination	string

Returns

Promise<void>

---

StoreScope

StoreScope = "identity" | "node"

---

StoreSnapshotAdapter

StoreSnapshotAdapter = (ref, source, destination) => Promise<SnapshotResource[]>

Parameters

Parameter	Type
ref	StoreRef
source	string
destination	string

Returns

Promise<SnapshotResource[]>

Variables

SnapshotManifestSchema

const SnapshotManifestSchema: ZodObject<{ bag: ZodString; bytes: ZodNumber; capturedAt: ZodISODateTime; checksum: ZodString; format: ZodLiteral<1>; identity: ZodOptional<ZodString>; node: ZodString; resources: ZodOptional<ZodArray<ZodObject<{ files: ZodArray<ZodObject<{ bytes: ZodNumber; checksum: ZodString; path: ZodString; }, $strict>>; name: ZodString; }, $strict>>>; revision: ZodString; schemaVersion: ZodNumber; store: ZodString; }, $strict>

---

SnapshotResourceSchema

const SnapshotResourceSchema: ZodObject<{ files: ZodArray<ZodObject<{ bytes: ZodNumber; checksum: ZodString; path: ZodString; }, $strict>>; name: ZodString; }, $strict>

---

StoreOptionsSchema

const StoreOptionsSchema: ZodObject<{ app_url: ZodOptional<ZodURL>; engine: ZodOptional<ZodLiteral<"sqlite">>; filepath: ZodOptional<ZodString>; url: ZodOptional<ZodURL>; }, $strict>

Functions

assertScratchStoreUnderTest()

assertScratchStoreUnderTest(label, path): void

Enforce scratch paths at store opening under VITEST, unless the explicit BARRY_ALLOW_NON_TEST_STORE opt-out is set. Path-only lookups do not open stores. See docs/decisions/0038-test-isolation-and-command-reservations.md.

Parameters

Parameter	Type
label	string
path	string

Returns

void

---

copySnapshot()

copySnapshot(snapshot, destination): Promise<void>

Parameters

Parameter	Type
snapshot	StoreSnapshot
destination	string

Returns

Promise<void>

---

identityStorePaths()

identityStorePaths(bag, store): object[]

Parameters

Parameter	Type
bag	string
store	string

Returns

object[]

---

installSnapshot()

installSnapshot(snapshot, directory): Promise<StoreSnapshot>

Install into a new generation; callers switch their index only after validation.

Parameters

Parameter	Type
snapshot	StoreSnapshot
directory	string

Returns

Promise<StoreSnapshot>

---

mergeStoreOptions()

mergeStoreOptions(parent?, child?): object

Parameters

Parameter	Type
parent	{ app_url?: string; engine?: "sqlite"; filepath?: string; url?: string; }
parent.app_url?	string
parent.engine?	"sqlite"
parent.filepath?	string
parent.url?	string
child	{ app_url?: string; engine?: "sqlite"; filepath?: string; url?: string; }
child.app_url?	string
child.engine?	"sqlite"
child.filepath?	string
child.url?	string

Returns

object

Name	Type
app_url?	string
engine?	"sqlite"
filepath?	string
url?	string

---

migratedStorePath()

migratedStorePath(bag, store, legacy, nodeStore?, scope?): string

Parameters

Parameter	Type	Default value
bag	string	undefined
store	string	undefined
legacy	() => string	undefined
nodeStore	string	store
scope	"identity" | "node"	"identity"

Returns

string

---

migrateStore()

migrateStore(db, migrations, store): MigrationResult

Apply every migration the store has not seen, in order, all in one transaction with the version read.

Refuses a store stamped newer than migrations knows about: an older build would otherwise read the tables it recognises and silently ignore columns added since.

Parameters

Parameter	Type	Description
db	MigratableDatabase	-
migrations	readonly Migration[]	-
store	string	A name for error messages, e.g. “sessions.db”.

Returns

MigrationResult

---

openBagStore()

openBagStore<D>(options): BagStore<D>

Type Parameters

Type Parameter
D extends StoreHandle

Parameters

Parameter	Type
options	BagStoreOptions<D>

Returns

BagStore<D>

---

openStoreFile()

openStoreFile<D>(path, options): D

Open a SQLite file with the settings every bag store uses, before any migration.

Type Parameters

Type Parameter
D extends StoreHandle

Parameters

Parameter	Type
path	string
options	Pick<BagStoreOptions<D>, "connect" | "foreignKeys" | "synchronous">

Returns

D

---

resolveStoreBinding()

resolveStoreBinding(bag, declarations, resolution): StoreBinding

Parameters

Parameter	Type
bag	string
declarations	Readonly<Record<string, StoreDeclaration>>
resolution	StoreResolution

Returns

StoreBinding

---

sessionIdentity()

sessionIdentity(sessionId): string | undefined

Parameters

Parameter	Type
sessionId	string

Returns

string | undefined

---

storeKey()

storeKey(ref): string

Parameters

Parameter	Type
ref	StoreRef

Returns

string

---

storePath()

storePath(ref, scope, root?): string

Parameters

Parameter	Type
ref	StoreRef
scope	StoreScope
root	string

Returns

string

---

validateSnapshot()

validateSnapshot(snapshot): Promise<void>

Parameters

Parameter	Type
snapshot	StoreSnapshot

Returns

Promise<void>

References

StoreBinding

Re-exports StoreBinding