KV API for Bun and Node

type ValueType = 'string' | 'bytes' | 'int' | 'bigint' | 'float' | 'bool'

'string'   its UTF-8 bytes
'bytes'    the bytes
'int'      an integer a number holds exactly
'bigint'   an integer past what a number holds
'float'    its eight bytes, big-endian, every bit kept
'bool'     1 or 0

interface BucketOptions {
    /** a key expires this long after it was written, unless its write gives its own */
    ttl?: Duration | undefined
    /** a key expires this long after it was last read or written; not beside ttl */
    idle?: Duration | undefined
    /** how values are kept when they are not JSON */
    type?: ValueType | undefined
    /**
     * Keeps every value sealed with the store's encryption key, as a password or a
     * token is kept: the file holds what nobody reads without the key. The
     * store seals and opens, so this program never holds the key. A key is not
     * sealed, so a secret is a value and never a key, and a name keeps whether
     * it is encrypted.
     */
    encrypted?: boolean | undefined
}

interface WriteOptions {
    /** the key expires this long from now */
    ttl?: Duration | undefined
    /** the key expires at this time */
    expiresAt?: Time | undefined
    /** writes only while the key is at this version: ConflictError otherwise */
    ifVersion?: string
}

interface Entry<T> {
    key: string
    value: T
    /** compared only for equality: give it back to ifVersion */
    version: string
    /** undefined for a key that never expires */
    expiresAt: Date | undefined
}

interface Page<T> {
    entries: Entry<T>[]
    next: string | undefined
}

interface CountersOptions {
    /** a counter lasts this long from its first add */
    ttl?: Duration | undefined
    /**
     * keeps counts in memory and writes them this often, so that an add costs
     * no commit and a crash loses at most this span: attempts and hits, not money
     */
    flushEvery?: Duration | undefined
}

class Bucket<T> {
    readonly name: string
}

under(...owners: Key[]): Bucket<T>

get(key: Key): Promise<T | undefined>

entry(key: Key): Promise<Entry<T> | undefined>

has(key: Key): Promise<boolean>

set(key: Key, value: T, options?: WriteOptions): Promise<void>

create(key: Key, value: T, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean>

add(key: Key, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean>

take(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<T | undefined>

delete(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<boolean>

expire(key: Key, when: Duration | Date, options?: Pick<WriteOptions, 'ifVersion'>): Promise<boolean>

clear(): Promise<void>

list(options?: {
        limit?: number | undefined
        after?: Key | undefined
    }): Promise<Page<T>>

all(options?: {
        limit?: number | undefined
    }): AsyncGenerator<Entry<T>>

class Counters {
    readonly name: string
}

under(...owners: Key[]): Counters

add(key: Key, n?: number | bigint): Promise<number>

get(key: Key): Promise<number>

delete(key: Key): Promise<boolean>

clear(): Promise<void>

type Rate = `${number}/${Unit}` | `${number}/${number}${Unit}`

interface RateLimitOptions {
    /** how many requests a key passes a span */
    rate: Rate
    /** how many may pass at once before the rate holds the next; the rate's count when absent */
    burst?: number | undefined
}

interface WindowUse {
    used: number
    limit: number
    left: number
    /** when the window resets; undefined for one not started */
    resetsAt: Date | undefined
}

interface Allowance<W extends string = never> {
    ok: boolean
    /** how many more would pass now */
    left: number
    /** when a refused request may try again; undefined when it passed */
    retryAt: Date | undefined
    /** a quota's windows by name; none for a rate limit */
    windows: Record<W, WindowUse>
}

class RateLimit {
    readonly name: string
}

under(...owners: Key[]): RateLimit

allow(key: Key, n?: number): Promise<Allowance>

peek(key: Key): Promise<Allowance>

reset(key: Key): Promise<void>

class Quota<W extends string = string> {
    readonly name: string
}

under(...owners: Key[]): Quota<W>

allow(key: Key, n?: number): Promise<Allowance<W>>

const { ok, retryAt, windows } = await ai.allow(user.id)

peek(key: Key): Promise<Allowance<W>>

reset(key: Key): Promise<void>

refund(key: Key, n?: number): Promise<void>

interface OnceOptions {
    /** how long an answer is kept: a day when absent */
    keep?: Duration | undefined
}

class Once<T> {
    readonly name: string
}

under(...owners: Key[]): Once<T>

run(key: Key, fn: () => T | Promise<T>): Promise<T>

const receipt = await charges.run(requestId, () => pay.charge(order, requestId))

get(key: Key): Promise<T | undefined>

delete(key: Key): Promise<boolean>

class Tx {}

with<T>(bucket: Bucket<T>): TxBucket<T>
with(counters: Counters): TxCounters
with<T>(queue: Queue<T>): StoreTxQueue<T>
with<T>(channel: Channel<T>): TxChannel<T>

read(parts: Parts, key: Key): Promise<Found>

write(method: Method, parts: Parts, fields: CallFields, found?: Found): void

clear(parts: Parts): void

commit(): Promise<void>

class TxBucket<T> {}

under(...owners: Key[]): TxBucket<T>

get(key: Key): Promise<T | undefined>

entry(key: Key): Promise<Entry<T> | undefined>

has(key: Key): Promise<boolean>

set(key: Key, value: T, options?: WriteOptions): Promise<void>

create(key: Key, value: T, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean>

add(key: Key, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean>

take(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<T | undefined>

delete(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<boolean>

expire(key: Key, when: Duration | Date, options?: Pick<WriteOptions, 'ifVersion'>): Promise<boolean>

clear(): Promise<void>

class TxCounters {}

under(...owners: Key[]): TxCounters

add(key: Key, n?: number | bigint): Promise<void>