@atscript/db-memory 0.1.149 → 0.1.151

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/lib/memory-adapter.d.ts
@@ -33,6 +33,8 @@ declare class MemoryAdapter extends BaseDbAdapter {
   private _db;
   /** Memoized physical PK field names — stable for the adapter's lifetime. */
   private _pkFieldsCache?;
+  /** Memoized compiled readers of {@link _physicalPkFields}. */
+  private _pkReadersCache?;
   /**
    * Memoized map of PHYSICAL field name → optional `start` for every field
    * carrying `@db.default.increment`. Stable per adapter (see
@@ -123,6 +125,8 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * `pkKey`/projection — recomputing would re-read `this._table.*` and re-allocate.
    */
   private _physicalPkFields;
+  /** Compiled readers of {@link _physicalPkFields} (memoized like it). */
+  private _pkReaders;
   /**
    * PHYSICAL field name → optional `start` for every `@db.default.increment`
    * field. Discovered lazily from the table's field descriptors — each carries
@@ -175,6 +179,16 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * `['a:b','c']` differ, and `1` differs from `'1'`.
    */
   private pkKey;
+  /**
+   * 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.
+   */
+  private _pinnedKey;
   /**
    * Builds a DEFINED inserted-id for a table with NO single `@meta.id` — a
    * composite (or single non-meta) primary key, where
@@ -251,8 +265,9 @@ declare 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.
    */
@@ -261,12 +276,21 @@ declare 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.
    */
   private _enforceUniqueIndexes;
+  /**
+   * 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.
+   */
+  private _storeRow;
+  /** Removes the row stored under `key` (and its unique-index entries). */
+  private _removeRow;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
   supportsInsertIgnore(): boolean;
@@ -311,7 +335,7 @@ declare 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
@@ -323,10 +347,11 @@ declare class MemoryAdapter extends BaseDbAdapter {
    */
   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.
+   * 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.
    */
   private _commitRow;
   /**
@@ -335,22 +360,24 @@ declare 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).
    */
   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>;
+  updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number, opts?: TDbUpdateOptions): 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.
+   * {@link sortRows}, injecting {@link pkKey} as the total-order tie-break;
+   * `topK` asks for the head of that order only (`$skip + $limit`).
    */
   private _sortRows;
   /**
-   * 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
@@ -361,7 +388,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * Top-level and nested dot-paths are supported; exotic Mongo projection
    * quirks (array positional, `$slice`, etc.) are intentionally NOT replicated.
    */
-  private _projectAndClone;
+  private _projector;
   /**
    * Reads the pagination/sort/projection controls with their intended types.
    * `DbControls` carries a `[key: `$${string}`]: unknown` index signature, and
@@ -375,6 +402,10 @@ declare 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`).
    */
   private _filteredRows;
   findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
@@ -415,7 +446,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
   supportsAggregateExpressions(): boolean;
   /** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
-  updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
   /**
@@ -520,13 +551,16 @@ declare function buildMemoryPredicate(filter: FilterExpr, relationSets?: Relatio
  *   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.
  */
-declare function sortRows(rows: Record<string, unknown>[], $sort?: Partial<Record<string, 1 | -1>>, tieBreak?: (row: Record<string, unknown>) => string | number): Record<string, unknown>[];
+declare function sortRows(rows: Record<string, unknown>[], $sort?: Partial<Record<string, 1 | -1>>, tieBreak?: (row: Record<string, unknown>) => string | number, topK?: number): Record<string, unknown>[];
 /** Options for {@link projectRow}. */
 interface ProjectRowOptions {
   /**
@@ -560,6 +594,9 @@ interface ProjectRowOptions {
  *
  * 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}.
  */
 declare function projectRow(row: Record<string, unknown>, projection?: Record<string, 0 | 1>, opts?: ProjectRowOptions): Record<string, unknown>;
 //#endregion

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/lib/memory-adapter.d.ts
@@ -33,6 +33,8 @@ declare class MemoryAdapter extends BaseDbAdapter {
   private _db;
   /** Memoized physical PK field names — stable for the adapter's lifetime. */
   private _pkFieldsCache?;
+  /** Memoized compiled readers of {@link _physicalPkFields}. */
+  private _pkReadersCache?;
   /**
    * Memoized map of PHYSICAL field name → optional `start` for every field
    * carrying `@db.default.increment`. Stable per adapter (see
@@ -123,6 +125,8 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * `pkKey`/projection — recomputing would re-read `this._table.*` and re-allocate.
    */
   private _physicalPkFields;
+  /** Compiled readers of {@link _physicalPkFields} (memoized like it). */
+  private _pkReaders;
   /**
    * PHYSICAL field name → optional `start` for every `@db.default.increment`
    * field. Discovered lazily from the table's field descriptors — each carries
@@ -175,6 +179,16 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * `['a:b','c']` differ, and `1` differs from `'1'`.
    */
   private pkKey;
+  /**
+   * 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.
+   */
+  private _pinnedKey;
   /**
    * Builds a DEFINED inserted-id for a table with NO single `@meta.id` — a
    * composite (or single non-meta) primary key, where
@@ -251,8 +265,9 @@ declare 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.
    */
@@ -261,12 +276,21 @@ declare 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.
    */
   private _enforceUniqueIndexes;
+  /**
+   * 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.
+   */
+  private _storeRow;
+  /** Removes the row stored under `key` (and its unique-index entries). */
+  private _removeRow;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
   supportsInsertIgnore(): boolean;
@@ -311,7 +335,7 @@ declare 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
@@ -323,10 +347,11 @@ declare class MemoryAdapter extends BaseDbAdapter {
    */
   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.
+   * 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.
    */
   private _commitRow;
   /**
@@ -335,22 +360,24 @@ declare 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).
    */
   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>;
+  updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number, opts?: TDbUpdateOptions): 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.
+   * {@link sortRows}, injecting {@link pkKey} as the total-order tie-break;
+   * `topK` asks for the head of that order only (`$skip + $limit`).
    */
   private _sortRows;
   /**
-   * 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
@@ -361,7 +388,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * Top-level and nested dot-paths are supported; exotic Mongo projection
    * quirks (array positional, `$slice`, etc.) are intentionally NOT replicated.
    */
-  private _projectAndClone;
+  private _projector;
   /**
    * Reads the pagination/sort/projection controls with their intended types.
    * `DbControls` carries a `[key: `$${string}`]: unknown` index signature, and
@@ -375,6 +402,10 @@ declare 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`).
    */
   private _filteredRows;
   findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
@@ -415,7 +446,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
   supportsAggregateExpressions(): boolean;
   /** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
-  updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
   /**
@@ -520,13 +551,16 @@ declare function buildMemoryPredicate(filter: FilterExpr, relationSets?: Relatio
  *   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.
  */
-declare function sortRows(rows: Record<string, unknown>[], $sort?: Partial<Record<string, 1 | -1>>, tieBreak?: (row: Record<string, unknown>) => string | number): Record<string, unknown>[];
+declare function sortRows(rows: Record<string, unknown>[], $sort?: Partial<Record<string, 1 | -1>>, tieBreak?: (row: Record<string, unknown>) => string | number, topK?: number): Record<string, unknown>[];
 /** Options for {@link projectRow}. */
 interface ProjectRowOptions {
   /**
@@ -560,6 +594,9 @@ interface ProjectRowOptions {
  *
  * 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}.
  */
 declare function projectRow(row: Record<string, unknown>, projection?: Record<string, 0 | 1>, opts?: ProjectRowOptions): Record<string, unknown>;
 //#endregion