@atscript/mongo 0.1.35 → 0.1.36

package/dist/index.d.ts

@@ -1,15 +1,6 @@
-import * as mongodb from 'mongodb';
-import { Filter, UpdateFilter, Document, UpdateOptions, Db, ClientSession, Collection, AggregationCursor, ObjectId, MongoClient } from 'mongodb';
+import { getKeyProps, BaseDbAdapter, WithRelation, TDbRelation, TDbForeignKey, TTableResolver, FilterExpr, TDbUpdateResult, TSearchIndexInfo, DbQuery, TDbInsertResult, TDbInsertManyResult, TDbDeleteResult, TColumnDiff, TSyncColumnResult, DbSpace } from '@atscript/utils-db';
 import { TAtscriptAnnotatedType, TValidatorOptions, Validator, TValidatorPlugin, TMetadataMap } from '@atscript/typescript/utils';
-import { getKeyProps, BaseDbAdapter, AtscriptDbTable, FilterExpr, TDbUpdateResult, TSearchIndexInfo, DbQuery, TDbInsertResult, TDbInsertManyResult, TDbDeleteResult, DbSpace } from '@atscript/utils-db';
-
-interface TGenericLogger {
-    error(...messages: any[]): void;
-    warn(...messages: any[]): void;
-    log(...messages: any[]): void;
-    info(...messages: any[]): void;
-    debug(...messages: any[]): void;
-}
+import { Filter, UpdateFilter, Document, UpdateOptions, Db, MongoClient, ClientSession, Collection, AggregationCursor, ObjectId } from 'mongodb';
 
 /**
  * Context interface for CollectionPatcher.
@@ -46,16 +37,6 @@ declare class CollectionPatcher {
     private payload;
     constructor(collection: TCollectionPatcherContext, payload: any);
     static getKeyProps: typeof getKeyProps;
-    /**
-     * 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.
@@ -167,7 +148,7 @@ interface TSearchIndex {
 type TMongoIndex = TPlainIndex | TSearchIndex;
 declare class MongoAdapter extends BaseDbAdapter {
     protected readonly db: Db;
-    protected readonly asMongo?: AsMongo | undefined;
+    protected readonly client?: MongoClient | undefined;
     private _collection?;
     /** MongoDB-specific indexes (search, vector) — separate from table.indexes. */
     protected _mongoIndexes: Map<string, TMongoIndex>;
@@ -182,7 +163,9 @@ declare class MongoAdapter extends BaseDbAdapter {
         size: number;
         max?: number;
     };
-    constructor(db: Db, asMongo?: AsMongo | undefined);
+    /** Whether the schema explicitly defines _id (via @db.mongo.collection or manual _id field). */
+    protected _hasExplicitId: boolean;
+    constructor(db: Db, client?: MongoClient | undefined);
     private get _client();
     /** Whether transaction support has been detected as unavailable (standalone MongoDB). */
     private _txDisabled;
@@ -206,10 +189,35 @@ declare class MongoAdapter extends BaseDbAdapter {
     supportsNestedObjects(): boolean;
     supportsNativePatch(): boolean;
     getValidatorPlugins(): TValidatorPlugin[];
-    getTopLevelArrayTag(): string;
     getAdapterTableName(type: TAtscriptAnnotatedType): string | undefined;
-    buildInsertValidator(table: AtscriptDbTable): any;
-    buildPatchValidator(table: AtscriptDbTable): any;
+    supportsNativeRelations(): boolean;
+    loadRelations(rows: Array<Record<string, unknown>>, withRelations: WithRelation[], relations: ReadonlyMap<string, TDbRelation>, foreignKeys: ReadonlyMap<string, TDbForeignKey>, tableResolver?: TTableResolver): Promise<void>;
+    /** Builds a $match filter to re-select source rows by PK. */
+    private _buildPKMatchFilter;
+    /** Dispatches to the correct $lookup builder based on relation direction. */
+    private _buildRelationLookup;
+    /** Builds `let` variable bindings and the corresponding `$expr` match for `$lookup`. */
+    private _buildLookupJoin;
+    /** $lookup for TO relations (FK is on this table → target). Always single-valued. */
+    private _buildToLookup;
+    /** $lookup for FROM relations (FK is on target → this table). */
+    private _buildFromLookup;
+    /** $lookup for VIA relations (M:N through junction table). Always array. */
+    private _buildViaLookup;
+    /** Builds inner pipeline stages for relation controls ($sort, $limit, $skip, $select, filter). */
+    private _buildLookupInnerPipeline;
+    /** Extracts nested $with from a WithRelation's controls. */
+    private _extractNestedWith;
+    /** Post-processes nested $with by delegating to the target table's own relation loading. */
+    private _loadNestedRelations;
+    /** Merges aggregation results back onto the original rows by PK. */
+    private _mergeRelationResults;
+    /** Finds FK entry for a TO relation from this table's foreignKeys map. */
+    private _findFKForRelationLookup;
+    /** Finds a FK on a remote table that points back to the given table name. */
+    private _findRemoteFKFromMeta;
+    /** Resolves the target table/collection name from a relation's target type. */
+    private _resolveRelTargetTableName;
     /** Returns the context object used by CollectionPatcher. */
     getPatcherContext(): TCollectionPatcherContext;
     nativePatch(filter: FilterExpr, patch: unknown): Promise<TDbUpdateResult>;
@@ -226,12 +234,12 @@ declare class MongoAdapter extends BaseDbAdapter {
      * Builds a MongoDB `$search` pipeline stage.
      * Override `buildVectorSearchStage` in subclasses to provide embeddings.
      */
-    protected buildSearchStage(text: string, indexName?: string): Document | undefined;
+    protected buildSearchStage(text: string, indexName?: string): Promise<Document | undefined>;
     /**
      * 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;
+    protected buildVectorSearchStage(text: string, index: TMongoIndex): Promise<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>>;
@@ -243,6 +251,11 @@ declare class MongoAdapter extends BaseDbAdapter {
     }>;
     collectionExists(): Promise<boolean>;
     ensureCollectionExists(): Promise<void>;
+    /**
+     * Wraps an async operation to catch MongoDB duplicate key errors
+     * (code 11000) and rethrow as structured `DbError`.
+     */
+    private _wrapDuplicateKeyError;
     insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
     insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
     findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
@@ -254,13 +267,64 @@ declare class MongoAdapter extends BaseDbAdapter {
     updateMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
     replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
     deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+    tableExists(): Promise<boolean>;
+    detectTableOptionDrift(): Promise<boolean>;
     ensureTable(): Promise<void>;
+    /**
+     * Creates a MongoDB view from the AtscriptDbView's view plan.
+     * Translates joins → $lookup/$unwind, filter → $match, columns → $project.
+     */
+    private _ensureView;
+    /**
+     * Extracts localField/foreignField from a join condition like `User.id = Task.assigneeId`.
+     * The condition is a comparison node with two field refs.
+     */
+    private _resolveJoinFields;
+    /**
+     * Translates an AtscriptQueryNode to a MongoDB $match expression.
+     * Field refs are resolved to dot-path references (joined fields use JOINED_PREFIX).
+     */
+    private _queryNodeToMatch;
+    /**
+     * Resolves a field ref to a MongoDB dot path for view pipeline expressions.
+     */
+    private _resolveViewFieldPath;
     dropTable(): Promise<void>;
+    dropViewByName(viewName: string): Promise<void>;
+    dropTableByName(tableName: string): Promise<void>;
+    recreateTable(): Promise<void>;
+    syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
+    dropColumns(columns: string[]): Promise<void>;
+    renameTable(oldName: string): Promise<void>;
+    /**
+     * Resolves a field's default value for bulk $set during column sync.
+     * Returns `undefined` if no concrete default can be determined.
+     */
+    private _resolveSyncDefault;
     syncIndexes(): Promise<void>;
+    /** Cached physical name of the single @meta.id field, or null if none/composite. */
+    private _metaIdPhysical;
+    /**
+     * Returns the physical column name of the single @meta.id field (if any).
+     * Used to return the user's logical ID instead of MongoDB's _id on insert.
+     */
+    private _getMetaIdPhysical;
+    /** Returns the counters collection used for atomic auto-increment. */
+    protected get _countersCollection(): Collection<{
+        _id: string;
+        seq: number;
+    }>;
     /** 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;
+    /**
+     * Atomically allocates `count` sequential values for each increment field
+     * using a counter collection. Returns a map of field → first allocated value.
+     */
+    private _allocateIncrementValues;
+    /** Reads current max value for a single field via $group aggregation. */
+    private _getCurrentFieldMax;
+    /** Allocates increment values for a batch of items, assigning in order. */
+    private _assignBatchIncrements;
     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;
@@ -289,31 +353,6 @@ interface TMongoSearchIndexDefinition {
     };
 }
 
-/**
- * MongoDB database space — extends {@link DbSpace} with MongoDB-specific
- * features (cached collection list, `Db` access, `MongoAdapter` factory).
- *
- * ```typescript
- * const asMongo = new AsMongo('mongodb://localhost:27017/mydb')
- * const users = asMongo.getTable(UsersType)
- * const posts = asMongo.getTable(PostsType)
- * // Relation loading via $with works automatically
- * ```
- */
-declare class AsMongo extends DbSpace {
-    readonly client: MongoClient;
-    constructor(client: string | MongoClient, logger?: TGenericLogger);
-    get db(): mongodb.Db;
-    protected collectionsList?: Promise<Set<string>>;
-    protected getCollectionsList(): Promise<Set<string>>;
-    collectionExists(name: string): Promise<boolean>;
-    /**
-     * Returns the MongoAdapter for the given type.
-     * Convenience accessor for Mongo-specific adapter operations.
-     */
-    getAdapter(type: TAtscriptAnnotatedType): MongoAdapter;
-}
-
 /**
  * Translates a generic {@link FilterExpr} into a MongoDB-compatible
  * {@link Filter} document.
@@ -325,7 +364,7 @@ declare function buildMongoFilter(filter: FilterExpr): Filter<any>;
 
 declare const validateMongoIdPlugin: TValidatorPlugin;
 
-declare function createAdapter(connection: string, _options?: Record<string, unknown>): AsMongo;
+declare function createAdapter(connection: string, _options?: Record<string, unknown>): DbSpace;
 
-export { AsMongo, CollectionPatcher, MongoAdapter, buildMongoFilter, createAdapter, validateMongoIdPlugin };
+export { CollectionPatcher, MongoAdapter, buildMongoFilter, createAdapter, validateMongoIdPlugin };
 export type { TCollectionPatcherContext, TMongoIndex, TMongoSearchIndexDefinition, TPlainIndex, TSearchIndex };