@atscript/db-memory 0.1.149 → 0.1.151

package/dist/index.mjs

@@ -1,6 +1,69 @@
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, containsRelationFilter, deletePath, evaluateExpr, forEachResolvedRelation, getPath, getPath as getPath$1, isAtscriptDbView, isConflict, isResolvedRelationFilter, walkFilter } from "@atscript/db";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, INTEGER_REGEX_OP, containsRelationFilter, deletePath, evaluateExpr, forEachResolvedRelation, getPath, isAtscriptDbView, isConflict, isPlainObject, isResolvedRelationFilter, walkFilter } from "@atscript/db";
 import { assertAggregateFn, resolveAlias } from "@atscript/db/agg";
 import { bucketer } from "@uniqu/core";
+//#region src/lib/memory-clone.ts
+/**
+* Deep clone with the exact observable result of `structuredClone` — fast for
+* the plain data the store holds (plain objects, dense arrays, `Date`s and
+* primitives), and delegating to `structuredClone` for everything else.
+*
+* The fast walk gives up — and the WHOLE value is re-cloned by
+* `structuredClone` — on anything whose `structuredClone` result it would not
+* reproduce exactly: a function or symbol (so the `DataCloneError` still
+* throws), a non-plain prototype (class instances, `Map`, `Set`, typed arrays,
+* `RegExp`, boxed primitives, …), an own `__proto__` key, a sparse array or
+* one carrying extra own properties, and an object reached twice (a cycle or a
+* shared subtree — `structuredClone` preserves both, a tree walk would not).
+*/
+function cloneValue(value) {
+	if (value === null || typeof value !== "object") return typeof value === "function" || typeof value === "symbol" ? structuredClone(value) : value;
+	const out = walk(value, /* @__PURE__ */ new Set());
+	return out === GIVE_UP ? structuredClone(value) : out;
+}
+const GIVE_UP = Symbol("give-up");
+const OBJECT_PROTO = Object.prototype;
+const ARRAY_PROTO = Array.prototype;
+const DATE_PROTO = Date.prototype;
+function walk(value, seen) {
+	if (seen.has(value)) return GIVE_UP;
+	seen.add(value);
+	const proto = Object.getPrototypeOf(value);
+	if (proto === ARRAY_PROTO) {
+		const src = value;
+		const len = src.length;
+		const arr = [];
+		for (let i = 0; i < len; i++) {
+			if (!(i in src)) return GIVE_UP;
+			const item = leaf(src[i], seen);
+			if (item === GIVE_UP) return GIVE_UP;
+			arr.push(item);
+		}
+		return Object.keys(src).length === len ? arr : GIVE_UP;
+	}
+	if (proto === OBJECT_PROTO || proto === null) {
+		const src = value;
+		const obj = {};
+		for (const key of Object.keys(src)) {
+			if (key === "__proto__") return GIVE_UP;
+			const item = leaf(src[key], seen);
+			if (item === GIVE_UP) return GIVE_UP;
+			obj[key] = item;
+		}
+		return obj;
+	}
+	if (proto === DATE_PROTO) return new Date(value.getTime());
+	return GIVE_UP;
+}
+function leaf(value, seen) {
+	if (value === null) return null;
+	switch (typeof value) {
+		case "object": return walk(value, seen);
+		case "function":
+		case "symbol": return GIVE_UP;
+		default: return value;
+	}
+}
+//#endregion
 //#region src/lib/memory-filter.ts
 /**
 * {@link getPath} compiled for one path: split once, and a single segment is
@@ -70,9 +133,8 @@ function parseRegexString(value) {
 function stringifyLeaf(v) {
 	return String(v);
 }
-/** `$eq` semantics, factored out so `$ne` can be its exact negation. */
-function evalEq(row, field, value) {
-	const fieldValue = getPath$1(row, field);
+/** `$eq` semantics over the field's value, factored out so `$ne` can be its exact negation. */
+function evalEq(fieldValue, value) {
 	if (value === null) return matchesScalar(fieldValue, null);
 	if (value instanceof RegExp) return fieldValue != null && value.test(stringifyLeaf(fieldValue));
 	return matchesScalar(fieldValue, value);
@@ -88,11 +150,37 @@ function matchesScalar(fieldValue, value) {
 	if (Array.isArray(fieldValue) && !Array.isArray(value)) return fieldValue.some((el) => valuesEqual(el, value));
 	return valuesEqual(fieldValue, value);
 }
-/** `$in` membership, factored out so `$nin` can be its exact negation. */
-function evalIn(row, field, value) {
-	if (!Array.isArray(value)) return false;
-	const fieldValue = getPath$1(row, field);
-	return value.some((element) => matchesScalar(fieldValue, element));
+/**
+* `$in` membership compiled once per filter leaf, factored out so `$nin` can be
+* its exact negation: true iff the field value {@link matchesScalar matches}
+* SOME element. Primitive elements (and `Date`s, by instant) are looked up in a
+* `Set` instead of scanned per row — `NaN` is left out of it (it equals
+* nothing, while a `Set` would find it), `-0`/`0` collapse as under `===`.
+* Any other element (an object / array — reference equality) keeps the scan.
+*/
+function compileIn(value) {
+	if (!Array.isArray(value)) return () => false;
+	const primitives = /* @__PURE__ */ new Set();
+	const instants = /* @__PURE__ */ new Set();
+	const rest = [];
+	let hasNull = false;
+	for (const element of value) if (element === null) hasNull = true;
+	else if (element instanceof Date) {
+		const time = element.getTime();
+		if (!Number.isNaN(time)) instants.add(time);
+	} else if (typeof element === "object") rest.push(element);
+	else if (!(typeof element === "number" && Number.isNaN(element))) primitives.add(element);
+	const one = (v) => v instanceof Date ? instants.has(v.getTime()) : (v === null || typeof v !== "object") && primitives.has(v);
+	return (fieldValue) => {
+		if (Array.isArray(fieldValue)) {
+			if (hasNull && fieldValue.includes(null)) return true;
+			for (const el of fieldValue) if (one(el)) return true;
+			return rest.some((el) => Array.isArray(el) ? el === fieldValue : fieldValue.includes(el));
+		}
+		if (fieldValue === null) return hasNull;
+		if (fieldValue === void 0) return hasNull || primitives.has(void 0);
+		return one(fieldValue) || rest.includes(fieldValue);
+	};
 }
 /**
 * Coerce a leaf to something the JS relational operators can order. `Date`s
@@ -110,8 +198,7 @@ function toOrdinal(v) {
 * lexicographically) — NO collation or locale awareness. This intentionally
 * differs from SQL engines' collated ordering.
 */
-function evalRelational(row, field, op, value) {
-	const fieldValue = getPath$1(row, field);
+function evalRelational(fieldValue, op, value) {
 	if (fieldValue === void 0 || fieldValue === null) return false;
 	const a = toOrdinal(fieldValue);
 	const b = toOrdinal(value);
@@ -143,24 +230,39 @@ const memoryVisitor = {
 		return (row) => !child(row);
 	},
 	comparison(field, op, value) {
+		const read = pathReader(field);
+		if (op === INTEGER_REGEX_OP) {
+			const { pattern, flags } = parseRegexString(value);
+			const regex = new RegExp(pattern, flags);
+			return (row) => {
+				const fieldValue = read(row);
+				return (typeof fieldValue === "bigint" || typeof fieldValue === "number" && Number.isInteger(fieldValue)) && regex.test(String(fieldValue));
+			};
+		}
 		switch (op) {
-			case "$eq": return (row) => evalEq(row, field, value);
-			case "$ne": return (row) => !evalEq(row, field, value);
+			case "$eq": return (row) => evalEq(read(row), value);
+			case "$ne": return (row) => !evalEq(read(row), value);
 			case "$gt":
 			case "$gte":
 			case "$lt":
-			case "$lte": return (row) => evalRelational(row, field, op, value);
-			case "$in": return (row) => evalIn(row, field, value);
-			case "$nin": return (row) => !evalIn(row, field, value);
+			case "$lte": return (row) => evalRelational(read(row), op, value);
+			case "$in": {
+				const isIn = compileIn(value);
+				return (row) => isIn(read(row));
+			}
+			case "$nin": {
+				const isIn = compileIn(value);
+				return (row) => !isIn(read(row));
+			}
 			case "$regex": {
 				const { pattern, flags } = parseRegexString(value);
 				const regex = new RegExp(pattern, flags);
 				return (row) => {
-					const fieldValue = getPath$1(row, field);
+					const fieldValue = read(row);
 					return fieldValue != null && regex.test(stringifyLeaf(fieldValue));
 				};
 			}
-			case "$exists": return (row) => value === !evalEq(row, field, null);
+			case "$exists": return (row) => value === !evalEq(read(row), null);
 			default: throw new DbError("INVALID_QUERY", [{
 				path: field,
 				message: `Unsupported filter operator: ${op}`
@@ -182,7 +284,7 @@ const memoryVisitor = {
 function correlationKey(row, fields) {
 	const parts = [];
 	for (const field of fields) {
-		const part = keyPart(getPath$1(row, field));
+		const part = keyPart(getPath(row, field));
 		if (part === void 0) return;
 		parts.push(part);
 	}
@@ -357,7 +459,10 @@ function compareLeaves(a, b) {
 * nested dot-paths both work.
 */
 function setPath(target, path, value) {
-	const segments = path.split(".");
+	setSegments(target, path.split("."), value);
+}
+/** {@link setPath} over an already-split path. */
+function setSegments(target, segments, value) {
 	let current = target;
 	for (let i = 0; i < segments.length - 1; i++) {
 		const seg = segments[i];
@@ -377,31 +482,88 @@ function setPath(target, path, value) {
 *   rows with equal sort keys still order deterministically. When ABSENT the
 *   sort falls back to preserving input order among equal keys (via each row's
 *   original index), so a consumer with no primary key keeps insertion order.
+* - `topK` (since 0.1.151), when supplied, asks for only the first `topK` rows
+*   of that order (e.g. `$skip + $limit`): a small one is selected in one pass
+*   instead of sorting everything. The rows returned are exactly the head of
+*   the full sort — same comparator, same stable tie handling.
 *
-* NEVER mutates the input array: `.map` decorates into a fresh array and
-* `.toSorted` returns another new sorted array (unlike `.sort`, which reorders
-* in place). The `tieBreak`/index is computed ONCE per row (O(n)), not inside
-* the O(n log n) comparator.
+* NEVER mutates the input array. Each row's sort keys are read ONCE (O(n)) and
+* its `tieBreak` only when two rows tie on every key — not inside the
+* O(n log n) comparator.
 */
-function sortRows(rows, $sort, tieBreak) {
+function sortRows(rows, $sort, tieBreak, topK) {
 	const keys = $sort ? Object.entries($sort) : [];
 	if (keys.length === 0) return rows;
-	return rows.map((row, index) => ({
+	const readers = keys.map(([field]) => pathReader(field));
+	const desc = keys.map(([, dir]) => dir === -1);
+	const decorated = rows.map((row, index) => ({
 		row,
 		index,
-		tie: tieBreak?.(row)
-	})).toSorted((a, b) => {
-		for (const [field, dir] of keys) {
-			const cmp = compareLeaves(getPath(a.row, field), getPath(b.row, field));
-			if (cmp !== 0) return dir === -1 ? -cmp : cmp;
+		keys: readers.map((read) => {
+			const value = read(row);
+			return value instanceof Date ? value.getTime() : value;
+		}),
+		tie: void 0
+	}));
+	const compare = (a, b) => {
+		for (let i = 0; i < desc.length; i++) {
+			const cmp = compareLeaves(a.keys[i], b.keys[i]);
+			if (cmp !== 0) return desc[i] ? -cmp : cmp;
 		}
 		if (tieBreak) {
-			const at = a.tie;
-			const bt = b.tie;
+			const at = a.tie ??= tieBreak(a.row);
+			const bt = b.tie ??= tieBreak(b.row);
 			return at < bt ? -1 : at > bt ? 1 : 0;
 		}
 		return a.index - b.index;
-	}).map((decorated) => decorated.row);
+	};
+	return (topK !== void 0 && topK <= TOP_K_MAX && topK * 4 < decorated.length && totallyOrdered(decorated, desc.length) ? selectTop(decorated, topK, compare) : decorated.toSorted(compare)).map((entry) => entry.row);
+}
+/**
+* Whether every sort key holds values of ONE ordered kind — numbers (`Date`s
+* included) without `NaN`, strings, or booleans — besides `null`/missing.
+* Only then is the comparator a total order, so selecting the head gives
+* exactly the rows the full (stable) sort puts first; mixed kinds compare
+* inconsistently (`"a" < 1` and `"a" > 1` are both false), and their full
+* sort order depends on the algorithm, so it keeps the full sort.
+*/
+function totallyOrdered(entries, keyCount) {
+	for (let i = 0; i < keyCount; i++) {
+		let kind;
+		for (const entry of entries) {
+			const value = entry.keys[i];
+			if (value === null || value === void 0) continue;
+			const type = typeof value;
+			if (type === "number" ? Number.isNaN(value) : type !== "string" && type !== "boolean") return false;
+			if (kind === void 0) kind = type;
+			else if (kind !== type) return false;
+		}
+	}
+	return true;
+}
+/** Largest `topK` {@link sortRows} selects in one pass instead of sorting. */
+const TOP_K_MAX = 128;
+/**
+* The first `k` entries of the stable sort by `compare`, in order: a bounded
+* sorted buffer, each entry inserted AFTER its equals (entries arrive in input
+* order, so ties keep it — exactly as the stable full sort does).
+*/
+function selectTop(entries, k, compare) {
+	const top = [];
+	if (k <= 0) return top;
+	for (const entry of entries) {
+		if (top.length === k && compare(entry, top[k - 1]) >= 0) continue;
+		let lo = 0;
+		let hi = top.length;
+		while (lo < hi) {
+			const mid = lo + hi >>> 1;
+			if (compare(entry, top[mid]) < 0) hi = mid;
+			else lo = mid + 1;
+		}
+		top.splice(lo, 0, entry);
+		if (top.length > k) top.pop();
+	}
+	return top;
 }
 /**
 * Applies `$skip` then `$limit` (both optional) via a single slice. No-op
@@ -430,24 +592,121 @@ function paginate(rows, skip, limit) {
 *
 * Top-level and nested dot-paths are supported; exotic Mongo projection quirks
 * (array positional, `$slice`, etc.) are intentionally NOT replicated.
+*
+* Clones are `structuredClone`-equivalent. To project many rows the same way,
+* compile once with {@link compileProjection}.
 */
 function projectRow(row, projection, opts) {
+	return compileProjection(projection, opts)(row);
+}
+/**
+* {@link projectRow} compiled for one projection: the projection map is read
+* and every dot-path split once, then applied to each row.
+*/
+function compileProjection(projection, opts) {
 	const clone = opts?.clone ?? false;
 	const entries = projection ? Object.entries(projection) : [];
-	if (entries.length === 0) return clone ? structuredClone(row) : row;
+	if (entries.length === 0) return clone ? cloneValue : (row) => row;
 	if (entries[0][1] === 1) {
 		const paths = new Set(entries.filter(([, v]) => v === 1).map(([k]) => k));
 		for (const pk of opts?.pkFields ?? []) paths.add(pk);
-		const out = {};
-		for (const path of paths) {
-			const value = getPath(row, path);
-			if (value !== void 0) setPath(out, path, value);
-		}
-		return clone ? structuredClone(out) : out;
+		const plan = [...paths].map((path) => ({
+			read: pathReader(path),
+			segments: path.split(".")
+		}));
+		return (row) => {
+			const out = {};
+			for (const { read, segments } of plan) {
+				const value = read(row);
+				if (value !== void 0) setSegments(out, segments, value);
+			}
+			return clone ? cloneValue(out) : out;
+		};
+	}
+	const dropped = entries.filter(([, v]) => v === 0).map(([path]) => path.split("."));
+	return (row) => {
+		const out = cloneValue(row);
+		for (const segments of dropped) deletePath(out, segments);
+		return out;
+	};
+}
+//#endregion
+//#region src/lib/memory-unique.ts
+/** Builds an empty {@link RecordedUniqueIndex}. */
+function recordUniqueIndex(name, fields, optionalFields) {
+	return {
+		name,
+		fields,
+		readers: fields.map((field) => pathReader(field)),
+		optional: fields.map((field) => optionalFields.has(field)),
+		entries: /* @__PURE__ */ new Map()
+	};
+}
+/**
+* Identity of `row`'s tuple in `index`, or `undefined` when the row can never
+* collide in it. Two rows collide exactly when every component is equal under
+* the memory filter's strict equality (`valuesEqual`: `===`, `Date`s by
+* instant), so each component is type-tagged:
+*
+* - an optional member absent / `null` → `undefined` (present-only index);
+* - `NaN`, an invalid `Date`, or any other object (arrays included — compared
+*   by reference, and rows never share one) → `undefined`: equal to nothing;
+* - a required member that is `null` or missing is a value like any other
+*   (`null` ≠ missing).
+*/
+function uniqueTupleKey(index, row) {
+	const parts = [];
+	for (let i = 0; i < index.readers.length; i++) {
+		const value = index.readers[i](row);
+		if (index.optional[i] && (value === null || value === void 0)) return;
+		const part = tuplePart(value);
+		if (part === void 0) return;
+		parts.push(part);
+	}
+	return JSON.stringify(parts);
+}
+function tuplePart(value) {
+	switch (typeof value) {
+		case "string": return `s:${value}`;
+		case "number": return Number.isNaN(value) ? void 0 : `n:${value === 0 ? 0 : value}`;
+		case "bigint": return `b:${value}`;
+		case "boolean": return `t:${value}`;
+		case "undefined": return "u";
+		default:
+			if (value === null) return "z";
+			if (value instanceof Date) {
+				const time = value.getTime();
+				return Number.isNaN(time) ? void 0 : `d:${time}`;
+			}
+			return;
+	}
+}
+/** Records `row` (stored under `key`) in every index; `tuples` are its precomputed tuple keys. */
+function indexRow(indexes, key, row, tuples) {
+	for (let i = 0; i < indexes.length; i++) {
+		const index = indexes[i];
+		const tuple = tuples ? tuples[i] : uniqueTupleKey(index, row);
+		if (tuple === void 0) continue;
+		const holders = index.entries.get(tuple);
+		if (holders) holders.add(key);
+		else index.entries.set(tuple, new Set([key]));
 	}
-	const out = structuredClone(row);
-	for (const [path, v] of entries) if (v === 0) deletePath(out, path);
-	return out;
+}
+/** Removes `row` (stored under `key`) from every index. */
+function unindexRow(indexes, key, row) {
+	for (const index of indexes) {
+		const tuple = uniqueTupleKey(index, row);
+		if (tuple === void 0) continue;
+		const holders = index.entries.get(tuple);
+		if (holders?.delete(key) && holders.size === 0) index.entries.delete(tuple);
+	}
+}
+/** Whether a row other than the one stored under `excludeKey` holds `tuple`. */
+function tupleTaken(index, tuple, excludeKey) {
+	const holders = index.entries.get(tuple);
+	if (!holders) return false;
+	if (excludeKey === void 0 || !holders.has(excludeKey)) return holders.size > 0;
+	return holders.size > 1;
 }
 //#endregion
 //#region src/lib/memory-aggregate.ts
@@ -542,7 +801,7 @@ function aggregateRows(rows, controls) {
 }
 /** Group values and min / max results may be store-owned objects (JSON values): hand back copies. */
 function copyValue(value) {
-	return value !== null && typeof value === "object" ? structuredClone(value) : value;
+	return value !== null && typeof value === "object" ? cloneValue(value) : value;
 }
 /** Reads one `$groupBy` key off a row: a bucket alias → its label, a path → its value. */
 function groupKeyReader(key, controls) {
@@ -735,6 +994,8 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	_db = /* @__PURE__ */ new Map();
 	/** Memoized physical PK field names — stable for the adapter's lifetime. */
 	_pkFieldsCache;
+	/** Memoized compiled readers of {@link _physicalPkFields}. */
+	_pkReadersCache;
 	/**
 	* Memoized map of PHYSICAL field name → optional `start` for every field
 	* carrying `@db.default.increment`. Stable per adapter (see
@@ -847,6 +1108,7 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 				kind: this._table.isView ? "view" : "table",
 				rows: /* @__PURE__ */ new Map(),
 				uniqueIndexes: [],
+				opaquePk: false,
 				incrementCounters: /* @__PURE__ */ new Map()
 			};
 			db.set(name, state);
@@ -867,6 +1129,10 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 		this._pkFieldsCache = fields;
 		return fields;
 	}
+	/** Compiled readers of {@link _physicalPkFields} (memoized like it). */
+	_pkReaders() {
+		return this._pkReadersCache ??= this._physicalPkFields().map((field) => pathReader(field));
+	}
 	/**
 	* PHYSICAL field name → optional `start` for every `@db.default.increment`
 	* field. Discovered lazily from the table's field descriptors — each carries
@@ -946,8 +1212,25 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	* `['a:b','c']` differ, and `1` differs from `'1'`.
 	*/
 	pkKey(row) {
-		const values = this._physicalPkFields().map((field) => getPath$1(row, field));
-		return JSON.stringify(values);
+		const readers = this._pkReaders();
+		return JSON.stringify(readers.length === 1 ? [readers[0](row)] : readers.map((r) => r(row)));
+	}
+	/**
+	* The storage key a filter pins by exact equality on EVERY primary-key field
+	* — `{ id: v }`, `{ id: { $eq: v } }`, also inside (nested) `$and` — or
+	* `undefined`. Only a string / number / boolean / `Date` value pins: for
+	* those, a row the filter matches is stored exactly under this key (strict
+	* equality ⇒ equal `JSON.stringify`), so a read can look the row up and
+	* still run the full predicate on it. Unavailable once the table holds an
+	* {@link MemoryTableState.opaquePk opaque} key.
+	*/
+	_pinnedKey(state, filter) {
+		if (state.opaquePk) return;
+		const fields = this._physicalPkFields();
+		const pinned = /* @__PURE__ */ new Map();
+		collectPins(filter, fields, pinned);
+		if (pinned.size !== fields.length) return;
+		return JSON.stringify(fields.map((field) => pinned.get(field)));
 	}
 	/**
 	* Builds a DEFINED inserted-id for a table with NO single `@meta.id` — a
@@ -967,7 +1250,7 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	*/
 	_compositeInsertedId(row) {
 		const id = {};
-		for (const field of this._physicalPkFields()) id[field] = getPath$1(row, field);
+		for (const field of this._physicalPkFields()) id[field] = getPath(row, field);
 		return id;
 	}
 	/**
@@ -1056,20 +1339,21 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	/**
 	* Clones the payload in, applies the version default, generates any
 	* `@db.default.increment` values, enforces PK + unique constraints, stores
-	* the row, and returns the resolved inserted id. Clone-in (`structuredClone`)
-	* is what makes post-insert mutation of the caller's object never leak into
+	* the row, and returns the resolved inserted id. Clone-in ({@link cloneValue},
+	* `structuredClone`-equivalent) is what makes post-insert mutation of the
+	* caller's object never leak into
 	* the store. Called once per item by both `insertOne` and `insertMany`, so
 	* increment values advance sequentially across a batch.
 	*/
 	_insertRow(state, data) {
-		const row = structuredClone(data);
+		const row = cloneValue(data);
 		const versionColumn = this._table.versionColumnPhysical;
 		if (versionColumn !== void 0 && !(versionColumn in row)) row[versionColumn] = 0;
 		this._applyIncrements(state.incrementCounters, row);
 		const key = this.pkKey(row);
 		if (state.rows.has(key)) throw this._pkConflict();
-		this._enforceUniqueIndexes(state, row);
-		state.rows.set(key, row);
+		const tuples = this._enforceUniqueIndexes(state, row);
+		this._storeRow(state, key, row, tuples);
 		const fallback = this._table.metaIdPhysical ? void 0 : this._compositeInsertedId(row);
 		return this._resolveInsertedId(row, fallback);
 	}
@@ -1077,38 +1361,40 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	* Enforces every recorded unique index against the current store. A row is
 	* exempted from an index (present-only semantics) when ANY of that index's
 	* optional fields is absent/`null`. Otherwise a stored row with an equal
-	* tuple → `CONFLICT`.
+	* tuple → `CONFLICT`. Returns the row's tuple key per index (for
+	* {@link _storeRow}).
 	*
 	* `excludeKey` (when given) skips the row stored under that {@link pkKey} — so
 	* a row updating its own unique value does not false-conflict with itself.
 	*/
 	_enforceUniqueIndexes(state, row, excludeKey) {
-		for (const index of state.uniqueIndexes) {
-			const tuple = [];
-			let skip = false;
-			for (const field of index.fields) {
-				const value = getPath$1(row, field);
-				if (index.optionalFields.has(field) && (value === null || value === void 0)) {
-					skip = true;
-					break;
-				}
-				tuple.push(value);
-			}
-			if (skip) continue;
-			for (const [existingKey, existing] of state.rows) {
-				if (excludeKey !== void 0 && existingKey === excludeKey) continue;
-				let equal = true;
-				for (let i = 0; i < index.fields.length; i++) if (!valuesEqual(getPath$1(existing, index.fields[i]), tuple[i])) {
-					equal = false;
-					break;
-				}
-				if (equal) throw new DbError("CONFLICT", [{
-					path: index.fields[0] ?? index.name,
-					message: `Duplicate value for unique index "${index.name}"`
-				}]);
-			}
+		return state.uniqueIndexes.map((index) => {
+			const tuple = uniqueTupleKey(index, row);
+			if (tuple !== void 0 && tupleTaken(index, tuple, excludeKey)) throw new DbError("CONFLICT", [{
+				path: index.fields[0] ?? index.name,
+				message: `Duplicate value for unique index "${index.name}"`
+			}]);
+			return tuple;
+		});
+	}
+	/**
+	* Stores `row` under `key` and records it in the unique indexes (`tuples`:
+	* its precomputed tuple keys). The ONLY way a row enters the store, so the
+	* indexes and {@link MemoryTableState.opaquePk} never drift from it.
+	*/
+	_storeRow(state, key, row, tuples) {
+		state.rows.set(key, row);
+		indexRow(state.uniqueIndexes, key, row, tuples);
+		if (!state.opaquePk) for (const read of this._pkReaders()) {
+			const value = read(row);
+			if (value !== null && typeof value === "object" && !(value instanceof Date)) state.opaquePk = true;
 		}
 	}
+	/** Removes the row stored under `key` (and its unique-index entries). */
+	_removeRow(state, key, row) {
+		state.rows.delete(key);
+		unindexRow(state.uniqueIndexes, key, row);
+	}
 	async insertOne(data) {
 		this._assertWritable();
 		return { insertedId: this._insertRow(this._state(), data) };
@@ -1162,7 +1448,14 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 		if (expectedVersion !== void 0 && versionColumn === void 0) throw new Error("expectedVersion requires a versioned table");
 		const match = buildMemoryPredicate(filter, relationSets);
 		const matched = [];
-		for (const [key, row] of state?.rows ?? []) {
+		if (!state) return matched;
+		const pinned = this._pinnedKey(state, filter);
+		let candidates = state.rows;
+		if (pinned !== void 0) {
+			const row = state.rows.get(pinned);
+			candidates = row ? [[pinned, row]] : [];
+		}
+		for (const [key, row] of candidates) {
 			if (!match(row)) continue;
 			if (expectedVersion !== void 0 && row[versionColumn] !== expectedVersion) continue;
 			matched.push({
@@ -1195,7 +1488,7 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	*   because this adapter reports no {@link supportsNativePatch}), so they must
 	*   nest into the stored document — MERGING siblings — exactly like Mongo's
 	*   `$set: { "profile.city": v }`, not create a literal dotted key. Top-level
-	*   (dot-free) keys behave as a plain assignment. `data` is `structuredClone`d
+	*   (dot-free) keys behave as a plain assignment. `data` is deep-cloned
 	*   first so nested subtrees from the caller never alias into the store.
 	* - `ops.inc` / `ops.mul`: numeric increment / multiply on the (dot-path)
 	*   target, coercing a missing or non-numeric current value to `0` (parity with
@@ -1206,22 +1499,24 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	* bump always wins over whatever `data`/`inc` wrote and lands on `oldVersion + 1`.
 	*/
 	_applyUpdate(row, data, ops) {
-		const patch = structuredClone(data);
+		const patch = cloneValue(data);
 		for (const k of Object.keys(patch)) setPath(row, k, patch[k]);
-		if (ops?.inc) for (const [col, n] of Object.entries(ops.inc)) setPath(row, col, (Number(getPath$1(row, col)) || 0) + n);
-		if (ops?.mul) for (const [col, n] of Object.entries(ops.mul)) setPath(row, col, (Number(getPath$1(row, col)) || 0) * n);
+		if (ops?.inc) for (const [col, n] of Object.entries(ops.inc)) setPath(row, col, (Number(getPath(row, col)) || 0) + n);
+		if (ops?.mul) for (const [col, n] of Object.entries(ops.mul)) setPath(row, col, (Number(getPath(row, col)) || 0) * n);
 	}
 	/**
-	* Places `next` into the store under its (possibly changed) {@link pkKey},
-	* re-keying when a mutation/replace moved the primary key. A collision on the
-	* NEW key (some other row already owns it) throws `CONFLICT`. Throws BEFORE
-	* touching the Map so a failed re-key leaves the store unchanged.
+	* Places `next` into the store under its (possibly changed) {@link pkKey} in
+	* place of `oldRow` (stored under `oldKey`), re-keying when a mutation/replace
+	* moved the primary key. A collision on the NEW key (some other row already
+	* owns it) throws `CONFLICT`. Throws BEFORE touching the Map so a failed
+	* re-key leaves the store unchanged. `tuples` are `next`'s unique-index keys.
 	*/
-	_commitRow(rows, oldKey, next) {
+	_commitRow(state, oldKey, oldRow, next, tuples) {
 		const newKey = this.pkKey(next);
-		if (newKey !== oldKey && rows.has(newKey)) throw this._pkConflict();
-		if (newKey !== oldKey) rows.delete(oldKey);
-		rows.set(newKey, next);
+		if (newKey !== oldKey && state.rows.has(newKey)) throw this._pkConflict();
+		unindexRow(state.uniqueIndexes, oldKey, oldRow);
+		if (newKey !== oldKey) state.rows.delete(oldKey);
+		this._storeRow(state, newKey, next, tuples);
 	}
 	/**
 	* Update-then-commit for a single matched row: clones the pristine `row`,
@@ -1229,14 +1524,15 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	* `row`), enforces unique indexes on the result EXCLUDING the row's own key (so
 	* a row keeping/rewriting its own unique value never self-conflicts), then
 	* commits. Nothing is written to the store until both the unique and PK checks
-	* pass, so a conflict leaves the store untouched.
+	* pass, so a conflict leaves the store untouched. `keepVersion` skips the
+	* bump (a version-exempt patch, since 0.1.150).
 	*/
-	_commitUpdate(state, oldKey, row, data, ops) {
-		const next = structuredClone(row);
+	_commitUpdate(state, oldKey, row, data, ops, keepVersion = false) {
+		const next = cloneValue(row);
 		this._applyUpdate(next, data, ops);
-		this._bumpVersion(next, row);
-		this._enforceUniqueIndexes(state, next, oldKey);
-		this._commitRow(state.rows, oldKey, next);
+		if (!keepVersion) this._bumpVersion(next, row);
+		const tuples = this._enforceUniqueIndexes(state, next, oldKey);
+		this._commitRow(state, oldKey, row, next, tuples);
 	}
 	async replaceOne(filter, data, expectedVersion) {
 		this._assertWritable();
@@ -1248,16 +1544,17 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 			modifiedCount: 0
 		};
 		const { key, row } = matched[0];
-		const next = structuredClone(data);
+		const next = cloneValue(data);
 		this._bumpVersion(next, row);
-		this._enforceUniqueIndexes(state, next, key);
-		this._commitRow(state.rows, key, next);
+		const tuples = this._enforceUniqueIndexes(state, next, key);
+		this._commitRow(state, key, row, next, tuples);
 		return {
 			matchedCount: 1,
 			modifiedCount: 1
 		};
 	}
-	async updateOne(filter, data, ops, expectedVersion) {
+	async updateOne(filter, data, ops, expectedVersion, opts) {
+		const keepVersion = this._versionColumnFor(opts, expectedVersion) === void 0;
 		this._assertWritable();
 		const sets = containsRelationFilter(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
@@ -1267,7 +1564,7 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 			modifiedCount: 0
 		};
 		const { key, row } = matched[0];
-		this._commitUpdate(state, key, row, data, ops);
+		this._commitUpdate(state, key, row, data, ops, keepVersion);
 		return {
 			matchedCount: 1,
 			modifiedCount: 1
@@ -1279,21 +1576,22 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 		const state = this._peekState();
 		const matched = this._selectForWrite(state, filter, void 0, false, sets);
 		if (!state || matched.length === 0) return { deletedCount: 0 };
-		state.rows.delete(matched[0].key);
+		this._removeRow(state, matched[0].key, matched[0].row);
 		return { deletedCount: 1 };
 	}
 	/**
 	* Stable multi-key comparator from `$sort`, with a final tie-break on
 	* {@link pkKey} for a deterministic total order. Returns the input unchanged
 	* (insertion order) when there is no `$sort`. Delegates to the shared pure
-	* {@link sortRows}, injecting {@link pkKey} as the total-order tie-break.
+	* {@link sortRows}, injecting {@link pkKey} as the total-order tie-break;
+	* `topK` asks for the head of that order only (`$skip + $limit`).
 	*/
-	_sortRows(rows, $sort) {
-		return sortRows(rows, $sort, (r) => this.pkKey(r));
+	_sortRows(rows, $sort, topK) {
+		return sortRows(rows, $sort, (r) => this.pkKey(r), topK);
 	}
 	/**
-	* Projects a stored row per `$select` and returns a fresh, deep-cloned object
-	* so the store can never be mutated through a returned value.
+	* Compiles the `$select` projection of one read: each returned row is a
+	* fresh, deep-cloned object so the store can never be mutated through it.
 	*
 	* - No projection → a full clone.
 	* - INCLUSION form (`{ field: 1 }`) → a new object with exactly the selected
@@ -1304,8 +1602,8 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	* Top-level and nested dot-paths are supported; exotic Mongo projection
 	* quirks (array positional, `$slice`, etc.) are intentionally NOT replicated.
 	*/
-	_projectAndClone(row, $select) {
-		return projectRow(row, $select?.asProjection, { clone: true });
+	_projector($select) {
+		return compileProjection($select?.asProjection, { clone: true });
 	}
 	/**
 	* Reads the pagination/sort/projection controls with their intended types.
@@ -1327,11 +1625,25 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	* shares. Goes through the {@link _loadRows} seam exactly ONCE per call, so a
 	* reader (and provider read-through mode) has one place that materializes the
 	* working set — one provider invocation per logical read.
+	*
+	* Stored mode reads the table's Map in place (no snapshot copy), resolves a
+	* filter pinning the whole primary key by direct lookup, and stops after
+	* `limit` matches when given (an unsorted `findOne`).
 	*/
-	async _filteredRows(query) {
+	async _filteredRows(query, limit) {
 		if (!containsRelationFilter(query.filter)) {
 			const match = buildMemoryPredicate(query.filter);
-			return (await this._loadRows()).filter(match);
+			if (!this._provider && this._loadRows === MemoryAdapter.prototype._loadRows) {
+				const state = this._peekState();
+				if (!state) return [];
+				const pinned = this._pinnedKey(state, query.filter);
+				if (pinned !== void 0) {
+					const row = state.rows.get(pinned);
+					return row && match(row) ? [row] : [];
+				}
+				return collectMatches(state.rows.values(), match, limit);
+			}
+			return collectMatches(await this._loadRows(), match, limit);
 		}
 		const own = Promise.resolve(this._loadRows());
 		own.catch(() => {});
@@ -1339,10 +1651,10 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 		return (await own).filter(buildMemoryPredicate(query.filter, sets));
 	}
 	async findOne(query) {
-		const filtered = await this._filteredRows(query);
 		const { $sort, $skip, $select } = this._readControls(query.controls ?? {});
-		const row = this._sortRows(filtered, $sort)[$skip ?? 0];
-		return row ? this._projectAndClone(row, $select) : null;
+		const index = $skip ?? 0;
+		const row = (hasSort($sort) ? this._sortRows(await this._filteredRows(query), $sort, index + 1) : await this._filteredRows(query, index + 1))[index];
+		return row ? this._projector($select)(row) : null;
 	}
 	async findMany(query) {
 		return (await this.findManyWithCount(query)).data;
@@ -1360,8 +1672,9 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	async findManyWithCount(query) {
 		const filtered = await this._filteredRows(query);
 		const { $sort, $skip, $limit, $select } = this._readControls(query.controls ?? {});
+		const topK = $limit === void 0 ? void 0 : ($skip ?? 0) + $limit;
 		return {
-			data: paginate(this._sortRows(filtered, $sort), $skip, $limit).map((row) => this._projectAndClone(row, $select)),
+			data: paginate(this._sortRows(filtered, $sort, topK), $skip, $limit).map(this._projector($select)),
 			count: filtered.length
 		};
 	}
@@ -1399,7 +1712,7 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	viewCapabilities() {
 		return ALL_VIEW_CAPABILITIES;
 	}
-	async updateMany(filter, data, ops) {
+	async updateMany(filter, data, ops, opts) {
 		this._assertWritable();
 		const sets = containsRelationFilter(filter) ? await this._relationSets(filter) : void 0;
 		const state = this._peekState();
@@ -1408,7 +1721,7 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 			modifiedCount: 0
 		};
 		const matched = this._selectForWrite(state, filter, void 0, true, sets);
-		for (const { key, row } of matched) this._commitUpdate(state, key, row, data, ops);
+		for (const { key, row } of matched) this._commitUpdate(state, key, row, data, ops, opts?.keepVersion);
 		return {
 			matchedCount: matched.length,
 			modifiedCount: matched.length
@@ -1435,7 +1748,7 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 		const state = this._peekState();
 		if (!state) return { deletedCount: 0 };
 		const matched = this._selectForWrite(state, filter, void 0, true, sets);
-		for (const { key } of matched) state.rows.delete(key);
+		for (const { key, row } of matched) this._removeRow(state, key, row);
 		return { deletedCount: matched.length };
 	}
 	/**
@@ -1447,13 +1760,11 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 		const uniqueIndexes = [];
 		for (const index of this._table.indexes.values()) {
 			if (index.type !== "unique") continue;
-			uniqueIndexes.push({
-				name: index.name,
-				fields: index.fields.map((f) => f.name),
-				optionalFields: new Set(index.fields.filter((f) => f.optional).map((f) => f.name))
-			});
+			uniqueIndexes.push(recordUniqueIndex(index.name, index.fields.map((f) => f.name), new Set(index.fields.filter((f) => f.optional).map((f) => f.name))));
 		}
-		this._state().uniqueIndexes = uniqueIndexes;
+		const state = this._state();
+		state.uniqueIndexes = uniqueIndexes;
+		for (const [key, row] of state.rows) indexRow(uniqueIndexes, key, row);
 	}
 	/** Creates the table's (empty) state when it does not exist. Idempotent. */
 	async ensureTable() {
@@ -1502,6 +1813,38 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 		this._db.delete(name);
 	}
 };
+/** Whether a `$sort` control orders by at least one key. */
+function hasSort($sort) {
+	return $sort !== void 0 && Object.keys($sort).length > 0;
+}
+/** The rows of `rows` matching `match`, in order — at most `limit` when given. */
+function collectMatches(rows, match, limit) {
+	const out = [];
+	if (limit !== void 0 && limit <= 0) return out;
+	for (const row of rows) if (match(row)) {
+		out.push(row);
+		if (out.length === limit) break;
+	}
+	return out;
+}
+/**
+* Collects into `pinned` the primary-key fields `filter` pins by exact equality
+* on a string / number / boolean / `Date` value — at its top level and inside
+* (nested) `$and`s, which `walkFilter` conjoins the same way. The first pin of
+* a field wins: a contradicting second one is still checked by the predicate.
+*/
+function collectPins(filter, fields, pinned) {
+	if (filter === null || typeof filter !== "object" || Array.isArray(filter)) return;
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and") {
+			if (Array.isArray(value)) for (const child of value) collectPins(child, fields, pinned);
+			continue;
+		}
+		if (pinned.has(key) || !fields.includes(key)) continue;
+		const operand = isPlainObject(value) ? value.$eq : value;
+		if (typeof operand === "string" || typeof operand === "number" || typeof operand === "boolean" || operand instanceof Date) pinned.set(key, operand);
+	}
+}
 /**
 * Ergonomic late-binding entry point for provider (read-through) mode. Resolves
 * the ALREADY-BUILT {@link MemoryAdapter} backing `type` on `space` (reached