@naturalcycles/db-lib/dist/kv/commonKeyValueDao.d.ts

Lowest Common Denominator API to supported Databases

import type { CommonLogger } from '@naturalcycles/js-lib/log';
import { type Integer, type KeyValueTuple } from '@naturalcycles/js-lib/types';
import type { Pipeline } from '@naturalcycles/nodejs-lib/stream';
import type { CommonDaoLogLevel } from '../commondao/common.dao.model.js';
import type { CommonDBCreateOptions } from '../db.model.js';
import type { CommonKeyValueDB, CommonKeyValueDBSaveBatchOptions, IncrementTuple, KeyValueDBTuple } from './commonKeyValueDB.js';
export interface CommonKeyValueDaoCfg<V> {
    db: CommonKeyValueDB;
    table: string;
    /**
     * @default to false
     * Set to true to limit DB writing (will throw an error is such case).
     */
    readOnly?: boolean;
    /**
     * Default to console
     */
    logger?: CommonLogger;
    /**
     * @default OPERATIONS
     */
    logLevel?: CommonDaoLogLevel;
    /**
     * @default false
     */
    logStarted?: boolean;
    transformer?: CommonKeyValueDaoTransformer<V>;
}
export type CommonKeyValueDaoSaveOptions = CommonKeyValueDBSaveBatchOptions;
export interface CommonKeyValueDaoTransformer<V> {
    valueToBuffer: (v: V) => Promise<Buffer>;
    bufferToValue: (buf: Buffer) => Promise<V>;
}
/**
 * @deprecated use zstd instead, gzip is obsolete
 */
export declare function commonKeyValueDaoDeflatedJsonTransformer<T = any>(): CommonKeyValueDaoTransformer<T>;
export declare function commonKeyValueDaoZstdJsonTransformer<T = any>(level: Integer | undefined): CommonKeyValueDaoTransformer<T>;
/**
 * Saves: zstd
 * Reads: zstd or deflate (backwards compatible)
 */
export declare function commonKeyValueDaoCompressedTransformer<T = any>(): CommonKeyValueDaoTransformer<T>;
export declare class CommonKeyValueDao<K extends string = string, V = Buffer> {
    constructor(cfg: CommonKeyValueDaoCfg<V>);
    cfg: CommonKeyValueDaoCfg<V> & {
        logger: CommonLogger;
    };
    ping(): Promise<void>;
    createTable(opt?: CommonDBCreateOptions): Promise<void>;
    getById(id?: K): Promise<V | null>;
    getByIdAsBuffer(id?: K): Promise<Buffer | null>;
    requireById(id: K): Promise<V>;
    requireByIdAsBuffer(id: K): Promise<Buffer>;
    getByIds(ids: K[]): Promise<KeyValueTuple<string, V>[]>;
    getByIdsAsBuffer(ids: K[]): Promise<KeyValueDBTuple[]>;
    save(id: K, value: V, opt?: CommonKeyValueDaoSaveOptions): Promise<void>;
    saveBatch(entries: KeyValueTuple<K, V>[], opt?: CommonKeyValueDaoSaveOptions): Promise<void>;
    deleteByIds(ids: K[]): Promise<void>;
    deleteById(id: K): Promise<void>;
    streamIds(limit?: number): Pipeline<K>;
    streamValues(limit?: number): Pipeline<V>;
    streamEntries(limit?: number): Pipeline<KeyValueTuple<K, V>>;
    getAllKeys(limit?: number): Promise<K[]>;
    getAllValues(limit?: number): Promise<V[]>;
    getAllEntries(limit?: number): Promise<KeyValueTuple<K, V>[]>;
    /**
     * Increments the `id` field by the amount specified in `by`,
     * or by 1 if `by` is not specified.
     *
     * Returns the new value of the field.
     */
    increment(id: K, by?: number): Promise<number>;
    incrementBatch(entries: IncrementTuple[]): Promise<IncrementTuple[]>;
}