Store API for Bun and Node

interface OpenOptions {
    /**
     * A server of this process's own, a child on stdin and stdout that lives
     * and dies with it, rather than the directory's shared sidecar: tests,
     * scripts, one process alone.
     */
    private?: boolean
    /**
     * The core inside this process, loaded from its library, rather than a
     * server beside it: no process and no socket.
     */
    embedded?: boolean
    /**
     * The core for `embedded`: under Bun the C library, TINYSTORE_LIBRARY when
     * absent, and under Node its addon, tinystore.node, TINYSTORE_ADDON when
     * absent; then this platform's package's.
     */
    library?: string | undefined
    /**
     * Measures the store into its own metrics, under names that start with
     * `tinystore_`: its commits and their waits, its files, its memory and
     * the machine it runs on, which `{ system: false }` leaves out. Off
     * unless asked for; a sidecar found running keeps its own.
     */
    selfMetrics?: SelfMetrics
    /** The tinystore binary: TINYSTORE_BIN, this platform's package, or PATH's when absent. */
    binary?: string
    /**
     * How long a sidecar this process starts stays once its last connection
     * has gone: 30 s unless given, 0 for ever. One found running keeps its own.
     */
    idle?: Duration
    /**
     * Runs a private server on a test's clock, starting at this time, which
     * `store.clock` moves forward instead of a test waiting: keys expire, jobs
     * come due and records age at once. Needs `private`.
     */
    clock?: Time
    /**
     * How far a commit of the store's files goes before it returns: `'full'`
     * unless given. `'os'` does not wait for the disk, so a write returns in
     * microseconds, survives this program's crash, and may be lost with the
     * last others to a power loss. It is the store's, set by whoever opens it
     * first: a sidecar found running with another is refused. A database may
     * say its own, `store.database('audit', { durability: 'full' })`.
     */
    durability?: Durability
    /**
     * The file of the store's encryption key, which seals the values of its
     * encrypted buckets: 64 hex digits, as `openssl rand -hex 32` writes, kept
     * apart from the store's data. The store reads it and never makes it.
     * Without it the key is `encryption.key` in the store's directory, which the
     * store makes when the first encrypted bucket opens. A sidecar found
     * running keeps the key it was started with.
     */
    encryptionKeyFile?: string
    /**
     * Makes the store a node: it keeps a log of each file it writes, serves
     * its files to other nodes, and copies the files of the node it takes
     * from, reading them here and passing their writes to their home. A draft,
     * as its names are:
     *
     *     const store = await open('./data', { embedded: true, node: { from: ['eu.internal:7444'] } })
     */
    node?: NodeOptions | undefined
}

interface NodeOptions {
    /** where this node takes the files it copies, `host:port`, tried in order */
    from?: string[] | undefined
    /** where other nodes take files from this one, `host:port` */
    serve?: string | undefined
    /** the files it copies, as `kv.db` or `sql/app.db`; every file but its own records and metrics when absent */
    files?: string[] | undefined
    /** what it says to the node it takes from, and asks of the nodes that take from it; embedded alone */
    token?: string | undefined
    /** the file of that token, for a server this process starts */
    tokenFile?: string | undefined
    /** a write of a file this node writes answers once a node copying it holds the commit */
    synchronous?: boolean | undefined
    /** the nodes, by address or id, a synchronous commit waits for one of; any node copying the file when absent */
    synchronousWith?: string[] | undefined
    /**
     * this node is the home of the catalog, which names each file's home: one
     * node of a network, chosen by a person; the others then write each file
     * they make once their claim of its name won, and need no `files`
     */
    catalog?: boolean | undefined
    /** where other nodes reach this one, `host:port`, when `serve` listens on every interface */
    advertise?: string | undefined
    /** plain TCP on links beyond this machine, which anyone on the way reads; without it such a link takes TLS */
    insecure?: boolean | undefined
}

interface Status {
    /** its version: v0.1.0, or (devel) for one built from a checkout */
    server: string
    protocol: number
    /** the engines it serves */
    engines: string[]
    /** admin may change a schema and drop records; data reads and writes */
    capability: 'admin' | 'data'
}

interface ConnectOptions {
    /** a line of the server's tokens file, admin or data */
    token: string
    tls?: TlsOptions
}

class Store implements AsyncDisposable {
    readonly metrics: Metrics
    readonly clock: Clock
}

events(): AllEvents
events(stream: string, options?: EventsOptions): Events

const audit = store.events('audit', { keep: '365d' })
await audit.append('role.changed', { user: 42, role: 'admin' })
const page = await store.events().list({ since: '1h', minLevel: 'warn' })

logger(stream: string, options?: StoreLoggerOptions): Logger

const log = store.logger('api', { redact: secrets })
log.info('signed in', { user: 42 })
const settings = await store.config('log', [{ level: live('info') }])
await settings.update({ level: 'debug' })

bucket<T = unknown>(name: string, options?: BucketOptions): Bucket<T>

const sessions = store.bucket<Session>('sessions', { idle: '30d' })
const codes = store.bucket<number>('login-codes', { ttl: '15m', type: 'int' })
const seen = store.bucket('stripe-events', { ttl: '7d' })   // keys alone: a set

counters(name: string, options?: CountersOptions): Counters

rateLimit(name: string, options: RateLimitOptions): RateLimit

quota<W extends string>(name: string, windows: Record<W, Rate>): Quota<W>

index<T = unknown>(name: string, options?: IndexOptions): SearchIndex<T>

const articles = store.index<Article>('articles', { fields: { title: 2, body: 1 } })
const { hits } = await articles.search('как испечь хлеб')

reindex<T = unknown>(name: string, options?: IndexOptions): Promise<SearchIndex<T>>

dropIndex(name: string): Promise<boolean>

indexes(): Promise<IndexInfo[]>

channel<T = unknown>(name: string): Channel<T>

lock(name: string, options?: LockOptions): Lock

semaphore(name: string, options: SemaphoreOptions): Semaphore

once<T = unknown>(name: string, options?: OnceOptions): Once<T>

queue<S extends StandardSchemaV1>(name: string, options: QueueOptions & {
        schema: S
    }): Queue<StandardSchemaV1.InferOutput<S>>
queue<T = unknown>(name: string, options?: QueueOptions): Queue<T>

const emails = store.queue<Email>('emails', { attempts: 20, backoff: { initial: '5s', max: '30m' } })
const refreshes = store.queue('refreshes', { schema: Refresh, concurrency: { total: 8, group: 2 } })

schedule(name: string, when: ScheduleWhen, handler: (run: Run) => unknown, options?: ScheduleOptions): Schedule

store.schedule('cleanup', { cron: '10 3 * * *', timeZone: 'Europe/Berlin' }, async run => {
  await purgeDeletedBefore(daysBefore(run.at, 30))
})

tx<T>(fn: (tx: Tx) => T | Promise<T>): Promise<T>

await store.tx(async tx => {
  const left = (await tx.with(stock).get(sku)) ?? 0
  if (left < 1) throw new SoldOut()
  await tx.with(stock).set(sku, left - 1)
})

config<D extends object>(name: string, layers: readonly [D, ...NoInfer<Layer<D>>[]], options?: ConfigOptions<Value<D>>): Promise<Config<D>>

const config = await store.config('app', [
  { port: 8080, db: { url: secret(String) }, limits: { rps: live(100) } },
  file('app.yaml'),
  env('APP', { vars: { port: 'PORT' } }),
])

backup(path: string, options?: BackupOptions): Promise<Backup>

const backup = await store.backup('backup-2026-10-13.zip', { include: ['secret.key'] })
if (backup.keyLeftOut) console.warn('keep encryption.key apart: the backup opens with it alone')

status(): Promise<Status>

files(name: string, options?: FilesOptions): Files

const avatars = store.files('avatars')
const reports = store.files('reports', { ttl: '24h', maxFileSize: '2GiB' })

database(name: string, options?: DatabaseOptions): Promise<Database>

const db = await store.database('app', { migrations: `${import.meta.dir}/migrations` })

close(): Promise<void>

[Symbol.asyncDispose](): Promise<void>

function open(dir: string, options?: OpenOptions): Promise<Store>

function connect(url: string, options: ConnectOptions): Promise<Store>

type Durability = 'full' | 'os'

'full'   synced to the disk: it survives a crash of the operating
         system and a power loss. What every file is unless told.
'os'     written to the operating system, synced a little later: it
         survives the program's crash, and a power loss may take the
         last commits, never the file.

type SelfMetrics = boolean | {
    system?: boolean
}

class Link {}

connection(): Promise<Connection>

ready(): Connection | undefined

run<T>(idempotence: Idempotence, attempt: (connection: Connection) => Promise<T>, signal?: AbortSignal): Promise<T>

close(): Promise<void>

class Clock {}

await using store = await open(dir, { private: true, clock: new Date('2026-10-03T09:00:00Z') })
await store.clock.advance('1h')

now(): Promise<Date>

advance(by: Duration): Promise<Date>

set(to: Time): Promise<Date>

type Code = 'invalid' | 'not_found' | 'limit' | 'closed' | 'in_use' | 'conflict' | 'corrupt' | 'too_old' | 'too_new' | 'suspended' | 'outcome_unknown' | 'committed_locally' | 'lost' | 'permission' | 'unimplemented' | 'cancelled' | 'unavailable' | 'internal' | 'protocol' | 'unauthenticated'

type What = Record<string, string | Uint8Array>

interface Constraint {
    kind: 'unique' | 'primaryKey' | 'foreignKey' | 'check' | 'notNull'
    /** the table, when SQLite names it */
    table: string | undefined
    /** the columns, when SQLite names them */
    columns: string[]
    /** a check's name, or its text when it has none; the index of a unique key on an expression */
    name: string | undefined
}

if (err instanceof ConflictError && err.constraint?.columns.includes('email')) return 'that email is taken'

class TinystoreError extends Error {
    readonly code: Code
    readonly what: What
    readonly constraint: Constraint | undefined
}

class InvalidError extends TinystoreError {}

class LimitError extends TinystoreError {
    readonly limit: string | undefined
    readonly wanted: number | undefined
    readonly bound: number | undefined
}

const limits: Readonly<{
    readonly storeMemory: "store memory"
    readonly storeMemoryNow: "store memory, now"
    readonly matchedSeries: "matched series"
    readonly decodedBlocks: "decoded blocks"
    readonly fetchedBytes: "fetched bytes"
    readonly decodedSamples: "decoded samples"
    readonly outputSamples: "output samples"
    readonly outputBuckets: "output buckets"
    readonly recordBytes: "bytes of a record, a block's"
    readonly appendBytes: "bytes of records in one Append, a segment's; split it"
    readonly jobValueBytes: "bytes of a job's value"
    readonly stepBytes: "bytes of a step's answer"
    readonly objectBytes: "bytes of an object, the bucket's MaxSize"
    readonly rowBytes: "bytes of a call's rows"
}>

if (err instanceof LimitError && err.limit === limits.decodedSamples) { … }

class NotFoundError extends TinystoreError {}

class ClosedError extends TinystoreError {}

class InUseError extends TinystoreError {}

class ConflictError extends TinystoreError {}

class CorruptError extends TinystoreError {}

class TooOldError extends TinystoreError {}

class TooNewError extends TinystoreError {}

class SuspendedError extends TinystoreError {}

class OutcomeUnknownError extends TinystoreError {}

class CommittedLocallyError extends TinystoreError {}

class PermissionDeniedError extends TinystoreError {}

class UnimplementedError extends TinystoreError {}

class CancelledError extends TinystoreError {}

class UnavailableError extends TinystoreError {}

class InternalError extends TinystoreError {}

class LostError extends TinystoreError {}

class ProtocolError extends TinystoreError {}

class UnauthenticatedError extends TinystoreError {}

const codes: Code[]

function errorOf(code: string, message: string, what?: What): TinystoreError

interface Page<T, After> {
    items: T[]
    /** the place the next page begins after; undefined once the scan has ended */
    next: After | undefined
}

function withSignal<T>(signal: AbortSignal, fn: () => T): T

await withSignal(AbortSignal.timeout(2000), async () => {
  const notes = await app.all`select * from notes`
})

type DurationText = Offered | (Spelled<Units> & Record<never, never>)

type Duration = number | DurationText

type Time = Date | number

type Key = string | Uint8Array | number | bigint