@atscript/db-memory 0.1.146 → 0.1.148

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/lib/memory-adapter.d.ts
@@ -76,6 +76,17 @@ declare class MemoryAdapter extends BaseDbAdapter {
    *   decomposes patches into dot-path `$set`s and loads relations app-level.
    */
   canFilterField(fd: TDbFieldMeta): boolean;
+  /**
+   * Relational predicates (`{ nav: { $some | $none: … } }`) are evaluated in
+   * reads AND mutation filters. Before a filter holding them is compiled, every
+   * related table (and junction) is loaded ONCE for that operation — through
+   * its own adapter's snapshot seam, so a provider-backed related table works
+   * too — and each predicate becomes a set of matching correlation keys
+   * (see {@link _relationSets}). Predicate-free filters take the plain path.
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): 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
@@ -107,7 +118,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
   /**
    * 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
+   * PK path through `physicalPath` (`@db.column` renames included). 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.
    */
@@ -221,6 +232,22 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * AND single-snapshot-per-`findManyWithCount` both fall out for free.
    */
   protected _loadRows(): Record<string, unknown>[] | Promise<Record<string, unknown>[]>;
+  /**
+   * A per-operation row loader for relational predicates: each related table
+   * is snapshotted at most once per operation (the first predicate that needs
+   * it loads it; later ones — and nested ones — reuse that snapshot), so a
+   * provider-backed related table is invoked once per read. `own` seeds this
+   * table's snapshot so a self relation reads the same rows as the outer scan.
+   */
+  private _snapshotLoader;
+  /**
+   * The prepared correlation sets for `filter`'s relational predicates.
+   * Callers only await it when `containsRelationFilter(filter)` — a
+   * predicate-free filter keeps its fully synchronous path. Write methods call
+   * it BEFORE reading the table state, so the related tables (a self relation
+   * included) are snapshotted before any row changes, like SQL.
+   */
+  private _relationSets;
   /**
    * Clones the payload in, applies the version default, generates any
    * `@db.default.increment` values, enforces PK + unique constraints, stores
@@ -242,6 +269,9 @@ declare class MemoryAdapter extends BaseDbAdapter {
   private _enforceUniqueIndexes;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  supportsInsertIgnore(): boolean;
+  /** A row colliding on the primary key or a unique index (`CONFLICT`) becomes a skipped slot. */
+  insertManyIgnore(data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
   /**
    * 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 table's Map
@@ -257,6 +287,9 @@ declare class MemoryAdapter extends BaseDbAdapter {
    *
    * When `many` is `false` at most the first match is returned. A table that
    * does not exist (`state` undefined) matches nothing and is not created.
+   *
+   * A filter with relational predicates needs `relationSets`, prepared by the
+   * caller BEFORE it reads `state` (see {@link _relationSets}).
    */
   private _selectForWrite;
   /**
@@ -376,8 +409,12 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * there is no zone this adapter cannot resolve).
    */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
-  /** Every aggregate function, `countDistinct` included. */
+  /** Every aggregate function: `countDistinct`, `first` and `last` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
+  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>;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
@@ -449,6 +486,14 @@ type Predicate = (row: Record<string, unknown>) => boolean;
  * later concern; the SQL/Mongo adapters flatten differently and we do not want
  * to fake a semantic the store can't back yet.
  */
+/**
+ * Per-predicate correlation sets: for every {@link ResolvedRelationFilter} of
+ * a filter, the SOURCE correlation tuples (see {@link correlationKey}) that
+ * have at least one related row matching the predicate's inner filter.
+ * Built asynchronously by {@link prepareRelationSets}; consumed synchronously
+ * by {@link buildMemoryPredicate}.
+ */
+type RelationSets = ReadonlyMap<ResolvedRelationFilter, ReadonlySet<string>>;
 /**
  * Compiles a {@link FilterExpr} into an in-memory row predicate
  * `(row) => boolean`, reusing the shared {@link walkFilter} walker so filter
@@ -456,8 +501,13 @@ type Predicate = (row: Record<string, unknown>) => boolean;
  *
  * An empty/absent filter (for which `walkFilter` returns `undefined`) compiles
  * to a match-everything predicate.
+ *
+ * A filter holding relational predicates (`ResolvedRelationFilter` operands,
+ * since 0.1.147) needs `relationSets` — prepared internally by
+ * `MemoryAdapter` from the related tables; a standalone call on such a
+ * filter throws `REL_FILTER_NOT_SUPPORTED`.
  */
-declare function buildMemoryPredicate(filter: FilterExpr): Predicate;
+declare function buildMemoryPredicate(filter: FilterExpr, relationSets?: RelationSets): Predicate;
 //#endregion
 //#region src/lib/memory-engine.d.ts
 /**
@@ -525,4 +575,4 @@ declare function projectRow(row: Record<string, unknown>, projection?: Record<st
  */
 declare function createAdapter(): DbSpace;
 //#endregion
-export { MemoryAdapter, MemoryProviderFn, buildMemoryPredicate, createAdapter, projectRow, setMemoryProvider, sortRows };
+export { MemoryAdapter, type MemoryProviderFn, buildMemoryPredicate, createAdapter, projectRow, setMemoryProvider, sortRows };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/lib/memory-adapter.d.ts
@@ -76,6 +76,17 @@ declare class MemoryAdapter extends BaseDbAdapter {
    *   decomposes patches into dot-path `$set`s and loads relations app-level.
    */
   canFilterField(fd: TDbFieldMeta): boolean;
+  /**
+   * Relational predicates (`{ nav: { $some | $none: … } }`) are evaluated in
+   * reads AND mutation filters. Before a filter holding them is compiled, every
+   * related table (and junction) is loaded ONCE for that operation — through
+   * its own adapter's snapshot seam, so a provider-backed related table works
+   * too — and each predicate becomes a set of matching correlation keys
+   * (see {@link _relationSets}). Predicate-free filters take the plain path.
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): 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
@@ -107,7 +118,7 @@ declare class MemoryAdapter extends BaseDbAdapter {
   /**
    * 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
+   * PK path through `physicalPath` (`@db.column` renames included). 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.
    */
@@ -221,6 +232,22 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * AND single-snapshot-per-`findManyWithCount` both fall out for free.
    */
   protected _loadRows(): Record<string, unknown>[] | Promise<Record<string, unknown>[]>;
+  /**
+   * A per-operation row loader for relational predicates: each related table
+   * is snapshotted at most once per operation (the first predicate that needs
+   * it loads it; later ones — and nested ones — reuse that snapshot), so a
+   * provider-backed related table is invoked once per read. `own` seeds this
+   * table's snapshot so a self relation reads the same rows as the outer scan.
+   */
+  private _snapshotLoader;
+  /**
+   * The prepared correlation sets for `filter`'s relational predicates.
+   * Callers only await it when `containsRelationFilter(filter)` — a
+   * predicate-free filter keeps its fully synchronous path. Write methods call
+   * it BEFORE reading the table state, so the related tables (a self relation
+   * included) are snapshotted before any row changes, like SQL.
+   */
+  private _relationSets;
   /**
    * Clones the payload in, applies the version default, generates any
    * `@db.default.increment` values, enforces PK + unique constraints, stores
@@ -242,6 +269,9 @@ declare class MemoryAdapter extends BaseDbAdapter {
   private _enforceUniqueIndexes;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  supportsInsertIgnore(): boolean;
+  /** A row colliding on the primary key or a unique index (`CONFLICT`) becomes a skipped slot. */
+  insertManyIgnore(data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
   /**
    * 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 table's Map
@@ -257,6 +287,9 @@ declare class MemoryAdapter extends BaseDbAdapter {
    *
    * When `many` is `false` at most the first match is returned. A table that
    * does not exist (`state` undefined) matches nothing and is not created.
+   *
+   * A filter with relational predicates needs `relationSets`, prepared by the
+   * caller BEFORE it reads `state` (see {@link _relationSets}).
    */
   private _selectForWrite;
   /**
@@ -376,8 +409,12 @@ declare class MemoryAdapter extends BaseDbAdapter {
    * there is no zone this adapter cannot resolve).
    */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
-  /** Every aggregate function, `countDistinct` included. */
+  /** Every aggregate function: `countDistinct`, `first` and `last` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
+  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>;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
@@ -449,6 +486,14 @@ type Predicate = (row: Record<string, unknown>) => boolean;
  * later concern; the SQL/Mongo adapters flatten differently and we do not want
  * to fake a semantic the store can't back yet.
  */
+/**
+ * Per-predicate correlation sets: for every {@link ResolvedRelationFilter} of
+ * a filter, the SOURCE correlation tuples (see {@link correlationKey}) that
+ * have at least one related row matching the predicate's inner filter.
+ * Built asynchronously by {@link prepareRelationSets}; consumed synchronously
+ * by {@link buildMemoryPredicate}.
+ */
+type RelationSets = ReadonlyMap<ResolvedRelationFilter, ReadonlySet<string>>;
 /**
  * Compiles a {@link FilterExpr} into an in-memory row predicate
  * `(row) => boolean`, reusing the shared {@link walkFilter} walker so filter
@@ -456,8 +501,13 @@ type Predicate = (row: Record<string, unknown>) => boolean;
  *
  * An empty/absent filter (for which `walkFilter` returns `undefined`) compiles
  * to a match-everything predicate.
+ *
+ * A filter holding relational predicates (`ResolvedRelationFilter` operands,
+ * since 0.1.147) needs `relationSets` — prepared internally by
+ * `MemoryAdapter` from the related tables; a standalone call on such a
+ * filter throws `REL_FILTER_NOT_SUPPORTED`.
  */
-declare function buildMemoryPredicate(filter: FilterExpr): Predicate;
+declare function buildMemoryPredicate(filter: FilterExpr, relationSets?: RelationSets): Predicate;
 //#endregion
 //#region src/lib/memory-engine.d.ts
 /**
@@ -525,4 +575,4 @@ declare function projectRow(row: Record<string, unknown>, projection?: Record<st
  */
 declare function createAdapter(): DbSpace;
 //#endregion
-export { MemoryAdapter, MemoryProviderFn, buildMemoryPredicate, createAdapter, projectRow, setMemoryProvider, sortRows };
+export { MemoryAdapter, type MemoryProviderFn, buildMemoryPredicate, createAdapter, projectRow, setMemoryProvider, sortRows };