olmdb/dist/src/lowlevel.d.ts

Optimistic LMDB. A very fast embedded key/value store featuring ACID optimistic read/write-transactions, based on LMDB.

/**
 * Initializes the database system with the specified directory.
 *
 * Must be called once per JavaScript thread (i.e. once on the main thread
 * and once inside each Node.js / Bun `Worker` that intends to use OLMDB).
 * Each Worker gets its own independent native client, so concurrent
 * transactions across Workers are safe; all clients in the same process that
 * point at the same database directory share a single commit-worker daemon.
 *
 * Can be called multiple times within the same thread if directory and
 * commitWorkerBin are identical.
 *
 * @param directory Optional path to the database directory. If not provided,
 *   defaults to the OLMDB_DIR environment variable or "./.olmdb".
 * @param commitWorkerBin Path to the commit worker binary. Defaults to
 *  `<base_dir>/build/release/commit_worker`.
 * @throws DatabaseError if initialization fails
 */
export declare function init(directory?: string, commitWorkerBin?: string): void;
/**
 * Starts a new transaction for database operations.
 *
 * @returns A transaction ID (positive integer) to be used in subsequent operations
 * @throws DatabaseError if the transaction cannot be created
 */
export declare const startTransaction: () => number;
/**
 * Commits the transaction with the given ID.
 *
 * If the transaction is read-only, returns the commit sequence number immediately.
 * If the transaction has modifications, returns a Promise that resolves to the commit sequence when the commit completes.
 *
 * @param transactionId The ID of the transaction to commit
 * @param reopen If true, the transaction is kept open after committing.
 *   For read-only transactions, the read context is unchanged and the commit sequence is returned synchronously.
 *   For write transactions, the write and read logs are cleared and the read context
 *   is refreshed to a snapshot that includes the committed writes (and any concurrent changes).
 *   The transaction can then be used for further reads and writes.
 * @returns For read-only transactions: the commit sequence number (synchronous)
 *          For write transactions: a Promise that resolves to the commit sequence number (0 when the transaction failed due to conflicts)
 * @throws DatabaseError if the transaction cannot be committed
 */
export declare const commitTransaction: (transactionId: number, reopen?: boolean) => number | Promise<number>;
/**
 * Aborts the transaction with the given ID, discarding all changes.
 *
 * @param transactionId The ID of the transaction to abort
 * @throws DatabaseError if the transaction cannot be aborted
 */
export declare const abortTransaction: (transactionId: number) => void;
/**
 * Retrieves a value for the given key within a transaction.
 *
 * @param transactionId The ID of the transaction
 * @param key Key to look up
 * @returns The value if found, or undefined if the key doesn't exist
 * @throws DatabaseError if the operation fails
 */
export declare const get: (transactionId: number, key: ArrayBufferLike) => Readonly<ArrayBuffer> | undefined;
/**
 * Stores a key-value pair within a transaction.
 *
 * @param transactionId The ID of the transaction
 * @param key Key to store
 * @param value Value to store
 * @throws DatabaseError if the operation fails
 */
export declare const put: (transactionId: number, key: ArrayBufferLike, value: ArrayBufferLike) => void;
/**
 * Deletes a key-value pair within a transaction.
 *
 * @param transactionId The ID of the transaction
 * @param key Key to delete
 * @throws DatabaseError if the operation fails
 */
export declare const del: (transactionId: number, key: ArrayBufferLike) => void;
/**
 * Creates an iterator for scanning a range of keys within a transaction.
 *
 * The iterator covers the half-open range `[startKey, endKey)` — `startKey` is
 * the inclusive lower bound and `endKey` the exclusive upper bound. This holds
 * regardless of direction: `reverse` only changes the order in which keys are
 * emitted, not which bound is inclusive. So a forward scan yields the range
 * ascending starting at `startKey`, while a reverse scan yields the same range
 * descending starting at the largest key below `endKey`.
 *
 * @param transactionId The ID of the transaction
 * @param startKey Optional inclusive lower bound (defaults to the first key)
 * @param endKey Optional exclusive upper bound (defaults to past the last key)
 * @param reverse If true, keys are returned in descending order
 * @returns An iterator ID to be used with readIterator() and closeIterator()
 * @throws DatabaseError if the operation fails
 */
export declare const createIterator: (transactionId: number, startKey?: ArrayBufferLike, endKey?: ArrayBufferLike, reverse?: boolean) => number;
/**
 * Reads the next key-value pair from an iterator.
 *
 * @param iteratorId The ID of the iterator
 * @returns An object containing the key and value, or undefined if iteration is complete
 * @throws DatabaseError if the operation fails
 */
export declare const readIterator: (iteratorId: number) => Readonly<{
    key: Readonly<ArrayBuffer>;
    value: Readonly<ArrayBuffer>;
}> | undefined;
/**
 * Closes an iterator when it's no longer needed.
 *
 * @param iteratorId The ID of the iterator to close
 * @throws DatabaseError if the operation fails
 */
export declare const closeIterator: (iteratorId: number) => void;
/**
 * Interface for DatabaseError, which extends the standard Error class.
 * Contains an additional code property for machine-readable error identification.
 */
export interface DatabaseError extends Error {
    /**
     * A machine-readable string code identifying the type of error.
     * Example codes include: "NOT_INIT", "INVALID_TRANSACTION", "KEY_TOO_LONG", etc.
     */
    code: string;
}
/**
 * Constructor interface for DatabaseError.
 */
export interface DatabaseErrorConstructor {
    /**
     * Creates a new DatabaseError with the specified message and code.
     *
     * @param message Human-readable error message
     * @param code Machine-readable error code
     */
    new (message: string, code: string): DatabaseError;
    prototype: DatabaseError;
}
/**
 * The DatabaseError class is used to represent errors that occur during database operations.
 * It extends the built-in Error class and has a machine readable error code string property.
 *
 * The lowlevel API will throw DatabaseError instances for all database-related errors.
 * Invalid function arguments will throw TypeError.
 */
export declare const DatabaseError: DatabaseErrorConstructor;