@harperfast/harper 5.2.9 → 5.3.0-alpha.1

package/resources/LMDBTransaction.ts

@@ -1,11 +1,13 @@
 import {
 	DatabaseTransaction,
+	shouldSpareCommitPhase,
 	transactionOpenTooLongError,
 	type CommitOptions,
 	type TransactionWrite,
 	type CommitResolution,
 } from './DatabaseTransaction';
 import { cleanupUnusedBlobs, collectRetainedFileIds } from './blob.ts';
+import { ServerError } from '../utility/errors/hdbError.ts';
 import { getNextMonotonicTime } from '../utility/lmdb/commonUtility.ts';
 import * as harperLogger from '../utility/logging/harper_logger.ts';
 import type { Context } from './ResourceInterface.ts';
@@ -38,7 +40,7 @@ export class LMDBTransaction extends DatabaseTransaction {
 	getReadTxn(): any {
 		// used optimistically
 		this.readTxnRefCount = (this.readTxnRefCount || 0) + 1;
-		this.timeout = txnExpiration; // reset the timeout
+		this.timeout = Math.max(txnExpiration, this.timeoutBudget ?? 0); // reset the timeout
 		if (this.stale) this.stale = false;
 		if (this.readTxn) {
 			if ((this.readTxn as any).openTimer) (this.readTxn as any).openTimer = 0;
@@ -153,6 +155,9 @@ export class LMDBTransaction extends DatabaseTransaction {
 				// source writes will finish (with right to refuse/abort) before proceeeding to less
 				// canonical sources.
 				if (hasBefore) {
+					// see `committing` in DatabaseTransaction (issue #2062)
+					this.setCommitPhase(true);
+					const stagedWrites = this.writes.length;
 					return (async () => {
 						try {
 							for (let phase = 0; phase < 2; phase++) {
@@ -172,9 +177,15 @@ export class LMDBTransaction extends DatabaseTransaction {
 								if (completion) await (completion.push ? Promise.all(completion) : completion);
 							}
 						} catch (error) {
+							this.setCommitPhase(false);
 							this.abort();
 							throw error;
 						}
+						this.setCommitPhase(false);
+						// aborted underneath us while parked above — see DatabaseTransaction's twin guard
+						if (this.timedOut) throw transactionOpenTooLongError();
+						if (stagedWrites > 0 && this.writes.length === 0 && this.open === TRANSACTION_STATE.CLOSED)
+							throw new ServerError('Transaction was aborted while its commit was waiting on pre-commit work', 500);
 						return this.commit(options);
 					})();
 				}
@@ -372,10 +383,21 @@ let timer;
 
 function startMonitoringTxns() {
 	timer = setInterval(function () {
+		const checkedCommitPhaseChains = new Set<DatabaseTransaction>();
 		for (const txn of trackedTxns) {
+			const commitChainHead = txn.commitChainHead ?? txn;
 			if (txn.timeout <= 0) {
 				const url = (txn.getContext() as any)?.url;
-				if (txn.hasPendingWrites() && !txn.sourceApply && !txn.isReplay) {
+				if (shouldSpareCommitPhase(txn, checkedCommitPhaseChains)) {
+					// see DatabaseTransaction's monitor (issue #2062)
+					harperLogger.warn?.(
+						`Transaction has been in its commit phase past the open-transaction limit, waiting on pre-commit work (e.g. a large blob write); letting it complete, from table: ${
+							(txn.db as any)?.name + (url ? ' path: ' + url : '')
+						}`,
+						...(txn.startedFrom ? [`was started from ${txn.startedFrom.resourceName}.${txn.startedFrom.method}`] : [])
+					);
+					txn.timeout = Math.max(txnExpiration, txn.timeoutBudget ?? 0);
+				} else if (txn.hasPendingWrites() && !txn.sourceApply && !txn.isReplay) {
 					// Abort and surface an error rather than force-committing a partial write set: silently
 					// committing on the application's behalf breaks atomicity and can leave orphaned
 					// secondary-index entries that only a full index rebuild repairs (issue #1407). The app
@@ -390,7 +412,7 @@ function startMonitoringTxns() {
 						}`
 					);
 					try {
-						txn.abortDueToTimeout();
+						commitChainHead.abortDueToTimeout();
 					} catch (error) {
 						harperLogger.debug?.(`Error aborting timed out transaction: ${error.message}`);
 					}
@@ -408,7 +430,7 @@ function startMonitoringTxns() {
 					} catch (error) {
 						harperLogger.debug?.(`Error committing timed out transaction: ${error.message}`);
 					}
-					txn.timeout = txnExpiration;
+					txn.timeout = Math.max(txnExpiration, txn.timeoutBudget ?? 0);
 				}
 			} else {
 				txn.timeout -= txnExpiration;

package/resources/PrimaryRocksDatabase.ts

@@ -1,4 +1,4 @@
-import { RocksDatabase, type RocksDatabaseOptions, constants, type Store } from '@harperfast/rocksdb-js';
+import { RocksDatabase, type RocksDatabaseOptions, constants, type Store, Transaction } from '@harperfast/rocksdb-js';
 
 const FRESH_VERSION_FLAG = constants.FRESH_VERSION_FLAG;
 import { WeakLRUCache } from 'weak-lru-cache';
@@ -41,6 +41,33 @@ export class PrimaryRocksDatabase extends RocksDatabase {
 		}
 	}
 
+	// Match LMDB's remove(key, version) contract without splitting the version check from the delete.
+	async removeIfVersion(id: any, version: number): Promise<boolean> {
+		let retried = false;
+		while (true) {
+			let transaction: Transaction | undefined;
+			try {
+				transaction = new Transaction(this.store);
+				const entry = this.#processEntry(super.getSync(id, { transaction }), id);
+				if (!entry || entry.version !== version) {
+					transaction.abort();
+					return false;
+				}
+				this.#cache?.delete(id);
+				super.removeSync(id, { transaction });
+				await transaction.commit();
+				return true;
+			} catch (error: any) {
+				try {
+					transaction?.abort();
+				} catch {}
+				// rocksdb-js reports a writer that committed between our read and our commit as ERR_BUSY
+				if (retried || error?.code !== 'ERR_BUSY') throw error;
+				retried = true;
+			}
+		}
+	}
+
 	/**
 	 * Initialises encoder/decoder state. Must be called once after open() with the root
 	 * RocksDatabase. Equivalent to the RocksDB branch of handleLocalTimeForGets, but as

package/resources/RecordEncoder.ts

@@ -42,6 +42,33 @@ const StructonEncoder = createStructon(Encoder) as typeof Encoder;
 // monitoring; the store name is passed as the metric path.
 const MISSING_STRUCTURE_METRIC = 'decode-missing-structure';
 
+// Reaching this bound is not an error: novel shapes fall back to plain msgpackr encoding, which
+// round-trips correctly but gives up random-access field reads.
+export const DEFAULT_MAX_TYPED_STRUCTURES = 256;
+
+export interface StructureCounts {
+	typed: number;
+	classic: number;
+	typedLimit: number;
+	typedEnabled: boolean;
+}
+
+// Mirrors structon's onLoadedStructures over the four durable payload shapes it accepts. The
+// bare-array and cbor-x forms carry named structures only; structon keeps the encoder's own typed
+// dictionary for them, and they are written by the capped fallback path (msgpackr's base save
+// overwriting the combined payload, before structon's best-effort re-save). That window is by
+// definition a saturated store, so reporting zero there would show an empty dictionary at the one
+// moment the count matters most.
+function countDurableStructures(sharedData: any, localTyped: number): { typed: number; classic: number } {
+	if (!sharedData) return { typed: 0, classic: 0 };
+	if (sharedData instanceof Map)
+		return { typed: sharedData.get('typed')?.length ?? 0, classic: sharedData.get('named')?.length ?? 0 };
+	if (Array.isArray(sharedData)) return { typed: localTyped, classic: sharedData.length };
+	if (!sharedData.named && !sharedData.typed && Array.isArray(sharedData.structures))
+		return { typed: localTyped, classic: sharedData.structures.length };
+	return { typed: sharedData.typed?.length ?? 0, classic: sharedData.named?.length ?? 0 };
+}
+
 // Terminal error messages msgpackr/structon throw when a record references a shared structure that
 // is not in this node's structures buffer. Both the typed (random-access) path (structon's
 // readStruct) and the classic path (msgpackr's createSecondByteReader) reload the structures from
@@ -77,6 +104,8 @@ export type Entry = {
 export const TIMESTAMP_PLACEHOLDER = new Uint8Array([1, 1, 1, 1, 4, 0x40, 0, 0]);
 // the first byte here indicates that we use the last timestamp
 export const LAST_TIMESTAMP_PLACEHOLDER = new Uint8Array([1, 1, 1, 1, 1, 0, 0, 0]);
+// Never write this into an audit entry value: the substitution resolves to 2.0 when no previous time
+// was recorded, and the audit format reads a leading byte other than 0x42 as "no field here". See harper#2247.
 export const PREVIOUS_TIMESTAMP_PLACEHOLDER = new Uint8Array([1, 1, 1, 1, 3, 0x40, 0, 0]);
 export const NEW_TIMESTAMP_PLACEHOLDER = new Uint8Array([1, 1, 1, 1, 0, 0x40, 0, 0]);
 export const LOCAL_TIMESTAMP = Symbol('local-timestamp');
@@ -95,6 +124,7 @@ export const HAS_NODE_ID = 64;
 export const PENDING_LOCAL_TIME = 1;
 export const HAS_STRUCTURE_UPDATE = 0x100;
 export const HAS_ADDITIONAL_AUDIT_REFS = 0x80;
+export const VERSION_NOT_UNIQUE_FLAG = 0x10000;
 
 const TRACKED_WRITE_TYPES = new Set(['put', 'patch', 'delete', 'message', 'publish']);
 // For now we use this as the private property mechanism for mapping records to entries.
@@ -197,6 +227,10 @@ export class RecordEncoder extends StructonEncoder {
 	declare saveStructures: any;
 	declare getStructures: any;
 	declare _writeStruct: any;
+	declare typedStructs: any[];
+	declare structures: any[];
+	declare maxOwnStructures: number;
+	randomAccessStructure = false;
 	structureUpdate?: any;
 	// Set by TableResource.updatedAttributes. Undefined for a store with no resolved attributes, which
 	// is what keeps the projection off that store's writes entirely.
@@ -217,7 +251,7 @@ export class RecordEncoder extends StructonEncoder {
 		// Bound the per-encoder typed-structure dictionary. It is append-only and pinned on the
 		// long-lived primary store, so a wide/sparse schema (whose records vary by per-field value
 		// width) can grow it unbounded and exhaust memory. Caller-overridable; default caps it.
-		options.maxOwnStructures ??= 256;
+		options.maxOwnStructures ??= DEFAULT_MAX_TYPED_STRUCTURES;
 		/**
 		 * The base class for records that provides the read-only methods for accessing
 		 * metadata and will be assigned computed property getters. On its own, these instances
@@ -233,6 +267,7 @@ export class RecordEncoder extends StructonEncoder {
 		// (e.g. __dbis__, useVersions=false) must not — see the encode hook + harper#1307. Default to
 		// true when unspecified so an option that doesn't propagate can't silently strip prefixes.
 		this.useVersions = options.useVersions !== false;
+		this.randomAccessStructure = options.randomAccessStructure === true;
 		// structon (the StructonEncoder base) always installs the struct write hook. For DBIs
 		// that don't opt into struct mode (non-primary, e.g. __dbis__), force it to bail (return
 		// 0) so objects are written in plain msgpackr records mode — decodable by readers without
@@ -417,12 +452,14 @@ export class RecordEncoder extends StructonEncoder {
 				// HAS_STRUCTURE_UPDATE in the audit log for a structure that was never persisted.
 				if (committed === true) {
 					this.structureUpdate = structures;
+					this.checkStructureCapacity();
 					return true;
 				}
 				return false;
 			} else {
 				const result = superSaveStructures.call(this, structures, isCompatible);
 				this.structureUpdate = structures;
+				if (result !== false) this.checkStructureCapacity();
 				return result;
 			}
 		};
@@ -432,10 +469,51 @@ export class RecordEncoder extends StructonEncoder {
 				const buffer = this.rootStore.getBinarySync(sharedStructuresKey);
 				return buffer ? this.decode(buffer) : undefined;
 			} else {
-				return superGetStructures.call(this);
+				// msgpackr only defines getStructures when the option was supplied; a store with no
+				// shared-structures mechanism has no durable dictionary to report.
+				return superGetStructures?.call(this);
 			}
 		};
 	}
+	/**
+	 * Sizes of this store's record-structure dictionaries. Read from the durable payload, not this
+	 * encoder's arrays: each worker owns an encoder and loads lazily, so a worker that never encoded
+	 * for this store holds empty arrays for a store whose dictionary is full.
+	 */
+	getStructureCounts(): StructureCounts {
+		const { typed, classic } = countDurableStructures(this.getStructures(), this.typedStructs?.length ?? 0);
+		return {
+			typed,
+			classic,
+			typedLimit: this.maxOwnStructures ?? DEFAULT_MAX_TYPED_STRUCTURES,
+			typedEnabled: this.randomAccessStructure,
+		};
+	}
+	/**
+	 * Warn once per encoder when its typed dictionary is at the bound. Fires from the post-save path,
+	 * so it needs some structure save to happen -- any save, including a classic one -- and it needs
+	 * this encoder to have loaded the dictionary. Several workers can therefore each warn for one
+	 * table, and a worker that never saves after loading a full dictionary stays silent. The counts
+	 * above are the reliable signal; this is the heads-up. It must not escape into the save's return
+	 * value -- the structures are committed.
+	 */
+	#reportedStructureSaturation = false;
+	checkStructureCapacity() {
+		if (this.#reportedStructureSaturation) return;
+		const typedLimit = this.maxOwnStructures ?? DEFAULT_MAX_TYPED_STRUCTURES;
+		if ((this.typedStructs?.length ?? 0) < typedLimit) return;
+		this.#reportedStructureSaturation = true;
+		try {
+			harperLogger.warn(
+				`Typed-structure dictionary for store ${this.name ?? this.rootStore?.name ?? '(unnamed)'} reached its limit of ` +
+					`${typedLimit} structures; new record shapes will be stored without random-access field ` +
+					'encoding. Dictionary size follows the variety of shapes written -- field set, key order, ' +
+					'and per-field value width -- not column count (see HarperFast/harper#2220).'
+			);
+		} catch {
+			// the structures are already committed; a failing sink must not fail the write
+		}
+	}
 	decode(buffer, options) {
 		lastMetadata = null;
 		const start = options?.start || 0;
@@ -807,6 +885,9 @@ export function recordUpdater(store, tableId, auditStore) {
 				: NO_TIMESTAMP;
 		const expiresAt = options?.expiresAt;
 		if (expiresAt >= 0) assignMetadata |= HAS_EXPIRATION;
+		if (isRocksDB && record !== undefined && existingEntry?.version != null && newVersion <= existingEntry.version) {
+			assignMetadata = Math.max(assignMetadata, 0) | VERSION_NOT_UNIQUE_FLAG;
+		}
 		metadataInNextEncoding = assignMetadata;
 		expiresAtNextEncoding = expiresAt;
 		const putOptions: {
@@ -829,9 +910,9 @@ export function recordUpdater(store, tableId, auditStore) {
 				metadataInNextEncoding |= HAS_RESIDENCY_ID;
 				extendedType |= HAS_CURRENT_RESIDENCY_ID;
 			} else residencyIdAtNextEncoding = 0;
-			const nodeId = options?.nodeId ?? (audit ? getThisNodeId(auditStore) : undefined);
-			if (nodeId >= 0) {
-				nodeIdAtNextEncoding = nodeId;
+			const recordNodeId = options?.recordNodeId ?? options?.nodeId ?? (audit ? getThisNodeId(auditStore) : undefined);
+			if (recordNodeId >= 0) {
+				nodeIdAtNextEncoding = recordNodeId;
 				metadataInNextEncoding |= HAS_NODE_ID;
 			} else nodeIdAtNextEncoding = -1;
 			const additionalAuditRefs = options?.additionalAuditRefs;
@@ -904,8 +985,22 @@ export function recordUpdater(store, tableId, auditStore) {
 				const nodeId = options?.nodeId ?? getThisNodeId(auditStore) ?? 0;
 				const viaNodeId = options?.viaNodeId ?? nodeId;
 				if (resolveRecord && existingEntry?.localTime) {
-					const replacingId = existingEntry?.localTime;
-					const replacingEntry = auditStore.get(replacingId, tableId, id);
+					let replacingId = existingEntry.localTime;
+					let replacingEntry;
+					if (isRocksDB && existingEntry.additionalAuditRefs) {
+						for (const ref of existingEntry.additionalAuditRefs) {
+							const candidate = auditStore.get(ref.version, tableId, id, ref.nodeId);
+							if (
+								candidate?.version === existingEntry.version &&
+								(candidate.nodeId ?? 0) === (existingEntry.nodeId ?? 0)
+							) {
+								replacingId = ref.version;
+								replacingEntry = candidate;
+								break;
+							}
+						}
+					}
+					replacingEntry ??= auditStore.get(replacingId, tableId, id, existingEntry.nodeId);
 					if (replacingEntry) {
 						const previousVersion = replacingEntry.previousVersion;
 						result = auditStore[isRocksDB ? 'putSync' : 'put'](
@@ -934,7 +1029,7 @@ export function recordUpdater(store, tableId, auditStore) {
 				result = auditStore[isRocksDB ? 'putSync' : 'put'](
 					record === undefined ? NEW_TIMESTAMP_PLACEHOLDER : LAST_TIMESTAMP_PLACEHOLDER,
 					{
-						version: newVersion,
+						version: options?.recordVersion ?? newVersion,
 						tableId,
 						recordId: id,
 						previousVersion: isRocksDB ? existingEntry?.version : existingEntry?.localTime,

package/resources/RequestTarget.ts

@@ -36,6 +36,8 @@ export class RequestTarget extends URLSearchParams {
 	declare select?: Select;
 	/**	 Return an explanation of the query order */
 	declare explain?: boolean;
+	/** Request a total count of matching records for pagination (REST `Prefer: count=exact|estimated`). */
+	declare count?: 'exact' | 'estimated';
 	/**	 Force the query to be executed in the order of conditions */
 	declare enforceExecutionOrder?: boolean;
 	declare lazy?: boolean;

package/resources/Resource.ts

@@ -963,15 +963,23 @@ function registerLiveSubscriptionForContext(subscription: any, resource: any, ad
 		// JWT exp of the bearer credential (set by the auth layer); undefined for password/mTLS/session.
 		authExpiresAt: user.authExpiresAt,
 		recheck: async () => {
-			// Re-fetch current user state — the user/role cache is rebuilt on mutations — so a dropped or
-			// role-stripped user no longer authorizes.
-			const { findAndValidateUser } = require('../security/user');
-			const fresh: any = await findAndValidateUser(username, undefined, false);
-			if (!fresh?.role) return false;
-			// Advance the subscription's context to the fresh user so downstream checks — context.user
-			// and getCurrentUser() (which reads the resource's context) — evaluate against current state,
-			// not the stale user captured at subscribe time.
-			if (context) (context as any).user = fresh;
+			let fresh: any;
+			if (user._scopedToken) {
+				// A scoped token's identity IS its embedded role — never re-resolve its attribution
+				// username against hdb_user (it may not exist, or may name an unrelated principal
+				// created later). Expiry (authExpiresAt above) is its only revocation.
+				fresh = user;
+			} else {
+				// Re-fetch current user state — the user/role cache is rebuilt on mutations — so a dropped or
+				// role-stripped user no longer authorizes.
+				const { findAndValidateUser } = require('../security/user');
+				fresh = await findAndValidateUser(username, undefined, false);
+				if (!fresh?.role) return false;
+				// Advance the subscription's context to the fresh user so downstream checks — context.user
+				// and getCurrentUser() (which reads the resource's context) — evaluate against current state,
+				// not the stale user captured at subscribe time.
+				if (context) (context as any).user = fresh;
+			}
 			// Re-run the same operation-level allowRead that granted the subscription.
 			const reTarget: any = cloneRequestTarget(admittedTarget);
 			reTarget.checkPermission = fresh.role?.permission;

package/resources/ResourceInterface.ts

@@ -4,6 +4,7 @@ import { DatabaseTransaction } from './DatabaseTransaction.ts';
 import { IterableEventQueue } from './IterableEventQueue.ts';
 import type { Entry, RecordObject } from './RecordEncoder.ts';
 import { RequestTarget } from './RequestTarget.ts';
+import type { RecordLockOptions } from './recordLock.ts';
 
 export interface ResourceInterface<Record extends object = any>
 	extends Partial<RecordObject>, Pick<UpdatableRecord<Record>, 'addTo' | 'subtractFrom'> {
@@ -45,6 +46,11 @@ export interface ResourceInterface<Record extends object = any>
 
 	invalidate(target: RequestTargetOrId): void | Promise<void>;
 
+	/** Acquire an exclusive lock on a record and return it ready for updates (see `RecordLockOptions`) */
+	lock?(target?: RequestTargetOrId | RecordLockOptions, options?: RecordLockOptions): Promise<WritableRecord<Record>>;
+	/** Release the lock this instance holds; resolves true when this call cleared it */
+	unlock?(): Promise<boolean>;
+
 	publish?(target: RequestTargetOrId, record: Record, options?: any): void;
 	subscribe?(request: SubscriptionRequest): AsyncIterable<Record> | Promise<AsyncIterable<Record>>;
 
@@ -258,6 +264,23 @@ interface TypedUpdatableRecord<Record extends object, Property extends keyof Rec
 	subtractFrom(property: Property, value: Record[Property]): void;
 }
 
+export type { RecordLockOptions } from './recordLock.ts';
+
+/**
+ * What `lock()` resolves with: the locked record, loaded after the lock committed and tracking
+ * changes for `save()`. Inside an explicit `transaction()` scope a scoped lock is released when
+ * that transaction commits or aborts. Outside any explicit scope (ImmediateTransaction context),
+ * a scoped lock persists until `unlock()` is called or the lease expires. A held lock
+ * (`{ hold: true }`) is always released by `unlock()` or its lease, regardless of scope.
+ */
+export type WritableRecord<Record extends object = any> = UpdatableRecord<Record> & {
+	save(): void | Promise<void>;
+	update(updates?: Partial<Record>): unknown;
+	delete(target?: RequestTargetOrId): boolean | Promise<boolean>;
+	lock(target?: RequestTargetOrId | RecordLockOptions, options?: RecordLockOptions): Promise<WritableRecord<Record>>;
+	unlock(): Promise<boolean>;
+};
+
 export interface Subscription<Event extends object = any> extends IterableEventQueue<Event> {
 	new (listener: Listener<Event>);
 

package/resources/RocksIndexStore.ts

@@ -1,4 +1,6 @@
 import {
+	type CountEstimate,
+	type CountEstimateOptions,
 	DBI,
 	type StoreIteratorOptions,
 	type StorePutOptions,
@@ -14,6 +16,25 @@ declare module '@harperfast/rocksdb-js' {
 	}
 }
 
+/**
+ * Widen value-space bounds to `[value, MAXIMUM_KEY]` composite bounds. The base implementation's
+ * encoded-byte successor of the bare indexed value would exclude the wrong entries on composite
+ * `[indexedValue, primaryKey]` keys.
+ */
+function translateIndexBounds<
+	T extends { start?: any; end?: any; exclusiveStart?: boolean; inclusiveEnd?: boolean; reverse?: boolean },
+>(options: T): T {
+	let { start, end } = options;
+	const { exclusiveStart, inclusiveEnd, reverse } = options;
+	if ((reverse ? !exclusiveStart : exclusiveStart) && start !== undefined) {
+		start = [start, MAXIMUM_KEY];
+	}
+	if ((reverse ? !inclusiveEnd : inclusiveEnd) && end !== undefined) {
+		end = [end, MAXIMUM_KEY];
+	}
+	return { ...options, start, end };
+}
+
 /**
  * A specialized RocksDB-based index store that maintains indexed references to primary keys.
  * This store uses composite keys consisting of indexed values and primary keys, enabling
@@ -27,19 +48,19 @@ export class RocksIndexStore extends RocksDatabase {
 	 * @param options
 	 */
 	getRange(options: StoreIteratorOptions): Iterable<any> {
-		let { start, end, exclusiveStart, inclusiveEnd, reverse } = options;
-		if ((reverse ? !exclusiveStart : exclusiveStart) && start !== undefined) {
-			start = [start, MAXIMUM_KEY];
-		}
-		if ((reverse ? !inclusiveEnd : inclusiveEnd) && end !== undefined) {
-			end = [end, MAXIMUM_KEY];
-		}
-		const translatedOptions = { ...options, start, end };
-		return super.getRange(translatedOptions).map(({ key }) => {
+		return super.getRange(translateIndexBounds(options)).map(({ key }) => {
 			return { key: key[0], value: key.length > 2 ? key.slice(1) : key[1] };
 		});
 	}
 
+	/**
+	 * Estimate the entry count of a range of indexed values. Shares `getRange`'s bound translation
+	 * so a planner estimate always covers exactly the range execution would iterate.
+	 */
+	estimateCount(options?: CountEstimateOptions): CountEstimate {
+		return super.estimateCount(translateIndexBounds(options ?? {}));
+	}
+
 	/**
 	 * Translate a put with indexed value and primary key to an underlying put
 	 * @param indexedValue - ignored, only used by LMDB