@harperfast/rocksdb-js 2.9.0 → 2.10.0

package/dist/index.d.cts

@@ -551,10 +551,16 @@ export declare class Store {
   /**
    * The bytes of recent memtable history to retain in memory for transaction
    * conflict checking. `-1` derives the value from
-   * `maxWriteBufferNumber * writeBufferSize`, except under a stalling
-   * `writeBufferManager`, where it derives `0`: retained history is charged to
-   * that manager and is only trimmable down to this target, so a target the
-   * budget cannot hold stalls writes permanently. Set a number to size it
+   * `maxWriteBufferNumber * writeBufferSize`, except when a
+   * `writeBufferManager` is configured, where it derives `1`: retained history
+   * is charged to that manager and is only trimmable down to this target, so a
+   * target the budget cannot hold is memory the manager never reclaims, and
+   * stalls writes permanently when `writeBufferManagerAllowStall` is on. Any
+   * configured manager, not only a stalling one — that flag is mutable at
+   * runtime while this value is fixed when the family is created. `1`, not `0`, because
+   * RocksDB's transaction wrappers rewrite a `0` target to the derived value —
+   * so `0` asks for the largest history rather than none, and an explicit `0`
+   * is normalized to `1` for that reason. Set a positive number to size it
    * yourself against the budget and the column-family count.
    */
   maxWriteBufferSizeToMaintain?: number;
@@ -1372,6 +1378,7 @@ type StatsBasics = {
   "txnlog.replayGapBytes": number;
   "commitPipeline.logQueueDepth": number;
   "commitPipeline.commitQueueDepth": number;
+  "columnFamily.pendingReclaims": number;
   "writeBufferManager.bufferSize": number;
   "writeBufferManager.memoryUsage": number;
   "writeBufferManager.mutableMemoryUsage": number;
@@ -2214,7 +2221,7 @@ type NativeDatabase = {
   compactSync(start?: Key, end?: Key, bottommost?: boolean): void;
   columns: string[];
   createCheckpoint(resolve: ResolveCallback<void>, reject: RejectCallback, targetPath: string): void;
-  destroy(): void;
+  destroy(readOnly?: boolean): void;
   drop(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   dropSync(): void;
   flush(resolve: ResolveCallback<void>, reject: RejectCallback, options?: FlushOptions): void;
@@ -2249,6 +2256,7 @@ type NativeDatabase = {
   identityPath: string | undefined;
   listeners(event: string | BufferWithDataView): number;
   listLogs(): string[];
+  closing: boolean;
   opened: boolean;
   open(path: string, options?: NativeDatabaseOptions): void;
   populateVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): void;
@@ -2283,6 +2291,11 @@ type RocksDatabaseConfig = {
    */
   verificationTableEntries?: number;
   compactOnClose?: boolean;
+  /**
+   * Maximum seconds an open, destroy, or shutdown call waits for another
+   * lifecycle operation. Defaults to 30.
+   */
+  lifecycleWaitSeconds?: number;
   /**
    * Total memtable memory limit (bytes) shared across every database opened
    * in this process. When set, RocksDB uses a single `WriteBufferManager` so
@@ -2326,6 +2339,10 @@ type RegistryStatusTransaction = {
 };
 type RegistryStatusDB = {
   path: string;
+  closeError?: string;
+  /** A prior close failed and `shutdown()`/`destroy()` is currently retrying it. */
+  closeRetrying?: boolean;
+  destroyCleanupPending?: boolean;
   refCount: number;
   columnFamilies: string[];
   transactions: number;
@@ -2480,8 +2497,48 @@ declare const NativeDatabase: NativeDatabase;
 declare const NativeTransaction: NativeTransaction;
 export declare const TransactionLog: TransactionLog;
 export declare const registryStatus: () => RegistryStatus;
+/**
+ * Flushes every open database and waits for outstanding compactions, then
+ * releases the registry.
+ *
+ * **Throws** the first failure it encounters: a close whose native teardown
+ * failed (that descriptor stays quarantined — call `shutdown()` again to retry
+ * it), or a `lifecycleWaitSeconds` timeout waiting on a concurrent
+ * open/destroy/shutdown. A quarantining close also emits
+ * `database:closeFailed`; a timeout has no event, so the throw is its only
+ * signal.
+ *
+ * A `process.on('exit')` listener must therefore wrap it: an exception thrown
+ * from an `exit` listener skips every `exit` listener registered after it (and
+ * sets exit code 1 unless an `uncaughtException` handler is installed).
+ *
+ * ```typescript
+ * process.on('exit', () => {
+ * 	try {
+ * 		shutdown();
+ * 	} catch (error) {
+ * 		console.error('rocksdb-js shutdown failed', error);
+ * 	}
+ * });
+ * ```
+ */
 export declare const shutdown: () => void;
 export declare const currentThreadId: () => number;
+/**
+ * Reads the process-wide steady clock: `std::chrono::steady_clock` as
+ * fractional milliseconds from an unspecified origin that is fixed for the life
+ * of the process. Every sample in the process — main thread and every
+ * `worker_threads` worker, whenever started or restarted, on Node, Bun and Deno
+ * — is in one domain, and the difference between two samples is real elapsed
+ * time unaffected by wall-clock steps. Non-decreasing but not unique (two
+ * samples may be equal; treat `==` as "not later"). Windows QPC samples from
+ * different threads within one native tick also have ambiguous ordering.
+ * Clock readings alone do not prove causality. Not comparable with
+ * `Date.now()`, `db.getMonotonicTimestamp()` or transaction timestamps, and not
+ * meaningful across processes or restarts. Time spent in host suspend is
+ * platform-defined. No open database is needed.
+ */
+export declare const steadyClockNow: () => number;
 /**
  * Advises the kernel that the file-backed pages of every mapped transaction log
  * are cold (Linux MADV_COLD), so they are reclaimed first under memory pressure
@@ -2819,7 +2876,10 @@ export declare class RocksDatabase extends DBI<DBITransactional> {
    * native binding use namespaced keys (e.g. `'transactionLog:warning'`).
    *
    * Listeners are not tied to any specific database — they fire for every
-   * matching event emitted in this process.
+   * matching event emitted in this process. Native lifecycle failures use
+   * `'database:closeFailed'` with `(path, error)` string arguments. The event
+   * reports both completed and incomplete teardowns; an incomplete close can
+   * be retried by `shutdown()` or explicitly deleted by `destroy()`.
    *
    * @example
    * ```typescript

package/dist/index.d.mts

@@ -551,10 +551,16 @@ export declare class Store {
   /**
    * The bytes of recent memtable history to retain in memory for transaction
    * conflict checking. `-1` derives the value from
-   * `maxWriteBufferNumber * writeBufferSize`, except under a stalling
-   * `writeBufferManager`, where it derives `0`: retained history is charged to
-   * that manager and is only trimmable down to this target, so a target the
-   * budget cannot hold stalls writes permanently. Set a number to size it
+   * `maxWriteBufferNumber * writeBufferSize`, except when a
+   * `writeBufferManager` is configured, where it derives `1`: retained history
+   * is charged to that manager and is only trimmable down to this target, so a
+   * target the budget cannot hold is memory the manager never reclaims, and
+   * stalls writes permanently when `writeBufferManagerAllowStall` is on. Any
+   * configured manager, not only a stalling one — that flag is mutable at
+   * runtime while this value is fixed when the family is created. `1`, not `0`, because
+   * RocksDB's transaction wrappers rewrite a `0` target to the derived value —
+   * so `0` asks for the largest history rather than none, and an explicit `0`
+   * is normalized to `1` for that reason. Set a positive number to size it
    * yourself against the budget and the column-family count.
    */
   maxWriteBufferSizeToMaintain?: number;
@@ -1372,6 +1378,7 @@ type StatsBasics = {
   "txnlog.replayGapBytes": number;
   "commitPipeline.logQueueDepth": number;
   "commitPipeline.commitQueueDepth": number;
+  "columnFamily.pendingReclaims": number;
   "writeBufferManager.bufferSize": number;
   "writeBufferManager.memoryUsage": number;
   "writeBufferManager.mutableMemoryUsage": number;
@@ -2214,7 +2221,7 @@ type NativeDatabase = {
   compactSync(start?: Key, end?: Key, bottommost?: boolean): void;
   columns: string[];
   createCheckpoint(resolve: ResolveCallback<void>, reject: RejectCallback, targetPath: string): void;
-  destroy(): void;
+  destroy(readOnly?: boolean): void;
   drop(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   dropSync(): void;
   flush(resolve: ResolveCallback<void>, reject: RejectCallback, options?: FlushOptions): void;
@@ -2249,6 +2256,7 @@ type NativeDatabase = {
   identityPath: string | undefined;
   listeners(event: string | BufferWithDataView): number;
   listLogs(): string[];
+  closing: boolean;
   opened: boolean;
   open(path: string, options?: NativeDatabaseOptions): void;
   populateVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): void;
@@ -2283,6 +2291,11 @@ type RocksDatabaseConfig = {
    */
   verificationTableEntries?: number;
   compactOnClose?: boolean;
+  /**
+   * Maximum seconds an open, destroy, or shutdown call waits for another
+   * lifecycle operation. Defaults to 30.
+   */
+  lifecycleWaitSeconds?: number;
   /**
    * Total memtable memory limit (bytes) shared across every database opened
    * in this process. When set, RocksDB uses a single `WriteBufferManager` so
@@ -2326,6 +2339,10 @@ type RegistryStatusTransaction = {
 };
 type RegistryStatusDB = {
   path: string;
+  closeError?: string;
+  /** A prior close failed and `shutdown()`/`destroy()` is currently retrying it. */
+  closeRetrying?: boolean;
+  destroyCleanupPending?: boolean;
   refCount: number;
   columnFamilies: string[];
   transactions: number;
@@ -2480,8 +2497,48 @@ declare const NativeDatabase: NativeDatabase;
 declare const NativeTransaction: NativeTransaction;
 export declare const TransactionLog: TransactionLog;
 export declare const registryStatus: () => RegistryStatus;
+/**
+ * Flushes every open database and waits for outstanding compactions, then
+ * releases the registry.
+ *
+ * **Throws** the first failure it encounters: a close whose native teardown
+ * failed (that descriptor stays quarantined — call `shutdown()` again to retry
+ * it), or a `lifecycleWaitSeconds` timeout waiting on a concurrent
+ * open/destroy/shutdown. A quarantining close also emits
+ * `database:closeFailed`; a timeout has no event, so the throw is its only
+ * signal.
+ *
+ * A `process.on('exit')` listener must therefore wrap it: an exception thrown
+ * from an `exit` listener skips every `exit` listener registered after it (and
+ * sets exit code 1 unless an `uncaughtException` handler is installed).
+ *
+ * ```typescript
+ * process.on('exit', () => {
+ * 	try {
+ * 		shutdown();
+ * 	} catch (error) {
+ * 		console.error('rocksdb-js shutdown failed', error);
+ * 	}
+ * });
+ * ```
+ */
 export declare const shutdown: () => void;
 export declare const currentThreadId: () => number;
+/**
+ * Reads the process-wide steady clock: `std::chrono::steady_clock` as
+ * fractional milliseconds from an unspecified origin that is fixed for the life
+ * of the process. Every sample in the process — main thread and every
+ * `worker_threads` worker, whenever started or restarted, on Node, Bun and Deno
+ * — is in one domain, and the difference between two samples is real elapsed
+ * time unaffected by wall-clock steps. Non-decreasing but not unique (two
+ * samples may be equal; treat `==` as "not later"). Windows QPC samples from
+ * different threads within one native tick also have ambiguous ordering.
+ * Clock readings alone do not prove causality. Not comparable with
+ * `Date.now()`, `db.getMonotonicTimestamp()` or transaction timestamps, and not
+ * meaningful across processes or restarts. Time spent in host suspend is
+ * platform-defined. No open database is needed.
+ */
+export declare const steadyClockNow: () => number;
 /**
  * Advises the kernel that the file-backed pages of every mapped transaction log
  * are cold (Linux MADV_COLD), so they are reclaimed first under memory pressure
@@ -2819,7 +2876,10 @@ export declare class RocksDatabase extends DBI<DBITransactional> {
    * native binding use namespaced keys (e.g. `'transactionLog:warning'`).
    *
    * Listeners are not tied to any specific database — they fire for every
-   * matching event emitted in this process.
+   * matching event emitted in this process. Native lifecycle failures use
+   * `'database:closeFailed'` with `(path, error)` string arguments. The event
+   * reports both completed and incomplete teardowns; an incomplete close can
+   * be retried by `shutdown()` or explicitly deleted by `destroy()`.
    *
    * @example
    * ```typescript

package/dist/index.mjs

@@ -106,9 +106,49 @@ const NativeIterator = binding.Iterator;
 const NativeTransaction = binding.Transaction;
 const TransactionLog = binding.TransactionLog;
 const registryStatus = binding.registryStatus;
+/**
+* Flushes every open database and waits for outstanding compactions, then
+* releases the registry.
+*
+* **Throws** the first failure it encounters: a close whose native teardown
+* failed (that descriptor stays quarantined — call `shutdown()` again to retry
+* it), or a `lifecycleWaitSeconds` timeout waiting on a concurrent
+* open/destroy/shutdown. A quarantining close also emits
+* `database:closeFailed`; a timeout has no event, so the throw is its only
+* signal.
+*
+* A `process.on('exit')` listener must therefore wrap it: an exception thrown
+* from an `exit` listener skips every `exit` listener registered after it (and
+* sets exit code 1 unless an `uncaughtException` handler is installed).
+*
+* ```typescript
+* process.on('exit', () => {
+* 	try {
+* 		shutdown();
+* 	} catch (error) {
+* 		console.error('rocksdb-js shutdown failed', error);
+* 	}
+* });
+* ```
+*/
 const shutdown = binding.shutdown;
 const currentThreadId = binding.currentThreadId;
 /**
+* Reads the process-wide steady clock: `std::chrono::steady_clock` as
+* fractional milliseconds from an unspecified origin that is fixed for the life
+* of the process. Every sample in the process — main thread and every
+* `worker_threads` worker, whenever started or restarted, on Node, Bun and Deno
+* — is in one domain, and the difference between two samples is real elapsed
+* time unaffected by wall-clock steps. Non-decreasing but not unique (two
+* samples may be equal; treat `==` as "not later"). Windows QPC samples from
+* different threads within one native tick also have ambiguous ordering.
+* Clock readings alone do not prove causality. Not comparable with
+* `Date.now()`, `db.getMonotonicTimestamp()` or transaction timestamps, and not
+* meaningful across processes or restarts. Time spent in host suspend is
+* platform-defined. No open database is needed.
+*/
+const steadyClockNow = binding.steadyClockNow;
+/**
 * Advises the kernel that the file-backed pages of every mapped transaction log
 * are cold (Linux MADV_COLD), so they are reclaimed first under memory pressure
 * without being freed — useful during replication catch-up, where a full read of
@@ -134,6 +174,21 @@ const transactionLogMapCount = binding.transactionLogMapCount;
 * disarm. Used by the ERR_TRY_AGAIN retry regression test.
 */
 const forceTryAgainForTesting = binding.forceTryAgainForTesting;
+/**
+* Test-only seam: makes the physical column-family drop report failure.
+* `0` = inert, `1` = fail without dropping (the retry performs the drop),
+* `2` = drop for real and then report failure (the retry resolves as
+* "already dropped"). Process-global, like `forceTryAgainForTesting`.
+*/
+const forceDropFailureForTesting = binding.forceDropFailureForTesting;
+/** Parks one selected transaction write after its retirement precheck. */
+const setTransactionStagingDelayForTesting = binding.setTransactionStagingDelayForTesting;
+/** Reports whether the selected transaction write is parked. */
+const isTransactionStagingDelayedForTesting = binding.isTransactionStagingDelayedForTesting;
+/** Reports whether a transaction is parked at the native commit seam. */
+const isTransactionCommitExecuteDelayedForTesting = binding.isTransactionCommitExecuteDelayedForTesting;
+const setTransactionCommitAdmissionDelayForTesting = binding.setTransactionCommitAdmissionDelayForTesting;
+const isTransactionCommitAdmissionDelayedForTesting = binding.isTransactionCommitAdmissionDelayedForTesting;
 /** Delays one selected watchdog join in the concurrent-shutdown regression test. */
 const setWriteBufferManagerJoinDelayForTesting = binding.setWriteBufferManagerJoinDelayForTesting;
 /**
@@ -1268,7 +1323,15 @@ var DBIterator = class {
 			this.iterator.return?.();
 			return DONE_RESULT;
 		}
-		const result = this.iterator.next();
+		let result;
+		try {
+			result = this.iterator.next();
+		} catch (err) {
+			try {
+				this.iterator.return?.();
+			} catch {}
+			throw err;
+		}
 		if (result === ITERATOR_RESULT_DONE) return DONE_RESULT;
 		this.#yielded++;
 		const includeValues = this.#includeValues;
@@ -1546,10 +1609,16 @@ var Store = class {
 	/**
 	* The bytes of recent memtable history to retain in memory for transaction
 	* conflict checking. `-1` derives the value from
-	* `maxWriteBufferNumber * writeBufferSize`, except under a stalling
-	* `writeBufferManager`, where it derives `0`: retained history is charged to
-	* that manager and is only trimmable down to this target, so a target the
-	* budget cannot hold stalls writes permanently. Set a number to size it
+	* `maxWriteBufferNumber * writeBufferSize`, except when a
+	* `writeBufferManager` is configured, where it derives `1`: retained history
+	* is charged to that manager and is only trimmable down to this target, so a
+	* target the budget cannot hold is memory the manager never reclaims, and
+	* stalls writes permanently when `writeBufferManagerAllowStall` is on. Any
+	* configured manager, not only a stalling one — that flag is mutable at
+	* runtime while this value is fixed when the family is created. `1`, not `0`, because
+	* RocksDB's transaction wrappers rewrite a `0` target to the derived value —
+	* so `0` asks for the largest history rather than none, and an explicit `0`
+	* is normalized to `1` for that reason. Set a positive number to size it
 	* yourself against the budget and the column-family count.
 	*/
 	maxWriteBufferSizeToMaintain;
@@ -2080,12 +2149,12 @@ var Store = class {
 		return false;
 	}
 	putSync(context, key, value, options) {
-		if (!this.db.opened) throw new Error("Database not open");
+		if (!this.db.opened) throw new Error(this.db.closing ? "Database is closing" : "Database not open");
 		const valueBuffer = this.encodeValue(value);
 		context.putSync(this.encodeKey(key), valueBuffer, this.getTxnId(options));
 	}
 	removeSync(context, key, options) {
-		if (!this.db.opened) throw new Error("Database not open");
+		if (!this.db.opened) throw new Error(this.db.closing ? "Database is closing" : "Database not open");
 		context.removeSync(this.encodeKey(key), this.getTxnId(options));
 	}
 	/**
@@ -2589,7 +2658,10 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	* native binding use namespaced keys (e.g. `'transactionLog:warning'`).
 	*
 	* Listeners are not tied to any specific database — they fire for every
-	* matching event emitted in this process.
+	* matching event emitted in this process. Native lifecycle failures use
+	* `'database:closeFailed'` with `(path, error)` string arguments. The event
+	* reports both completed and incomplete teardowns; an incomplete close can
+	* be retried by `shutdown()` or explicitly deleted by `destroy()`.
 	*
 	* @example
 	* ```typescript
@@ -2673,7 +2745,7 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		this.store.db.catchUpWithPrimarySync();
 	}
 	destroy() {
-		this.store.db.destroy();
+		this.store.db.destroy(this.store.readOnly);
 	}
 	async drop() {
 		return new Promise((resolve, reject) => {
@@ -3539,8 +3611,8 @@ function frameFits(dataView, pos, dataEnd) {
 * terminator, let a chain "end" anywhere in megabytes of padding. Against the written extent the
 * end is a single offset, so a chain landing on it is ~1/2^32 to be coincidence.
 *
-* The JS counterpart of `validFramingResumes()` in `transaction_log_recovery.cpp`, which answers
-* the same question at open time but keeps only the yes/no, discarding the offset.
+* The JS counterpart of `findFramingResumeOffset()` in `transaction_log_recovery.cpp`, which the
+* open-time scan and the timestamp index use to keep walking past the same break.
 */
 function findResyncPosition(dataView, from, dataEnd) {
 	const lastStart = dataEnd - TRANSACTION_LOG_ENTRY_HEADER_SIZE;
@@ -3764,9 +3836,9 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.9.0"
+	"rocksdb-js": "2.10.0"
 };
 
 //#endregion
-export { BackgroundError, CorruptFrameError, CountEstimator, DBI, DBIterator, RocksDatabase, Store, Transaction, TransactionLog, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, getWriteBufferManagerStats, parseTransactionLog, registryStatus, shutdown, stats, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
+export { BackgroundError, CorruptFrameError, CountEstimator, DBI, DBIterator, RocksDatabase, Store, Transaction, TransactionLog, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, getWriteBufferManagerStats, parseTransactionLog, registryStatus, shutdown, stats, steadyClockNow, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
 //# sourceMappingURL=index.mjs.map