@harperfast/rocksdb-js 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -16,6 +16,7 @@ interface Encoder {
   encode?: (value: any, mode?: number) => Buffer;
   Encoder?: EncoderFunction;
   freezeData?: boolean;
+  name?: string;
   needsStableBuffer?: boolean;
   randomAccessStructure?: boolean;
   readKey?: (buffer: Buffer, start: number, end: number, inSequence?: boolean) => any;
@@ -35,16 +36,21 @@ interface DBIteratorValue<T> {
   value: T;
 }
 /**
-* Wraps an iterator, namely the `NativeIterator` class, and decodes the key
-* and value.
+* Wraps the `NativeIterator` C++ binding, decoding keys and values from the
+* shared key/value buffers (fast path) or from per-iteration buffers (slow
+* fallback path used for oversized data or stable-buffer decoders).
+*
+* The native `next()` returns a primitive signal (and writes lengths to the
+* shared `ITERATOR_STATE` buffer) instead of constructing a JS result object,
+* so this class is responsible for building the `IteratorResult`.
 */
 declare class DBIterator<T> implements Iterator<DBIteratorValue<T>> {
   #private;
-  iterator: Iterator<DBIteratorValue<T>>;
+  iterator: InstanceType<typeof NativeIteratorCls>;
   store: Store;
-  constructor(iterator: Iterator<DBIteratorValue<T>>, store: Store, options?: IteratorOptions & T);
+  constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean);
   [Symbol.iterator](): Iterator<DBIteratorValue<T>>;
-  next(...[_value]: [] | [any]): IteratorResult<DBIteratorValue<T>>;
+  next(): IteratorResult<DBIteratorValue<T>>;
   return(value?: any): IteratorResult<DBIteratorValue<T>, any>;
   throw(err: unknown): IteratorResult<DBIteratorValue<T>, any>;
 }
@@ -56,6 +62,10 @@ type StoreIteratorOptions = IteratorOptions & DBITransactional;
 type StorePutOptions = PutOptions & DBITransactional;
 type StoreRangeOptions = RangeOptions & DBITransactional;
 type StoreRemoveOptions = DBITransactional | unknown;
+type CompactOptions = {
+  start?: Key;
+  end?: Key;
+};
 /**
 * Options for the `Store` class.
 */
@@ -244,6 +254,28 @@ declare class Store {
   */
   close(): void;
   /**
+  * Compacts the entire key range of the database asynchronously.
+  * This triggers manual compaction which removes tombstones and reclaims space.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * await db.compact();
+  * ```
+  */
+  compact(options?: CompactOptions): Promise<void>;
+  /**
+  * Compacts the entire key range of the database synchronously.
+  * This triggers manual compaction which removes tombstones and reclaims space.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * db.compactSync();
+  * ```
+  */
+  compactSync(options?: CompactOptions): void;
+  /**
   * Decodes a key from the database.
   *
   * @param key - The key to decode.
@@ -372,29 +404,17 @@ interface PutOptions {
 }
 //#endregion
 //#region src/load-binding.d.ts
-type TransactionOptions = {
+type NativeTransactionOptions = {
   /**
   * Whether to disable snapshots.
   *
   * @default false
   */
   disableSnapshot?: boolean;
-  /**
-  * The maximum number of times to retry the transaction.
-  *
-  * @default 3
-  */
-  maxRetries?: number;
-  /**
-  * Whether to retry the transaction if it fails with `IsBusy`.
-  *
-  * @default `true` when the transaction is bound to a transaction log, otherwise `false`
-  */
-  retryOnBusy?: boolean;
 };
 type NativeTransaction = {
   id: number;
-  new (context: NativeDatabase, options?: TransactionOptions): NativeTransaction;
+  new (context: NativeDatabase, options?: NativeTransactionOptions): NativeTransaction;
   abort(): void;
   commit(resolve: () => void, reject: (err: Error) => void): void;
   commitSync(): void;
@@ -440,6 +460,36 @@ type TransactionLog = {
   _lastCommittedPosition: Float64Array;
   _logBuffers: Map<number, WeakRef<LogBuffer>>;
 };
+/**
+* Shape of options that can be passed to the native iterator constructor for
+* the rare case of advanced RocksDB ReadOptions overrides. Common iterator
+* options are passed via the bitmask `flags` argument instead.
+*/
+type NativeIteratorAdvancedOptions = {
+  adaptiveReadahead?: boolean;
+  asyncIO?: boolean;
+  autoReadaheadSize?: boolean;
+  backgroundPurgeOnIteratorCleanup?: boolean;
+  fillCache?: boolean;
+  readaheadSize?: number;
+  tailing?: boolean;
+};
+/**
+* The result of a single native iterator step. A number value matches one of
+* the `ITERATOR_RESULT_*` constants. The slow-path object is returned when
+* the data does not fit in the shared key/value buffers, or when the decoder
+* needs a stable value buffer.
+*/
+type NativeIteratorResult = number | {
+  key: Buffer;
+  value?: Buffer;
+};
+declare class NativeIteratorCls {
+  constructor(context: StoreContext, flags: number, startKeyEnd: number, endKeyStart: number, endKeyEnd: number, options?: NativeIteratorAdvancedOptions);
+  next(): NativeIteratorResult;
+  return(): void;
+  throw(err?: unknown): void;
+}
 type NativeDatabaseMode = "optimistic" | "pessimistic";
 type NativeDatabaseOptions = {
   disableWAL?: boolean;
@@ -480,6 +530,9 @@ type NativeDatabase = {
   clear(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   clearSync(): void;
   close(): void;
+  compact(resolve: ResolveCallback<void>, reject: RejectCallback, start?: Key, end?: Key): void;
+  compactSync(start?: Key, end?: Key): void;
+  columns: string[];
   destroy(): void;
   drop(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   dropSync(): void;
@@ -488,8 +541,8 @@ type NativeDatabase = {
   notify(event: string | BufferWithDataView, args?: any[]): boolean;
   get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer>, reject: RejectCallback, txnId?: number): number;
   getCount(options?: RangeOptions, txnId?: number): number;
-  getDBIntProperty(propertyName: string): number;
-  getDBProperty(propertyName: string): string;
+  getDBIntProperty(propertyName: string): number | undefined;
+  getDBProperty(propertyName: string): string | undefined;
   getMonotonicTimestamp(): number;
   getOldestSnapshotTimestamp(): number;
   getStat(statName: string): number | StatsHistogramData;
@@ -507,6 +560,7 @@ type NativeDatabase = {
   removeSync(key: BufferWithDataView, txnId?: number): void;
   setDefaultKeyBuffer(buffer: Buffer | Uint8Array | null): void;
   setDefaultValueBuffer(buffer: Buffer | Uint8Array | null): void;
+  setIteratorState(buffer: Buffer | Uint8Array): void;
   tryLock(key: BufferWithDataView, callback?: () => void): boolean;
   unlock(key: BufferWithDataView): void;
   useLog(name: string): TransactionLog;
@@ -514,6 +568,7 @@ type NativeDatabase = {
 };
 type RocksDatabaseConfig = {
   blockCacheSize?: number;
+  compactOnClose?: boolean;
 };
 type RegistryStatusDB = {
   path: string;
@@ -533,6 +588,14 @@ declare const constants: {
   TRANSACTION_LOG_TOKEN: number;
   TRANSACTION_LOG_ENTRY_HEADER_SIZE: number;
   TRANSACTION_LOG_FILE_HEADER_SIZE: number;
+  ITERATOR_REVERSE_FLAG: number;
+  ITERATOR_INCLUSIVE_END_FLAG: number;
+  ITERATOR_EXCLUSIVE_START_FLAG: number;
+  ITERATOR_INCLUDE_VALUES_FLAG: number;
+  ITERATOR_NEEDS_STABLE_VALUE_BUFFER_FLAG: number;
+  ITERATOR_CONTEXT_IS_TRANSACTION_FLAG: number;
+  ITERATOR_RESULT_DONE: number;
+  ITERATOR_RESULT_FAST: number;
 };
 declare const NativeDatabase: NativeDatabase;
 declare const NativeTransaction: NativeTransaction;
@@ -566,7 +629,7 @@ declare class Transaction extends DBI {
   * @param store - The base store interface for this transaction.
   * @param options - The options for the transaction.
   */
-  constructor(store: Store, options?: TransactionOptions);
+  constructor(store: Store, options?: NativeTransactionOptions);
   /**
   * Abort the transaction.
   */
@@ -922,6 +985,20 @@ interface RocksDatabaseOptions extends StoreOptions {
   */
   name?: string;
 }
+interface TransactionOptions extends NativeTransactionOptions {
+  /**
+  * The maximum number of times to retry the transaction.
+  *
+  * @default 3
+  */
+  maxRetries?: number;
+  /**
+  * Whether to retry the transaction if it fails with `IsBusy`.
+  *
+  * @default `true` when the transaction is bound to a transaction log, otherwise `false`
+  */
+  retryOnBusy?: boolean;
+}
 type RocksDBStat = number | StatsHistogramData;
 type RocksDBStats = Record<string, RocksDBStat>;
 /**
@@ -971,6 +1048,32 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   */
   close(): void;
   /**
+  * Compacts the entire key range of the database asynchronously.
+  * This triggers manual compaction which removes tombstones and reclaims space.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * await db.compact();
+  * ```
+  */
+  compact(options?: CompactOptions): Promise<void>;
+  /**
+  * Compacts the entire key range of the database synchronously.
+  * This triggers manual compaction which removes tombstones and reclaims space.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * db.compactSync();
+  * ```
+  */
+  compactSync(options?: CompactOptions): void;
+  /**
+  * Returns the list of column families in the RocksDB database.
+  */
+  get columns(): string[];
+  /**
   * Set global database settings.
   *
   * @param options - The options for the database.
@@ -1010,7 +1113,7 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * const numKeys = db.getDBIntProperty('rocksdb.estimate-num-keys');
   * ```
   */
-  getDBIntProperty(propertyName: string): number;
+  getDBIntProperty(propertyName: string): number | undefined;
   /**
   * Gets a RocksDB database property as a string.
   *
@@ -1024,7 +1127,18 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * const stats = db.getDBProperty('rocksdb.stats');
   * ```
   */
-  getDBProperty(propertyName: string): string;
+  getDBProperty(propertyName: string): string | undefined;
+  /**
+  * Retrieves the estimated number of keys in the database.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * const estimated = db.getEstimatedKeyCount();
+  * console.log(estimated);
+  * ```
+  */
+  getEstimatedKeyCount(): number;
   /**
   * Returns the current timestamp as a monotonically increasing timestamp in
   * milliseconds represented as a decimal number.

package/dist/index.d.mts

@@ -16,6 +16,7 @@ interface Encoder {
   encode?: (value: any, mode?: number) => Buffer;
   Encoder?: EncoderFunction;
   freezeData?: boolean;
+  name?: string;
   needsStableBuffer?: boolean;
   randomAccessStructure?: boolean;
   readKey?: (buffer: Buffer, start: number, end: number, inSequence?: boolean) => any;
@@ -35,16 +36,21 @@ interface DBIteratorValue<T> {
   value: T;
 }
 /**
-* Wraps an iterator, namely the `NativeIterator` class, and decodes the key
-* and value.
+* Wraps the `NativeIterator` C++ binding, decoding keys and values from the
+* shared key/value buffers (fast path) or from per-iteration buffers (slow
+* fallback path used for oversized data or stable-buffer decoders).
+*
+* The native `next()` returns a primitive signal (and writes lengths to the
+* shared `ITERATOR_STATE` buffer) instead of constructing a JS result object,
+* so this class is responsible for building the `IteratorResult`.
 */
 declare class DBIterator<T> implements Iterator<DBIteratorValue<T>> {
   #private;
-  iterator: Iterator<DBIteratorValue<T>>;
+  iterator: InstanceType<typeof NativeIteratorCls>;
   store: Store;
-  constructor(iterator: Iterator<DBIteratorValue<T>>, store: Store, options?: IteratorOptions & T);
+  constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean);
   [Symbol.iterator](): Iterator<DBIteratorValue<T>>;
-  next(...[_value]: [] | [any]): IteratorResult<DBIteratorValue<T>>;
+  next(): IteratorResult<DBIteratorValue<T>>;
   return(value?: any): IteratorResult<DBIteratorValue<T>, any>;
   throw(err: unknown): IteratorResult<DBIteratorValue<T>, any>;
 }
@@ -56,6 +62,10 @@ type StoreIteratorOptions = IteratorOptions & DBITransactional;
 type StorePutOptions = PutOptions & DBITransactional;
 type StoreRangeOptions = RangeOptions & DBITransactional;
 type StoreRemoveOptions = DBITransactional | unknown;
+type CompactOptions = {
+  start?: Key;
+  end?: Key;
+};
 /**
 * Options for the `Store` class.
 */
@@ -244,6 +254,28 @@ declare class Store {
   */
   close(): void;
   /**
+  * Compacts the entire key range of the database asynchronously.
+  * This triggers manual compaction which removes tombstones and reclaims space.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * await db.compact();
+  * ```
+  */
+  compact(options?: CompactOptions): Promise<void>;
+  /**
+  * Compacts the entire key range of the database synchronously.
+  * This triggers manual compaction which removes tombstones and reclaims space.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * db.compactSync();
+  * ```
+  */
+  compactSync(options?: CompactOptions): void;
+  /**
   * Decodes a key from the database.
   *
   * @param key - The key to decode.
@@ -372,29 +404,17 @@ interface PutOptions {
 }
 //#endregion
 //#region src/load-binding.d.ts
-type TransactionOptions = {
+type NativeTransactionOptions = {
   /**
   * Whether to disable snapshots.
   *
   * @default false
   */
   disableSnapshot?: boolean;
-  /**
-  * The maximum number of times to retry the transaction.
-  *
-  * @default 3
-  */
-  maxRetries?: number;
-  /**
-  * Whether to retry the transaction if it fails with `IsBusy`.
-  *
-  * @default `true` when the transaction is bound to a transaction log, otherwise `false`
-  */
-  retryOnBusy?: boolean;
 };
 type NativeTransaction = {
   id: number;
-  new (context: NativeDatabase, options?: TransactionOptions): NativeTransaction;
+  new (context: NativeDatabase, options?: NativeTransactionOptions): NativeTransaction;
   abort(): void;
   commit(resolve: () => void, reject: (err: Error) => void): void;
   commitSync(): void;
@@ -440,6 +460,36 @@ type TransactionLog = {
   _lastCommittedPosition: Float64Array;
   _logBuffers: Map<number, WeakRef<LogBuffer>>;
 };
+/**
+* Shape of options that can be passed to the native iterator constructor for
+* the rare case of advanced RocksDB ReadOptions overrides. Common iterator
+* options are passed via the bitmask `flags` argument instead.
+*/
+type NativeIteratorAdvancedOptions = {
+  adaptiveReadahead?: boolean;
+  asyncIO?: boolean;
+  autoReadaheadSize?: boolean;
+  backgroundPurgeOnIteratorCleanup?: boolean;
+  fillCache?: boolean;
+  readaheadSize?: number;
+  tailing?: boolean;
+};
+/**
+* The result of a single native iterator step. A number value matches one of
+* the `ITERATOR_RESULT_*` constants. The slow-path object is returned when
+* the data does not fit in the shared key/value buffers, or when the decoder
+* needs a stable value buffer.
+*/
+type NativeIteratorResult = number | {
+  key: Buffer;
+  value?: Buffer;
+};
+declare class NativeIteratorCls {
+  constructor(context: StoreContext, flags: number, startKeyEnd: number, endKeyStart: number, endKeyEnd: number, options?: NativeIteratorAdvancedOptions);
+  next(): NativeIteratorResult;
+  return(): void;
+  throw(err?: unknown): void;
+}
 type NativeDatabaseMode = "optimistic" | "pessimistic";
 type NativeDatabaseOptions = {
   disableWAL?: boolean;
@@ -480,6 +530,9 @@ type NativeDatabase = {
   clear(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   clearSync(): void;
   close(): void;
+  compact(resolve: ResolveCallback<void>, reject: RejectCallback, start?: Key, end?: Key): void;
+  compactSync(start?: Key, end?: Key): void;
+  columns: string[];
   destroy(): void;
   drop(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   dropSync(): void;
@@ -488,8 +541,8 @@ type NativeDatabase = {
   notify(event: string | BufferWithDataView, args?: any[]): boolean;
   get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer>, reject: RejectCallback, txnId?: number): number;
   getCount(options?: RangeOptions, txnId?: number): number;
-  getDBIntProperty(propertyName: string): number;
-  getDBProperty(propertyName: string): string;
+  getDBIntProperty(propertyName: string): number | undefined;
+  getDBProperty(propertyName: string): string | undefined;
   getMonotonicTimestamp(): number;
   getOldestSnapshotTimestamp(): number;
   getStat(statName: string): number | StatsHistogramData;
@@ -507,6 +560,7 @@ type NativeDatabase = {
   removeSync(key: BufferWithDataView, txnId?: number): void;
   setDefaultKeyBuffer(buffer: Buffer | Uint8Array | null): void;
   setDefaultValueBuffer(buffer: Buffer | Uint8Array | null): void;
+  setIteratorState(buffer: Buffer | Uint8Array): void;
   tryLock(key: BufferWithDataView, callback?: () => void): boolean;
   unlock(key: BufferWithDataView): void;
   useLog(name: string): TransactionLog;
@@ -514,6 +568,7 @@ type NativeDatabase = {
 };
 type RocksDatabaseConfig = {
   blockCacheSize?: number;
+  compactOnClose?: boolean;
 };
 type RegistryStatusDB = {
   path: string;
@@ -533,6 +588,14 @@ declare const constants: {
   TRANSACTION_LOG_TOKEN: number;
   TRANSACTION_LOG_ENTRY_HEADER_SIZE: number;
   TRANSACTION_LOG_FILE_HEADER_SIZE: number;
+  ITERATOR_REVERSE_FLAG: number;
+  ITERATOR_INCLUSIVE_END_FLAG: number;
+  ITERATOR_EXCLUSIVE_START_FLAG: number;
+  ITERATOR_INCLUDE_VALUES_FLAG: number;
+  ITERATOR_NEEDS_STABLE_VALUE_BUFFER_FLAG: number;
+  ITERATOR_CONTEXT_IS_TRANSACTION_FLAG: number;
+  ITERATOR_RESULT_DONE: number;
+  ITERATOR_RESULT_FAST: number;
 };
 declare const NativeDatabase: NativeDatabase;
 declare const NativeTransaction: NativeTransaction;
@@ -566,7 +629,7 @@ declare class Transaction extends DBI {
   * @param store - The base store interface for this transaction.
   * @param options - The options for the transaction.
   */
-  constructor(store: Store, options?: TransactionOptions);
+  constructor(store: Store, options?: NativeTransactionOptions);
   /**
   * Abort the transaction.
   */
@@ -922,6 +985,20 @@ interface RocksDatabaseOptions extends StoreOptions {
   */
   name?: string;
 }
+interface TransactionOptions extends NativeTransactionOptions {
+  /**
+  * The maximum number of times to retry the transaction.
+  *
+  * @default 3
+  */
+  maxRetries?: number;
+  /**
+  * Whether to retry the transaction if it fails with `IsBusy`.
+  *
+  * @default `true` when the transaction is bound to a transaction log, otherwise `false`
+  */
+  retryOnBusy?: boolean;
+}
 type RocksDBStat = number | StatsHistogramData;
 type RocksDBStats = Record<string, RocksDBStat>;
 /**
@@ -971,6 +1048,32 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   */
   close(): void;
   /**
+  * Compacts the entire key range of the database asynchronously.
+  * This triggers manual compaction which removes tombstones and reclaims space.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * await db.compact();
+  * ```
+  */
+  compact(options?: CompactOptions): Promise<void>;
+  /**
+  * Compacts the entire key range of the database synchronously.
+  * This triggers manual compaction which removes tombstones and reclaims space.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * db.compactSync();
+  * ```
+  */
+  compactSync(options?: CompactOptions): void;
+  /**
+  * Returns the list of column families in the RocksDB database.
+  */
+  get columns(): string[];
+  /**
   * Set global database settings.
   *
   * @param options - The options for the database.
@@ -1010,7 +1113,7 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * const numKeys = db.getDBIntProperty('rocksdb.estimate-num-keys');
   * ```
   */
-  getDBIntProperty(propertyName: string): number;
+  getDBIntProperty(propertyName: string): number | undefined;
   /**
   * Gets a RocksDB database property as a string.
   *
@@ -1024,7 +1127,18 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * const stats = db.getDBProperty('rocksdb.stats');
   * ```
   */
-  getDBProperty(propertyName: string): string;
+  getDBProperty(propertyName: string): string | undefined;
+  /**
+  * Retrieves the estimated number of keys in the database.
+  *
+  * @example
+  * ```typescript
+  * const db = RocksDatabase.open('/path/to/database');
+  * const estimated = db.getEstimatedKeyCount();
+  * console.log(estimated);
+  * ```
+  */
+  getEstimatedKeyCount(): number;
   /**
   * Returns the current timestamp as a monotonically increasing timestamp in
   * milliseconds represented as a decimal number.