@atscript/db-mongo 0.1.145 → 0.1.147

package/dist/index.d.cts

@@ -1,5 +1,6 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbRelation, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TTableResolver, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
-import { AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
+import { a as buildMongoFilter, c as mongoFilterStages, i as TMongoFilterPlan, l as planStages, n as TMongoFieldCollation, o as buildMongoQuery, r as TMongoFilterOptions, s as collationOfAdapter, t as REL_FILTER_TEMP_PREFIX } from "./mongo-filter-CGd9ryOD.cjs";
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbCollation, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbRelation, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TTableResolver, TViewCapability, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
+import { AggregateOptions, AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
 import { TAtscriptAnnotatedType, TMetadataMap, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 import { AggregateFn, BucketUnit } from "@uniqu/core";
 
@@ -277,6 +278,12 @@ declare class MongoAdapter extends BaseDbAdapter {
   private get _client();
   /** Every adapter over this client (or database handle) shares one session (since 0.1.128). */
   protected _transactionOwner(): unknown;
+  /**
+   * Same store = same client (or database handle) AND the same database: a
+   * `$lookup` only reads collections of the pipeline's own database, and one
+   * client may serve several (since 0.1.147).
+   */
+  sharesStoreWith(other: BaseDbAdapter): boolean;
   /**
    * Per-client cache: whether transactions are unavailable (standalone MongoDB).
    * Shared across all adapter instances for the same client so topology is probed once.
@@ -296,7 +303,7 @@ declare class MongoAdapter extends BaseDbAdapter {
     session: ClientSession;
   } | Record<string, never>;
   get collection(): Collection<any>;
-  aggregatePipeline(pipeline: Document[]): AggregationCursor;
+  aggregatePipeline(pipeline: Document[], options?: AggregateOptions): AggregationCursor;
   aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
   get idType(): "string" | "number" | "objectId";
   prepareId(id: unknown, _fieldType: unknown): unknown;
@@ -307,10 +314,12 @@ declare class MongoAdapter extends BaseDbAdapter {
   prepareIdFromIdType<D = string | number | ObjectId>(id: string | number | ObjectId): D;
   supportsNestedObjects(): boolean;
   supportsNativePatch(): boolean;
-  /** All five units, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
+  /** Every unit, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /** Every aggregate function, `countDistinct` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Computed view columns and first-row joins. */
+  viewCapabilities(): ReadonlySet<TViewCapability>;
   /**
    * See BaseDbAdapter.viewRenderRevision. 2 = 0.1.137 (null-guarded field filters, nested document paths).
    * BUMP whenever `buildViewPipeline` output changes for an unchanged view definition.
@@ -348,6 +357,46 @@ declare class MongoAdapter extends BaseDbAdapter {
   } | undefined;
   getAdapterTableName(_type: unknown): string | undefined;
   supportsNativeRelations(): boolean;
+  /**
+   * Relational predicates (`{ nav: { $some | $none: … } }`) render as
+   * correlated `$lookup` stages, so a read whose filter holds one runs as an
+   * aggregation pipeline (find / count / findManyWithCount / grouped
+   * aggregate / search / geo); predicate-free reads keep their plain
+   * `find` / `countDocuments` path.
+   *
+   * Writes (`updateMany` / `replaceMany` / `deleteMany` and the single-row
+   * variants, whose scope may carry a predicate) first resolve the matching
+   * `_id`s through that pipeline, then write by `_id` in batches of
+   * {@link REL_WRITE_BATCH} — re-checking the predicate-free part of the
+   * filter. Inside an active transaction both steps share its session and
+   * are atomic; without one there is a window between resolving and writing
+   * in which a related document can change, so a written document may no
+   * longer satisfy the predicate (or a newly matching one is missed).
+   *
+   * Collation: such a pipeline runs without an operation-wide `collation`
+   * (it would govern the join keys and every related field too); each
+   * table's `'nocase'` fields are compared case-insensitively explicitly
+   * ({@link TMongoFilterOptions.collation}) — on reads and on these writes.
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): boolean;
+  /**
+   * The `@db.column.collate` of a field (physical or logical path), or
+   * `undefined` for a byte-wise one — how predicate pipelines render this
+   * table's `'nocase'` comparisons ({@link TMongoFilterOptions.collation}).
+   *
+   * @since 0.1.147
+   */
+  fieldCollation(field: string): TDbCollation | undefined;
+  /** Filter-rendering options of a pipeline with relational predicates on this table. */
+  private get _predicateFilterOpts();
+  /**
+   * Operation options of a read: the request collation for a predicate-free
+   * filter ({@link _getCollationOpts}); none with relational predicates —
+   * those pipelines render collation per field ({@link _predicateFilterOpts}).
+   */
+  private _readOpts;
   loadRelations(rows: Array<Record<string, unknown>>, withRelations: WithRelation[], relations: ReadonlyMap<string, TDbRelation>, foreignKeys: ReadonlyMap<string, TDbForeignKey>, tableResolver?: TTableResolver): Promise<void>;
   /** Returns the context object used by CollectionPatcher. */
   getPatcherContext(): TCollectionPatcherContext;
@@ -394,6 +443,37 @@ declare class MongoAdapter extends BaseDbAdapter {
    * rather than silently dropping the CAS predicate.
    */
   private _buildCasFilter;
+  /**
+   * The id-resolving pipeline of a write filter holding relational
+   * predicates: the matching `_id`s (in the active transaction's session,
+   * if any), each table's `'nocase'` fields compared like on reads
+   * ({@link _predicateFilterOpts}). `pre` is the predicate-free part, which
+   * every `_id`-based write re-checks — so a document that stopped matching
+   * it in between is not written.
+   */
+  private _predicateWritePlan;
+  /** A write filter's `_id` filter (re-checking `pre`). */
+  private static _byIds;
+  /** Single-document write over a predicate filter: the first match's `_id` filter (`undefined`: none). */
+  private _predicateWriteFilterOne;
+  /**
+   * Multi-document write over `filter`: a predicate-free filter is written
+   * as is; one with predicates calls `write` with one `_id`-based filter per
+   * batch of {@link REL_WRITE_BATCH} matching ids, streamed from the cursor
+   * (never all ids in memory at once).
+   *
+   * The ids come sorted by `_id`, so writes made while the cursor is open
+   * can never feed back into it (otherwise a document an update moves within
+   * the index the cursor scans could be returned — and written — twice):
+   * after the `$lookup`s that `$sort` consumes every match before the first
+   * batch returns, and an `_id` order read from the `_id` index is stable
+   * (`_id` never changes).
+   */
+  private _forEachMatching;
+  /** Runs an update-shaped write over `filter` ({@link _forEachMatching}), counts summed. */
+  private _updateMatching;
+  /** The filter of a single-document write — its predicates resolved to one `_id`. */
+  private _writeFilterOne;
   /**
    * Wraps an async operation to catch MongoDB duplicate key errors
    * (code 11000) and rethrow as structured `DbError` — every write path
@@ -452,11 +532,16 @@ declare class MongoAdapter extends BaseDbAdapter {
   private _getCurrentFieldMax;
   /** Allocates increment values for a batch of items, assigning in order. */
   private _assignBatchIncrements;
+  /** A find whose filter holds relational predicates, as an aggregation pipeline. */
+  private _aggregateFind;
   private _buildFindOptions;
   /**
    * Returns MongoDB collation options if any filter field has a non-binary collation.
    * Uses pre-computed insights when available, falls back to computing them on demand.
    * Maps: nocase → strength 2 (case-insensitive), unicode → strength 1 (case+accent-insensitive).
+   * Predicate-free filters only — a filter with relational predicates never gets an
+   * operation-wide collation ({@link _readOpts}), so insights are never computed over
+   * resolved predicate operands.
    */
   private _getCollationOpts;
   protected _addMongoIndexField(type: TPlainIndex["type"], name: string, field: string, weight?: number): void;
@@ -484,27 +569,10 @@ declare class MongoAdapter extends BaseDbAdapter {
   private _descendSearchNode;
 }
 //#endregion
-//#region src/lib/mongo-filter.d.ts
-/**
- * Translates a generic {@link FilterExpr} into a MongoDB-compatible
- * {@link Filter} document.
- *
- * MongoDB's query language is nearly identical to the `FilterExpr` structure,
- * so this is largely a structural pass-through via the `walkFilter` visitor.
- * `fieldOperands` (view predicates only — `translateQueryTree` output) turns
- * `{ $field: path }` operands into field-to-field `$expr` comparisons; a
- * request filter never gets that reading.
- */
-declare function buildMongoFilter(filter: FilterExpr, {
-  fieldOperands
-}?: {
-  fieldOperands?: boolean;
-}): Filter<any>;
-//#endregion
 //#region src/lib/validate-plugins.d.ts
 declare const validateMongoIdPlugin: TValidatorPlugin;
 //#endregion
 //#region src/lib/index.d.ts
 declare function createAdapter(connection: string, _options?: Record<string, unknown>): DbSpace;
 //#endregion
-export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, TCollectionPatcherContext, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, createAdapter, mongoIndexKey, validateMongoIdPlugin };
+export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, REL_FILTER_TEMP_PREFIX, TCollectionPatcherContext, TMongoFieldCollation, TMongoFilterOptions, TMongoFilterPlan, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, buildMongoQuery, collationOfAdapter, createAdapter, mongoFilterStages, mongoIndexKey, planStages, validateMongoIdPlugin };

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbRelation, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TTableResolver, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
-import { AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
+import { a as buildMongoFilter, c as mongoFilterStages, i as TMongoFilterPlan, l as planStages, n as TMongoFieldCollation, o as buildMongoQuery, r as TMongoFilterOptions, s as collationOfAdapter, t as REL_FILTER_TEMP_PREFIX } from "./mongo-filter-CGd9ryOD.mjs";
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbCollation, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbRelation, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TTableResolver, TViewCapability, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
+import { AggregateOptions, AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
 import { AggregateFn, BucketUnit } from "@uniqu/core";
 import { TAtscriptAnnotatedType, TMetadataMap, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 
@@ -277,6 +278,12 @@ declare class MongoAdapter extends BaseDbAdapter {
   private get _client();
   /** Every adapter over this client (or database handle) shares one session (since 0.1.128). */
   protected _transactionOwner(): unknown;
+  /**
+   * Same store = same client (or database handle) AND the same database: a
+   * `$lookup` only reads collections of the pipeline's own database, and one
+   * client may serve several (since 0.1.147).
+   */
+  sharesStoreWith(other: BaseDbAdapter): boolean;
   /**
    * Per-client cache: whether transactions are unavailable (standalone MongoDB).
    * Shared across all adapter instances for the same client so topology is probed once.
@@ -296,7 +303,7 @@ declare class MongoAdapter extends BaseDbAdapter {
     session: ClientSession;
   } | Record<string, never>;
   get collection(): Collection<any>;
-  aggregatePipeline(pipeline: Document[]): AggregationCursor;
+  aggregatePipeline(pipeline: Document[], options?: AggregateOptions): AggregationCursor;
   aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
   get idType(): "string" | "number" | "objectId";
   prepareId(id: unknown, _fieldType: unknown): unknown;
@@ -307,10 +314,12 @@ declare class MongoAdapter extends BaseDbAdapter {
   prepareIdFromIdType<D = string | number | ObjectId>(id: string | number | ObjectId): D;
   supportsNestedObjects(): boolean;
   supportsNativePatch(): boolean;
-  /** All five units, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
+  /** Every unit, over MongoDB's bundled time zone database (see `agg.ts` `bucketExpression`). */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /** Every aggregate function, `countDistinct` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Computed view columns and first-row joins. */
+  viewCapabilities(): ReadonlySet<TViewCapability>;
   /**
    * See BaseDbAdapter.viewRenderRevision. 2 = 0.1.137 (null-guarded field filters, nested document paths).
    * BUMP whenever `buildViewPipeline` output changes for an unchanged view definition.
@@ -348,6 +357,46 @@ declare class MongoAdapter extends BaseDbAdapter {
   } | undefined;
   getAdapterTableName(_type: unknown): string | undefined;
   supportsNativeRelations(): boolean;
+  /**
+   * Relational predicates (`{ nav: { $some | $none: … } }`) render as
+   * correlated `$lookup` stages, so a read whose filter holds one runs as an
+   * aggregation pipeline (find / count / findManyWithCount / grouped
+   * aggregate / search / geo); predicate-free reads keep their plain
+   * `find` / `countDocuments` path.
+   *
+   * Writes (`updateMany` / `replaceMany` / `deleteMany` and the single-row
+   * variants, whose scope may carry a predicate) first resolve the matching
+   * `_id`s through that pipeline, then write by `_id` in batches of
+   * {@link REL_WRITE_BATCH} — re-checking the predicate-free part of the
+   * filter. Inside an active transaction both steps share its session and
+   * are atomic; without one there is a window between resolving and writing
+   * in which a related document can change, so a written document may no
+   * longer satisfy the predicate (or a newly matching one is missed).
+   *
+   * Collation: such a pipeline runs without an operation-wide `collation`
+   * (it would govern the join keys and every related field too); each
+   * table's `'nocase'` fields are compared case-insensitively explicitly
+   * ({@link TMongoFilterOptions.collation}) — on reads and on these writes.
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): boolean;
+  /**
+   * The `@db.column.collate` of a field (physical or logical path), or
+   * `undefined` for a byte-wise one — how predicate pipelines render this
+   * table's `'nocase'` comparisons ({@link TMongoFilterOptions.collation}).
+   *
+   * @since 0.1.147
+   */
+  fieldCollation(field: string): TDbCollation | undefined;
+  /** Filter-rendering options of a pipeline with relational predicates on this table. */
+  private get _predicateFilterOpts();
+  /**
+   * Operation options of a read: the request collation for a predicate-free
+   * filter ({@link _getCollationOpts}); none with relational predicates —
+   * those pipelines render collation per field ({@link _predicateFilterOpts}).
+   */
+  private _readOpts;
   loadRelations(rows: Array<Record<string, unknown>>, withRelations: WithRelation[], relations: ReadonlyMap<string, TDbRelation>, foreignKeys: ReadonlyMap<string, TDbForeignKey>, tableResolver?: TTableResolver): Promise<void>;
   /** Returns the context object used by CollectionPatcher. */
   getPatcherContext(): TCollectionPatcherContext;
@@ -394,6 +443,37 @@ declare class MongoAdapter extends BaseDbAdapter {
    * rather than silently dropping the CAS predicate.
    */
   private _buildCasFilter;
+  /**
+   * The id-resolving pipeline of a write filter holding relational
+   * predicates: the matching `_id`s (in the active transaction's session,
+   * if any), each table's `'nocase'` fields compared like on reads
+   * ({@link _predicateFilterOpts}). `pre` is the predicate-free part, which
+   * every `_id`-based write re-checks — so a document that stopped matching
+   * it in between is not written.
+   */
+  private _predicateWritePlan;
+  /** A write filter's `_id` filter (re-checking `pre`). */
+  private static _byIds;
+  /** Single-document write over a predicate filter: the first match's `_id` filter (`undefined`: none). */
+  private _predicateWriteFilterOne;
+  /**
+   * Multi-document write over `filter`: a predicate-free filter is written
+   * as is; one with predicates calls `write` with one `_id`-based filter per
+   * batch of {@link REL_WRITE_BATCH} matching ids, streamed from the cursor
+   * (never all ids in memory at once).
+   *
+   * The ids come sorted by `_id`, so writes made while the cursor is open
+   * can never feed back into it (otherwise a document an update moves within
+   * the index the cursor scans could be returned — and written — twice):
+   * after the `$lookup`s that `$sort` consumes every match before the first
+   * batch returns, and an `_id` order read from the `_id` index is stable
+   * (`_id` never changes).
+   */
+  private _forEachMatching;
+  /** Runs an update-shaped write over `filter` ({@link _forEachMatching}), counts summed. */
+  private _updateMatching;
+  /** The filter of a single-document write — its predicates resolved to one `_id`. */
+  private _writeFilterOne;
   /**
    * Wraps an async operation to catch MongoDB duplicate key errors
    * (code 11000) and rethrow as structured `DbError` — every write path
@@ -452,11 +532,16 @@ declare class MongoAdapter extends BaseDbAdapter {
   private _getCurrentFieldMax;
   /** Allocates increment values for a batch of items, assigning in order. */
   private _assignBatchIncrements;
+  /** A find whose filter holds relational predicates, as an aggregation pipeline. */
+  private _aggregateFind;
   private _buildFindOptions;
   /**
    * Returns MongoDB collation options if any filter field has a non-binary collation.
    * Uses pre-computed insights when available, falls back to computing them on demand.
    * Maps: nocase → strength 2 (case-insensitive), unicode → strength 1 (case+accent-insensitive).
+   * Predicate-free filters only — a filter with relational predicates never gets an
+   * operation-wide collation ({@link _readOpts}), so insights are never computed over
+   * resolved predicate operands.
    */
   private _getCollationOpts;
   protected _addMongoIndexField(type: TPlainIndex["type"], name: string, field: string, weight?: number): void;
@@ -484,27 +569,10 @@ declare class MongoAdapter extends BaseDbAdapter {
   private _descendSearchNode;
 }
 //#endregion
-//#region src/lib/mongo-filter.d.ts
-/**
- * Translates a generic {@link FilterExpr} into a MongoDB-compatible
- * {@link Filter} document.
- *
- * MongoDB's query language is nearly identical to the `FilterExpr` structure,
- * so this is largely a structural pass-through via the `walkFilter` visitor.
- * `fieldOperands` (view predicates only — `translateQueryTree` output) turns
- * `{ $field: path }` operands into field-to-field `$expr` comparisons; a
- * request filter never gets that reading.
- */
-declare function buildMongoFilter(filter: FilterExpr, {
-  fieldOperands
-}?: {
-  fieldOperands?: boolean;
-}): Filter<any>;
-//#endregion
 //#region src/lib/validate-plugins.d.ts
 declare const validateMongoIdPlugin: TValidatorPlugin;
 //#endregion
 //#region src/lib/index.d.ts
 declare function createAdapter(connection: string, _options?: Record<string, unknown>): DbSpace;
 //#endregion
-export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, TCollectionPatcherContext, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, createAdapter, mongoIndexKey, validateMongoIdPlugin };
+export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, REL_FILTER_TEMP_PREFIX, TCollectionPatcherContext, TMongoFieldCollation, TMongoFilterOptions, TMongoFilterPlan, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, buildMongoQuery, collationOfAdapter, createAdapter, mongoFilterStages, mongoIndexKey, planStages, validateMongoIdPlugin };