@moyodb/sdk 1.1.0 → 1.4.0

package/dist/node.js

@@ -1,12 +1,15 @@
-import { $ as StoreExistsError, A as prefixRange, B as DatabaseClosedError, C as compoundKey, Ct as isWorkerProtocolReadyEnvelope, D as indexKey, Dt as isWorkerProtocolResponseBatchMessage, E as encodeIndexScalar, F as utf8Encode, G as InvalidRangeError, H as InjectedFailureError, Ht as compareStringsByCodeUnit, I as ChangeFeedCompactedError, J as ReadonlyTransactionError, K as KeyTooLargeError, L as ConstraintError, M as splitCompoundKey, Mt as prepareWorkerCommandPayload, N as u64Key, O as jsonDecode, Ot as isWorkerProtocolResponseMessage, P as utf8Decode, Q as StorageError, R as CorruptionError, S as toPublicIndexDefinitions, T as encodeCompoundKeyParts, U as InternalError, Ut as isRecord$1, V as IndexNotFoundError, Vt as workerProtocolError, W as InvalidOpenOptionsError, X as ReservedStoreNameError, Y as RecoveryRequiredError, Z as SerializationError, _ as indexRangeToPhysicalRange, a as createIndexKeyExtractor, at as UnsupportedPlatformError, b as normalizeIndexDefinitions, c as decodeIndexedDocument, ct as WriteTransactionAlreadyOpenError, d as encodeIndexMetadataValue, et as StoreNameTooLongError, f as extractLogicalIndexKey, ft as WORKER_PROTOCOL_REQUEST, g as indexKeyExactRange, gt as captureWorkerPayload, h as indexDefinitionIdentity, i as compareNormalizedIndexDefinitions, it as UniqueIndexConstraintError, j as prefixSuccessor, k as jsonEncode, l as encodeIndexEntryKey, lt as normalizeError, m as findIndexDefinition, n as assertPublicStoreName, nt as TransactionClosedError, o as decodeIndexEntryKey, ot as ValueTooLargeError, p as extractLogicalIndexKeyFromDocument, pt as WORKER_PROTOCOL_REQUEST_BATCH, q as MoyoDbError, r as cloneNormalizedIndexDefinitions, rt as TransactionConflictError, s as decodeIndexMetadataValue, st as VersionError, t as INDEX_METADATA_STORE, tt as StoreNotFoundError, u as encodeIndexMetadataKey, v as indexesForStore, vt as decodeWorkerResponsePayload, w as compoundKeyRange, wt as isWorkerProtocolReadyMessage, x as serializeNormalizedIndexDefinitions, y as isInternalStoreName, yt as deserializeWorkerError, z as DatabaseBusyError } from "./chunks/indexing-BzmFhWXs.js";
+import { $ as StoreExistsError, A as prefixRange, B as DatabaseClosedError, C as compoundKey, Ct as isWorkerProtocolReadyEnvelope, D as indexKey, Dt as isWorkerProtocolResponseBatchMessage, E as encodeIndexScalar, F as utf8Encode, G as InvalidRangeError, Gt as isRecord$1, H as InjectedFailureError, Ht as workerProtocolError, I as ChangeFeedCompactedError, J as ReadonlyTransactionError, K as KeyTooLargeError, L as ConstraintError, M as splitCompoundKey, N as u64Key, Nt as prepareWorkerCommandPayload, O as jsonDecode, Ot as isWorkerProtocolResponseMessage, P as utf8Decode, Q as StorageError, R as CorruptionError, S as toPublicIndexDefinitions, T as encodeCompoundKeyParts, U as InternalError, Ut as clampTimerDelayMs, V as IndexNotFoundError, W as InvalidOpenOptionsError, Wt as compareStringsByCodeUnit, X as ReservedStoreNameError, Y as RecoveryRequiredError, Z as SerializationError, _ as indexRangeToPhysicalRange, a as createIndexKeyExtractor, at as UnsupportedPlatformError, b as normalizeIndexDefinitions, c as decodeIndexedDocument, ct as WriteTransactionAlreadyOpenError, d as encodeIndexMetadataValue, et as StoreNameTooLongError, f as extractLogicalIndexKey, ft as WORKER_PROTOCOL_REQUEST, g as indexKeyExactRange, gt as captureWorkerPayload, h as indexDefinitionIdentity, i as compareNormalizedIndexDefinitions, it as UniqueIndexConstraintError, j as prefixSuccessor, k as jsonEncode, l as encodeIndexEntryKey, lt as normalizeError, m as findIndexDefinition, n as assertPublicStoreName, nt as TransactionClosedError, o as decodeIndexEntryKey, ot as ValueTooLargeError, p as extractLogicalIndexKeyFromDocument, pt as WORKER_PROTOCOL_REQUEST_BATCH, q as MoyoDbError, r as cloneNormalizedIndexDefinitions, rt as TransactionConflictError, s as decodeIndexMetadataValue, st as VersionError, t as INDEX_METADATA_STORE, tt as StoreNotFoundError, u as encodeIndexMetadataKey, v as indexesForStore, vt as decodeWorkerResponsePayload, w as compoundKeyRange, wt as isWorkerProtocolReadyMessage, x as serializeNormalizedIndexDefinitions, y as isInternalStoreName, yt as deserializeWorkerError, z as DatabaseBusyError } from "./chunks/indexing-B0duqlUs.js";
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, realpath } from "node:fs/promises";
+import { realpath } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { Worker as Worker$1 } from "node:worker_threads";
 import fs from "node:fs";
 //#region src/worker-client.ts
 function clearPendingTimeout(pending) {
-	if (pending.timeout) clearTimeout(pending.timeout);
+	if (pending.timeout) {
+		clearTimeout(pending.timeout);
+		pending.timeout = null;
+	}
 }
 var WorkerProtocolClient = class {
 	worker;
@@ -26,16 +29,19 @@ var WorkerProtocolClient = class {
 	flushScheduled = false;
 	awaitingReady = 0;
 	readyTimeout = null;
+	forwardScanPackets;
 	constructor(worker, options = {}) {
 		this.worker = worker;
-		this.requestTimeoutMs = options.requestTimeoutMs ?? 0;
+		this.forwardScanPackets = options.forwardScanPackets === true;
+		this.requestTimeoutMs = clampTimerDelayMs(options.requestTimeoutMs ?? 0);
 		this.ready = new Promise((resolve, reject) => {
 			this.readyResolve = resolve;
 			this.readyReject = reject;
 		});
-		if ((options.readyTimeoutMs ?? 0) > 0) this.readyTimeout = setTimeout(() => {
+		const readyTimeoutMs = clampTimerDelayMs(options.readyTimeoutMs ?? 0);
+		if (readyTimeoutMs > 0) this.readyTimeout = setTimeout(() => {
 			this.fail(workerProtocolError("WorkerReadyTimeoutError", "worker did not become ready"));
-		}, options.readyTimeoutMs);
+		}, readyTimeoutMs);
 		this.ready.catch(() => void 0);
 		this.worker.addEventListener("message", this.handleMessage);
 		this.worker.addEventListener("messageerror", this.handleMessageError);
@@ -160,6 +166,12 @@ var WorkerProtocolClient = class {
 			range
 		]);
 	}
+	scanPage(request) {
+		return this.request("scanPage", [request]);
+	}
+	closeCursor(cursorId) {
+		return this.request("closeCursor", [cursorId]);
+	}
 	getByIndex(txId, store, indexName, key) {
 		return this.request("getByIndex", [
 			txId,
@@ -176,14 +188,15 @@ var WorkerProtocolClient = class {
 			range
 		]);
 	}
-	scanByIndexPage(txId, store, indexName, range, cursor, limit) {
+	scanByIndexPage(txId, store, indexName, range, cursor, limit, maxBytes) {
 		return this.request("scanByIndexPage", [
 			txId,
 			store,
 			indexName,
 			range,
 			cursor,
-			limit
+			limit,
+			maxBytes
 		]);
 	}
 	getIndexes(txId) {
@@ -256,7 +269,10 @@ var WorkerProtocolClient = class {
 		};
 		return await new Promise((resolve, reject) => {
 			const timeout = this.requestTimeoutMs > 0 ? setTimeout(() => {
+				const current = this.pending.get(id);
+				if (!current || current.timeout === null) return;
 				this.pending.delete(id);
+				current.timeout = null;
 				reject(workerProtocolError("WorkerRequestTimeoutError", `worker command ${command} timed out after ${this.requestTimeoutMs}ms`));
 			}, this.requestTimeoutMs) : null;
 			this.pending.set(id, {
@@ -335,6 +351,10 @@ var WorkerProtocolClient = class {
 			this.fail(workerProtocolError("WorkerProtocolError", "incompatible worker protocol ready message"));
 			return;
 		}
+		if (isRecord$1(data) && (data.type === "moyodb:worker-protocol:response" || data.type === "moyodb:worker-protocol:response-batch") && data.version !== 1) {
+			this.fail(workerProtocolError("WorkerProtocolError", "incompatible worker protocol response"));
+			return;
+		}
 		if (isWorkerProtocolResponseBatchMessage(data)) {
 			for (const response of data.responses) this.handleResponse(response);
 			return;
@@ -355,7 +375,7 @@ var WorkerProtocolClient = class {
 		this.pending.delete(data.id);
 		clearPendingTimeout(pending);
 		try {
-			if (data.ok) pending.resolve(decodeWorkerResponsePayload(pending.command, data.result));
+			if (data.ok) pending.resolve(this.forwardScanPackets && (pending.command === "scanPage" || pending.command === "scan" || pending.command === "scanByIndex" || pending.command === "scanByIndexPage") ? data.result : decodeWorkerResponsePayload(pending.command, data.result));
 			else pending.reject(deserializeWorkerError(data.error));
 		} catch (error) {
 			pending.reject(error instanceof Error && error.name === "WorkerProtocolError" ? error : workerProtocolError("WorkerProtocolError", "worker response could not be decoded"));
@@ -1042,7 +1062,7 @@ function bindSqlParameters(parsed, parameters = []) {
 	return Array.from(parameters, (value, index) => {
 		if (value === null || typeof value === "boolean") return value;
 		if (typeof value === "number") {
-			if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value)) throw new RangeError(`SQL parameter ${index + 1} must be finite; use bigint for integers outside the safe range`);
+			if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value) && fitsSigned64(value)) throw new RangeError(`SQL parameter ${index + 1} must be finite; use bigint for integers outside the safe range`);
 			return value;
 		}
 		if (typeof value === "bigint") {
@@ -1508,6 +1528,11 @@ function tokenize(sql) {
 	});
 	return tokens;
 }
+function fitsSigned64(value) {
+	if (!Number.isInteger(value)) return false;
+	const integer = BigInt(value);
+	return integer >= SQL_INTEGER_MIN && integer <= SQL_INTEGER_MAX;
+}
 function parseNumber(text, position) {
 	if (/^[+-]?\d+$/u.test(text)) {
 		const integer = BigInt(text);
@@ -1515,7 +1540,7 @@ function parseNumber(text, position) {
 		return integer >= BigInt(Number.MIN_SAFE_INTEGER) && integer <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(integer) : integer;
 	}
 	const value = Number(text);
-	if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value)) throw new SqlSyntaxError("REAL literal must be finite; use integer notation for large integers", position);
+	if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value) && fitsSigned64(value)) throw new SqlSyntaxError("REAL literal must be finite; use integer notation for large integers", position);
 	const [mantissa, exponentText = "0"] = text.toLowerCase().split("e");
 	const digits = mantissa.replace(/[+.-]/gu, "");
 	const nonzero = /[1-9]/u.test(digits);
@@ -1678,9 +1703,10 @@ async function executeStatement(tx, statement, parameters, indexes, explain) {
 		rowsAffected: 0,
 		plan: plan.public
 	};
-	const rows = (limit === 0 ? [] : await readRows(tx, schema, plan)).filter(({ row }) => !statement.where || evaluateWhere(row, statement.where, parameters) === true);
+	const maxMatches = statement.kind === "select" && plan.public.sort === "none" && limit !== null ? Math.min(Number.MAX_SAFE_INTEGER, offset + limit) : void 0;
+	const rows = limit === 0 ? [] : await readRows(tx, schema, plan, statement.where, parameters, maxMatches);
 	if (statement.kind === "select") {
-		if (orderBy.length) rows.sort((left, right) => compareRows(left, right, orderBy));
+		if (plan.public.sort === "memory") rows.sort((left, right) => compareRows(left, right, orderBy));
 		return {
 			rows: rows.slice(offset, limit === null ? void 0 : offset + limit).map(({ row }) => projectRow(row, statement.columns ?? schema.columns.map((column) => column.name))),
 			rowsAffected: 0,
@@ -1816,7 +1842,10 @@ function normalizeValue(column, value) {
 		}
 		case "REAL":
 			if (typeof value === "number" && Number.isFinite(value)) return Object.is(value, -0) ? 0 : value;
-			if (typeof value === "bigint" && value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) return Number(value);
+			if (typeof value === "bigint") {
+				const asNumber = Number(value);
+				if (Number.isFinite(asNumber) && BigInt(asNumber) === value) return asNumber;
+			}
 			break;
 		case "TEXT":
 			if (typeof value === "string") {
@@ -1950,13 +1979,15 @@ function planAccess(schema, where, orderBy, parameters, indexes) {
 		}
 		if (!key && !Object.keys(range).length) continue;
 		const access = candidate.index ? equalityOnly ? "index-lookup" : "index-range" : equalityOnly ? "primary-key-lookup" : "primary-key-range";
+		const ordered = traversalOrder(schema, candidate.column, candidate.index, orderBy, key);
+		if (ordered && orderBy[0]?.direction === "desc") range.reverse = true;
 		return {
 			public: {
 				table: schema.table,
 				access,
 				column: candidate.column.name,
 				...candidate.index ? { index: candidate.index.name } : {},
-				sort: orderBy.length ? "memory" : "none",
+				sort: ordered ? "none" : "memory",
 				reason: `use ${candidate.index ? `index ${candidate.index.name}` : "primary key"} for ${equalityOnly ? "equality" : "range"}; apply remaining predicates after lookup`
 			},
 			key,
@@ -1964,6 +1995,20 @@ function planAccess(schema, where, orderBy, parameters, indexes) {
 			empty: !key && emptyRange(range)
 		};
 	}
+	if (orderBy.length) for (const candidate of candidates) {
+		if (!traversalOrder(schema, candidate.column, candidate.index, orderBy)) continue;
+		return {
+			public: {
+				table: schema.table,
+				access: candidate.index ? "index-range" : "table-scan",
+				column: candidate.column.name,
+				...candidate.index ? { index: candidate.index.name } : {},
+				sort: "none",
+				reason: `use ${candidate.index ? `index ${candidate.index.name}` : "primary key"} traversal order`
+			},
+			range: { reverse: orderBy[0].direction === "desc" }
+		};
+	}
 	return { public: {
 		table: schema.table,
 		access: "table-scan",
@@ -1971,6 +2016,15 @@ function planAccess(schema, where, orderBy, parameters, indexes) {
 		reason: "no supported primary key or index bound; filter table rows"
 	} };
 }
+function traversalOrder(schema, column, index, orders, key) {
+	if (!orders.length || key && !index) return true;
+	if (orders[0].column !== column.name) return false;
+	if (!index) return orders.length === 1;
+	if (column.type === "INTEGER" && !key) return false;
+	if (orders.length === 1) return orders[0].direction === "asc" || index.unique && !column.nullable;
+	const primary = primaryColumn(schema);
+	return orders.length === 2 && orders[1].column === primary?.name && orders[1].direction === orders[0].direction;
+}
 function planKey(column, value, secondary, equality) {
 	if (value === null) return null;
 	if (column.type === "INTEGER") {
@@ -2023,27 +2077,48 @@ function emptyRange(range) {
 	const compared = compareBytes(lower, upper);
 	return compared > 0 || compared === 0 && (Boolean(range.gt) || Boolean(range.lt));
 }
-async function readRows(tx, schema, plan) {
+async function readRows(tx, schema, plan, where, parameters, maxMatches) {
 	if (plan.empty) return [];
-	let items;
+	const rows = [];
+	const accept = (item) => {
+		if (item.key.length === 1 && item.key[0] === TABLE_OWNER_KEY[0]) return false;
+		const row = decodeRow(schema, item);
+		if (!where || evaluateWhere(row.row, where, parameters) === true) rows.push(row);
+		return maxMatches !== void 0 && rows.length >= maxMatches;
+	};
 	if (plan.public.index) {
-		items = [];
 		const range = plan.key ? {
+			...plan.range,
 			gte: plan.key,
 			lte: plan.key
 		} : plan.range;
-		for await (const [key, value] of tx.scanByIndex(schema.table, plan.public.index, range)) items.push({
+		for await (const [key, value] of tx.scanByIndex(schema.table, plan.public.index, range, { maxRows: Math.min(256, maxMatches ?? 256) })) if (accept({
 			key,
 			value
-		});
+		})) break;
 	} else if (plan.key) {
 		const value = await tx.get(schema.table, plan.key);
-		items = value ? [{
+		if (value) accept({
 			key: plan.key,
 			value
-		}] : [];
-	} else items = await tx.scan(schema.table, plan.range);
-	return items.filter(({ key }) => key.length !== 1 || key[0] !== TABLE_OWNER_KEY[0]).map((item) => decodeRow(schema, item));
+		});
+	} else if (typeof tx.scanPage === "function" && typeof tx.closeScanCursor === "function") {
+		let cursor;
+		try {
+			for (;;) {
+				const page = await tx.scanPage(schema.table, plan.range, {
+					cursor,
+					maxRows: Math.min(256, maxMatches === void 0 ? 256 : maxMatches - rows.length)
+				});
+				cursor = page.cursor;
+				for (const item of page.rows) if (accept(item)) return rows;
+				if (page.done) break;
+			}
+		} finally {
+			if (cursor !== void 0) await tx.closeScanCursor(cursor);
+		}
+	} else for (const item of await tx.scan(schema.table, plan.range)) if (accept(item)) break;
+	return rows;
 }
 function compareRows(left, right, orders) {
 	for (const order of orders) {
@@ -2123,6 +2198,8 @@ function compareBytes(left, right) {
 //#endregion
 //#region src/index.ts
 var INDEX_SCAN_PAGE_ROWS = 256;
+var SCAN_PAGE_ROWS = 256;
+var SCAN_PAGE_BYTES = 8389662;
 async function callProxy(fn) {
 	try {
 		return await fn();
@@ -2135,6 +2212,7 @@ var TransactionImpl = class {
 	#entry;
 	#txId;
 	#closed = false;
+	#scanCursors = /* @__PURE__ */ new Set();
 	#onClose;
 	constructor(entry, txId, mode, onClose) {
 		this.#entry = entry;
@@ -2191,21 +2269,48 @@ var TransactionImpl = class {
 		assertPublicStoreName(store);
 		return callProxy(() => this.#entry.proxy.scan(this.#txId, store, range));
 	}
+	async scanPage(store, range = {}, options = {}) {
+		this.#ensureOpen();
+		assertPublicStoreName(store);
+		const normalized = normalizeScanPageOptions(options);
+		if (normalized.cursor !== void 0 && !this.#scanCursors.has(normalized.cursor)) throw new TypeError("scan cursor does not belong to this transaction");
+		const page = await callProxy(() => this.#entry.proxy.scanPage({
+			txId: this.#txId,
+			store,
+			range,
+			cursorId: normalized.cursor,
+			maxRows: normalized.maxRows,
+			maxBytes: normalized.maxBytes
+		}));
+		this.#ensureOpen();
+		if (normalized.cursor !== void 0) this.#scanCursors.delete(normalized.cursor);
+		if (page.cursorId !== void 0 && !this.#closed) this.#scanCursors.add(page.cursorId);
+		return publicScanPage(page);
+	}
+	scanIter(store, range = {}, options = {}) {
+		return iterateScanPages(this, store, range, options);
+	}
+	async closeScanCursor(cursor) {
+		normalizeScanCursor(cursor);
+		if (!this.#scanCursors.delete(cursor) || this.#entry.invalidated) return;
+		await callProxy(() => this.#entry.proxy.closeCursor(cursor));
+	}
 	async getByIndex(store, indexName, key) {
 		this.#ensureOpen();
 		assertPublicStoreName(store);
 		return callProxy(() => this.#entry.proxy.getByIndex(this.#txId, store, indexName, key));
 	}
-	async *scanByIndex(store, indexName, range = {}) {
+	async *scanByIndex(store, indexName, range = {}, options = {}) {
 		this.#ensureOpen();
 		assertPublicStoreName(store);
+		const { maxRows: pageRows, maxBytes } = normalizeScanPageOptions(options);
 		let remaining = range.limit ?? Number.POSITIVE_INFINITY;
 		let cursor = null;
 		while (remaining > 0) {
 			this.#ensureOpen();
-			const pageLimit = Math.min(remaining, INDEX_SCAN_PAGE_ROWS);
+			const pageLimit = Math.min(remaining, pageRows, INDEX_SCAN_PAGE_ROWS);
 			const resumeAfter = cursor;
-			const page = await callProxy(() => this.#entry.proxy.scanByIndexPage(this.#txId, store, indexName, range, resumeAfter, pageLimit));
+			const page = await callProxy(() => this.#entry.proxy.scanByIndexPage(this.#txId, store, indexName, range, resumeAfter, pageLimit, maxBytes));
 			for (const row of page.rows) yield [row.key, row.value];
 			remaining -= page.rows.length;
 			if (page.cursor === null) return;
@@ -2270,6 +2375,7 @@ var TransactionImpl = class {
 	#markClosed() {
 		if (this.#closed) return;
 		this.#closed = true;
+		this.#scanCursors.clear();
 		this.#onClose();
 	}
 };
@@ -2279,6 +2385,8 @@ var DBImpl = class {
 	#closePromise = null;
 	#transactions = /* @__PURE__ */ new Set();
 	#pendingBegins = /* @__PURE__ */ new Set();
+	#scanCursors = /* @__PURE__ */ new Set();
+	#pendingScanPages = /* @__PURE__ */ new Set();
 	#transactionGeneration = 0;
 	#subscriptions;
 	#unsubscribeTxInvalidated = null;
@@ -2320,20 +2428,17 @@ var DBImpl = class {
 		}
 	}
 	async listStores() {
-		this.#ensureOpen();
-		return callProxy(() => this.#entry.proxy.listStores());
+		return this.#call(() => this.#entry.proxy.listStores());
 	}
 	async listIndexes() {
 		this.#ensureOpen();
 		return callProxy(() => this.#entry.proxy.getIndexes());
 	}
 	async getVersion() {
-		this.#ensureOpen();
-		return callProxy(() => this.#entry.proxy.getVersion());
+		return this.#call(() => this.#entry.proxy.getVersion());
 	}
 	async changesSince(txid, options = {}) {
-		this.#ensureOpen();
-		return callProxy(() => this.#entry.proxy.changesSince(normalizeTxId(txid), normalizeChangeFeedOptions(options)));
+		return this.#call(() => this.#entry.proxy.changesSince(normalizeTxId(txid), normalizeChangeFeedOptions(options)));
 	}
 	async #beginImpl(mode) {
 		this.#ensureOpen();
@@ -2402,60 +2507,82 @@ var DBImpl = class {
 		assertPublicStoreName(store);
 		return this.#autocommit("readonly", "scan", [store, range]);
 	}
+	async scanPage(store, range = {}, options = {}) {
+		this.#ensureOpen();
+		assertPublicStoreName(store);
+		const normalized = normalizeScanPageOptions(options);
+		if (normalized.cursor !== void 0 && !this.#scanCursors.has(normalized.cursor)) throw new TypeError("scan cursor does not belong to this database handle");
+		const generation = this.#transactionGeneration;
+		const pending = callProxy(() => this.#entry.proxy.scanPage({
+			store,
+			range,
+			cursorId: normalized.cursor,
+			maxRows: normalized.maxRows,
+			maxBytes: normalized.maxBytes
+		}));
+		this.#pendingScanPages.add(pending);
+		try {
+			const page = await pending;
+			if (normalized.cursor !== void 0) this.#scanCursors.delete(normalized.cursor);
+			if (page.cursorId !== void 0) this.#scanCursors.add(page.cursorId);
+			this.#ensureOpen();
+			if (generation !== this.#transactionGeneration) {
+				if (page.cursorId !== void 0) await this.closeScanCursor(page.cursorId);
+				throw new TransactionClosedError();
+			}
+			return publicScanPage(page);
+		} finally {
+			this.#pendingScanPages.delete(pending);
+		}
+	}
+	scanIter(store, range = {}, options = {}) {
+		return iterateScanPages(this, store, range, options);
+	}
+	async closeScanCursor(cursor) {
+		normalizeScanCursor(cursor);
+		if (!this.#scanCursors.delete(cursor) || this.#entry.invalidated) return;
+		await callProxy(() => this.#entry.proxy.closeCursor(cursor));
+	}
 	/** The transaction boundary stays in the worker, so one round trip is enough. */
 	async #autocommit(mode, command, args) {
 		this.#ensureOpen();
 		return callProxy(() => this.#entry.proxy.autocommit(mode, command, args));
 	}
 	async exportSnapshot(options = {}) {
-		this.#ensureOpen();
-		return callProxy(async () => {
+		return this.#call(async () => {
 			const bytes = await this.#entry.proxy.exportSnapshot(normalizeExportSnapshotOptions(options));
 			return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
 		});
 	}
 	async importSnapshot(data) {
-		this.#ensureOpen();
-		invalidateTransactions(this.#entry);
-		return callProxy(() => {
+		return this.#callAfterTxInvalidation(() => {
 			const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
 			return this.#entry.proxy.importSnapshot(bytes);
 		});
 	}
 	async reset() {
-		this.#ensureOpen();
-		invalidateTransactions(this.#entry);
-		return callProxy(() => this.#entry.proxy.reset());
+		return this.#callAfterTxInvalidation(() => this.#entry.proxy.reset());
 	}
 	async compact() {
-		this.#ensureOpen();
-		invalidateTransactions(this.#entry);
-		return callProxy(() => this.#entry.proxy.compact());
+		return this.#callAfterTxInvalidation(() => this.#entry.proxy.compact());
 	}
 	async rebuild() {
-		this.#ensureOpen();
-		invalidateTransactions(this.#entry);
-		return callProxy(() => this.#entry.proxy.rebuild());
+		return this.#callAfterTxInvalidation(() => this.#entry.proxy.rebuild());
 	}
 	async stats() {
-		this.#ensureOpen();
-		return callProxy(() => this.#entry.proxy.stats());
+		return this.#call(() => this.#entry.proxy.stats());
 	}
 	async storageInfo() {
-		this.#ensureOpen();
-		return callProxy(() => this.#entry.proxy.storageInfo());
+		return this.#call(() => this.#entry.proxy.storageInfo());
 	}
 	async requestPersistence() {
-		this.#ensureOpen();
-		return callProxy(() => this.#entry.proxy.requestPersistence());
+		return this.#call(() => this.#entry.proxy.requestPersistence());
 	}
 	async destroy() {
-		this.#ensureOpen();
-		return callProxy(() => this.#entry.destroy?.() ?? destroyDbWorker(this.#entry));
+		return this.#call(() => this.#entry.destroy?.() ?? destroyDbWorker(this.#entry));
 	}
 	async setFailpoint(failpoint) {
-		this.#ensureOpen();
-		return callProxy(() => this.#entry.proxy.setFailpoint(failpoint));
+		return this.#call(() => this.#entry.proxy.setFailpoint(failpoint));
 	}
 	subscribe(arg1, arg2, arg3) {
 		this.#ensureOpen();
@@ -2481,7 +2608,10 @@ var DBImpl = class {
 	}
 	async #finishClose() {
 		await Promise.allSettled(Array.from(this.#pendingBegins));
+		await Promise.allSettled(Array.from(this.#pendingScanPages));
 		let rollbackError = null;
+		const cursorResults = await Promise.allSettled(Array.from(this.#scanCursors, (cursor) => this.closeScanCursor(cursor)));
+		for (const result of cursorResults) if (result.status === "rejected" && rollbackError === null) rollbackError = normalizeError(result.reason);
 		const txs = Array.from(this.#transactions);
 		if (txs.length > 0) {
 			const results = await Promise.allSettled(txs.map((tx) => tx.rollbackIfOpen()));
@@ -2502,6 +2632,7 @@ var DBImpl = class {
 	}
 	#forceCloseTransactions() {
 		this.#transactionGeneration += 1;
+		this.#scanCursors.clear();
 		for (const tx of Array.from(this.#transactions)) tx.forceClose();
 	}
 	#markInvalidated() {
@@ -2511,6 +2642,15 @@ var DBImpl = class {
 		this.#forceCloseTransactions();
 		this.#subscriptions.close();
 	}
+	#call(run) {
+		this.#ensureOpen();
+		return callProxy(run);
+	}
+	#callAfterTxInvalidation(run) {
+		this.#ensureOpen();
+		invalidateTransactions(this.#entry);
+		return callProxy(run);
+	}
 	#ensureOpen() {
 		if (this.#closed || this.#entry.invalidated) throw new DatabaseClosedError();
 	}
@@ -2573,11 +2713,20 @@ var MigrationTransactionImpl = class {
 	async scan(store, range = {}) {
 		return this.#inner.scan(store, range);
 	}
+	scanPage(store, range = {}, options = {}) {
+		return this.#inner.scanPage(store, range, options);
+	}
+	scanIter(store, range = {}, options = {}) {
+		return this.#inner.scanIter(store, range, options);
+	}
+	closeScanCursor(cursor) {
+		return this.#inner.closeScanCursor(cursor);
+	}
 	async getByIndex(store, indexName, key) {
 		return this.#inner.getByIndex(store, indexName, key);
 	}
-	scanByIndex(store, indexName, range = {}) {
-		return this.#inner.scanByIndex(store, indexName, range);
+	scanByIndex(store, indexName, range = {}, options = {}) {
+		return this.#inner.scanByIndex(store, indexName, range, options);
 	}
 	async createStore(name, options = {}) {
 		await this.#inner.createStore(name, options);
@@ -2648,6 +2797,15 @@ var MigrationDbImpl = class {
 	async scan(store, range = {}) {
 		return this.#transaction.scan(store, range);
 	}
+	scanPage(store, range = {}, options = {}) {
+		return this.#transaction.scanPage(store, range, options);
+	}
+	scanIter(store, range = {}, options = {}) {
+		return this.#transaction.scanIter(store, range, options);
+	}
+	closeScanCursor(cursor) {
+		return this.#transaction.closeScanCursor(cursor);
+	}
 	exportSnapshot(_options = {}) {
 		return Promise.reject(migrationUnsupportedMethod("db.exportSnapshot"));
 	}
@@ -2693,8 +2851,61 @@ function migrationUnsupportedMethod(method) {
 	error.name = "InvalidStateError";
 	return error;
 }
+function publicScanPage(page) {
+	return {
+		rows: page.rows,
+		cursor: page.cursorId,
+		done: page.done,
+		bytes: page.bytes
+	};
+}
+function normalizeScanCursor(value) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new TypeError("scan cursor must be a positive safe integer");
+	return value;
+}
+function normalizeScanPageOptions(options) {
+	const input = normalizeOptionsObject(options, "scan page options must be an object");
+	const maxRows = input.maxRows ?? SCAN_PAGE_ROWS;
+	const maxBytes = input.maxBytes ?? SCAN_PAGE_BYTES;
+	if (!Number.isSafeInteger(maxRows) || maxRows <= 0 || maxRows > 4294967295) throw new TypeError("scan page maxRows must be a positive 32-bit integer");
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 4 || maxBytes > 4294967295) throw new TypeError("scan page maxBytes must be a 32-bit integer of at least 4");
+	return {
+		maxRows,
+		maxBytes,
+		cursor: input.cursor === void 0 ? void 0 : normalizeScanCursor(input.cursor)
+	};
+}
+async function* iterateScanPages(source, store, range, options) {
+	const bounds = { ...range };
+	for (const field of [
+		"gt",
+		"gte",
+		"lt",
+		"lte"
+	]) {
+		const bound = bounds[field];
+		if (bound instanceof Uint8Array) bounds[field] = bound.slice();
+	}
+	const pageOptions = normalizeScanPageOptions(options);
+	let cursor;
+	try {
+		for (;;) {
+			const page = await source.scanPage(store, bounds, {
+				...pageOptions,
+				cursor
+			});
+			cursor = page.cursor;
+			for (const row of page.rows) yield row;
+			if (page.done) return;
+		}
+	} finally {
+		if (cursor !== void 0) await source.closeScanCursor(cursor);
+	}
+}
 function normalizeDatabaseName(value, method) {
 	if (typeof value !== "string" || value.length === 0) throw new TypeError(`${method}() database name must be a non-empty string`);
+	if (/[\uD800-\uDFFF]/u.test(value)) throw new TypeError(`${method}() database name must contain valid Unicode`);
+	if (new TextEncoder().encode(value).length > 127) throw new TypeError(`${method}() database name must contain at most 127 UTF-8 bytes`);
 	return value;
 }
 var typeError = (message) => new TypeError(message);
@@ -2722,17 +2933,17 @@ function normalizePutOptions(options) {
 	const normalizedTtl = normalizeOptionalNonNegativeSafeInteger(ttl, "ttl must be a non-negative safe integer");
 	return normalizedTtl === void 0 ? {} : { ttl: normalizedTtl };
 }
-function normalizeCompressionOptions(options, message) {
+function normalizeCompressionOptions(options, message, allowSnappy) {
 	const { compression } = normalizeOptionsObject(options, message);
 	if (compression === void 0) return {};
-	if (compression !== false && compression !== "gzip" && compression !== "deflate") throw new TypeError("compression must be \"gzip\", \"deflate\", or false");
+	if (compression !== false && compression !== "gzip" && compression !== "deflate" && !(allowSnappy && compression === "snappy")) throw new TypeError(allowSnappy ? "compression must be \"gzip\", \"deflate\", \"snappy\", or false" : "compression must be \"gzip\", \"deflate\", or false");
 	return { compression };
 }
 function normalizeCreateStoreOptions(options) {
-	return normalizeCompressionOptions(options, "createStore options must be an object");
+	return normalizeCompressionOptions(options, "createStore options must be an object", true);
 }
 function normalizeExportSnapshotOptions(options) {
-	return normalizeCompressionOptions(options, "exportSnapshot options must be an object");
+	return normalizeCompressionOptions(options, "exportSnapshot options must be an object", false);
 }
 function normalizeTxId(value) {
 	return normalizeNonNegativeSafeInteger(value, "txid must be a non-negative safe integer");
@@ -2883,6 +3094,9 @@ var NodeWorkerTransport = class {
 var LOCK_DIRECTORY = ".moyodb.lock";
 var PENDING_PREFIX = ".moyodb.pending-";
 var TOKEN_PATTERN = /^[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}$/i;
+var MAX_LEASE_RECORD_BYTES = 1024;
+var MAX_LEASE_PID = 4294967295;
+var MISSING_DATABASE_MESSAGE = "database missing and create_if_missing=false";
 function namedError(name, message, cause) {
 	const error = new Error(message, cause === void 0 ? void 0 : { cause });
 	error.name = name;
@@ -2928,9 +3142,9 @@ function readLease(directory, token) {
 	const lockDirectory = join(directory, LOCK_DIRECTORY);
 	entryStat(lockDirectory, "directory");
 	const recordPath = join(lockDirectory, `${validateToken(token)}.json`);
-	entryStat(recordPath, "file");
+	if (entryStat(recordPath, "file").size > MAX_LEASE_RECORD_BYTES) throw namedError("DatabaseBusyError", "storage lock owner cannot be verified");
 	const owner = JSON.parse(fs.readFileSync(recordPath, "utf8"));
-	if (owner.token !== token || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) throw namedError("DatabaseBusyError", "storage lock owner cannot be verified");
+	if (owner.token !== token || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 || owner.pid > MAX_LEASE_PID) throw namedError("DatabaseBusyError", "storage lock owner cannot be verified");
 	return {
 		lockDirectory,
 		recordPath,
@@ -3011,6 +3225,21 @@ function releaseNodeStorageLease(directory, lockToken) {
 		throw storageError(error);
 	}
 }
+function ensureStorageRoot(directory, createIfMissing = true) {
+	const path = validateDirectory(directory);
+	if (!createIfMissing) {
+		try {
+			entryStat(path, "directory");
+		} catch (error) {
+			if (error?.code === "ENOENT") throw namedError("StorageError", MISSING_DATABASE_MESSAGE);
+			if (error?.name === "TypeMismatchError" || error?.name === "SecurityError") throw error;
+			throw storageError(error);
+		}
+		return path;
+	}
+	fs.mkdirSync(path, { recursive: true });
+	return path;
+}
 //#endregion
 //#region src/node.ts
 var registry = /* @__PURE__ */ new Map();
@@ -3035,7 +3264,12 @@ function validateDirectoryOptions(options) {
 	if (typeof directory !== "string" || directory.length === 0 || directory.includes("\0")) throw new InvalidOpenOptionsError("directory must be a non-empty filesystem path");
 }
 async function databaseLocation(name, options) {
-	await mkdir(options.directory, { recursive: true });
+	try {
+		ensureStorageRoot(options.directory, options.createIfMissing !== false);
+	} catch (error) {
+		if (error instanceof Error && error.name === "StorageError") throw new StorageError(error.message || "database missing and create_if_missing=false");
+		throw error;
+	}
 	const root = await realpath(options.directory);
 	const directory = join(root, "stackdb", Buffer.from(name, "utf8").toString("hex"));
 	return {
@@ -3069,7 +3303,8 @@ function createEntry(dbName, directory, registryKey, options) {
 		channelName,
 		lockToken,
 		ownerWaitMs: normalized.ownerWaitMs,
-		encodedDbName: Buffer.from(dbName, "utf8").toString("hex")
+		encodedDbName: Buffer.from(dbName, "utf8").toString("hex"),
+		createIfMissing: normalized.createIfMissing
 	}, () => {
 		releaseNodeStorageLease(directory, lockToken);
 	});