@atscript/db-memory 0.1.113

package/dist/index.mjs

@@ -0,0 +1,972 @@
+import { BaseDbAdapter, DbError, DbSpace, walkFilter } from "@atscript/db";
+//#region src/lib/memory-filter.ts
+/**
+* Dot-path getter. Splits `path` on `.` and walks plain objects, returning the
+* value at the end of the path or `undefined` if any intermediate segment is
+* missing or is not a plain object.
+*
+* LIMITATION (v1, accepted): this does NOT descend into arrays. If a segment
+* resolves to an array, traversal stops and `undefined` is returned — there is
+* no positional/`$elemMatch`-style indexing. Array-of-object matching is a
+* later concern; the SQL/Mongo adapters flatten differently and we do not want
+* to fake a semantic the store can't back yet.
+*/
+function getPath(row, path) {
+	const segments = path.split(".");
+	let current = row;
+	for (const seg of segments) {
+		if (current === null || typeof current !== "object" || Array.isArray(current)) return;
+		current = current[seg];
+	}
+	return current;
+}
+/**
+* Like {@link getPath}, but reports whether the FINAL key EXISTS rather than
+* its value. A key holding `null` counts as present. This is what lets
+* `$exists` distinguish a `null`-valued field (present) from an absent one —
+* a distinction {@link getPath} alone cannot make (both would read back as a
+* nullish value). Same array limitation as {@link getPath}.
+*/
+function hasPath(row, path) {
+	const segments = path.split(".");
+	const last = segments.pop();
+	let current = row;
+	for (const seg of segments) {
+		if (current === null || typeof current !== "object" || Array.isArray(current)) return false;
+		current = current[seg];
+	}
+	if (current === null || typeof current !== "object" || Array.isArray(current)) return false;
+	return Object.prototype.hasOwnProperty.call(current, last);
+}
+/**
+* Deep-equality for leaf values, used by `$eq`/`$ne`/`$in`/`$nin`.
+*
+* - `Date`s compare by their instant (`getTime()`), not identity.
+* - Everything else uses strict `===`. In particular `null === null` is `true`,
+*   while `undefined` (how {@link getPath} reports a missing field) is never
+*   equal to `null` here.
+*
+* NOTE: this stays STRICT on purpose — it backs `$in`/`$nin` and unique-index
+* tuple equality. The Mongo-like `$eq: null` ⇒ "null OR missing" match is a
+* separate, loose-`==` null branch handled in {@link evalEq} BEFORE it reaches
+* `valuesEqual`, so this function never has to conflate `undefined` with `null`.
+*
+* No structural/object comparison: filter leaves are primitives, so reference
+* equality is the correct floor for anything non-primitive.
+*/
+function valuesEqual(a, b) {
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	return a === b;
+}
+/**
+* Mirror of `mongo-filter.ts`'s `parseRegexString`: normalize a `$regex` value
+* (or a bare `RegExp`) into a `{ pattern, flags }` pair. Accepts a `RegExp`
+* instance, a `/pattern/flags` string literal, or a plain string (treated as
+* the literal pattern with no flags).
+*/
+function parseRegexString(value) {
+	if (value instanceof RegExp) return {
+		pattern: value.source,
+		flags: value.flags
+	};
+	const str = String(value);
+	const match = str.match(/^\/(.+)\/([gimsuy]*)$/);
+	if (match) return {
+		pattern: match[1],
+		flags: match[2]
+	};
+	return {
+		pattern: str,
+		flags: ""
+	};
+}
+/**
+* Coerce an arbitrary leaf to a string for regex testing. The `unknown`
+* parameter is load-bearing: it keeps the `String()` coercion behind a typed
+* boundary so `no-base-to-string` does not fire at the call sites (where the
+* value narrows to a non-primitive `{}` and would otherwise trip the rule). Do
+* NOT inline `String(...)` at the call sites — that reintroduces the lint error.
+*/
+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(row, field);
+	if (value === null) return fieldValue == null;
+	if (value instanceof RegExp) return fieldValue != null && value.test(stringifyLeaf(fieldValue));
+	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(row, field);
+	return value.some((element) => valuesEqual(fieldValue, element));
+}
+/**
+* Coerce a leaf to something the JS relational operators can order. `Date`s
+* become their epoch millis; everything else is passed through. Typed as
+* `number` purely so `<`/`>` type-check — at runtime JS still orders strings
+* lexicographically and numbers numerically (see {@link evalRelational}).
+*/
+function toOrdinal(v) {
+	return v instanceof Date ? v.getTime() : v;
+}
+/**
+* `$gt`/`$gte`/`$lt`/`$lte`. A missing or `null` field never matches an
+* ordering comparison. `Date` operands are normalized to epoch millis; all
+* other comparisons use plain JS ordering (numbers numerically, strings
+* lexicographically) — NO collation or locale awareness. This intentionally
+* differs from SQL engines' collated ordering.
+*/
+function evalRelational(row, field, op, value) {
+	const fieldValue = getPath(row, field);
+	if (fieldValue === void 0 || fieldValue === null) return false;
+	const a = toOrdinal(fieldValue);
+	const b = toOrdinal(value);
+	switch (op) {
+		case "$gt": return a > b;
+		case "$gte": return a >= b;
+		case "$lt": return a < b;
+		case "$lte": return a <= b;
+		default: return false;
+	}
+}
+/**
+* Visitor that assembles an in-memory {@link Predicate} from a `FilterExpr`.
+*
+* The STRUCTURE (which logical/comparison nodes exist and how they nest) is
+* dictated by the shared {@link walkFilter} walker — the same one the SQL and
+* Mongo adapters use — so structural parity is guaranteed by construction. Only
+* the leaf/composition SEMANTICS below are this adapter's own, JS-native
+* contract.
+*/
+const memoryVisitor = {
+	and(children) {
+		return (row) => children.every((child) => child(row));
+	},
+	or(children) {
+		return (row) => children.some((child) => child(row));
+	},
+	not(child) {
+		return (row) => !child(row);
+	},
+	comparison(field, op, value) {
+		switch (op) {
+			case "$eq": return (row) => evalEq(row, field, value);
+			case "$ne": return (row) => !evalEq(row, field, 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 "$regex": {
+				const { pattern, flags } = parseRegexString(value);
+				const regex = new RegExp(pattern, flags);
+				return (row) => {
+					const fieldValue = getPath(row, field);
+					return fieldValue != null && regex.test(stringifyLeaf(fieldValue));
+				};
+			}
+			case "$exists": return (row) => value === hasPath(row, field);
+			default: throw new DbError("INVALID_QUERY", [{
+				path: field,
+				message: `Unsupported filter operator: ${op}`
+			}]);
+		}
+	}
+};
+/**
+* Compiles a {@link FilterExpr} into an in-memory row predicate
+* `(row) => boolean`, reusing the shared {@link walkFilter} walker so filter
+* structure matches the SQL/Mongo adapters by construction.
+*
+* An empty/absent filter (for which `walkFilter` returns `undefined`) compiles
+* to a match-everything predicate.
+*/
+function buildMemoryPredicate(filter) {
+	return walkFilter(filter, memoryVisitor) ?? (() => true);
+}
+//#endregion
+//#region src/lib/memory-engine.ts
+/**
+* Pure, store-agnostic core of the in-memory query engine: the `$sort`
+* comparator and `$select` projection, factored out of {@link MemoryAdapter} so
+* there is exactly ONE implementation. Everything here is a pure function over
+* plain `Record<string, unknown>` rows — no adapter/table state — so other
+* consumers (e.g. moost-db's value-help controller) can reuse the SAME engine
+* instead of hand-rolling a second copy. The adapter wires its own PK-derived
+* tie-break / physical-PK fields in as parameters.
+*
+* Dot-path READ (`getPath`) lives in {@link ./memory-filter} and is shared;
+* the dot-path WRITE/DELETE helpers ({@link setPath}/{@link deletePath}) live
+* here because projection (and the adapter's update path) are their only users.
+*/
+/**
+* Total ordering for `$sort`. `null`/`undefined` sort LOW (before any concrete
+* value); `Date`s compare by their instant; numbers numerically; everything
+* else via JS-native `<`/`>` (strings lexicographically) — NO collation or
+* locale awareness (documented divergence from the SQL adapters).
+*/
+function compareLeaves(a, b) {
+	const aNil = a === null || a === void 0;
+	const bNil = b === null || b === void 0;
+	if (aNil && bNil) return 0;
+	if (aNil) return -1;
+	if (bNil) return 1;
+	const av = a instanceof Date ? a.getTime() : a;
+	const bv = b instanceof Date ? b.getTime() : b;
+	if (typeof av === "number" && typeof bv === "number") return av < bv ? -1 : av > bv ? 1 : 0;
+	const as = av;
+	const bs = bv;
+	return as < bs ? -1 : as > bs ? 1 : 0;
+}
+/**
+* Dot-path setter used by inclusion projection. Creates intermediate plain
+* objects as needed; overwrites a non-object intermediate. Top-level keys and
+* nested dot-paths both work.
+*/
+function setPath(target, path, value) {
+	const segments = path.split(".");
+	let current = target;
+	for (let i = 0; i < segments.length - 1; i++) {
+		const seg = segments[i];
+		const next = current[seg];
+		if (next === null || typeof next !== "object" || Array.isArray(next)) current[seg] = {};
+		current = current[seg];
+	}
+	current[segments[segments.length - 1]] = value;
+}
+/**
+* Dot-path deleter used by exclusion projection. No-op when any intermediate
+* segment is missing or not a plain object. Top-level keys and nested dot-paths
+* both work.
+*/
+function deletePath(target, path) {
+	const segments = path.split(".");
+	let current = target;
+	for (let i = 0; i < segments.length - 1; i++) {
+		if (current === null || typeof current !== "object" || Array.isArray(current)) return;
+		current = current[segments[i]];
+	}
+	if (current !== null && typeof current === "object" && !Array.isArray(current)) delete current[segments[segments.length - 1]];
+}
+/**
+* Stable multi-key sort from `$sort`, applied over plain rows.
+*
+* - No `$sort` (or an empty one) → returns the input array UNCHANGED (same
+*   reference, insertion order preserved) — the fast path for an unsorted read.
+* - `tieBreak`, when supplied, is the FINAL deterministic tie-break key for a
+*   TOTAL order — the adapter injects its {@link MemoryAdapter.pkKey} here so
+*   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.
+*
+* 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.
+*/
+function sortRows(rows, $sort, tieBreak) {
+	const keys = $sort ? Object.entries($sort) : [];
+	if (keys.length === 0) return rows;
+	return 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;
+		}
+		if (tieBreak) {
+			const at = a.tie;
+			const bt = b.tie;
+			return at < bt ? -1 : at > bt ? 1 : 0;
+		}
+		return a.index - b.index;
+	}).map((decorated) => decorated.row);
+}
+/**
+* Projects a plain row per a `{ path: 0 | 1 }` projection map. Decoupled from
+* `UniquSelect`: the caller passes the resolved projection map (e.g. from
+* `$select.asProjection`) so the engine has no query-layer dependency.
+*
+* - No projection (undefined / empty) → the whole row (cloned per `clone`).
+* - INCLUSION form (first entry is `1`) → a new object with only the selected
+*   paths PLUS `opts.pkFields`. Absent fields are omitted; a present-`null`
+*   (value === null) is kept.
+* - EXCLUSION form (first entry is `0`) → a clone with those paths removed. This
+*   branch ALWAYS clones (it must own a copy to drop paths without mutating the
+*   input), so `clone: false` is a no-op here.
+*
+* Top-level and nested dot-paths are supported; exotic Mongo projection quirks
+* (array positional, `$slice`, etc.) are intentionally NOT replicated.
+*/
+function projectRow(row, projection, opts) {
+	const clone = opts?.clone ?? false;
+	const entries = projection ? Object.entries(projection) : [];
+	if (entries.length === 0) return clone ? structuredClone(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 out = structuredClone(row);
+	for (const [path, v] of entries) if (v === 0) deletePath(out, path);
+	return out;
+}
+//#endregion
+//#region src/lib/memory-adapter.ts
+/**
+* In-memory {@link BaseDbAdapter} implementation.
+*
+* Runs in one of two modes:
+* - STORED mode (default): storage is a plain `Map` living on the adapter
+*   instance — adapter instances are 1:1 with a readable (table/view), so the
+*   Map is this table's whole store. Documents are kept in their nested PHYSICAL
+*   shape (no flattening), which is why {@link supportsNestedObjects} is `true`.
+*   Full CRUD surface: inserts, reads, update / replace / delete with
+*   optimistic-concurrency CAS.
+* - PROVIDER (read-through) mode: enabled via {@link setProvider} /
+*   {@link setMemoryProvider}. Reads are served from a runtime closure
+*   recomputed per request (e.g. a Redis/job-manager snapshot) so a
+*   runtime-owned entity with NO database can be observed as a READ-ONLY
+*   atscript table; all writes are rejected (see {@link _assertWritable}).
+*/
+var MemoryAdapter = class extends BaseDbAdapter {
+	/**
+	* The table's store, keyed by {@link pkKey}. Values are the stored rows in
+	* nested physical shape. An instance field — no `ensureTable` DDL needed.
+	*/
+	rows = /* @__PURE__ */ new Map();
+	/** Unique indexes recorded by {@link syncIndexes}. Enforced on insert. */
+	uniqueIndexes = [];
+	/** Memoized physical PK field names — stable for the adapter's lifetime. */
+	_pkFieldsCache;
+	/**
+	* Memoized map of PHYSICAL field name → optional `start` for every field
+	* carrying `@db.default.increment`. Stable per adapter (see
+	* {@link _incrementFields}).
+	*/
+	_incrementFieldsCache;
+	/**
+	* Running per-field auto-increment counters (PHYSICAL name → last value
+	* handed out). Lives on the adapter INSTANCE, so it resets whenever a new
+	* DbSpace/adapter is built — correct for an in-memory store (parity with
+	* SQLite `:memory:`, whose sequence also restarts with a fresh DB). Never
+	* persisted.
+	*/
+	_incrementCounters = /* @__PURE__ */ new Map();
+	/**
+	* Provider (read-through) backing closure. When set, this adapter is
+	* PROVIDER-BACKED: reads recompute rows from this closure per request and all
+	* writes are rejected (see {@link _assertWritable}). `undefined` ⇒ stored mode.
+	*
+	* WHY late-binding only (no constructor provider option): a {@link DbSpace}'s
+	* zero-arg `TAdapterFactory` builds EVERY table's adapter with the SAME
+	* factory — INCLUDING the internal `__atscript_control` sync table. A provider
+	* injected at construction would therefore leak onto the control table and
+	* break schema sync. Provider mode must target ONE specific table's
+	* already-built adapter, so it is only settable AFTER construction via
+	* {@link setProvider}.
+	*/
+	_provider;
+	/**
+	* The in-memory store keeps documents nested (no flattening), so the generic
+	* layer should pass nested objects through as-is.
+	*/
+	supportsNestedObjects() {
+		return true;
+	}
+	/**
+	* Parity with the Mongo adapter (`return !fd.encrypted`). The in-memory
+	* dot-path filter visitor CAN filter into nested objects AND array
+	* (`storage === 'json'`) fields, so JSON storage is NOT a filterability
+	* blocker here. The base default vetoes `storage === 'json'` — correct for SQL
+	* engines that cannot reach into a raw JSON column, but WRONG for this
+	* nested-object-capable adapter, and it would under-report `filterable` to
+	* `/meta` for UIs. Overriding fixes that. The `@db.encrypted` veto is
+	* core-supplied and absolute (equality/range over ciphertext is meaningless),
+	* so it is preserved.
+	*
+	* NOTE on the capabilities left at their base defaults ON PURPOSE:
+	* - `canSortField` — its conservative JSON veto (array sort-by-min/max-element
+	*   is a footgun for generic UI sort headers) is deliberate, matching Mongo.
+	* - `supportsNativePatch` / `supportsNativeRelations` — stay `false`: core
+	*   decomposes patches into dot-path `$set`s and loads relations app-level.
+	*/
+	canFilterField(fd) {
+		return !fd.encrypted;
+	}
+	/**
+	* Coerces a by-id value to the id field's declared leaf type. The framework
+	* calls `adapter.prepareId(value, fieldType)` when building by-id filters, so a
+	* URL id like `"21"` reaches this adapter as the STRING `"21"`. Memory does
+	* STRICT JS comparison like the Mongo adapter, so the strict `$eq` would then
+	* compare `"21" === 21` against a numeric PK and never match — every
+	* fetch/patch/delete/replace-by-id of a numeric-PK row would 404. Coercing the
+	* id to the field type here fixes that. SQL adapters can rely on the DB to
+	* coerce the bound parameter; memory cannot, so it MUST coerce here.
+	*
+	* Mirrors the Mongo adapter's `prepareId` MINUS its `objectId` branch (an
+	* in-memory store has no ObjectId ids): a leaf `designType` of `"number"`
+	* coerces via `Number(id)`, everything else via `String(id)`.
+	*/
+	prepareId(id, _fieldType) {
+		const fieldType = _fieldType;
+		if (fieldType.type.kind === "") {
+			if (fieldType.type.designType === "number") return Number(id);
+		}
+		return String(id);
+	}
+	/**
+	* Physical names of the primary-key field(s). Single `@meta.id` resolves via
+	* {@link AtscriptDbReadable.metaIdPhysical}; a composite key maps each logical
+	* PK path through `pathToPhysical` (falling back to the name itself). Memoized
+	* because it is stable per adapter (1:1 with a fixed table) yet read on every
+	* `pkKey`/projection — recomputing would re-read `this._table.*` and re-allocate.
+	*/
+	_physicalPkFields() {
+		if (this._pkFieldsCache) return this._pkFieldsCache;
+		const metaIdPhysical = this._table.metaIdPhysical;
+		const fields = metaIdPhysical ? [metaIdPhysical] : this._table.primaryKeys.map((pk) => this._table.pathToPhysical.get(pk) ?? pk);
+		this._pkFieldsCache = fields;
+		return fields;
+	}
+	/**
+	* PHYSICAL field name → optional `start` for every `@db.default.increment`
+	* field. Discovered lazily from the table's field descriptors — each carries
+	* both `physicalName` (the key the stored row uses) and `defaultValue`
+	* (sourced from `this._table.defaults`), so this resolves column renames
+	* correctly where iterating the logical-keyed `defaults` map would not.
+	* Memoized because it is stable per adapter (1:1 with a fixed table), like
+	* {@link _physicalPkFields}. An empty map ⇒ the insert fast-path skips all
+	* increment work.
+	*
+	* Mirrors the Mongo adapter's `_incrementFields`
+	* (`mongo-adapter.ts` — populated in `onFieldScanned`, keyed by physical
+	* name): core NEVER generates `increment` values (its `_applyDefaults`
+	* switch has no `increment` case, so the field reaches the adapter absent),
+	* whether or not the adapter claims it via `nativeDefaultFns()`. The adapter
+	* MUST fill it in. Mongo does not override `nativeDefaultFns()` /
+	* `supportsNativeValueDefaults()` for increment, so neither does this adapter.
+	*/
+	_incrementFields() {
+		if (this._incrementFieldsCache) return this._incrementFieldsCache;
+		const fields = /* @__PURE__ */ new Map();
+		for (const fd of this._table.fieldDescriptors) {
+			const def = fd.defaultValue;
+			if (def?.kind === "fn" && def.fn === "increment") fields.set(fd.physicalName, def.start);
+		}
+		this._incrementFieldsCache = fields;
+		return fields;
+	}
+	/**
+	* Assigns `@db.default.increment` values onto `row` (PHYSICAL shape) IN
+	* PLACE — called from {@link _insertRow} BEFORE `pkKey`/uniqueness/inserted-id
+	* are computed so an increment PRIMARY KEY produces a real `insertedId` and
+	* stores under a real key. The memory analogue of the Mongo adapter's
+	* insert-time increment (Mongo uses an atomic `__atscript_counters`
+	* collection; an in-memory store just keeps the counter on the instance):
+	*
+	* - No value for the field → assign the next counter value. First use starts
+	*   at `start ?? 1` (`max(counter, (start ?? 1) - 1) + 1`); thereafter it is
+	*   the previous value + 1. Sequential across an `insertMany` batch because
+	*   {@link _insertRow} runs per item in `insertedIds` order against the shared
+	*   counter.
+	* - Explicit value present → keep it, but advance the counter to
+	*   `max(counter, value)` so a later auto value can never collide with it.
+	*/
+	_applyIncrements(row) {
+		const fields = this._incrementFields();
+		if (fields.size === 0) return;
+		for (const [physical, start] of fields) {
+			const floor = (start ?? 1) - 1;
+			const base = this._incrementCounters.get(physical) ?? floor;
+			const current = row[physical];
+			if (current === void 0 || current === null) {
+				const next = base + 1;
+				row[physical] = next;
+				this._incrementCounters.set(physical, next);
+			} else if (typeof current === "number") this._incrementCounters.set(physical, Math.max(base, current));
+		}
+	}
+	/**
+	* Builds the duplicate-primary-key {@link DbError}. The reported `path` is the
+	* physical `@meta.id` name, falling back to the first (logical) primary key,
+	* then `""`. Centralized so the insert and re-key paths raise an identical
+	* CONFLICT.
+	*/
+	_pkConflict() {
+		return new DbError("CONFLICT", [{
+			path: this._table.metaIdPhysical ?? this._table.primaryKeys[0] ?? "",
+			message: "Duplicate primary key"
+		}]);
+	}
+	/**
+	* Derives the storage key from a row's PRIMARY KEY value(s), read by PHYSICAL
+	* name. Encoded as `JSON.stringify` of the ordered PK values so it is
+	* collision-proof across both value shapes and types — `['a','b:c']` and
+	* `['a:b','c']` differ, and `1` differs from `'1'`.
+	*/
+	pkKey(row) {
+		const values = this._physicalPkFields().map((field) => getPath(row, field));
+		return JSON.stringify(values);
+	}
+	/**
+	* Builds a DEFINED inserted-id for a table with NO single `@meta.id` — a
+	* composite (or single non-meta) primary key, where
+	* {@link BaseDbAdapter._resolveInsertedId} would otherwise fall back to
+	* `undefined` (memory has no rowid/`_id` to hand back). Returns an object
+	* mapping each PRIMARY KEY PHYSICAL field name → its value in the stored row
+	* (e.g. `{ part1: "a", part2: "b" }`), read by physical name via
+	* {@link getPath} so it matches how {@link pkKey} derives the storage key and
+	* honours column renames. A single-field non-meta PK yields the one-key object
+	* form for consistency (documented shape).
+	*
+	* Passed as the `dbGeneratedId` fallback in {@link _insertRow} ONLY when
+	* {@link AtscriptDbReadable.metaIdPhysical} is null; single-`@meta.id` tables
+	* keep an `undefined` fallback, so their scalar `insertedId`
+	* (`row[metaIdPhysical]`) is byte-identical to before.
+	*/
+	_compositeInsertedId(row) {
+		const id = {};
+		for (const field of this._physicalPkFields()) id[field] = getPath(row, field);
+		return id;
+	}
+	/**
+	* Switches this adapter into PROVIDER-BACKED mode: `fn` is invoked on every
+	* read to recompute the table's rows (e.g. a Redis/job-manager snapshot), so a
+	* runtime-owned entity with NO database can be observed as a read-only
+	* atscript table (and still carry `@DbAction`s). Rows are recomputed per read
+	* (no caching); once set, the table is READ-ONLY — all writes throw (see
+	* {@link _assertWritable}).
+	*
+	* Late-binding by design: set AFTER construction only, never via the
+	* constructor — see the {@link _provider} field comment for why a constructor
+	* option would leak onto the shared control-table adapter and break sync.
+	*/
+	setProvider(fn) {
+		this._provider = fn;
+	}
+	/**
+	* Write guard for provider-backed (read-only) mode. Called first in every one
+	* of the 8 write methods so all mutation entry points reject identically. Uses
+	* `INVALID_QUERY` (moost-db's validation interceptor maps it to HTTP 400, NOT
+	* 500 — the same choice `aggregate()` makes) since there is no dedicated
+	* read-only error code.
+	*/
+	_assertWritable() {
+		if (this._provider) throw new DbError("INVALID_QUERY", [{
+			path: "",
+			message: `Table "${this._table.tableName}" is provider-backed (read-only); writes are not supported`
+		}]);
+	}
+	/**
+	* Snapshot seam for reads. Returns the current rows.
+	*
+	* - Stored mode reads the instance Map directly (insertion order preserved).
+	* - Provider (read-through) mode calls {@link _provider} to recompute a fresh
+	*   snapshot per read.
+	*
+	* Does NOT clone — cloning happens only on OUTPUT (see {@link _projectAndClone})
+	* so the store stays authoritative and cheap. That same clone-on-output path
+	* ALSO covers provider rows: every value handed back to a caller is a
+	* `structuredClone`, so a provider that returns objects it still holds is
+	* protected from mutation by `reconstructFromRead`/callers.
+	*
+	* A single logical read invokes the provider EXACTLY ONCE: `findMany`
+	* delegates to `findManyWithCount` (one `_filteredRows` ⇒ one `_loadRows`),
+	* and `findOne`/`count` each call `_filteredRows` once — so recompute-per-read
+	* AND single-snapshot-per-`findManyWithCount` both fall out for free.
+	*/
+	_loadRows() {
+		if (this._provider) return this._provider();
+		return [...this.rows.values()];
+	}
+	/**
+	* 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 store. Called once per item by both `insertOne` and `insertMany`, so
+	* increment values advance sequentially across a batch.
+	*/
+	_insertRow(data) {
+		const row = structuredClone(data);
+		const versionColumn = this._table.versionColumn;
+		if (versionColumn !== void 0 && !(versionColumn in row)) row[versionColumn] = 0;
+		this._applyIncrements(row);
+		const key = this.pkKey(row);
+		if (this.rows.has(key)) throw this._pkConflict();
+		this._enforceUniqueIndexes(row);
+		this.rows.set(key, row);
+		const fallback = this._table.metaIdPhysical ? void 0 : this._compositeInsertedId(row);
+		return this._resolveInsertedId(row, fallback);
+	}
+	/**
+	* 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`.
+	*
+	* `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(row, excludeKey) {
+		for (const index of this.uniqueIndexes) {
+			const tuple = [];
+			let skip = false;
+			for (const field of index.fields) {
+				const value = getPath(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 this.rows) {
+				if (excludeKey !== void 0 && existingKey === excludeKey) continue;
+				let equal = true;
+				for (let i = 0; i < index.fields.length; i++) if (!valuesEqual(getPath(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}"`
+				}]);
+			}
+		}
+	}
+	async insertOne(data) {
+		this._assertWritable();
+		return { insertedId: this._insertRow(data) };
+	}
+	async insertMany(data) {
+		this._assertWritable();
+		const insertedIds = data.map((item) => this._insertRow(item));
+		return {
+			insertedCount: data.length,
+			insertedIds
+		};
+	}
+	/**
+	* Selects the stored rows a write should touch, as `{ key, row }` pairs so
+	* callers can mutate in place and re-key. Stored mode scans the instance Map
+	* directly (writes are authoritative against the store, unlike reads which go
+	* through the {@link _loadRows} snapshot seam).
+	*
+	* A defined `expectedVersion` layers an OCC (compare-and-set) predicate on top
+	* of `filter`: a row matches only when `row[versionColumn] === expectedVersion`.
+	* A version MISMATCH is NOT an error — it simply yields zero matches, so the
+	* caller reports `matchedCount: 0`. Supplying `expectedVersion` for a table
+	* that has no version column is a misconfiguration and throws (mirrors the
+	* Mongo adapter's `_buildCasFilter`).
+	*
+	* When `many` is `false` at most the first match is returned.
+	*/
+	_selectForWrite(filter, expectedVersion, many) {
+		const versionColumn = this._table.versionColumn;
+		if (expectedVersion !== void 0 && versionColumn === void 0) throw new Error("expectedVersion requires a versioned table");
+		const match = buildMemoryPredicate(filter);
+		const matched = [];
+		for (const [key, row] of this.rows) {
+			if (!match(row)) continue;
+			if (expectedVersion !== void 0 && row[versionColumn] !== expectedVersion) continue;
+			matched.push({
+				key,
+				row
+			});
+			if (!many) break;
+		}
+		return matched;
+	}
+	/**
+	* Sets `target`'s version column to `oldRow`'s version + 1, coercing a missing
+	* old version to `0`. No-op on an unversioned table. The OLD version is read
+	* from a pristine `oldRow` (not `target`) so the result is always
+	* `oldVersion + 1` regardless of what a patch/replace payload wrote onto
+	* `target`'s version column — the memory analogue of Mongo forcing
+	* `$inc: { version: 1 }` last. Shared by {@link _commitUpdate} (merge path) and
+	* {@link replaceOne} (full-replace path).
+	*/
+	_bumpVersion(target, oldRow) {
+		const versionColumn = this._table.versionColumn;
+		if (versionColumn !== void 0) target[versionColumn] = (oldRow[versionColumn] ?? 0) + 1;
+	}
+	/**
+	* Applies a merge-style update to `row` IN PLACE — the memory analogue of
+	* `buildMongoUpdateDoc`:
+	*
+	* - `$set` (`data`): each key is set onto the row via {@link setPath}. Keys are
+	*   DOT-PATHS (the table layer decomposes nested patches into `"profile.city"`
+	*   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
+	*   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
+	*   Mongo's `$inc`/`$mul`).
+	*
+	* Does NOT bump the version column — {@link _commitUpdate} does that LAST via
+	* {@link _bumpVersion} (after this merge, reading the pristine old row), so the
+	* bump always wins over whatever `data`/`inc` wrote and lands on `oldVersion + 1`.
+	*/
+	_applyUpdate(row, data, ops) {
+		const patch = structuredClone(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(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.
+	*/
+	_commitRow(oldKey, next) {
+		const newKey = this.pkKey(next);
+		if (newKey !== oldKey && this.rows.has(newKey)) throw this._pkConflict();
+		if (newKey !== oldKey) this.rows.delete(oldKey);
+		this.rows.set(newKey, next);
+	}
+	/**
+	* Update-then-commit for a single matched row: clones the pristine `row`,
+	* applies the merge update, bumps the version LAST (read from the pristine old
+	* `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.
+	*/
+	_commitUpdate(oldKey, row, data, ops) {
+		const next = structuredClone(row);
+		this._applyUpdate(next, data, ops);
+		this._bumpVersion(next, row);
+		this._enforceUniqueIndexes(next, oldKey);
+		this._commitRow(oldKey, next);
+	}
+	async replaceOne(filter, data, expectedVersion) {
+		this._assertWritable();
+		const matched = this._selectForWrite(filter, expectedVersion, false);
+		if (matched.length === 0) return {
+			matchedCount: 0,
+			modifiedCount: 0
+		};
+		const { key, row } = matched[0];
+		const next = structuredClone(data);
+		this._bumpVersion(next, row);
+		this._enforceUniqueIndexes(next, key);
+		this._commitRow(key, next);
+		return {
+			matchedCount: 1,
+			modifiedCount: 1
+		};
+	}
+	async updateOne(filter, data, ops, expectedVersion) {
+		this._assertWritable();
+		const matched = this._selectForWrite(filter, expectedVersion, false);
+		if (matched.length === 0) return {
+			matchedCount: 0,
+			modifiedCount: 0
+		};
+		const { key, row } = matched[0];
+		this._commitUpdate(key, row, data, ops);
+		return {
+			matchedCount: 1,
+			modifiedCount: 1
+		};
+	}
+	async deleteOne(filter) {
+		this._assertWritable();
+		const matched = this._selectForWrite(filter, void 0, false);
+		if (matched.length === 0) return { deletedCount: 0 };
+		this.rows.delete(matched[0].key);
+		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.
+	*/
+	_sortRows(rows, $sort) {
+		return sortRows(rows, $sort, (r) => this.pkKey(r));
+	}
+	/** Applies `$skip` then `$limit` (both optional) via a single slice. */
+	_paginate(rows, skip, limit) {
+		const start = skip ?? 0;
+		const end = limit === void 0 ? void 0 : start + limit;
+		if (start === 0 && end === void 0) return rows;
+		return rows.slice(start, end);
+	}
+	/**
+	* Projects a stored row per `$select` and returns a fresh, deep-cloned object
+	* so the store can never be mutated through a returned value.
+	*
+	* - No projection → a full clone.
+	* - INCLUSION form (`{ field: 1 }`) → a new object with only the selected
+	*   paths PLUS the primary-key field(s) (mirrors Mongo including `_id`).
+	* - EXCLUSION form (`{ field: 0 }`) → a clone with those paths removed.
+	*
+	* 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, {
+			pkFields: this._physicalPkFields(),
+			clone: true
+		});
+	}
+	/**
+	* Reads the pagination/sort/projection controls with their intended types.
+	* `DbControls` carries a `[key: `$${string}`]: unknown` index signature, and
+	* `Omit`-ing `$select` from `UniqueryControls` widens `$sort`/`$skip`/`$limit`
+	* back to `unknown` — so the casts here restore the declared shapes at a
+	* single, documented boundary. `$select` keeps its explicit `UniquSelect` type.
+	*/
+	_readControls(controls) {
+		return {
+			$sort: controls.$sort,
+			$skip: controls.$skip,
+			$limit: controls.$limit,
+			$select: controls.$select
+		};
+	}
+	/**
+	* The single "load a snapshot, apply the filter predicate" step every read
+	* 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.
+	*/
+	async _filteredRows(query) {
+		const match = buildMemoryPredicate(query.filter);
+		return (await this._loadRows()).filter(match);
+	}
+	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;
+	}
+	async findMany(query) {
+		return (await this.findManyWithCount(query)).data;
+	}
+	async count(query) {
+		return (await this._filteredRows(query)).length;
+	}
+	/**
+	* Overridden so the filtered snapshot is computed ONCE — the base default
+	* runs `findMany` and `count` separately (two `_loadRows` snapshots). A
+	* single snapshot is both cheaper here and the correct semantics for
+	* provider (read-through) mode, where two separate reads could otherwise
+	* observe different snapshots and make count/data disagree.
+	*/
+	async findManyWithCount(query) {
+		const filtered = await this._filteredRows(query);
+		const { $sort, $skip, $limit, $select } = this._readControls(query.controls ?? {});
+		const sorted = this._sortRows(filtered, $sort);
+		return {
+			data: this._paginate(sorted, $skip, $limit).map((row) => this._projectAndClone(row, $select)),
+			count: filtered.length
+		};
+	}
+	/**
+	* Aggregation (`$groupBy`) is a documented v1 non-goal for the in-memory
+	* adapter. The inherited base default throws a PLAIN `Error`, which a readable
+	* REST controller would surface as an unhandled HTTP 500 when a `?$groupBy=`
+	* query routes here. Throwing a typed {@link DbError} with `INVALID_QUERY`
+	* instead converts that into a clean client error — moost-db's validation
+	* interceptor maps `INVALID_QUERY` → HTTP 400.
+	*/
+	async aggregate(_query) {
+		throw new DbError("INVALID_QUERY", [{
+			path: "",
+			message: "Aggregation ($groupBy) is not supported by the in-memory adapter"
+		}]);
+	}
+	async updateMany(filter, data, ops) {
+		this._assertWritable();
+		const matched = this._selectForWrite(filter, void 0, true);
+		for (const { key, row } of matched) this._commitUpdate(key, row, data, ops);
+		return {
+			matchedCount: matched.length,
+			modifiedCount: matched.length
+		};
+	}
+	async replaceMany(filter, data) {
+		this._assertWritable();
+		const matched = this._selectForWrite(filter, void 0, true);
+		for (const { key, row } of matched) this._commitUpdate(key, row, data);
+		return {
+			matchedCount: matched.length,
+			modifiedCount: matched.length
+		};
+	}
+	async deleteMany(filter) {
+		this._assertWritable();
+		const matched = this._selectForWrite(filter, void 0, true);
+		for (const { key } of matched) this.rows.delete(key);
+		return { deletedCount: matched.length };
+	}
+	/**
+	* Records the model's `unique` indexes for insert-time enforcement. Idempotent
+	* (replaces the recorded set). Non-unique index types are ignored — an
+	* in-memory scan needs no plain/fulltext/geo index to answer queries.
+	*/
+	async syncIndexes() {
+		this.uniqueIndexes = [];
+		for (const index of this._table.indexes.values()) {
+			if (index.type !== "unique") continue;
+			this.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))
+			});
+		}
+	}
+	/**
+	* No-op: the store is the instance-level {@link rows} Map, which already
+	* exists. Safe to call repeatedly.
+	*/
+	async ensureTable() {}
+};
+/**
+* Ergonomic late-binding entry point for provider (read-through) mode. Resolves
+* the ALREADY-BUILT {@link MemoryAdapter} backing `type` on `space` (reached
+* after `getTable`/`syncSchema` has constructed it via `space.getAdapter`, which
+* exists in core — so this helper needs NO core change) and installs `fn` as its
+* provider, making that one table read-only and recomputed per read.
+*
+* Throws if the resolved adapter is not a {@link MemoryAdapter} (i.e. the space
+* is backed by a different engine) so a misuse fails loudly, not silently.
+*/
+function setMemoryProvider(space, type, fn) {
+	const adapter = space.getAdapter(type);
+	if (!(adapter instanceof MemoryAdapter)) throw new Error("setMemoryProvider: table is not backed by MemoryAdapter");
+	adapter.setProvider(fn);
+}
+//#endregion
+//#region src/lib/index.ts
+/**
+* Creates a {@link DbSpace} backed by an in-memory {@link MemoryAdapter}.
+*
+* Tables default to STORED mode (an instance-level `Map`). To make one table
+* read-only and read-through from a runtime closure, call `setMemoryProvider`
+* (re-exported from {@link ./memory-adapter}) on the space AFTER the table's
+* adapter has been built.
+*/
+function createAdapter() {
+	return new DbSpace(() => new MemoryAdapter());
+}
+//#endregion
+export { MemoryAdapter, buildMemoryPredicate, createAdapter, projectRow, setMemoryProvider, sortRows };