@optimystic/db-p2p-storage-rn 0.13.0 → 0.13.5

package/src/keys.ts

@@ -0,0 +1,139 @@
+/**
+ * Key encoding for the LevelDB-backed storage. All keys live in a single
+ * database and are sorted lexicographically by byte order. A leading tag
+ * byte partitions the keyspace per logical store; a 4-byte big-endian
+ * length prefix on the `blockId` ensures prefix scans cannot be confused
+ * by the variable-length `actionId` suffix of the previous store.
+ *
+ * Layout:
+ *   `tag (1)` || `len(blockId) (4 BE)` || `blockId UTF-8` || `suffix`
+ *
+ * Per-store suffix encoding:
+ *   - metadata:     (empty)
+ *   - revisions:    rev (8-byte big-endian unsigned via DataView.setBigUint64)
+ *   - pending:      actionId UTF-8 (terminal)
+ *   - transactions: actionId UTF-8 (terminal)
+ *   - materialized: actionId UTF-8 (terminal)
+ *
+ * `kv` and `identity` keys are flat — no `blockId` envelope — under their
+ * own tag bytes (`TAG_KV`, `TAG_IDENTITY`) and use UTF-8 of the full key.
+ *
+ * The tag bytes are deliberately spaced (`0x01`, `0x02`, …, `0x10`, `0x20`)
+ * so a future logical store can slot in between without colliding with
+ * existing prefix scans.
+ */
+
+export const TAG_METADATA = 0x01;
+export const TAG_REVISIONS = 0x02;
+export const TAG_PENDING = 0x03;
+export const TAG_TRANSACTIONS = 0x04;
+export const TAG_MATERIALIZED = 0x05;
+export const TAG_KV = 0x10;
+export const TAG_IDENTITY = 0x20;
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+function encodeBlockEnvelope(tag: number, blockId: string): Uint8Array {
+	const blockIdBytes = textEncoder.encode(blockId);
+	const out = new Uint8Array(1 + 4 + blockIdBytes.length);
+	out[0] = tag;
+	new DataView(out.buffer, out.byteOffset).setUint32(1, blockIdBytes.length, false);
+	out.set(blockIdBytes, 5);
+	return out;
+}
+
+function concat(...parts: Uint8Array[]): Uint8Array {
+	let total = 0;
+	for (const p of parts) total += p.length;
+	const out = new Uint8Array(total);
+	let off = 0;
+	for (const p of parts) {
+		out.set(p, off);
+		off += p.length;
+	}
+	return out;
+}
+
+export function metadataKey(blockId: string): Uint8Array {
+	return encodeBlockEnvelope(TAG_METADATA, blockId);
+}
+
+export function revisionKey(blockId: string, rev: number): Uint8Array {
+	const envelope = encodeBlockEnvelope(TAG_REVISIONS, blockId);
+	const out = new Uint8Array(envelope.length + 8);
+	out.set(envelope, 0);
+	new DataView(out.buffer, out.byteOffset).setBigUint64(envelope.length, BigInt(rev), false);
+	return out;
+}
+
+/** Decode the trailing 8-byte big-endian rev from a `revisionKey`-encoded key. */
+export function revisionFromKey(key: Uint8Array): number {
+	const view = new DataView(key.buffer, key.byteOffset, key.byteLength);
+	return Number(view.getBigUint64(key.byteLength - 8, false));
+}
+
+export function pendingKey(blockId: string, actionId: string): Uint8Array {
+	return concat(encodeBlockEnvelope(TAG_PENDING, blockId), textEncoder.encode(actionId));
+}
+
+export function transactionKey(blockId: string, actionId: string): Uint8Array {
+	return concat(encodeBlockEnvelope(TAG_TRANSACTIONS, blockId), textEncoder.encode(actionId));
+}
+
+export function materializedKey(blockId: string, actionId: string): Uint8Array {
+	return concat(encodeBlockEnvelope(TAG_MATERIALIZED, blockId), textEncoder.encode(actionId));
+}
+
+/** Returns the inclusive lower / exclusive upper range covering every key for `(tag, blockId, *)`. */
+export function blockEnvelopeRange(tag: number, blockId: string): { gte: Uint8Array; lt: Uint8Array } {
+	const gte = encodeBlockEnvelope(tag, blockId);
+	const lt = new Uint8Array(gte.length);
+	lt.set(gte);
+	// Increment the last byte to get the exclusive upper bound. The envelope
+	// ends in the last byte of the blockId (UTF-8); since the longest possible
+	// UTF-8 lead byte is 0xF4 and continuation bytes are <= 0xBF, no envelope
+	// byte is ever 0xFF — incrementing the last byte is always well-defined.
+	const lastIndex = lt.length - 1;
+	const lastByte = lt[lastIndex];
+	if (lastByte === undefined) throw new Error('empty blockId envelope');
+	lt[lastIndex] = lastByte + 1;
+	return { gte, lt };
+}
+
+/** Decode the `actionId` suffix from a `pendingKey` / `transactionKey` / `materializedKey`. */
+export function actionIdFromKey(key: Uint8Array, blockId: string): string {
+	const blockIdLen = textEncoder.encode(blockId).length;
+	const suffixOffset = 1 + 4 + blockIdLen;
+	return textDecoder.decode(key.subarray(suffixOffset));
+}
+
+export function kvKey(key: string): Uint8Array {
+	return concat(Uint8Array.of(TAG_KV), textEncoder.encode(key));
+}
+
+/** Returns the inclusive lower / exclusive upper range covering every kv key starting with `prefix`. */
+export function kvPrefixRange(prefix: string): { gte: Uint8Array; lt: Uint8Array } {
+	const prefixBytes = textEncoder.encode(prefix);
+	const gte = new Uint8Array(1 + prefixBytes.length);
+	gte[0] = TAG_KV;
+	gte.set(prefixBytes, 1);
+	// Upper bound: any string whose UTF-8 bytes start with `prefixBytes` sorts
+	// strictly below `[TAG_KV, ...prefixBytes, 0xFF]`. UTF-8 never produces a
+	// 0xFF byte (the maximum valid lead byte is 0xF4 and continuation bytes
+	// top out at 0xBF), so appending 0xFF yields an exact exclusive upper bound.
+	const lt = new Uint8Array(1 + prefixBytes.length + 1);
+	lt[0] = TAG_KV;
+	lt.set(prefixBytes, 1);
+	lt[lt.length - 1] = 0xff;
+	return { gte, lt };
+}
+
+/** Strip the leading `TAG_KV` byte from a key, returning the UTF-8 string portion. */
+export function kvKeyToString(raw: Uint8Array): string {
+	return textDecoder.decode(raw.subarray(1));
+}
+
+export function identityKey(keyName: string): Uint8Array {
+	return concat(Uint8Array.of(TAG_IDENTITY), textEncoder.encode(keyName));
+}

package/src/leveldb-kv-store.ts

@@ -0,0 +1,43 @@
+import type { IKVStore } from '@optimystic/db-p2p';
+import { drain, type LevelDBLike } from './leveldb-like.js';
+import { kvKey, kvKeyToString, kvPrefixRange } from './keys.js';
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+/**
+ * LevelDB-backed `IKVStore` adapter for React Native peers.
+ *
+ * Shares one `LevelDBLike` database with `LevelDBRawStorage` and the identity
+ * helper. KV keys are tagged with `TAG_KV` (and identity with `TAG_IDENTITY`),
+ * so the three subsystems can't collide regardless of the user-chosen
+ * `prefix`. `list(prefix)` is a range-bounded scan — never a full-database
+ * iteration plus JS-side filter — so listing latency stays bounded.
+ */
+export class LevelDBKVStore implements IKVStore {
+	private readonly prefix: string;
+
+	constructor(private readonly db: LevelDBLike, prefix: string = 'optimystic:txn:') {
+		this.prefix = prefix;
+	}
+
+	async get(key: string): Promise<string | undefined> {
+		const bytes = await this.db.get(kvKey(this.prefix + key));
+		if (!bytes) return undefined;
+		return textDecoder.decode(bytes);
+	}
+
+	async set(key: string, value: string): Promise<void> {
+		await this.db.put(kvKey(this.prefix + key), textEncoder.encode(value));
+	}
+
+	async delete(key: string): Promise<void> {
+		await this.db.delete(kvKey(this.prefix + key));
+	}
+
+	async list(prefix: string): Promise<string[]> {
+		const range = kvPrefixRange(this.prefix + prefix);
+		const entries = await drain(this.db.iterator({ gte: range.gte, lt: range.lt, keys: true }));
+		return entries.map(([rawKey]) => kvKeyToString(rawKey).slice(this.prefix.length));
+	}
+}

package/src/leveldb-like.ts

@@ -0,0 +1,84 @@
+/**
+ * Package-private LevelDB driver surface.
+ *
+ * The storage classes (`LevelDBRawStorage`, `LevelDBKVStore`) and the identity
+ * helper (`loadOrCreateRNPeerKey`) only depend on the interfaces declared here
+ * — never on `rn-leveldb` directly. That lets the suite run under Node mocha
+ * against `classic-level`, matching the pattern `db-p2p-storage-ns` uses with
+ * `node:sqlite` and `db-p2p-storage-web` uses with `fake-indexeddb`.
+ *
+ * Only `openOptimysticRNDb`, the user-facing constructors, and the identity
+ * helper are exported from `index.ts`; the interfaces in this file are
+ * internal — consumers never see them.
+ */
+
+/** Range options for a `LevelDBLike.iterator` scan. */
+export interface LevelDBIteratorOptions {
+	/** Inclusive lower bound. */
+	gte?: Uint8Array;
+	/** Exclusive lower bound. */
+	gt?: Uint8Array;
+	/** Inclusive upper bound. */
+	lte?: Uint8Array;
+	/** Exclusive upper bound. */
+	lt?: Uint8Array;
+	/** Reverse iteration order. */
+	reverse?: boolean;
+	/** Maximum number of entries to yield. */
+	limit?: number;
+	/** Skip values (return zero-length Uint8Array for value). Used by `getApproximateBytesUsed`. */
+	keys?: boolean;
+}
+
+/** Cursor over a `LevelDBLike` range scan. Caller must `close()` exactly once. */
+export interface LevelDBIteratorLike {
+	/** Return the next entry, or `undefined` when the range is exhausted. */
+	next(): Promise<[Uint8Array, Uint8Array] | undefined>;
+	/** Release any native resources held by the iterator. */
+	close(): Promise<void>;
+}
+
+/** Atomic batch of `put` / `delete` operations against a single database. */
+export interface LevelDBWriteBatchLike {
+	put(key: Uint8Array, value: Uint8Array): this;
+	delete(key: Uint8Array): this;
+	/** Commit the batch atomically. */
+	write(): Promise<void>;
+}
+
+/**
+ * Minimal LevelDB driver surface used by this package.
+ *
+ * Wraps either `rn-leveldb` (in production) or `classic-level` (in tests).
+ * The interface is `Promise`-returning on every method so the rn-leveldb
+ * adapter — which forwards to a synchronous native module — can stay
+ * uniform with `classic-level`'s native async API.
+ */
+export interface LevelDBLike {
+	get(key: Uint8Array): Promise<Uint8Array | undefined>;
+	put(key: Uint8Array, value: Uint8Array): Promise<void>;
+	delete(key: Uint8Array): Promise<void>;
+	batch(): LevelDBWriteBatchLike;
+	iterator(options?: LevelDBIteratorOptions): LevelDBIteratorLike;
+	/** Release the underlying database handle. */
+	close(): Promise<void>;
+}
+
+/**
+ * Drain an iterator into an array. Used by storage classes so a native
+ * iterator never stays open across consumer awaits — same rationale as the
+ * IndexedDB and SQLite backends.
+ */
+export async function drain(iter: LevelDBIteratorLike): Promise<Array<[Uint8Array, Uint8Array]>> {
+	const out: Array<[Uint8Array, Uint8Array]> = [];
+	try {
+		while (true) {
+			const entry = await iter.next();
+			if (!entry) break;
+			out.push(entry);
+		}
+	} finally {
+		await iter.close();
+	}
+	return out;
+}

package/src/leveldb-storage.ts

@@ -0,0 +1,155 @@
+import type { ActionId, ActionRev, BlockId, IBlock, Transform } from '@optimystic/db-core';
+import type { BlockMetadata, IRawStorage } from '@optimystic/db-p2p';
+import { drain, type LevelDBLike } from './leveldb-like.js';
+import {
+	TAG_PENDING,
+	actionIdFromKey,
+	blockEnvelopeRange,
+	materializedKey,
+	metadataKey,
+	pendingKey,
+	revisionFromKey,
+	revisionKey,
+	transactionKey,
+} from './keys.js';
+import { createLogger } from './logger.js';
+
+const log = createLogger('storage:leveldb');
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+/**
+ * LevelDB-backed `IRawStorage` implementation for React Native peers.
+ *
+ * All data lives in a single LevelDB database; per-store partitioning is by a
+ * leading tag byte (see `./keys.ts`). `listRevisions` and
+ * `listPendingTransactions` use range iterators with explicit bounds, drained
+ * into an array before yielding (same rationale as the IndexedDB / SQLite
+ * backends — a native iterator must not stay open across consumer awaits).
+ *
+ * `promotePendingTransaction` runs as a single `WriteBatch`, making the
+ * pending → committed move atomic against crashes.
+ */
+export class LevelDBRawStorage implements IRawStorage {
+	constructor(private readonly db: LevelDBLike) {}
+
+	async getMetadata(blockId: BlockId): Promise<BlockMetadata | undefined> {
+		const bytes = await this.db.get(metadataKey(blockId));
+		if (!bytes) return undefined;
+		return JSON.parse(textDecoder.decode(bytes)) as BlockMetadata;
+	}
+
+	async saveMetadata(blockId: BlockId, metadata: BlockMetadata): Promise<void> {
+		await this.db.put(metadataKey(blockId), textEncoder.encode(JSON.stringify(metadata)));
+	}
+
+	async getRevision(blockId: BlockId, rev: number): Promise<ActionId | undefined> {
+		const bytes = await this.db.get(revisionKey(blockId, rev));
+		if (!bytes) return undefined;
+		return textDecoder.decode(bytes) as ActionId;
+	}
+
+	async saveRevision(blockId: BlockId, rev: number, actionId: ActionId): Promise<void> {
+		await this.db.put(revisionKey(blockId, rev), textEncoder.encode(actionId));
+	}
+
+	async *listRevisions(blockId: BlockId, startRev: number, endRev: number): AsyncIterable<ActionRev> {
+		const ascending = startRev <= endRev;
+		const lo = ascending ? startRev : endRev;
+		const hi = ascending ? endRev : startRev;
+		// `revisionKey(blockId, hi)` is exactly the inclusive upper bound; LevelDB
+		// uses exclusive `lt`, so request `lte` via `lt = key(hi)+0x01` would
+		// require an extra byte. Easier: use `lt = revisionKey(blockId, hi+1)`.
+		const gte = revisionKey(blockId, lo);
+		const lt = revisionKey(blockId, hi + 1);
+		const entries = await drain(this.db.iterator({ gte, lt, reverse: !ascending }));
+		for (const [key, value] of entries) {
+			yield {
+				rev: revisionFromKey(key),
+				actionId: textDecoder.decode(value) as ActionId,
+			};
+		}
+	}
+
+	async getPendingTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
+		const bytes = await this.db.get(pendingKey(blockId, actionId));
+		if (!bytes) return undefined;
+		return JSON.parse(textDecoder.decode(bytes)) as Transform;
+	}
+
+	async savePendingTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
+		await this.db.put(pendingKey(blockId, actionId), textEncoder.encode(JSON.stringify(transform)));
+	}
+
+	async deletePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
+		await this.db.delete(pendingKey(blockId, actionId));
+	}
+
+	async *listPendingTransactions(blockId: BlockId): AsyncIterable<ActionId> {
+		const range = blockEnvelopeRange(TAG_PENDING, blockId);
+		const entries = await drain(this.db.iterator({ gte: range.gte, lt: range.lt, keys: true }));
+		for (const [key] of entries) {
+			yield actionIdFromKey(key, blockId) as ActionId;
+		}
+	}
+
+	async getTransaction(blockId: BlockId, actionId: ActionId): Promise<Transform | undefined> {
+		const bytes = await this.db.get(transactionKey(blockId, actionId));
+		if (!bytes) return undefined;
+		return JSON.parse(textDecoder.decode(bytes)) as Transform;
+	}
+
+	async saveTransaction(blockId: BlockId, actionId: ActionId, transform: Transform): Promise<void> {
+		await this.db.put(transactionKey(blockId, actionId), textEncoder.encode(JSON.stringify(transform)));
+	}
+
+	async getMaterializedBlock(blockId: BlockId, actionId: ActionId): Promise<IBlock | undefined> {
+		const bytes = await this.db.get(materializedKey(blockId, actionId));
+		if (!bytes) return undefined;
+		return JSON.parse(textDecoder.decode(bytes)) as IBlock;
+	}
+
+	async saveMaterializedBlock(blockId: BlockId, actionId: ActionId, block?: IBlock): Promise<void> {
+		const key = materializedKey(blockId, actionId);
+		if (block) {
+			await this.db.put(key, textEncoder.encode(JSON.stringify(block)));
+		} else {
+			await this.db.delete(key);
+		}
+	}
+
+	async getApproximateBytesUsed(): Promise<number> {
+		try {
+			let total = 0;
+			const iter = this.db.iterator();
+			try {
+				while (true) {
+					const entry = await iter.next();
+					if (!entry) break;
+					total += entry[0].byteLength + entry[1].byteLength;
+				}
+			} finally {
+				await iter.close();
+			}
+			return total;
+		} catch (err) {
+			log('getApproximateBytesUsed iterator failed: %o', err);
+			return 0;
+		}
+	}
+
+	async promotePendingTransaction(blockId: BlockId, actionId: ActionId): Promise<void> {
+		const pKey = pendingKey(blockId, actionId);
+		const value = await this.db.get(pKey);
+		if (!value) {
+			throw new Error(`Pending action ${actionId} not found for block ${blockId}`);
+		}
+		const tKey = transactionKey(blockId, actionId);
+		await this.db
+			.batch()
+			.put(tKey, value)
+			.delete(pKey)
+			.write();
+	}
+}

package/src/rn-opener.ts

@@ -0,0 +1,274 @@
+import type {
+	LevelDBIteratorLike,
+	LevelDBIteratorOptions,
+	LevelDBLike,
+	LevelDBWriteBatchLike,
+} from './leveldb-like.js';
+
+/**
+ * Minimal subset of `rn-leveldb`'s `LevelDB` we depend on. Re-declared
+ * locally so this module's *types* don't pull in the plugin's declarations
+ * (the plugin is a peer dependency that may not be installed at typecheck
+ * time on non-RN consumers).
+ *
+ * Matches the shape used by `@quereus/plugin-react-native-leveldb` so apps
+ * embedding both Optimystic and Quereus can share one native module.
+ */
+export interface RNLevelDBNative {
+	put(key: ArrayBuffer | string, value: ArrayBuffer | string): void;
+	getBuf(key: ArrayBuffer | string): ArrayBuffer | null;
+	delete(key: ArrayBuffer | string): void;
+	close(): void;
+	newIterator(): RNLevelDBIteratorNative;
+	write(batch: RNLevelDBWriteBatchNative): void;
+}
+
+export interface RNLevelDBWriteBatchNative {
+	put(key: ArrayBuffer | string, value: ArrayBuffer | string): void;
+	delete(key: ArrayBuffer | string): void;
+	close(): void;
+}
+
+export interface RNLevelDBIteratorNative {
+	valid(): boolean;
+	seek(target: ArrayBuffer | string): RNLevelDBIteratorNative;
+	seekToFirst(): RNLevelDBIteratorNative;
+	seekLast(): RNLevelDBIteratorNative;
+	next(): void;
+	prev(): void;
+	keyBuf(): ArrayBuffer;
+	valueBuf(): ArrayBuffer;
+	close(): void;
+}
+
+/** Constructor type for `rn-leveldb`'s `LevelDBWriteBatch`. */
+export type RNLevelDBWriteBatchCtor = new () => RNLevelDBWriteBatchNative;
+
+/**
+ * Open function shape — typically `(name, createIfMissing, errorIfExists) =>
+ * new LevelDB(name, createIfMissing, errorIfExists)`. The caller controls
+ * how `rn-leveldb` is imported so this package never directly imports it,
+ * which keeps the unit tests runnable under Node.
+ */
+export type RNLevelDBOpenFn = (name: string, createIfMissing: boolean, errorIfExists: boolean) => RNLevelDBNative;
+
+export const DEFAULT_DB_NAME = 'optimystic';
+
+export interface OpenOptimysticRNDbOptions {
+	/** `rn-leveldb`'s `LevelDB` constructor wrapped as an open function. */
+	openFn: RNLevelDBOpenFn;
+	/** `rn-leveldb`'s `LevelDBWriteBatch` constructor. */
+	WriteBatch: RNLevelDBWriteBatchCtor;
+	/** Database name (LevelDB directory). Default `optimystic`. */
+	name?: string;
+	/** Whether to create the database if it doesn't exist. Default `true`. */
+	createIfMissing?: boolean;
+	/** Whether to error if the database already exists. Default `false`. */
+	errorIfExists?: boolean;
+}
+
+/**
+ * Opens (creating if needed) the Optimystic LevelDB database used by
+ * `LevelDBRawStorage`, `LevelDBKVStore`, and `loadOrCreateRNPeerKey`.
+ *
+ * The caller passes the `rn-leveldb` constructors in; this keeps the
+ * native module out of the package's static import graph. Apps embedding
+ * both Optimystic and Quereus can pass the same constructors to both —
+ * one native module, one Podfile entry.
+ */
+export function openOptimysticRNDb(options: OpenOptimysticRNDbOptions): LevelDBLike {
+	const native = options.openFn(
+		options.name ?? DEFAULT_DB_NAME,
+		options.createIfMissing ?? true,
+		options.errorIfExists ?? false,
+	);
+	return wrapRNLevelDB(native, options.WriteBatch);
+}
+
+/**
+ * Wraps an already-open `rn-leveldb` `LevelDB` instance to satisfy the
+ * `LevelDBLike` interface. Exported for callers that already hold a handle
+ * (rare — usually `openOptimysticRNDb` is the right entry point).
+ */
+export function wrapRNLevelDB(native: RNLevelDBNative, WriteBatch: RNLevelDBWriteBatchCtor): LevelDBLike {
+	return new RNLevelDBAdapter(native, WriteBatch);
+}
+
+class RNLevelDBAdapter implements LevelDBLike {
+	constructor(
+		private readonly native: RNLevelDBNative,
+		private readonly WriteBatch: RNLevelDBWriteBatchCtor,
+	) {}
+
+	async get(key: Uint8Array): Promise<Uint8Array | undefined> {
+		const result = this.native.getBuf(toArrayBuffer(key));
+		return result === null ? undefined : new Uint8Array(result);
+	}
+
+	async put(key: Uint8Array, value: Uint8Array): Promise<void> {
+		this.native.put(toArrayBuffer(key), toArrayBuffer(value));
+	}
+
+	async delete(key: Uint8Array): Promise<void> {
+		this.native.delete(toArrayBuffer(key));
+	}
+
+	batch(): LevelDBWriteBatchLike {
+		return new RNLevelDBWriteBatchAdapter(this.native, new this.WriteBatch());
+	}
+
+	iterator(options: LevelDBIteratorOptions = {}): LevelDBIteratorLike {
+		return new RNLevelDBIteratorAdapter(this.native.newIterator(), options);
+	}
+
+	async close(): Promise<void> {
+		this.native.close();
+	}
+}
+
+class RNLevelDBWriteBatchAdapter implements LevelDBWriteBatchLike {
+	constructor(
+		private readonly native: RNLevelDBNative,
+		private readonly batch: RNLevelDBWriteBatchNative,
+	) {}
+
+	put(key: Uint8Array, value: Uint8Array): this {
+		this.batch.put(toArrayBuffer(key), toArrayBuffer(value));
+		return this;
+	}
+
+	delete(key: Uint8Array): this {
+		this.batch.delete(toArrayBuffer(key));
+		return this;
+	}
+
+	async write(): Promise<void> {
+		try {
+			this.native.write(this.batch);
+		} finally {
+			this.batch.close();
+		}
+	}
+}
+
+class RNLevelDBIteratorAdapter implements LevelDBIteratorLike {
+	private positioned = false;
+	private yielded = 0;
+	private done = false;
+
+	constructor(
+		private readonly iter: RNLevelDBIteratorNative,
+		private readonly opts: LevelDBIteratorOptions,
+	) {}
+
+	async next(): Promise<[Uint8Array, Uint8Array] | undefined> {
+		if (this.done) return undefined;
+		if (this.opts.limit !== undefined && this.yielded >= this.opts.limit) {
+			this.done = true;
+			return undefined;
+		}
+
+		if (!this.positioned) {
+			this.positionInitial();
+			this.positioned = true;
+		} else if (this.opts.reverse) {
+			this.iter.prev();
+		} else {
+			this.iter.next();
+		}
+
+		if (!this.iter.valid()) {
+			this.done = true;
+			return undefined;
+		}
+
+		const key = new Uint8Array(this.iter.keyBuf());
+
+		// Range bounds: bail out as soon as we cross.
+		if (this.opts.reverse) {
+			if (this.opts.gte && compareBytes(key, this.opts.gte) < 0) {
+				this.done = true;
+				return undefined;
+			}
+			if (this.opts.gt && compareBytes(key, this.opts.gt) <= 0) {
+				this.done = true;
+				return undefined;
+			}
+		} else {
+			if (this.opts.lt && compareBytes(key, this.opts.lt) >= 0) {
+				this.done = true;
+				return undefined;
+			}
+			if (this.opts.lte && compareBytes(key, this.opts.lte) > 0) {
+				this.done = true;
+				return undefined;
+			}
+		}
+
+		// `keys: true` means caller wants only keys; skip the `valueBuf` native call.
+		const value = this.opts.keys ? new Uint8Array(0) : new Uint8Array(this.iter.valueBuf());
+		this.yielded++;
+		return [key, value];
+	}
+
+	async close(): Promise<void> {
+		this.iter.close();
+	}
+
+	private positionInitial(): void {
+		if (this.opts.reverse) {
+			if (this.opts.lte !== undefined) {
+				this.iter.seek(toArrayBuffer(this.opts.lte));
+				if (!this.iter.valid()) {
+					this.iter.seekLast();
+				} else {
+					const key = new Uint8Array(this.iter.keyBuf());
+					if (compareBytes(key, this.opts.lte) > 0) this.iter.prev();
+				}
+			} else if (this.opts.lt !== undefined) {
+				this.iter.seek(toArrayBuffer(this.opts.lt));
+				if (this.iter.valid()) {
+					this.iter.prev();
+				} else {
+					this.iter.seekLast();
+				}
+			} else {
+				this.iter.seekLast();
+			}
+		} else {
+			if (this.opts.gte !== undefined) {
+				this.iter.seek(toArrayBuffer(this.opts.gte));
+			} else if (this.opts.gt !== undefined) {
+				this.iter.seek(toArrayBuffer(this.opts.gt));
+				if (this.iter.valid()) {
+					const key = new Uint8Array(this.iter.keyBuf());
+					if (compareBytes(key, this.opts.gt) === 0) this.iter.next();
+				}
+			} else {
+				this.iter.seekToFirst();
+			}
+		}
+	}
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+	const buffer = bytes.buffer;
+	if (buffer instanceof ArrayBuffer
+		&& bytes.byteOffset === 0
+		&& bytes.byteLength === buffer.byteLength) {
+		return buffer;
+	}
+	const copy = new ArrayBuffer(bytes.byteLength);
+	new Uint8Array(copy).set(bytes);
+	return copy;
+}
+
+function compareBytes(a: Uint8Array, b: Uint8Array): number {
+	const minLength = Math.min(a.length, b.length);
+	for (let i = 0; i < minLength; i++) {
+		const av = a[i]!;
+		const bv = b[i]!;
+		if (av !== bv) return av - bv;
+	}
+	return a.length - b.length;
+}