@harperfast/rocksdb-js 1.0.1 → 1.1.1

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;
@@ -75,6 +76,11 @@ interface StoreOptions extends Omit<NativeDatabaseOptions, "mode" | "transaction
   * If `true`, the encoder will use a random access structure.
   */
   randomAccessStructure?: boolean;
+  /**
+  * When `true`, the database is opened in read-only mode. Write operations
+  * will throw an error with code `ERR_DATABASE_READONLY`.
+  */
+  readOnly?: boolean;
   sharedStructuresKey?: symbol;
   /**
   * A string containing the amount of time or the number of milliseconds to
@@ -180,6 +186,11 @@ declare class Store {
   */
   pessimistic: boolean;
   /**
+  * Whether the database is open in readonly mode. When `true`, write
+  * operations will throw an error with code `ERR_DATABASE_READONLY`.
+  */
+  readOnly: boolean;
+  /**
   * Encoder specific flag used to signal that the encoder should use a random
   * access structure.
   */
@@ -362,29 +373,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;
@@ -416,7 +415,7 @@ type TransactionEntry = {
   endTxn: boolean;
 };
 type TransactionLog = {
-  new (name: string): TransactionLog;
+  new (db: NativeDatabase, name: string): TransactionLog;
   addEntry(data: Buffer | Uint8Array, txnId?: number): void;
   getLogFileSize(sequenceId?: number): number;
   name: string;
@@ -438,6 +437,7 @@ type NativeDatabaseOptions = {
   name?: string;
   noBlockCache?: boolean;
   parallelismThreads?: number;
+  readOnly?: boolean;
   statsLevel?: (typeof stats.StatsLevel)[keyof typeof stats.StatsLevel];
   transactionLogMaxAgeThreshold?: number;
   transactionLogMaxSize?: number;
@@ -469,6 +469,7 @@ type NativeDatabase = {
   clear(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   clearSync(): void;
   close(): void;
+  columns: string[];
   destroy(): void;
   drop(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   dropSync(): void;
@@ -477,8 +478,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;
@@ -555,7 +556,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.
   */
@@ -911,6 +912,22 @@ 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>;
 /**
 * The main class for interacting with a RocksDB database.
 *
@@ -958,6 +975,10 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   */
   close(): 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.
@@ -997,7 +1018,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.
   *
@@ -1011,7 +1032,7 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * const stats = db.getDBProperty('rocksdb.stats');
   * ```
   */
-  getDBProperty(propertyName: string): string;
+  getDBProperty(propertyName: string): string | undefined;
   /**
   * Returns the current timestamp as a monotonically increasing timestamp in
   * milliseconds represented as a decimal number.
@@ -1032,7 +1053,7 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * @param statName - The name of the statistic to retrieve.
   * @returns The statistic value.
   */
-  getStat(statName: string): number | StatsHistogramData;
+  getStat(statName: string): RocksDBStat;
   /**
   * Gets the RocksDB statistics. Requires statistics to be enabled.
   *
@@ -1042,7 +1063,7 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * const stats = db.getStats();
   * ```
   */
-  getStats(all?: boolean): Record<string, number | StatsHistogramData>;
+  getStats(all?: boolean): RocksDBStats;
   /**
   * Gets or creates a buffer that can be shared across worker threads.
   *
@@ -1096,6 +1117,10 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   */
   get name(): string;
   /**
+  * Whether the database is open in readonly mode.
+  */
+  get readOnly(): boolean;
+  /**
   * Sugar method for opening a database.
   *
   * @param pathOrStore - The filesystem path to the database or a custom store.
@@ -1246,5 +1271,5 @@ declare const versions: {
   "rocksdb-js": string;
 };
 //#endregion
-export { DBI, DBIterator, type IteratorOptions, type Key, RocksDatabase, type RocksDatabaseOptions, type StatsHistogramData, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
+export { DBI, DBIterator, type IteratorOptions, type Key, type RocksDBStat, type RocksDBStats, RocksDatabase, type RocksDatabaseOptions, type StatsHistogramData, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
 //# sourceMappingURL=index.d.cts.map

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;
@@ -75,6 +76,11 @@ interface StoreOptions extends Omit<NativeDatabaseOptions, "mode" | "transaction
   * If `true`, the encoder will use a random access structure.
   */
   randomAccessStructure?: boolean;
+  /**
+  * When `true`, the database is opened in read-only mode. Write operations
+  * will throw an error with code `ERR_DATABASE_READONLY`.
+  */
+  readOnly?: boolean;
   sharedStructuresKey?: symbol;
   /**
   * A string containing the amount of time or the number of milliseconds to
@@ -180,6 +186,11 @@ declare class Store {
   */
   pessimistic: boolean;
   /**
+  * Whether the database is open in readonly mode. When `true`, write
+  * operations will throw an error with code `ERR_DATABASE_READONLY`.
+  */
+  readOnly: boolean;
+  /**
   * Encoder specific flag used to signal that the encoder should use a random
   * access structure.
   */
@@ -362,29 +373,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;
@@ -416,7 +415,7 @@ type TransactionEntry = {
   endTxn: boolean;
 };
 type TransactionLog = {
-  new (name: string): TransactionLog;
+  new (db: NativeDatabase, name: string): TransactionLog;
   addEntry(data: Buffer | Uint8Array, txnId?: number): void;
   getLogFileSize(sequenceId?: number): number;
   name: string;
@@ -438,6 +437,7 @@ type NativeDatabaseOptions = {
   name?: string;
   noBlockCache?: boolean;
   parallelismThreads?: number;
+  readOnly?: boolean;
   statsLevel?: (typeof stats.StatsLevel)[keyof typeof stats.StatsLevel];
   transactionLogMaxAgeThreshold?: number;
   transactionLogMaxSize?: number;
@@ -469,6 +469,7 @@ type NativeDatabase = {
   clear(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   clearSync(): void;
   close(): void;
+  columns: string[];
   destroy(): void;
   drop(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   dropSync(): void;
@@ -477,8 +478,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;
@@ -555,7 +556,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.
   */
@@ -911,6 +912,22 @@ 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>;
 /**
 * The main class for interacting with a RocksDB database.
 *
@@ -958,6 +975,10 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   */
   close(): 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.
@@ -997,7 +1018,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.
   *
@@ -1011,7 +1032,7 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * const stats = db.getDBProperty('rocksdb.stats');
   * ```
   */
-  getDBProperty(propertyName: string): string;
+  getDBProperty(propertyName: string): string | undefined;
   /**
   * Returns the current timestamp as a monotonically increasing timestamp in
   * milliseconds represented as a decimal number.
@@ -1032,7 +1053,7 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * @param statName - The name of the statistic to retrieve.
   * @returns The statistic value.
   */
-  getStat(statName: string): number | StatsHistogramData;
+  getStat(statName: string): RocksDBStat;
   /**
   * Gets the RocksDB statistics. Requires statistics to be enabled.
   *
@@ -1042,7 +1063,7 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   * const stats = db.getStats();
   * ```
   */
-  getStats(all?: boolean): Record<string, number | StatsHistogramData>;
+  getStats(all?: boolean): RocksDBStats;
   /**
   * Gets or creates a buffer that can be shared across worker threads.
   *
@@ -1096,6 +1117,10 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   */
   get name(): string;
   /**
+  * Whether the database is open in readonly mode.
+  */
+  get readOnly(): boolean;
+  /**
   * Sugar method for opening a database.
   *
   * @param pathOrStore - The filesystem path to the database or a custom store.
@@ -1246,5 +1271,5 @@ declare const versions: {
   "rocksdb-js": string;
 };
 //#endregion
-export { DBI, DBIterator, type IteratorOptions, type Key, RocksDatabase, type RocksDatabaseOptions, type StatsHistogramData, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
+export { DBI, DBIterator, type IteratorOptions, type Key, type RocksDBStat, type RocksDBStats, RocksDatabase, type RocksDatabaseOptions, type StatsHistogramData, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -629,6 +629,11 @@ var Store = class {
 	*/
 	pessimistic;
 	/**
+	* Whether the database is open in readonly mode. When `true`, write
+	* operations will throw an error with code `ERR_DATABASE_READONLY`.
+	*/
+	readOnly;
+	/**
 	* Encoder specific flag used to signal that the encoder should use a random
 	* access structure.
 	*/
@@ -697,6 +702,7 @@ var Store = class {
 		this.parallelismThreads = options?.parallelismThreads ?? 1;
 		this.path = path;
 		this.pessimistic = options?.pessimistic ?? false;
+		this.readOnly = options?.readOnly ?? false;
 		this.randomAccessStructure = options?.randomAccessStructure ?? false;
 		this.readKey = readKey;
 		this.sharedStructuresKey = options?.sharedStructuresKey;
@@ -767,6 +773,7 @@ var Store = class {
 		const keyParam = getKeyParam(this.encodeKey(key));
 		let flags = 0;
 		if (alwaysCreateNewBuffer) flags |= ALWAYS_CREATE_NEW_BUFFER_FLAG;
+		if (this.readOnly) txnId = void 0;
 		const result = context.getSync(keyParam, flags | ONLY_IF_IN_MEMORY_CACHE_FLAG, txnId);
 		if (typeof result === "number") {
 			if (result === NOT_IN_MEMORY_CACHE_FLAG) return new Promise((resolve, reject) => {
@@ -839,7 +846,7 @@ var Store = class {
 	*/
 	getTxnId(options) {
 		let txnId;
-		if (options?.transaction) {
+		if (!this.readOnly && options?.transaction) {
 			txnId = options.transaction.id;
 			if (txnId === void 0) throw new TypeError("Invalid transaction");
 		}
@@ -907,6 +914,7 @@ var Store = class {
 			name: this.name,
 			noBlockCache: this.noBlockCache,
 			parallelismThreads: this.parallelismThreads,
+			readOnly: this.readOnly,
 			statsLevel: this.statsLevel,
 			transactionLogMaxAgeThreshold: this.transactionLogMaxAgeThreshold,
 			transactionLogMaxSize: this.transactionLogMaxSize,
@@ -1022,9 +1030,17 @@ var Transaction = class extends DBI {
 	* @param options - The options for the transaction.
 	*/
 	constructor(store, options) {
-		const txn = new NativeTransaction(store.db, options);
-		super(store, txn);
-		this.#txn = txn;
+		if (store.readOnly) {
+			super(store);
+			this.#txn = { id: 0 };
+			this.abort = this.commitSync = this.setTimestamp = () => {};
+			this.commit = async () => {};
+			this.getTimestamp = () => 0;
+		} else {
+			const txn = new NativeTransaction(store.db, options);
+			super(store, txn);
+			this.#txn = txn;
+		}
 	}
 	/**
 	* Abort the transaction.
@@ -1178,6 +1194,12 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		this.store.close();
 	}
 	/**
+	* Returns the list of column families in the RocksDB database.
+	*/
+	get columns() {
+		return this.store.db.columns;
+	}
+	/**
 	* Set global database settings.
 	*
 	* @param options - The options for the database.
@@ -1354,6 +1376,12 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.#name;
 	}
 	/**
+	* Whether the database is open in readonly mode.
+	*/
+	get readOnly() {
+		return this.store.readOnly;
+	}
+	/**
 	* Sugar method for opening a database.
 	*
 	* @param pathOrStore - The filesystem path to the database or a custom store.
@@ -1415,14 +1443,14 @@ var RocksDatabase = class RocksDatabase extends DBI {
 					return buffer && store.decoder?.decode ? store.decoder.decode(buffer) : void 0;
 				};
 				opts.saveStructures = (structures, isCompatible) => {
-					return this.transactionSync((txn) => {
+					return this.transactionSync((txn, _attempt) => {
 						const existingStructuresBuffer = this.getBinarySync(sharedStructuresKey);
 						const existingStructures = existingStructuresBuffer && store.decoder?.decode ? store.decoder.decode(existingStructuresBuffer) : void 0;
 						if (typeof isCompatible == "function") {
 							if (!isCompatible(existingStructures)) return false;
 						} else if (existingStructures && existingStructures.length !== isCompatible) return false;
 						txn.putSync(sharedStructuresKey, structures);
-					});
+					}, { retryOnBusy: true });
 				};
 			}
 			store.encoder = new EncoderClass({
@@ -1439,16 +1467,15 @@ var RocksDatabase = class RocksDatabase extends DBI {
 			};
 			store.decoder = store.encoder;
 		}
-		if (typeof store.encoder?.writeKey === "function" && !store.encoder?.encode) {
-			store.encoder = {
-				...store.encoder,
-				encode: (value, _mode) => {
-					const bytesWritten = store.writeKey(value, store.encodeBuffer, 0);
-					return store.encodeBuffer.subarray(0, bytesWritten);
-				}
-			};
-			store.encoder.copyBuffers = true;
-		}
+		if (typeof store.encoder?.writeKey === "function" && !store.encoder?.encode) store.encoder = {
+			...store.encoder,
+			encode: (value, _mode) => {
+				const bytesWritten = store.writeKey(value, store.encodeBuffer, 0);
+				return store.encodeBuffer.subarray(0, bytesWritten);
+			},
+			copyBuffers: true
+		};
+		if (store.encoder) store.encoder.name = this.#name;
 		if (store.decoder && store.decoder.needsStableBuffer !== true) store.decoderCopies = true;
 		if (store.decoder?.readKey && !store.decoder.decode) {
 			store.decoder.decode = (buffer) => {
@@ -1884,7 +1911,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "1.0.1"
+	"rocksdb-js": "1.1.1"
 };
 
 //#endregion