@atscript/db-memory 0.1.113

package/dist/index.d.mts

@@ -0,0 +1,484 @@
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TFieldOps } from "@atscript/db";
+import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+
+//#region src/lib/memory-adapter.d.ts
+/**
+ * Provider (read-through) backing closure. Recomputes and returns the table's
+ * rows on demand — a fresh snapshot every call (sync or async). See
+ * {@link MemoryAdapter.setProvider} / {@link setMemoryProvider}.
+ */
+type MemoryProviderFn = () => Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>>;
+/**
+ * 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}).
+ */
+declare class MemoryAdapter 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.
+   */
+  private rows;
+  /** Unique indexes recorded by {@link syncIndexes}. Enforced on insert. */
+  private uniqueIndexes;
+  /** Memoized physical PK field names — stable for the adapter's lifetime. */
+  private _pkFieldsCache?;
+  /**
+   * Memoized map of PHYSICAL field name → optional `start` for every field
+   * carrying `@db.default.increment`. Stable per adapter (see
+   * {@link _incrementFields}).
+   */
+  private _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.
+   */
+  private _incrementCounters;
+  /**
+   * 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}.
+   */
+  private _provider?;
+  /**
+   * The in-memory store keeps documents nested (no flattening), so the generic
+   * layer should pass nested objects through as-is.
+   */
+  supportsNestedObjects(): boolean;
+  /**
+   * 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: TDbFieldMeta): boolean;
+  /**
+   * 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: unknown, _fieldType: unknown): unknown;
+  /**
+   * 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.
+   */
+  private _physicalPkFields;
+  /**
+   * 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.
+   */
+  private _incrementFields;
+  /**
+   * 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.
+   */
+  private _applyIncrements;
+  /**
+   * 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.
+   */
+  private _pkConflict;
+  /**
+   * 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'`.
+   */
+  private pkKey;
+  /**
+   * 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.
+   */
+  private _compositeInsertedId;
+  /**
+   * 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: MemoryProviderFn): void;
+  /**
+   * 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.
+   */
+  private _assertWritable;
+  /**
+   * 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.
+   */
+  protected _loadRows(): Record<string, unknown>[] | Promise<Record<string, unknown>[]>;
+  /**
+   * 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.
+   */
+  private _insertRow;
+  /**
+   * 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.
+   */
+  private _enforceUniqueIndexes;
+  insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
+  insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  /**
+   * 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.
+   */
+  private _selectForWrite;
+  /**
+   * 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).
+   */
+  private _bumpVersion;
+  /**
+   * 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`.
+   */
+  private _applyUpdate;
+  /**
+   * 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.
+   */
+  private _commitRow;
+  /**
+   * 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.
+   */
+  private _commitUpdate;
+  replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
+  updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number): Promise<TDbUpdateResult>;
+  deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
+  /**
+   * 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.
+   */
+  private _sortRows;
+  /** Applies `$skip` then `$limit` (both optional) via a single slice. */
+  private _paginate;
+  /**
+   * 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.
+   */
+  private _projectAndClone;
+  /**
+   * 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.
+   */
+  private _readControls;
+  /**
+   * 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.
+   */
+  private _filteredRows;
+  findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
+  findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  count(query: DbQuery): Promise<number>;
+  /**
+   * 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.
+   */
+  findManyWithCount(query: DbQuery): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  /**
+   * 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.
+   */
+  aggregate(_query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+  deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+  /**
+   * 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.
+   */
+  syncIndexes(): Promise<void>;
+  /**
+   * No-op: the store is the instance-level {@link rows} Map, which already
+   * exists. Safe to call repeatedly.
+   */
+  ensureTable(): Promise<void>;
+}
+/**
+ * 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.
+ */
+declare function setMemoryProvider(space: DbSpace, type: TAtscriptAnnotatedType, fn: MemoryProviderFn): void;
+//#endregion
+//#region src/lib/memory-filter.d.ts
+/**
+ * In-memory row predicate: given a document, decide whether it matches a
+ * filter. This is the single unit of currency the whole engine composes —
+ * leaves, logical nodes and the top-level filter all reduce to one of these.
+ */
+type Predicate = (row: Record<string, unknown>) => boolean;
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+declare function buildMemoryPredicate(filter: FilterExpr): Predicate;
+//#endregion
+//#region src/lib/memory-engine.d.ts
+/**
+ * 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.
+ */
+declare function sortRows(rows: Record<string, unknown>[], $sort?: Partial<Record<string, 1 | -1>>, tieBreak?: (row: Record<string, unknown>) => string | number): Record<string, unknown>[];
+/** Options for {@link projectRow}. */
+interface ProjectRowOptions {
+  /**
+   * Physical field names ALWAYS kept by an inclusion projection (mirrors Mongo
+   * including `_id`). The adapter passes its primary-key field(s); a consumer
+   * with no PK (e.g. value-help) passes none. Ignored for exclusion / no
+   * projection.
+   */
+  pkFields?: string[];
+  /**
+   * When `true`, the returned object is `structuredClone`d so it shares NO
+   * structure with `row` (mutating the output leaves the input intact) — what
+   * the adapter needs to keep its store authoritative. When `false`/absent the
+   * output may alias nested subtrees of `row` (cheaper; for callers that own
+   * their rows).
+   */
+  clone?: boolean;
+}
+/**
+ * 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.
+ */
+declare function projectRow(row: Record<string, unknown>, projection?: Record<string, 0 | 1>, opts?: ProjectRowOptions): Record<string, unknown>;
+//#endregion
+//#region src/lib/index.d.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.
+ */
+declare function createAdapter(): DbSpace;
+//#endregion
+export { MemoryAdapter, MemoryProviderFn, buildMemoryPredicate, createAdapter, projectRow, setMemoryProvider, sortRows };