@atscript/mongo 0.1.31 → 0.1.32

package/dist/index.d.ts

@@ -1,10 +1,7 @@
-import { TAtscriptPlugin } from '@atscript/core';
+import { TAtscriptAnnotatedType, TValidatorOptions, Validator, TAtscriptTypeArray, TValidatorPlugin, TMetadataMap } from '@atscript/typescript/utils';
+import { AtscriptDbTable, BaseDbAdapter, FilterExpr, TDbUpdateResult, TSearchIndexInfo, DbQuery, TDbInsertResult, TDbInsertManyResult, TDbDeleteResult } from '@atscript/utils-db';
 import * as mongodb from 'mongodb';
-import { MongoClient, Collection, ObjectId, InsertOneOptions, ReplaceOptions, UpdateOptions, Filter } from 'mongodb';
-import * as _atscript_typescript_annotated_type from '@atscript/typescript/annotated-type';
-import { TAtscriptAnnotatedType, TAtscriptDataType, Validator, TValidatorOptions, TAtscriptTypeObject, TMetadataMap } from '@atscript/typescript/utils';
-
-declare const MongoPlugin: () => TAtscriptPlugin;
+import { MongoClient, Filter, UpdateFilter, Document, UpdateOptions, Db, Collection, AggregationCursor, ObjectId } from 'mongodb';
 
 interface TGenericLogger {
     error(...messages: any[]): void;
@@ -22,8 +19,157 @@ declare class AsMongo {
     protected collectionsList?: Promise<Set<string>>;
     protected getCollectionsList(): Promise<Set<string>>;
     collectionExists(name: string): Promise<boolean>;
-    getCollection<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AsCollection<T>;
-    private _collections;
+    getAdapter<T extends TAtscriptAnnotatedType>(type: T): MongoAdapter;
+    getTable<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbTable<T, any, any, any>;
+    private _ensureCreated;
+    private _adapters;
+    private _tables;
+}
+
+/**
+ * Context interface for CollectionPatcher.
+ * Decouples the patcher from AsCollection, allowing MongoAdapter to provide this.
+ */
+interface TCollectionPatcherContext {
+    flatMap: Map<string, TAtscriptAnnotatedType>;
+    prepareId(id: any): any;
+    createValidator(opts?: Partial<TValidatorOptions>): Validator<any>;
+}
+/**
+ * CollectionPatcher is a small helper that converts a *patch payload* produced
+ * by Atscript into a shape that the official MongoDB driver understands – a
+ * triple of `(filter, update, options)` to be fed to `collection.updateOne()`.
+ *
+ * Supported high‑level operations for *top‑level arrays* (see the attached
+ * spreadsheet in the chat):
+ *
+ * | Payload field | MongoDB operator        | Purpose                                |
+ * |-------------- |-------------------------|----------------------------------------|
+ * | `$replace`    | full `$set`             | Replace the whole array.               |
+ * | `$insert`     | `$push`                 | Append new items (duplicates allowed). |
+ * | `$upsert`     | custom                  | Insert or update by *key* (see TODO).  |
+ * | `$update`     | `$set` + `arrayFilters` | Update array elements matched by *key* |
+ * | `$remove`     | `$pullAll` / `$pull`    | Remove by value or by *key*.           |
+ *
+ * The class walks through the incoming payload, detects which of the above
+ * operations applies to each top‑level array and builds the corresponding
+ * MongoDB update document. Primitive fields are flattened into a regular
+ * `$set` map.
+ */
+declare class CollectionPatcher {
+    private collection;
+    private payload;
+    constructor(collection: TCollectionPatcherContext, payload: any);
+    /**
+     * Extract a set of *key properties* (annotated with `@expect.array.key`) from an
+     * array‐of‐objects type definition. These keys uniquely identify an element
+     * inside the array and are later used for `$update`, `$remove` and `$upsert`.
+     *
+     * @param def Atscript array type
+     * @returns Set of property names marked as keys; empty set if none
+     */
+    static getKeyProps(def: TAtscriptAnnotatedType<TAtscriptTypeArray>): Set<string>;
+    /**
+     * Build a runtime *Validator* that understands the extended patch payload.
+     *
+     *  * Adds per‑array *patch* wrappers (the `$replace`, `$insert`, … fields).
+     *  * Honors `db.patch.strategy === "merge"` metadata.
+     *
+     * @param collection Target collection wrapper
+     * @returns Atscript Validator
+     */
+    static prepareValidator(context: TCollectionPatcherContext): Validator<any, unknown>;
+    /**
+     * Internal accumulator: filter passed to `updateOne()`.
+     * Filled only with the `_id` field right now.
+     */
+    private filterObj;
+    /** MongoDB *update* document being built. */
+    private updatePipeline;
+    /** Additional *options* (mainly `arrayFilters`). */
+    private optionsObj;
+    /**
+     * Entry point – walk the payload, build `filter`, `update` and `options`.
+     *
+     * @returns Helper object exposing both individual parts and
+     *          a `.toArgs()` convenience callback.
+     */
+    preparePatch(): {
+        toArgs: () => [Filter<any>, UpdateFilter<any> | Document[], UpdateOptions];
+        filter: Filter<any>;
+        updateFilter: Document[];
+        updateOptions: UpdateOptions;
+    };
+    /**
+     * Helper – lazily create `$set` section and assign *key* → *value*.
+     *
+     * @param key Fully‑qualified dotted path
+     * @param val Value to be written
+     * @private
+     */
+    private _set;
+    /**
+     * Recursively walk through the patch *payload* and convert it into `$set`/…
+     * statements. Top‑level arrays are delegated to {@link parseArrayPatch}.
+     *
+     * @param payload Current payload chunk
+     * @param prefix  Dotted path accumulated so far
+     * @private
+     */
+    private flattenPayload;
+    /**
+     * Dispatch a *single* array patch. Exactly one of `$replace`, `$insert`,
+     * `$upsert`, `$update`, `$remove` must be present – otherwise we throw.
+     *
+     * @param key   Dotted path to the array field
+     * @param value Payload slice for that field
+     * @private
+     */
+    private parseArrayPatch;
+    /**
+     * Build an *aggregation‐expression* that checks equality by **all** keys in
+     * `keys`.  Example output for keys `["id", "lang"]` and bases `a`, `b`:
+     * ```json
+     * { "$and": [ { "$eq": ["$$a.id", "$$b.id"] }, { "$eq": ["$$a.lang", "$$b.lang"] } ] }
+     * ```
+     *
+     * @param keys  Ordered list of key property names
+     * @param left  Base token for *left* expression (e.g. `"$$el"`)
+     * @param right Base token for *right* expression (e.g. `"$$this"`)
+     */
+    private _keysEqual;
+    /**
+     * `$replace` – overwrite the entire array with `input`.
+     *
+     * @param key   Dotted path to the array
+     * @param input New array value (may be `undefined`)
+     * @private
+     */
+    private _replace;
+    /**
+     * `$insert`
+     * - plain append      → $concatArrays
+     * - unique / keyed    → delegate to _upsert (insert-or-update)
+     */
+    private _insert;
+    /**
+     * `$upsert`
+     * - keyed  → remove existing matching by key(s) then append candidate
+     * - unique → $setUnion (deep equality)
+     */
+    private _upsert;
+    /**
+     * `$update`
+     * - keyed       → map array and merge / replace matching element(s)
+     * - non-keyed   → behave like `$addToSet` (insert only when not present)
+     */
+    private _update;
+    /**
+     * `$remove`
+     * - keyed     → filter out any element whose key set matches a payload item
+     * - non-keyed → deep equality remove (`$setDifference`)
+     */
+    private _remove;
 }
 
 interface TPlainIndex {
@@ -39,99 +185,97 @@ interface TSearchIndex {
     type: 'dynamic_text' | 'search_text' | 'vector';
     definition: TMongoSearchIndexDefinition;
 }
-type TIndex = TPlainIndex | TSearchIndex;
-type TValidatorPurpose = 'insert' | 'update' | 'patch';
-declare class AsCollection<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
-    protected readonly asMongo: AsMongo;
-    protected readonly _type: T;
-    protected readonly logger: TGenericLogger;
-    readonly name: string;
-    readonly collection: Collection<any>;
-    protected readonly validators: Map<TValidatorPurpose, Validator<T, DataType>>;
-    createValidator(opts?: Partial<TValidatorOptions>): Validator<T, DataType>;
-    protected _indexes: Map<string, TIndex>;
+type TMongoIndex = TPlainIndex | TSearchIndex;
+declare class MongoAdapter extends BaseDbAdapter {
+    protected readonly db: Db;
+    protected readonly asMongo?: AsMongo | undefined;
+    private _collection?;
+    /** MongoDB-specific indexes (search, vector) — separate from table.indexes. */
+    protected _mongoIndexes: Map<string, TMongoIndex>;
+    /** Vector search filter associations built during flattening. */
     protected _vectorFilters: Map<string, string>;
-    protected _flatMap?: Map<string, TAtscriptAnnotatedType>;
-    constructor(asMongo: AsMongo, _type: T, logger?: TGenericLogger);
-    exists(): Promise<boolean>;
-    ensureExists(): Promise<void>;
+    /** Cached search index lookup. */
+    protected _searchIndexesMap?: Map<string, TMongoIndex>;
+    /** Physical field names with @db.default.fn "increment". */
+    protected _incrementFields: Set<string>;
+    constructor(db: Db, asMongo?: AsMongo | undefined);
+    get collection(): Collection<any>;
+    aggregate(pipeline: Document[]): AggregationCursor;
+    get idType(): 'string' | 'number' | 'objectId';
+    prepareId(id: unknown, fieldType: TAtscriptAnnotatedType): unknown;
     /**
-     * Returns the a type definition of the "_id" prop.
+     * Convenience method that uses `idType` to transform an ID value.
+     * For use in controllers that don't have access to the field type.
      */
-    get idType(): 'string' | 'number' | 'objectId';
+    prepareIdFromIdType<D = string | number | ObjectId>(id: string | number | ObjectId): D;
+    supportsNestedObjects(): boolean;
+    supportsNativePatch(): boolean;
+    getValidatorPlugins(): TValidatorPlugin[];
+    getTopLevelArrayTag(): string;
+    getAdapterTableName(type: TAtscriptAnnotatedType): string | undefined;
+    buildInsertValidator(table: AtscriptDbTable): any;
+    buildPatchValidator(table: AtscriptDbTable): any;
+    /** Returns the context object used by CollectionPatcher. */
+    getPatcherContext(): TCollectionPatcherContext;
+    nativePatch(filter: FilterExpr, patch: unknown): Promise<TDbUpdateResult>;
+    onBeforeFlatten(type: TAtscriptAnnotatedType): void;
+    onFieldScanned(field: string, type: TAtscriptAnnotatedType, metadata: TMetadataMap<AtscriptMetadata>): void;
+    onAfterFlatten(): void;
+    /** Returns MongoDB-specific search index map (internal). */
+    getMongoSearchIndexes(): Map<string, TMongoIndex>;
+    /** Returns a specific MongoDB search index by name. */
+    getMongoSearchIndex(name?: string): TMongoIndex | undefined;
+    /** Returns available search indexes as generic metadata for UI. */
+    getSearchIndexes(): TSearchIndexInfo[];
     /**
-     * Transforms an "_id" value to the expected type (`ObjectId`, `number`, or `string`).
-     * Assumes input has already been validated.
-     *
-     * @param {string | number | ObjectId} id - The validated ID.
-     * @returns {string | number | ObjectId} - The transformed ID.
-     * @throws {Error} If the `_id` type is unknown.
+     * Builds a MongoDB `$search` pipeline stage.
+     * Override `buildVectorSearchStage` in subclasses to provide embeddings.
      */
-    prepareId<D = string | number | ObjectId>(id: string | number | ObjectId): D;
+    protected buildSearchStage(text: string, indexName?: string): Document | undefined;
     /**
-     * Retrieves a validator for a given purpose. If the validator is not already cached,
-     * it creates and stores a new one based on the purpose.
-     *
-     * @param {TValidatorPurpose} purpose - The validation purpose (`input`, `update`, `patch`).
-     * @returns {Validator} The corresponding validator instance.
-     * @throws {Error} If an unknown purpose is provided.
-     */
-    getValidator(purpose: TValidatorPurpose): Validator<T, DataType> | undefined;
-    get type(): TAtscriptAnnotatedType<TAtscriptTypeObject>;
-    get indexes(): Map<string, TIndex>;
-    protected _addIndexField(type: TPlainIndex['type'], name: string, field: string, weight?: number): void;
+     * Builds a vector search stage. Override in subclasses to generate embeddings.
+     * Returns `undefined` by default (vector search requires custom implementation).
+     */
+    protected buildVectorSearchStage(text: string, index: TMongoIndex): Document | undefined;
+    search(text: string, query: DbQuery, indexName?: string): Promise<Array<Record<string, unknown>>>;
+    searchWithCount(text: string, query: DbQuery, indexName?: string): Promise<{
+        data: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    findManyWithCount(query: DbQuery): Promise<{
+        data: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    collectionExists(): Promise<boolean>;
+    ensureCollectionExists(): Promise<void>;
+    insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
+    insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+    findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
+    findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+    count(query: DbQuery): Promise<number>;
+    updateOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    replaceOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
+    updateMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+    ensureTable(): Promise<void>;
+    syncIndexes(): Promise<void>;
+    /** Returns physical field names of increment fields that are undefined in the data. */
+    private _fieldsNeedingIncrement;
+    /** Reads current max value for each field via $group aggregation. */
+    private _getMaxValues;
+    private _buildFindOptions;
+    protected _addMongoIndexField(type: TPlainIndex['type'], name: string, field: string, weight?: number): void;
     protected _setSearchIndex(type: TSearchIndex['type'], name: string | undefined, definition: TMongoSearchIndexDefinition): void;
     protected _addFieldToSearchIndex(type: TSearchIndex['type'], _name: string | undefined, fieldName: string, analyzer?: string): void;
-    protected _prepareIndexesForCollection(): void;
-    protected _uniqueProps: Set<string>;
-    get uniqueProps(): Set<string>;
-    protected _finalizeIndexesForCollection(): void;
-    protected _prepareIndexesForField(fieldName: string, metadata: TMetadataMap<AtscriptMetadata>): void;
-    protected _flatten(): void;
-    protected _searchIndexesMap?: Map<string, TIndex>;
-    getSearchIndexes(): Map<string, TIndex>;
-    getSearchIndex(name?: string): TIndex | undefined;
-    get flatMap(): Map<string, TAtscriptAnnotatedType<_atscript_typescript_annotated_type.TAtscriptTypeDef<unknown>, unknown>>;
-    syncIndexes(): Promise<void>;
-    insert(payload: (Omit<DataType, '_id'> & {
-        _id?: string | number | ObjectId;
-    }) | (Omit<DataType, '_id'> & {
-        _id?: string | number | ObjectId;
-    })[], options?: InsertOneOptions): Promise<mongodb.InsertManyResult<any>> | Promise<mongodb.InsertOneResult<any>>;
-    replace(payload: Omit<DataType, '_id'> & {
-        _id: string | number | ObjectId;
-    }, options?: ReplaceOptions): Promise<mongodb.UpdateResult<any>>;
-    update(payload: AsMongoPatch<Omit<DataType, '_id'>> & {
-        _id: string | number | ObjectId;
-    }, options?: UpdateOptions): Promise<mongodb.UpdateResult<any>>;
-    prepareInsert(payload: (Omit<DataType, '_id'> & {
-        _id?: string | number | ObjectId;
-    }) | (Omit<DataType, '_id'> & {
-        _id?: string | number | ObjectId;
-    })[]): DataType | DataType[];
-    prepareReplace(payload: Omit<DataType, '_id'> & {
-        _id: string | number | ObjectId;
-    }): {
-        toArgs: () => [Filter<any>, any, ReplaceOptions];
-        filter: Filter<any>;
-        updateFilter: any;
-        updateOptions: ReplaceOptions;
-    };
-    prepareUpdate(payload: AsMongoPatch<Omit<DataType, '_id'>> & {
-        _id: string | number | ObjectId;
-    }): {
-        toArgs: () => [Filter<any>, mongodb.UpdateFilter<any> | mongodb.Document[], UpdateOptions];
-        filter: Filter<any>;
-        updateFilter: mongodb.Document[];
-        updateOptions: UpdateOptions;
-    };
 }
 type TVectorSimilarity = 'cosine' | 'euclidean' | 'dotProduct';
 interface TMongoSearchIndexDefinition {
     mappings?: {
         dynamic?: boolean;
         fields?: Record<string, {
-            type: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array';
+            type: string;
             analyzer?: string;
         }>;
     };
@@ -148,26 +292,17 @@ interface TMongoSearchIndexDefinition {
         };
     };
 }
-interface TArrayPatch<A extends readonly unknown[]> {
-    $replace?: A;
-    $insert?: A;
-    $upsert?: A;
-    $update?: Array<Partial<TArrayElement<A>>>;
-    $remove?: Array<Partial<TArrayElement<A>>>;
-}
-type TArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends ReadonlyArray<infer ElementType> ? ElementType : never;
+
 /**
- * AsMongoPatch<T>
- * ─────────────────
- * - For every key K in T:
- *     • if T[K] is `X[]`, rewrite it to `TArrayPatch<X[]>`
- *     • otherwise omit the key (feel free to keep it if you want)
+ * Translates a generic {@link FilterExpr} into a MongoDB-compatible
+ * {@link Filter} document.
  *
- * The result is an *optional* property bag that matches a patch payload
- * for array fields only.
+ * MongoDB's query language is nearly identical to the `FilterExpr` structure,
+ * so this is largely a structural pass-through via the `walkFilter` visitor.
  */
-type AsMongoPatch<T> = {
-    [K in keyof T]?: T[K] extends Array<infer _> ? TArrayPatch<T[K]> : Partial<T[K]>;
-};
+declare function buildMongoFilter(filter: FilterExpr): Filter<any>;
+
+declare const validateMongoIdPlugin: TValidatorPlugin;
 
-export { AsCollection, AsMongo, MongoPlugin };
+export { AsMongo, CollectionPatcher, MongoAdapter, buildMongoFilter, validateMongoIdPlugin };
+export type { TCollectionPatcherContext, TMongoIndex, TMongoSearchIndexDefinition, TPlainIndex, TSearchIndex };