@airoom/nextmin-node 1.4.6 → 2.0.2

package/dist/database/NMAdapter.js

@@ -0,0 +1,1243 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NMAdapter = void 0;
+const typeorm_1 = require("typeorm");
+const mongodb_1 = require("mongodb");
+const Logger_1 = __importDefault(require("../utils/Logger"));
+const utils_1 = require("../api/router/utils");
+const utils_2 = require("./utils");
+/**
+ * NMAdapter implements the DatabaseAdapter interface.
+ * It supports SQL databases (PostgreSQL, MySQL, MariaDB, SQLite, MSSQL) and MongoDB.
+ */
+class NMAdapter {
+    constructor(options) {
+        this.options = options;
+        this.repositories = new Map();
+        this.entitySchemas = new Map();
+        this.registeredSchemas = {};
+        this.imageProxyOptions = {};
+        const isValidUrl = (url) => typeof url === 'string' && url.startsWith('http');
+        let imageProxy = options.imageProxy;
+        if (!imageProxy || Object.keys(imageProxy).length === 0) {
+            imageProxy = { proxyBase: '/images' };
+        }
+        if (imageProxy && imageProxy.proxyBase) {
+            this.imageProxyOptions = { ...imageProxy };
+            // Auto-detect originalBase if missing but s3/r2 config exists
+            if (!this.imageProxyOptions.originalBase) {
+                const s3 = options.s3 || {
+                    bucket: process.env.S3_BUCKET,
+                    region: process.env.S3_REGION,
+                    endpoint: process.env.S3_ENDPOINT,
+                    publicBaseUrl: process.env.S3_PUBLIC_BASE_URL
+                };
+                if (s3.publicBaseUrl) {
+                    this.imageProxyOptions.originalBase = s3.publicBaseUrl.replace(/\/+$/, '');
+                }
+                else if (s3.bucket) {
+                    if (isValidUrl(s3.endpoint)) {
+                        this.imageProxyOptions.originalBase = `${s3.endpoint.replace(/\/+$/, '')}/${s3.bucket}`;
+                    }
+                    else if (s3.region) {
+                        this.imageProxyOptions.originalBase = `https://${s3.bucket}.s3.${s3.region}.amazonaws.com`;
+                    }
+                }
+            }
+            if (this.imageProxyOptions.originalBase && this.imageProxyOptions.proxyBase) {
+                Logger_1.default.info('NMAdapter', `Image proxy enabled: ${this.imageProxyOptions.originalBase} -> ${this.imageProxyOptions.proxyBase}`);
+            }
+        }
+        this.dataSource = new typeorm_1.DataSource({
+            ...options,
+            entities: [], // Will be populated dynamically
+            synchronize: options.type === 'mongodb' ? false : true, // Only for development; use migrations for production in a real-world app
+            logging: false,
+        });
+    }
+    async connect() {
+        await this.dataSource.initialize();
+        Logger_1.default.info('NMAdapter', `Connected to database: ${this.dataSource.options.type}`);
+    }
+    async disconnect() {
+        await this.dataSource.destroy();
+        Logger_1.default.warn('NMAdapter', 'Disconnected from database');
+    }
+    async registerSchemas(schemas) {
+        // 1) Update cumulative schema map BEFORE building entities
+        for (const [name, def] of Object.entries(schemas)) {
+            this.registeredSchemas[name.toLowerCase()] = def;
+        }
+        // 2) Define EntitySchemas dynamically
+        for (const [name, def] of Object.entries(schemas)) {
+            const entitySchema = this.buildEntitySchema(def);
+            this.entitySchemas.set(name.toLowerCase(), entitySchema);
+        }
+        // 2) Update DataSource with new entities
+        // Note: For dynamic entity updates in TypeORM, we must clear old metadatas 
+        // and rebuild them to ensure synchronize() detects all changes correctly.
+        this.dataSource.options.entities = Array.from(this.entitySchemas.values());
+        // Re-initialize metadata
+        if (this.dataSource.entityMetadatas) {
+            this.dataSource.entityMetadatas.length = 0;
+        }
+        await this.dataSource.buildMetadatas();
+        // Synchronize schema (if applicable)
+        if (this.dataSource.options.synchronize) {
+            try {
+                Logger_1.default.info('NMAdapter', `Synchronizing ${Object.keys(schemas).length} schemas...`);
+                await this.dataSource.synchronize();
+                Logger_1.default.info('NMAdapter', 'Schema synchronization completed successfully');
+            }
+            catch (err) {
+                // Ignore "table already exists" errors during dynamic sync 
+                // This often happens in SQLite when metadata rebuilds don't perfectly align with existing tables
+                if (err.message?.includes('already exists')) {
+                    Logger_1.default.info('NMAdapter', `Synchronize notice: Table already exists, skipping create: ${err.message}`);
+                }
+                else {
+                    Logger_1.default.error('NMAdapter', `Schema synchronization failed: ${err.message}`, err);
+                    throw err; // Re-throw critical errors
+                }
+            }
+        }
+        // 3) Sync Indexes
+        for (const [name, def] of Object.entries(schemas)) {
+            const indexes = {};
+            for (const [key, attr] of Object.entries(def.attributes)) {
+                if (attr.index === true) {
+                    indexes[key] = 1;
+                }
+            }
+            if (Object.keys(indexes).length > 0) {
+                await this.syncIndexes(name, indexes);
+            }
+        }
+        // 4) Cache repositories
+        for (const name of Object.keys(schemas)) {
+            const lcName = name.toLowerCase();
+            const schema = this.entitySchemas.get(lcName);
+            if (schema) {
+                this.repositories.set(lcName, this.dataSource.getRepository(schema));
+            }
+        }
+    }
+    async syncIndexes(modelName, spec) {
+        const repo = this.repositories.get(modelName.toLowerCase());
+        if (!repo)
+            return;
+        if (this.dataSource.options.type === 'mongodb') {
+            const mongoRepo = repo.manager.getMongoRepository(repo.metadata.name);
+            for (const field of Object.keys(spec)) {
+                try {
+                    const mongoRepo = repo.manager.getMongoRepository(repo.metadata.name);
+                    // Use TypeORM's built-in createCollectionIndex if available, or native
+                    await mongoRepo.createCollectionIndex({ [field]: 1 }, { background: true });
+                    Logger_1.default.info('NMAdapter', `Created index on ${modelName}.${field}`);
+                }
+                catch (err) {
+                    Logger_1.default.warn('NMAdapter', `Failed to create index on ${modelName}.${field}: ${err}`);
+                }
+            }
+        }
+        else {
+            // For SQL, TypeORM handles basic indexing via EntitySchema.synchronize()
+            // which we already called in registerSchemas.
+        }
+    }
+    buildEntitySchema(def) {
+        const isMongo = this.dataSource.options.type === 'mongodb';
+        const columns = {
+            id: {
+                primary: true,
+                objectId: isMongo,
+                // For MongoDB we use name: '_id' to map the physical column
+                name: isMongo ? '_id' : undefined,
+                // For MongoDB we use string/ObjectId, for SQL we use int
+                type: isMongo ? 'objectId' : 'int',
+                generated: isMongo ? true : 'increment',
+            },
+            createdAt: {
+                type: 'datetime',
+                createDate: true,
+                default: () => 'CURRENT_TIMESTAMP',
+                nullable: true,
+            },
+            updatedAt: {
+                type: 'datetime',
+                updateDate: true,
+                default: () => 'CURRENT_TIMESTAMP',
+                nullable: true,
+            },
+        };
+        const indices = [];
+        for (const [key, attr] of Object.entries(def.attributes)) {
+            if (key === 'id' || key === '_id')
+                continue;
+            // CRITICAL: If this field is physically stored in a base collection, 
+            // do NOT define a column for it in this child entity internally,
+            // UNLESS it is an OVERRIDE (not inherited) and not marked as 'safe' in the base.
+            if (def.extends && key !== 'baseId') {
+                const head = Array.isArray(attr) ? attr[0] : attr;
+                if (head?.inherited) {
+                    continue; // Skip purely inherited fields; they live in the base record
+                }
+                // It's an override or child-specific field
+                const baseSchema = this.registeredSchemas[def.extends];
+                const baseAttr = baseSchema?.attributes?.[key];
+                const bHead = Array.isArray(baseAttr) ? baseAttr[0] : baseAttr;
+                if (bHead?.safe === true) {
+                    continue; // Base model protects this field; skip column in child
+                }
+            }
+            const head = Array.isArray(attr) ? attr[0] : attr;
+            if (head?.type === 'virtual')
+                continue;
+            const typeORMType = this.mapType(attr);
+            const isUnique = attr.unique === true;
+            const isSparse = attr.sparse === true;
+            columns[key] = {
+                type: typeORMType, // Map type appropriately (e.g., 'varchar' for strings)
+                nullable: true,
+                unique: isUnique && (!isMongo || !isSparse), // Standard unique if not sparse mongo
+                default: attr.default,
+                index: attr.index === true,
+            };
+            // For MongoDB, if unique and sparse, we use an explicit index definition 
+            // since column-level uniqueness doesn't support the 'sparse' option in TypeORM's EntitySchema for Mongo.
+            if (isMongo && isUnique && isSparse) {
+                indices.push({
+                    name: `IDX_${def.modelName}_${key}_UNIQUE`,
+                    columns: [key],
+                    unique: true,
+                    sparse: true,
+                });
+            }
+            if (typeORMType === 'datetime' && attr.default === 'now') {
+                columns[key].default = () => 'CURRENT_TIMESTAMP';
+            }
+        }
+        return new typeorm_1.EntitySchema({
+            name: def.modelName,
+            tableName: def.collection || def.modelName.toLowerCase(), // Reverted to lowercase for DB compatibility
+            columns,
+            indices: indices.length > 0 ? indices : undefined,
+        });
+    }
+    mapType(attr) {
+        if (Array.isArray(attr)) {
+            return 'simple-json';
+        }
+        const type = String(attr?.type || 'string').toLowerCase();
+        switch (type) {
+            case 'string': return 'varchar';
+            case 'number': return 'float';
+            case 'boolean': return 'boolean';
+            case 'date':
+            case 'datetime': return 'datetime';
+            case 'json':
+            case 'object': return 'json';
+            case 'array': return 'simple-json';
+            case 'objectid':
+                return 'varchar';
+            default: return 'varchar';
+        }
+    }
+    getRepository(collection) {
+        const repo = this.repositories.get(collection.toLowerCase());
+        if (!repo) {
+            throw new Error(`Repository for ${collection} not found. Did you register the schema?`);
+        }
+        return repo;
+    }
+    async create(collection, data, schemaDefinition) {
+        const repo = this.getRepository(collection);
+        const coerced = this.coercePayloadForStorage(data, schemaDefinition);
+        // Ensure timestamps are set if not provided (especially for MongoDB)
+        const now = new Date();
+        if (!coerced.createdAt)
+            coerced.createdAt = now;
+        if (!coerced.updatedAt)
+            coerced.updatedAt = now;
+        const created = await repo.save(coerced);
+        return this.prepareResult(created);
+    }
+    coercePayloadForStorage(payload, schema) {
+        if (!payload || !schema || this.dataSource.options.type !== 'mongodb')
+            return payload;
+        const coerced = { ...payload };
+        for (const [key, attr] of Object.entries(schema.attributes)) {
+            const a = Array.isArray(attr) ? attr[0] : attr;
+            const isObjectIdField = String(a?.type || '').toLowerCase() === 'objectid';
+            // For MongoDB, we remove null values to satisfy sparse indexes
+            if (coerced[key] === null) {
+                delete coerced[key];
+                continue;
+            }
+            if (isObjectIdField && coerced[key] != null) {
+                if (Array.isArray(coerced[key])) {
+                    coerced[key] = coerced[key].map((v) => this.convertToObjectId(v));
+                }
+                else {
+                    coerced[key] = this.convertToObjectId(coerced[key]);
+                }
+            }
+        }
+        return coerced;
+    }
+    async read(collection, query, limit, skip, schemaDefinition, includePrivateFields, options) {
+        const repo = this.getRepository(collection);
+        const isMongo = this.dataSource.options.type === 'mongodb';
+        const resolvedQuery = await this.resolveNestedSearches(query);
+        const where = this.transformQuery(resolvedQuery, schemaDefinition);
+        const findOptions = {
+            where,
+            take: limit,
+            skip: skip,
+            order: options?.sort,
+        };
+        if (options?.projection) {
+            const hasRootProj = this.isExclusiveProjection(options.projection, schemaDefinition);
+            if (hasRootProj) {
+                const dbProjection = {};
+                // Always include ID for hydration purposes
+                if (isMongo)
+                    dbProjection._id = true;
+                else
+                    dbProjection.id = true;
+                for (const [key, value] of Object.entries(options.projection)) {
+                    // Skip dynamic aggregate fields like model[count] for the DB query
+                    if (key.includes('[') && key.endsWith(']')) {
+                        continue;
+                    }
+                    if (key.includes('.') && schemaDefinition) {
+                        const root = key.split('.')[0];
+                        const attr = schemaDefinition.attributes[root];
+                        const a = Array.isArray(attr) ? attr[0] : attr;
+                        const isRelation = String(a?.type || '').toLowerCase() === 'objectid';
+                        if (isRelation) {
+                            // For relations, we only need the root field (the ID) in the DB query.
+                            // Adding the dotted key (e.g. 'districts.name') causes a path collision in Mongo
+                            // because 'districts' is just a list of ObjectIds in this collection.
+                            dbProjection[root] = true;
+                            continue;
+                        }
+                    }
+                    dbProjection[key] = !!value;
+                }
+                findOptions.select = dbProjection;
+                if (isMongo) {
+                    const mongoProj = {};
+                    for (const [k, v] of Object.entries(dbProjection)) {
+                        const tk = (k === 'id') ? '_id' : k;
+                        mongoProj[tk] = v ? 1 : 0;
+                    }
+                    findOptions.projection = mongoProj;
+                }
+            }
+        }
+        let results;
+        if (isMongo && options?.sample) {
+            const mongoRepo = repo.manager.getMongoRepository(repo.metadata.name);
+            const aggregation = [{ $match: where }];
+            aggregation.push({ $sample: { size: options.sample } });
+            if (findOptions.projection)
+                aggregation.push({ $project: findOptions.projection });
+            results = await mongoRepo.aggregate(aggregation).toArray();
+        }
+        else if (isMongo && findOptions.projection) {
+            const mongoRepo = repo.manager.getMongoRepository(repo.metadata.name);
+            const cursor = mongoRepo.createCursor(where);
+            cursor.project(findOptions.projection);
+            if (limit)
+                cursor.limit(limit);
+            if (skip)
+                cursor.skip(skip);
+            if (options?.sort)
+                cursor.sort(options.sort);
+            results = await cursor.toArray();
+        }
+        else {
+            if (options?.sample && !isMongo) {
+                const qb = repo.createQueryBuilder('entity');
+                qb.where(where);
+                if (limit)
+                    qb.take(limit);
+                if (skip)
+                    qb.skip(skip);
+                const dbType = this.dataSource.options.type;
+                if (dbType === 'postgres' || dbType === 'sqlite') {
+                    qb.orderBy('RANDOM()');
+                }
+                else if (dbType === 'mysql' || dbType === 'mariadb') {
+                    qb.orderBy('RAND()');
+                }
+                else if (dbType === 'mssql') {
+                    qb.orderBy('NEWID()');
+                }
+                results = await qb.getMany();
+            }
+            else {
+                results = await repo.find(findOptions);
+            }
+        }
+        const mappedResults = results.map(r => this.prepareResult(r));
+        if (schemaDefinition) {
+            await this.hydrateRelations(mappedResults, schemaDefinition, options?.depth ?? 0, options);
+        }
+        return mappedResults;
+    }
+    prepareResult(item) {
+        if (!item)
+            return item;
+        const isMongo = this.dataSource.options.type === 'mongodb';
+        if (isMongo) {
+            // For MongoDB, ensure id is set from _id consistently
+            const rawId = item._id || item.id;
+            if (rawId) {
+                item.id = this.idToString(rawId);
+            }
+        }
+        else {
+            if (item.id != null)
+                item.id = String(item.id);
+        }
+        // Apply image URL proxying/transformation if configured
+        if (this.imageProxyOptions.originalBase && this.imageProxyOptions.proxyBase) {
+            this.transformUrls(item);
+        }
+        return item;
+    }
+    transformUrls(obj) {
+        if (!obj || typeof obj !== 'object')
+            return;
+        const { originalBase, proxyBase } = this.imageProxyOptions;
+        if (!originalBase || !proxyBase)
+            return;
+        for (const key in obj) {
+            const val = obj[key];
+            if (typeof val === 'string') {
+                if (val.startsWith(originalBase)) {
+                    obj[key] = val.replace(originalBase, proxyBase);
+                }
+            }
+            else if (Array.isArray(val)) {
+                for (let i = 0; i < val.length; i++) {
+                    if (typeof val[i] === 'string' && val[i].startsWith(originalBase)) {
+                        val[i] = val[i].replace(originalBase, proxyBase);
+                    }
+                    else if (val[i] && typeof val[i] === 'object') {
+                        this.transformUrls(val[i]);
+                    }
+                }
+            }
+            else if (val && typeof val === 'object') {
+                this.transformUrls(val);
+            }
+        }
+    }
+    idToString(val) {
+        if (val == null)
+            return '';
+        if (typeof val === 'string')
+            return val;
+        if (typeof val === 'number')
+            return String(val);
+        // Handle MongoDB ObjectId or similar objects with toHexString
+        if (typeof val.toHexString === 'function')
+            return val.toHexString();
+        if (typeof val.toString === 'function' && val.constructor.name === 'ObjectId')
+            return val.toString();
+        if (Buffer.isBuffer(val))
+            return val.toString('hex');
+        if (val.id)
+            return this.idToString(val.id);
+        if (val._id)
+            return this.idToString(val._id);
+        return String(val);
+    }
+    convertToObjectId(val) {
+        if (val == null)
+            return val;
+        // If it's an object (potentially hydrated relation), extract the ID
+        if (typeof val === 'object' && !Buffer.isBuffer(val)) {
+            if (val instanceof mongodb_1.ObjectId || val.constructor?.name === 'ObjectId')
+                return val;
+            const extractedId = val.id || val._id;
+            if (extractedId)
+                return this.convertToObjectId(extractedId);
+        }
+        try {
+            if (this.dataSource.options.type === 'mongodb') {
+                if (typeof val === 'string' && val.length === 24 && /^[0-9a-fA-F]{24}$/.test(val)) {
+                    return new mongodb_1.ObjectId(val);
+                }
+            }
+            else {
+                const n = Number(val);
+                if (!isNaN(n) && String(val).trim() !== '')
+                    return n;
+            }
+            return val;
+        }
+        catch {
+            return val;
+        }
+    }
+    discoverInverseRelation(targetModelName, sourceModelHint) {
+        const targetLc = targetModelName.toLowerCase();
+        const sourceLc = sourceModelHint.toLowerCase();
+        // 1. Find a schema that matches sourceModelHint (plural or singular)
+        let sourceSchema;
+        // Try exact match first
+        sourceSchema = this.registeredSchemas[sourceLc];
+        // Try common plural/singular variations
+        if (!sourceSchema) {
+            const variations = [
+                sourceLc + 's',
+                sourceLc + 'es',
+                sourceLc.endsWith('y') ? sourceLc.slice(0, -1) + 'ies' : sourceLc,
+                sourceLc.endsWith('ies') ? sourceLc.slice(0, -3) + 'y' : sourceLc,
+                sourceLc.endsWith('s') ? sourceLc.slice(0, -1) : sourceLc
+            ];
+            for (const v of variations) {
+                if (this.registeredSchemas[v]) {
+                    sourceSchema = this.registeredSchemas[v];
+                    break;
+                }
+            }
+        }
+        if (!sourceSchema)
+            return null;
+        // 2. Find which field in sourceSchema points to targetModelName
+        for (const [field, attr] of Object.entries(sourceSchema.attributes)) {
+            const a = Array.isArray(attr) ? attr[0] : attr;
+            if (a.ref?.toLowerCase() === targetLc) {
+                return { sourceModel: sourceSchema.modelName, foreignField: field };
+            }
+        }
+        return null;
+    }
+    async hydrateDynamicAggregates(results, schema, projection) {
+        const promises = [];
+        const idsToFetch = results.map(r => r.id).filter(v => v != null);
+        if (idsToFetch.length === 0)
+            return;
+        for (const [projKey, projVal] of Object.entries(projection)) {
+            if (projVal !== 1)
+                continue;
+            if (!projKey.includes('[') || !projKey.endsWith(']'))
+                continue;
+            const parts = projKey.split('[');
+            const modelHint = parts[0];
+            const op = parts[1].slice(0, -1);
+            if (op !== 'count')
+                continue;
+            const relation = this.discoverInverseRelation(schema.modelName, modelHint);
+            if (!relation) {
+                Logger_1.default.warn('NMAdapter', `No inverse relation found for ${modelHint} pointing to ${schema.modelName}`);
+                continue;
+            }
+            promises.push((async () => {
+                try {
+                    const sourceSchema = this.registeredSchemas[relation.sourceModel.toLowerCase()];
+                    const counts = await this.countBy(relation.sourceModel, relation.foreignField, { [relation.foreignField]: { $in: idsToFetch } }, sourceSchema);
+                    const targetKey = `${modelHint}Count`;
+                    results.forEach(r => {
+                        const lid = this.idToString(r.id);
+                        r[targetKey] = counts[lid] || 0;
+                    });
+                }
+                catch (err) {
+                    Logger_1.default.warn('NMAdapter', `Failed to fetch dynamic aggregate ${projKey} for ${schema.modelName}: ${err}`);
+                }
+            })());
+        }
+        if (promises.length > 0) {
+            await Promise.all(promises);
+        }
+    }
+    async hydrateRelations(results, schema, depth = 0, options) {
+        if (!results.length || depth > 2)
+            return;
+        const projection = options?.projection;
+        // --- Dynamic Aggregates (e.g. model[count]) ---
+        if (projection) {
+            await this.hydrateDynamicAggregates(results, schema, projection);
+        }
+        // 1) Handle inheritance: if schema extends another, fetch base records
+        if (schema.extends) {
+            const baseLc = schema.extends.toLowerCase();
+            const baseRepo = this.repositories.get(baseLc);
+            if (baseRepo) {
+                const baseIds = new Set();
+                for (const item of results) {
+                    if (item.baseId != null) {
+                        baseIds.add(String(item.baseId));
+                    }
+                }
+                if (baseIds.size > 0) {
+                    const baseSchema = this.registeredSchemas[baseLc];
+                    const baseAttrKeys = new Set(Object.keys(baseSchema.attributes || {}));
+                    const hasRootProj = this.isExclusiveProjection(projection, baseSchema);
+                    let baseProjection = undefined;
+                    if (hasRootProj && projection) {
+                        baseProjection = { id: 1 };
+                        for (const [pk, pv] of Object.entries(projection)) {
+                            if (baseAttrKeys.has(pk)) {
+                                baseProjection[pk] = pv;
+                            }
+                        }
+                    }
+                    const baseDocs = await this.read(schema.extends, { id: { $in: Array.from(baseIds) } }, baseIds.size, 0, baseSchema, true, { projection: baseProjection });
+                    const baseMap = new Map();
+                    baseDocs.forEach(b => {
+                        const key = String(b.id);
+                        baseMap.set(key, b);
+                    });
+                    for (let i = 0; i < results.length; i++) {
+                        const item = results[i];
+                        if (item.baseId != null) {
+                            const bid = String(item.baseId);
+                            const baseData = baseMap.get(bid);
+                            if (baseData) {
+                                // Intelligent Merge: Prefer child data but skip nulls/empty for inherited or common fields
+                                const result = { ...baseData };
+                                for (const k of Object.keys(item)) {
+                                    const val = item[k];
+                                    const hasValue = val != null && (!Array.isArray(val) || val.length > 0);
+                                    if (hasValue) {
+                                        result[k] = val;
+                                    }
+                                }
+                                result.exId = String(baseData.id || baseData._id || '');
+                                result.id = String(item.id || item._id || '');
+                                result._id = result.id;
+                                if (hasRootProj && projection) {
+                                    for (const k of Object.keys(result)) {
+                                        if (k !== 'id' && k !== 'baseId' && !projection[k]) {
+                                            if (baseAttrKeys.has(k)) {
+                                                delete result[k];
+                                            }
+                                        }
+                                    }
+                                }
+                                results[i] = result;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // 2) Handle standard ObjectId hydration & 3) json-group in parallel
+        const hydrationPromises = [];
+        // --- Virtual fields (Inverse relationship counts) ---
+        const virtualFields = Object.entries(schema.attributes).filter(([key, attr]) => {
+            const a = Array.isArray(attr) ? attr[0] : attr;
+            return a?.type === 'virtual' && a?.op === 'count';
+        });
+        for (const [key, attr] of virtualFields) {
+            hydrationPromises.push((async () => {
+                const a = Array.isArray(attr) ? attr[0] : attr;
+                const refModel = a.ref;
+                const foreignField = a.foreignField;
+                const localField = a.localField || 'id';
+                if (!refModel || !foreignField)
+                    return;
+                const idsToFetch = results.map(r => r[localField]).filter(v => v != null);
+                if (idsToFetch.length === 0)
+                    return;
+                const counts = await this.countBy(refModel, foreignField, { [foreignField]: { $in: idsToFetch } });
+                results.forEach(r => {
+                    const lid = this.idToString(r[localField]);
+                    r[key] = counts[lid] || 0;
+                });
+            })());
+        }
+        // --- Standard Relations ---
+        const relFields = Object.entries(schema.attributes).filter(([key, attr]) => {
+            if (key === 'baseId')
+                return false;
+            const a = Array.isArray(attr) ? attr[0] : attr;
+            return String(a?.type).toLowerCase() === 'objectid' && a?.ref;
+        });
+        for (const [key, attr] of relFields) {
+            hydrationPromises.push((async () => {
+                const hasRootProj = this.isExclusiveProjection(projection, schema);
+                const isTargeted = projection && (projection[key] || Object.keys(projection).some(pk => pk.startsWith(`${key}.`)));
+                if (projection && hasRootProj && !isTargeted)
+                    return;
+                const isArray = Array.isArray(attr);
+                const refModelName = (isArray ? attr[0] : attr).ref;
+                if (!refModelName)
+                    return;
+                const refLc = refModelName.toLowerCase();
+                const refRepo = this.repositories.get(refLc);
+                if (!refRepo)
+                    return;
+                const idsToFetch = new Set();
+                for (const item of results) {
+                    const val = item[key];
+                    if (val == null)
+                        continue;
+                    if (isArray && Array.isArray(val)) {
+                        val.forEach(v => { if (v != null)
+                            idsToFetch.add(v); });
+                    }
+                    else {
+                        idsToFetch.add(val);
+                    }
+                }
+                if (idsToFetch.size === 0)
+                    return;
+                let subProjection = options?._populate?.[key];
+                if (subProjection) {
+                    subProjection = { ...subProjection, id: 1 };
+                }
+                if (!subProjection && projection) {
+                    const prefix = `${key}.`;
+                    for (const [pk, pv] of Object.entries(projection)) {
+                        if (pk.startsWith(prefix)) {
+                            if (!subProjection)
+                                subProjection = { id: 1 };
+                            subProjection[pk.slice(prefix.length)] = pv;
+                        }
+                    }
+                }
+                const fetchedDocs = await this.read(refModelName, { id: { $in: Array.from(idsToFetch) } }, idsToFetch.size, 0, this.registeredSchemas[refModelName], true, {
+                    depth: depth + 1,
+                    projection: subProjection
+                });
+                const docMap = new Map();
+                fetchedDocs.forEach(d => {
+                    const sid = this.idToString(d.id);
+                    if (sid)
+                        docMap.set(sid, d);
+                });
+                for (const item of results) {
+                    const val = item[key];
+                    if (val == null)
+                        continue;
+                    if (Array.isArray(val)) {
+                        item[key] = val.map(v => docMap.get(this.idToString(v)) || v);
+                    }
+                    else {
+                        item[key] = docMap.get(this.idToString(val)) || val;
+                    }
+                }
+            })());
+        }
+        // --- JSON groups ---
+        const jsonGroupFields = Object.entries(schema.attributes).filter(([key, attr]) => {
+            const a = Array.isArray(attr) ? attr[0] : attr;
+            return a?.format === 'json-group' && a?.attributes;
+        });
+        for (const [key, attr] of jsonGroupFields) {
+            hydrationPromises.push((async () => {
+                const a = Array.isArray(attr) ? attr[0] : attr;
+                const nestedSchema = {
+                    modelName: `${schema.modelName}_${key}`,
+                    attributes: a.attributes,
+                    allowedMethods: {},
+                    showCount: false
+                };
+                for (const item of results) {
+                    let val = item[key];
+                    if (!val)
+                        continue;
+                    if (typeof val === 'string' && val.trim()) {
+                        try {
+                            val = JSON.parse(val);
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                    if (val && (typeof val === 'object' || Array.isArray(val))) {
+                        const nestedResults = Array.isArray(val) ? val : [val];
+                        await this.hydrateRelations(nestedResults, nestedSchema, depth + 1);
+                        item[key] = val;
+                    }
+                }
+            })());
+        }
+        await Promise.all(hydrationPromises);
+    }
+    async update(collection, targetId, data, schemaDefinition) {
+        if (targetId == null || targetId === '' || targetId === 'undefined' || targetId === 'null') {
+            throw new Error(`[NMAdapter] Cannot perform update on '${collection}': targetId is required and cannot be null/undefined. This guard prevents accidental bulk updates.`);
+        }
+        const repo = this.repositories.get(collection.toLowerCase());
+        if (!repo)
+            throw new Error(`Repository for ${collection} not found.`);
+        const isMongo = this.dataSource.options.type === 'mongodb';
+        const resolvedTargetId = isMongo ? this.convertToObjectId(targetId) : targetId;
+        const coerced = this.coercePayloadForStorage(data, schemaDefinition);
+        // Strip ID fields from data to prevent primary key conflicts
+        const { id: _unusedId, _id: _unusedRawId, ...updateData } = coerced;
+        const now = new Date();
+        updateData.updatedAt = now;
+        if (isMongo) {
+            // Using explicit getMongoRepository and updateOne prevents accidental bulk updates
+            // that targetBy filter {} could cause in standard TypeORM .update()
+            const mongoRepo = this.dataSource.getMongoRepository(repo.metadata.name);
+            const setObj = {};
+            const unsetObj = {};
+            // We look at the original data for nulls because coercePayloadForStorage strips them
+            for (const [k, v] of Object.entries(data)) {
+                if (k === 'id' || k === '_id')
+                    continue;
+                if (v === null) {
+                    unsetObj[k] = "";
+                }
+                else {
+                    // Use the coerced value if it exists (for ObjectIds)
+                    setObj[k] = updateData[k] !== undefined ? updateData[k] : v;
+                }
+            }
+            // Always update the updatedAt field
+            setObj.updatedAt = now;
+            const updatePayload = {};
+            if (Object.keys(setObj).length > 0)
+                updatePayload.$set = setObj;
+            if (Object.keys(unsetObj).length > 0)
+                updatePayload.$unset = unsetObj;
+            if (Object.keys(updatePayload).length > 0) {
+                await mongoRepo.updateOne({ _id: resolvedTargetId }, updatePayload);
+            }
+        }
+        else {
+            await repo.update(resolvedTargetId, updateData);
+        }
+        const updated = await this.read(collection, { id: resolvedTargetId }, 1, 0, schemaDefinition);
+        return updated[0];
+    }
+    async delete(collection, targetId, schemaDefinition) {
+        if (targetId == null || targetId === '' || targetId === 'undefined' || targetId === 'null') {
+            throw new Error(`[NMAdapter] Cannot perform delete on '${collection}': targetId is required and cannot be null/undefined. This guard prevents accidental bulk deletions.`);
+        }
+        const repo = this.repositories.get(collection.toLowerCase());
+        if (!repo)
+            throw new Error(`Repository for ${collection} not found.`);
+        const isMongo = this.dataSource.options.type === 'mongodb';
+        // Use a string ID for the initial read to avoid any ObjectId conversion issues in transformQuery
+        const idStr = this.idToString(targetId);
+        const existing = await this.read(collection, { id: idStr }, 1, 0, schemaDefinition);
+        const id = isMongo ? this.convertToObjectId(targetId) : targetId;
+        if (isMongo) {
+            const item = await repo.findOneBy({ _id: id });
+            if (item)
+                await repo.remove(item);
+        }
+        else {
+            await repo.delete(id);
+        }
+        return existing[0] || null;
+    }
+    async count(collection, query, schemaDefinition) {
+        const repo = this.getRepository(collection);
+        const resolvedQuery = await this.resolveNestedSearches(query);
+        const where = this.transformQuery(resolvedQuery, schemaDefinition);
+        let total;
+        if (this.dataSource.options.type === 'mongodb') {
+            total = await repo.countBy(where);
+        }
+        else {
+            total = await repo.count({ where });
+        }
+        return total;
+    }
+    async countBy(collection, field, query, schema) {
+        const repo = this.getRepository(collection);
+        const where = this.transformQuery(query, schema);
+        const counts = {};
+        if (this.dataSource.options.type === 'mongodb') {
+            const mongoRepo = repo.manager.getMongoRepository(repo.metadata.name);
+            // Determine if field is an array from schema to use $unwind
+            const isArray = Array.isArray(schema?.attributes?.[field]);
+            const pipeline = [{ $match: where }];
+            if (isArray) {
+                pipeline.push({ $unwind: `$${field}` });
+            }
+            pipeline.push({ $group: { _id: `$${field}`, count: { $sum: 1 } } });
+            const results = await mongoRepo.aggregate(pipeline).toArray();
+            results.forEach((r) => {
+                if (r._id != null)
+                    counts[this.idToString(r._id)] = r.count;
+            });
+        }
+        else {
+            const results = await repo
+                .createQueryBuilder('entity')
+                .select(`entity.${field}`, 'key')
+                .addSelect('COUNT(*)', 'count')
+                .where(where)
+                .groupBy(`entity.${field}`)
+                .getRawMany();
+            results.forEach((r) => {
+                const k = r.key || r.KEY || r[`entity_${field}`];
+                if (k != null) {
+                    counts[this.idToString(k)] = parseInt(r.count || r.COUNT || 0, 10);
+                }
+            });
+        }
+        return counts;
+    }
+    async findFirstRelatedIds(collection, field, ids) {
+        const repo = this.getRepository(collection);
+        const map = new Map();
+        if (this.dataSource.options.type === 'mongodb') {
+            const objectIds = ids.map(id => this.convertToObjectId(id));
+            const stringIds = ids.map(id => this.idToString(id));
+            const allIds = Array.from(new Set([...objectIds, ...stringIds]));
+            const results = await repo.manager.getMongoRepository(repo.metadata.name).aggregate([
+                { $match: { [field]: { $in: allIds } } },
+                { $group: { _id: `$${field}`, firstId: { $first: '$_id' } } }
+            ]).toArray();
+            results.forEach(r => {
+                const parentId = this.idToString(r._id);
+                const firstId = this.idToString(r.firstId);
+                if (parentId && firstId) {
+                    map.set(parentId, firstId);
+                }
+            });
+        }
+        else {
+            // SQL: Use GROUP BY to find at least one related record per parent ID
+            const qb = repo.createQueryBuilder('entity');
+            const results = await qb
+                .select([`entity.${field}`, 'MIN(entity.id) as firstId'])
+                .where(`entity.${field} IN (:...ids)`, { ids })
+                .groupBy(`entity.${field}`)
+                .getRawMany();
+            results.forEach(r => {
+                // Handle various raw column name formats from different SQL drivers
+                const parentId = r[`entity_${field}`] || r[field] || r[`entity_${field.toLowerCase()}`];
+                const relId = r.firstId || r.firstid || r.FIRSTID;
+                if (parentId != null && relId != null) {
+                    map.set(this.idToString(parentId), this.idToString(relId));
+                }
+            });
+        }
+        return map;
+    }
+    /**
+     * Centralized Nested Search Resolver
+     * Recursively scans for $nestedSearch operators and resolves them to { $in: [ids] }
+     */
+    async resolveNestedSearches(query) {
+        if (!(0, utils_1.isPlainObject)(query))
+            return query;
+        const resolved = { ...query };
+        for (const [key, value] of Object.entries(resolved)) {
+            if ((key === '$or' || key === '$and') && Array.isArray(value)) {
+                resolved[key] = await Promise.all(value.map(v => this.resolveNestedSearches(v)));
+                continue;
+            }
+            if ((0, utils_1.isPlainObject)(value)) {
+                const opObj = value;
+                if (opObj.$nestedSearch) {
+                    const { ref, searchBy, show, value: searchVal, operator = '$in' } = opObj.$nestedSearch;
+                    const refSchema = Object.values(this.registeredSchemas).find(s => s.modelName.toLowerCase() === ref.toLowerCase());
+                    if (!refSchema) {
+                        Logger_1.default.warn('NMAdapter', `Schema not found for nested search ref: ${ref}`);
+                        delete resolved[key];
+                        continue;
+                    }
+                    // 1) Collect all unique fields to search in the referenced model
+                    const searchFields = new Set();
+                    if (show)
+                        searchFields.add(show);
+                    if (searchBy) {
+                        if (Array.isArray(searchBy)) {
+                            searchBy.forEach((f) => searchFields.add(f));
+                        }
+                        else {
+                            searchFields.add(searchBy);
+                        }
+                    }
+                    if (searchFields.size === 0)
+                        searchFields.add('name'); // fallback
+                    // 2) Build conditions for secondary search
+                    const conditions = [];
+                    const isArrayVal = Array.isArray(searchVal);
+                    for (const field of Array.from(searchFields)) {
+                        if (isArrayVal) {
+                            conditions.push({ [field]: { $in: searchVal } });
+                        }
+                        else {
+                            const anchoredValue = String(searchVal).startsWith('^') ? searchVal : `^${searchVal}`;
+                            if (field.includes('.')) {
+                                // Support deep nested search in relations (e.g. "districts.name")
+                                const [localKey, ...rest] = field.split('.');
+                                const attr = refSchema.attributes[localKey];
+                                const a = Array.isArray(attr) ? attr[0] : attr;
+                                if (a?.ref) {
+                                    // It's another relation! Delegate via another $nestedSearch
+                                    conditions.push({
+                                        [localKey]: {
+                                            $nestedSearch: {
+                                                ref: a.ref,
+                                                show: rest.join('.'),
+                                                value: anchoredValue
+                                            }
+                                        }
+                                    });
+                                }
+                                else {
+                                    // Just a nested object field
+                                    conditions.push({ [field]: { $regex: anchoredValue, $options: 'i' } });
+                                }
+                            }
+                            else {
+                                conditions.push({ [field]: { $regex: anchoredValue, $options: 'i' } });
+                            }
+                        }
+                    }
+                    // 2.1) ADDITION: If it looks like a 24-char hex string (ObjectId), also search by ID directly
+                    if (!isArrayVal && typeof searchVal === 'string' && /^[0-9a-fA-F]{24}$/.test(searchVal)) {
+                        conditions.push({ id: searchVal });
+                    }
+                    // 3) Use this.read() to find matching IDs in the referenced collection
+                    const foundRelDocs = await this.read(ref, { $or: conditions }, 2000, 0, refSchema, true);
+                    const ids = foundRelDocs.map(d => String(d.id || d._id)).filter(Boolean);
+                    if (operator === '$nin') {
+                        resolved[key] = { $nin: ids };
+                    }
+                    else if (ids.length === 1) {
+                        resolved[key] = ids[0];
+                    }
+                    else if (ids.length > 1) {
+                        resolved[key] = { $in: ids };
+                    }
+                    else {
+                        // Unmatchable ID to ensure result is empty for non-$nin
+                        resolved[key] = { $in: [this.convertToObjectId('000000000000000000000000')] };
+                    }
+                }
+                else {
+                    resolved[key] = await this.resolveNestedSearches(value);
+                }
+            }
+        }
+        return resolved;
+    }
+    transformQuery(query, schema) {
+        if (!(0, utils_1.isPlainObject)(query))
+            return query;
+        const isMongo = this.dataSource.options.type === 'mongodb';
+        const transformed = {};
+        for (const [key, value] of Object.entries(query)) {
+            // Map both 'id' and '_id' to '_id' for MongoDB queries
+            const targetKey = (isMongo && (key === 'id' || key === '_id')) ? '_id' : key;
+            const attr = schema?.attributes?.[key];
+            const a = Array.isArray(attr) ? attr[0] : attr;
+            // id and any field with type ObjectId are treated as ID fields
+            const isObjectIdField = key === 'id' || key === '_id' || (a && String(a.type).toLowerCase() === 'objectid');
+            if ((key === '$or' || key === '$and') && Array.isArray(value)) {
+                const subQueries = value.map(v => this.transformQuery(v, schema));
+                transformed[key] = subQueries;
+                continue;
+            }
+            if ((0, utils_1.isPlainObject)(value)) {
+                const keys = Object.keys(value);
+                if (keys.some(k => k.startsWith('$'))) {
+                    transformed[targetKey] = this.mapOperator(value, isMongo && isObjectIdField);
+                }
+                else {
+                    transformed[targetKey] = this.transformQuery(value, schema);
+                }
+            }
+            else {
+                if (isObjectIdField) {
+                    if (isMongo) {
+                        if (Array.isArray(value)) {
+                            transformed[targetKey] = { $in: value.map(v => this.convertToObjectId(v)) };
+                        }
+                        else {
+                            transformed[targetKey] = this.convertToObjectId(value);
+                        }
+                    }
+                    else {
+                        // Coerce to number for SQL if it is a string numeric
+                        if (Array.isArray(value)) {
+                            transformed[targetKey] = (0, typeorm_1.In)(value.map(v => {
+                                const n = Number(v);
+                                return !isNaN(n) ? n : v;
+                            }));
+                        }
+                        else {
+                            const num = Number(value);
+                            transformed[targetKey] = !isNaN(num) ? num : value;
+                        }
+                    }
+                }
+                else {
+                    // Coerce string numeric values for SQL, but keep as-is for Mongo (integrity for string fields)
+                    if (!isMongo) {
+                        const num = Number(value);
+                        transformed[key] = !isNaN(num) ? num : value;
+                    }
+                    else {
+                        transformed[key] = value;
+                    }
+                }
+            }
+        }
+        // Special handling for top-level $or in SQL (TypeORM expects array for OR, but our $or needs to be flattened/merged if combined with other ANDs)
+        if (!isMongo && transformed.$or && Array.isArray(transformed.$or)) {
+            const orPart = transformed.$or;
+            const otherPart = { ...transformed };
+            delete otherPart.$or;
+            if (Object.keys(otherPart).length === 0) {
+                return orPart;
+            }
+            else {
+                // Merge other filters into each OR condition: (A AND (B OR C)) -> (A AND B) OR (A AND C)
+                return orPart.map((sub) => ({ ...otherPart, ...sub }));
+            }
+        }
+        return transformed;
+    }
+    mapOperator(opObj, isObjectIdField = false) {
+        const isMongo = this.dataSource.options.type === 'mongodb';
+        if (opObj.$regex) {
+            const val = String(opObj.$regex);
+            const isCaseInsensitive = opObj.$options?.includes('i');
+            if (isMongo) {
+                return { $regex: val, $options: opObj.$options || '' };
+            }
+            let pattern = val;
+            if (pattern.startsWith('^')) {
+                pattern = pattern.slice(1);
+            }
+            else {
+                pattern = `%${pattern}`;
+            }
+            if (pattern.endsWith('$')) {
+                pattern = pattern.slice(0, -1);
+            }
+            else {
+                pattern = `${pattern}%`;
+            }
+            return isCaseInsensitive ? (0, typeorm_1.ILike)(pattern) : (0, typeorm_1.Like)(pattern);
+        }
+        if (opObj.$gt !== undefined) {
+            const val = isObjectIdField ? this.convertToObjectId(opObj.$gt) : opObj.$gt;
+            return isMongo ? { $gt: val } : (0, typeorm_1.MoreThan)(val);
+        }
+        if (opObj.$gte !== undefined) {
+            const val = isObjectIdField ? this.convertToObjectId(opObj.$gte) : opObj.$gte;
+            return isMongo ? { $gte: val } : (0, typeorm_1.MoreThanOrEqual)(val);
+        }
+        if (opObj.$lt !== undefined) {
+            const val = isObjectIdField ? this.convertToObjectId(opObj.$lt) : opObj.$lt;
+            return isMongo ? { $lt: val } : (0, typeorm_1.LessThan)(val);
+        }
+        if (opObj.$lte !== undefined) {
+            const val = isObjectIdField ? this.convertToObjectId(opObj.$lte) : opObj.$lte;
+            return isMongo ? { $lte: val } : (0, typeorm_1.LessThanOrEqual)(val);
+        }
+        if (opObj.$in !== undefined) {
+            const vals = Array.isArray(opObj.$in) ? opObj.$in : [opObj.$in];
+            const mappedVals = isObjectIdField ? vals.map((v) => this.convertToObjectId(v)) : vals;
+            return isMongo ? { $in: mappedVals } : (0, typeorm_1.In)(mappedVals);
+        }
+        if (opObj.$nin !== undefined) {
+            const vals = Array.isArray(opObj.$nin) ? opObj.$nin : [opObj.$nin];
+            const mappedVals = isObjectIdField ? vals.map((v) => this.convertToObjectId(v)) : vals;
+            return isMongo ? { $nin: mappedVals } : (0, typeorm_1.Not)((0, typeorm_1.In)(mappedVals));
+        }
+        if (opObj.$ne !== undefined) {
+            const val = isObjectIdField ? this.convertToObjectId(opObj.$ne) : opObj.$ne;
+            return isMongo ? { $ne: val } : (0, typeorm_1.Not)((0, typeorm_1.Equal)(val));
+        }
+        if (opObj.$eq !== undefined) {
+            const val = isObjectIdField ? this.convertToObjectId(opObj.$eq) : opObj.$eq;
+            return isMongo ? val : (0, typeorm_1.Equal)(val);
+        }
+        return opObj;
+    }
+    async cleanupUnusedFields(schemas) {
+        const report = {};
+        const isMongo = this.dataSource.options.type === 'mongodb';
+        if (isMongo) {
+            for (const def of Object.values(schemas)) {
+                const modelName = def.modelName;
+                const repo = this.dataSource.getMongoRepository(modelName);
+                // For MongoDB, we use the aggregation strategy to find all fields currently in the collection
+                const keysPipeline = [
+                    { $project: { data: { $objectToArray: '$$ROOT' } } },
+                    { $unwind: '$data' },
+                    { $group: { _id: null, allKeys: { $addToSet: '$data.k' } } },
+                ];
+                const keysResult = await repo.aggregate(keysPipeline).toArray();
+                const allKeys = keysResult[0]?.allKeys || [];
+                const schemaKeys = new Set([
+                    ...Object.keys(def.attributes),
+                    '_id',
+                    '__v',
+                    'createdAt',
+                    'updatedAt',
+                    'id',
+                ]);
+                const unusedKeys = allKeys.filter((k) => !schemaKeys.has(k));
+                if (unusedKeys.length > 0) {
+                    const unsetObj = {};
+                    for (const k of unusedKeys) {
+                        unsetObj[k] = '';
+                    }
+                    await repo.updateMany({}, { $unset: unsetObj });
+                    report[modelName] = unusedKeys;
+                    Logger_1.default.info('NMAdapter', `Cleaned up ${unusedKeys.length} fields in Mongo collection ${modelName}: ${unusedKeys.join(', ')}`);
+                }
+            }
+            return report;
+        }
+        // Default SQL Logic
+        const queryRunner = this.dataSource.createQueryRunner();
+        await queryRunner.connect();
+        try {
+            for (const def of Object.values(schemas)) {
+                const modelName = def.modelName;
+                const tableName = def.collection || modelName.toLowerCase();
+                const table = await queryRunner.getTable(tableName);
+                if (!table)
+                    continue;
+                const schemaKeys = new Set([
+                    ...Object.keys(def.attributes),
+                    'id',
+                    '_id',
+                    'createdAt',
+                    'updatedAt',
+                ]);
+                const columnsToDrop = table.columns
+                    .filter((col) => !schemaKeys.has(col.name))
+                    .map((col) => col.name);
+                if (columnsToDrop.length > 0) {
+                    Logger_1.default.info('NMAdapter', `Dropping ${columnsToDrop.length} columns in ${tableName}: ${columnsToDrop.join(', ')}`);
+                    for (const colName of columnsToDrop) {
+                        try {
+                            await queryRunner.dropColumn(tableName, colName);
+                        }
+                        catch (err) {
+                            Logger_1.default.warn('NMAdapter', `Failed to drop column ${colName} in ${tableName}: ${err.message}`);
+                        }
+                    }
+                    report[modelName] = columnsToDrop;
+                }
+            }
+        }
+        finally {
+            await queryRunner.release();
+        }
+        return report;
+    }
+    isExclusiveProjection(projection, schema) {
+        return (0, utils_2.isExclusiveProjection)(projection, schema);
+    }
+}
+exports.NMAdapter = NMAdapter;