Database

Constructor

new Database(config?: DatabaseConfig)

Properties

db.name: string
db.isConnected: boolean
db.adapterName: string

Methods

connect()

connect(): Promise<void>

Initializes the storage adapter. Idempotent — safe to call multiple times.

disconnect()

disconnect(): Promise<void>

Closes the adapter and clears collection cache. Idempotent.

collection()

collection<T>(name: string): Collection<T>

Returns a cached or new collection for the given name. Throws ConnectionError if not connected.

transaction()

transaction<T>(fn: (ctx: TransactionContext) => Promise<T>): Promise<T>

Runs fn inside an adapter-level transaction. Rolled back on throw.

on()

on(callback: (event: ChangeEvent) => void): () => void

Subscribes to all change events. Returns an unsubscribe function.

plugin()

plugin(name: string): CtroDBPlugin | undefined

Returns the plugin instance registered with the given name, or undefined.

sync()

sync(): Promise<void>

Triggers a full sync cycle. Requires the sync plugin to be registered.

onSync()

onSync(callback: (event: SyncEvent) => void): () => void

Subscribes to sync lifecycle events. Requires the sync plugin.

syncStatus

db.syncStatus: SyncStatus
// { isSyncing: boolean, isConnected: boolean, lastSyncAt: string | null,
//   pendingChanges: number, failedChanges: number, lastError: string | null }

getPendingCount()

getPendingCount(): Promise<number>

Count of pending outbound sync changes.

getFailedCount()

getFailedCount(): Promise<number>

Count of failed sync attempts.

Internal methods

db._getSchema(): Schema | null
db._getAdapter(): StorageAdapter

Underscore-prefixed methods exist for plugin use. Not part of the public API contract.

DatabaseConfig

interface DatabaseConfig {
  name?: string
  adapter?: "indexeddb" | "memory" | StorageAdapter
  schema?: SchemaConfig
  plugins?: CtroDBPlugin[]
  logLevel?: "debug" | "info" | "warn" | "error" | "silent"
}