@airoom/nextmin-node 2.0.1 → 2.0.3

package/dist/database/NMAdapter.js

@@ -9,6 +9,7 @@ const mongodb_1 = require("mongodb");
 const Logger_1 = __importDefault(require("../utils/Logger"));
 const utils_1 = require("../api/router/utils");
 const utils_2 = require("./utils");
+const QueryCache_1 = require("../utils/QueryCache");
 /**
  * NMAdapter implements the DatabaseAdapter interface.
  * It supports SQL databases (PostgreSQL, MySQL, MariaDB, SQLite, MSSQL) and MongoDB.
@@ -19,6 +20,39 @@ class NMAdapter {
         this.repositories = new Map();
         this.entitySchemas = new Map();
         this.registeredSchemas = {};
+        this.imageProxyOptions = {};
+        this.queryCache = new QueryCache_1.QueryCache();
+        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
@@ -75,8 +109,10 @@ class NMAdapter {
         // 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) {
+            for (const [key, attr] of Object.entries(def.attributes || {})) {
+                const a = Array.isArray(attr) ? attr[0] : attr;
+                const isRef = !!a?.ref || !!a?.refPath;
+                if (attr?.index === true || isRef || key === 'name' || key === 'title' || key === 'slug' || key === 'createdAt') {
                     indexes[key] = 1;
                 }
             }
@@ -84,7 +120,9 @@ class NMAdapter {
                 await this.syncIndexes(name, indexes);
             }
         }
-        // 4) Cache repositories
+        // 4) Validate refPath configurations
+        this.validateRefPathSchemas();
+        // 5) Cache repositories
         for (const name of Object.keys(schemas)) {
             const lcName = name.toLowerCase();
             const schema = this.entitySchemas.get(lcName);
@@ -93,6 +131,44 @@ class NMAdapter {
             }
         }
     }
+    validateRefPathSchemas() {
+        for (const [schemaName, schema] of Object.entries(this.registeredSchemas)) {
+            if (!schema?.attributes)
+                continue;
+            for (const [attrName, attr] of Object.entries(schema.attributes)) {
+                const a = Array.isArray(attr) ? attr[0] : attr;
+                if (!a?.refPath)
+                    continue;
+                const refPathField = String(a.refPath);
+                // 1) Warning if both 'ref' and 'refPath' are defined
+                if (a.ref) {
+                    Logger_1.default.warn('SchemaValidation', `Model "${schema.modelName}": Attribute "${attrName}" defines both "ref" ("${a.ref}") and "refPath" ("${refPathField}"). "refPath" takes precedence and "ref" will be ignored.`);
+                }
+                // 2) Warning if referenced refPath field does not exist in the same schema
+                const targetAttr = schema.attributes[refPathField];
+                if (!targetAttr) {
+                    Logger_1.default.warn('SchemaValidation', `Model "${schema.modelName}": Attribute "${attrName}" specifies refPath "${refPathField}", but field "${refPathField}" does not exist in schema "${schema.modelName}".`);
+                    continue;
+                }
+                // 3) Warning if target field is not an enum field with string items
+                const targetA = Array.isArray(targetAttr) ? targetAttr[0] : targetAttr;
+                const enumList = targetA?.enum;
+                if (!Array.isArray(enumList) || enumList.length === 0) {
+                    Logger_1.default.warn('SchemaValidation', `Model "${schema.modelName}": Attribute "${attrName}" refPath "${refPathField}" references field "${refPathField}", which must be a string attribute with an "enum" array of target model names.`);
+                    continue;
+                }
+                // 4) Warning for any enum value that is not a registered model
+                for (const enumVal of enumList) {
+                    if (typeof enumVal !== 'string')
+                        continue;
+                    const exists = Object.values(this.registeredSchemas).some(s => s.modelName.toLowerCase() === enumVal.trim().toLowerCase());
+                    if (!exists) {
+                        Logger_1.default.warn('SchemaValidation', `Model "${schema.modelName}": Attribute "${attrName}" refPath "${refPathField}" enum contains "${enumVal}", but schema "${enumVal}" is not a registered model.`);
+                    }
+                }
+            }
+        }
+    }
     async syncIndexes(modelName, spec) {
         const repo = this.repositories.get(modelName.toLowerCase());
         if (!repo)
@@ -118,6 +194,8 @@ class NMAdapter {
     }
     buildEntitySchema(def) {
         const isMongo = this.dataSource.options.type === 'mongodb';
+        const isPostgres = this.dataSource.options.type === 'postgres';
+        const dateTimeType = isPostgres ? 'timestamp' : 'datetime';
         const columns = {
             id: {
                 primary: true,
@@ -129,12 +207,14 @@ class NMAdapter {
                 generated: isMongo ? true : 'increment',
             },
             createdAt: {
-                type: 'datetime',
+                type: dateTimeType,
+                createDate: true,
                 default: () => 'CURRENT_TIMESTAMP',
                 nullable: true,
             },
             updatedAt: {
-                type: 'datetime',
+                type: dateTimeType,
+                updateDate: true,
                 default: () => 'CURRENT_TIMESTAMP',
                 nullable: true,
             },
@@ -159,6 +239,9 @@ class NMAdapter {
                     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;
@@ -179,7 +262,7 @@ class NMAdapter {
                     sparse: true,
                 });
             }
-            if (typeORMType === 'datetime' && attr.default === 'now') {
+            if ((typeORMType === 'datetime' || typeORMType === 'timestamp') && attr.default === 'now') {
                 columns[key].default = () => 'CURRENT_TIMESTAMP';
             }
         }
@@ -195,12 +278,13 @@ class NMAdapter {
             return 'simple-json';
         }
         const type = String(attr?.type || 'string').toLowerCase();
+        const isPostgres = this.dataSource.options.type === 'postgres';
         switch (type) {
             case 'string': return 'varchar';
             case 'number': return 'float';
             case 'boolean': return 'boolean';
             case 'date':
-            case 'datetime': return 'datetime';
+            case 'datetime': return isPostgres ? 'timestamp' : 'datetime';
             case 'json':
             case 'object': return 'json';
             case 'array': return 'simple-json';
@@ -216,51 +300,220 @@ class NMAdapter {
         }
         return repo;
     }
+    getActiveBaseUrl() {
+        if (this.options.imageProxy && this.options.imageProxy.proxyBase) {
+            return this.options.imageProxy.proxyBase.replace(/\/+$/, '');
+        }
+        if (this.imageProxyOptions.originalBase) {
+            return this.imageProxyOptions.originalBase.replace(/\/+$/, '');
+        }
+        if (this.imageProxyOptions.proxyBase) {
+            return this.imageProxyOptions.proxyBase.replace(/\/+$/, '');
+        }
+        if (process.env.S3_PUBLIC_BASE_URL) {
+            return process.env.S3_PUBLIC_BASE_URL.replace(/\/+$/, '');
+        }
+        return '';
+    }
+    cleanUrlForStorage(val) {
+        if (typeof val !== 'string')
+            return val;
+        // If string has spaces or HTML tags, it is not a pure image URL/key
+        if (val.includes(' ') || val.includes('<') || val.includes('>')) {
+            return val;
+        }
+        const basesToStrip = [
+            this.imageProxyOptions.originalBase,
+            this.imageProxyOptions.proxyBase,
+            process.env.S3_PUBLIC_BASE_URL,
+            this.options.s3?.publicBaseUrl
+        ].filter((b) => typeof b === 'string' && b.length > 0);
+        let cleaned = val;
+        for (const base of basesToStrip) {
+            const cleanBase = base.replace(/\/+$/, '');
+            if (cleaned.startsWith(cleanBase)) {
+                cleaned = cleaned.substring(cleanBase.length);
+            }
+        }
+        const uploadsIdx = cleaned.indexOf('uploads/');
+        if (uploadsIdx !== -1) {
+            cleaned = cleaned.substring(uploadsIdx);
+        }
+        return cleaned.replace(/^\/+/, '');
+    }
+    cleanPayloadForStorage(obj) {
+        if (!obj || typeof obj !== 'object')
+            return obj;
+        if (obj instanceof Date || Buffer.isBuffer(obj)) {
+            return obj;
+        }
+        if (Array.isArray(obj)) {
+            return obj.map(item => this.cleanPayloadForStorage(item));
+        }
+        const cleaned = {};
+        for (const key in obj) {
+            if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                const val = obj[key];
+                if (typeof val === 'string') {
+                    cleaned[key] = this.cleanUrlForStorage(val);
+                }
+                else if (val && typeof val === 'object') {
+                    cleaned[key] = this.cleanPayloadForStorage(val);
+                }
+                else {
+                    cleaned[key] = val;
+                }
+            }
+        }
+        return cleaned;
+    }
+    formatUrlForRead(val) {
+        if (typeof val !== 'string')
+            return val;
+        // If string has spaces or HTML tags, it is not a pure image URL/key
+        if (val.includes(' ') || val.includes('<') || val.includes('>')) {
+            return val;
+        }
+        let cleaned = val;
+        let matched = false;
+        const uploadsIdx = cleaned.indexOf('uploads/');
+        if (uploadsIdx !== -1) {
+            cleaned = cleaned.substring(uploadsIdx);
+            matched = true;
+        }
+        else {
+            // Also check if we can strip known bases
+            const basesToStrip = [
+                this.imageProxyOptions.originalBase,
+                this.imageProxyOptions.proxyBase,
+                process.env.S3_PUBLIC_BASE_URL,
+                this.options.s3?.publicBaseUrl
+            ].filter((b) => typeof b === 'string' && b.length > 0);
+            for (const base of basesToStrip) {
+                const cleanBase = base.replace(/\/+$/, '');
+                if (cleaned.startsWith(cleanBase)) {
+                    cleaned = cleaned.substring(cleanBase.length);
+                    matched = true;
+                    break;
+                }
+            }
+        }
+        cleaned = cleaned.replace(/^\/+/, '');
+        // If it was matched as a file URL/key, or if it is a clean storage path
+        if (matched || cleaned.startsWith('uploads/')) {
+            const activeBase = this.getActiveBaseUrl();
+            if (activeBase) {
+                return `${activeBase}/${cleaned}`;
+            }
+            return '/' + cleaned;
+        }
+        return val;
+    }
     async create(collection, data, schemaDefinition) {
+        await this.queryCache.invalidateCollection(collection);
         const repo = this.getRepository(collection);
-        const coerced = this.coercePayloadForStorage(data, schemaDefinition);
+        const cleanedData = this.cleanPayloadForStorage(data);
+        const coerced = this.coercePayloadForStorage(cleanedData, 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')
+        if (!payload || !schema)
             return payload;
+        const isMongo = this.dataSource.options.type === 'mongodb';
         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;
-            }
+            // Flatten nested objects/relations to their IDs
             if (isObjectIdField && coerced[key] != null) {
                 if (Array.isArray(coerced[key])) {
-                    coerced[key] = coerced[key].map((v) => this.convertToObjectId(v));
+                    coerced[key] = coerced[key].map((v) => {
+                        if (v && typeof v === 'object') {
+                            return v.id || v._id || v;
+                        }
+                        return v;
+                    });
                 }
-                else {
-                    coerced[key] = this.convertToObjectId(coerced[key]);
+                else if (coerced[key] && typeof coerced[key] === 'object') {
+                    coerced[key] = coerced[key].id || coerced[key]._id || coerced[key];
+                }
+            }
+            if (isMongo) {
+                // 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]);
+                    }
+                }
+            }
+            else {
+                // For SQL databases: single-value ObjectId relations are stored via simple-json.
+                // Coerce string numeric IDs to actual numbers so JSON.stringify produces '1' (not '"1"'),
+                // preventing the double-quote storage bug ("\"1\"" in the DB).
+                if (isObjectIdField && Array.isArray(attr) && !a?.multiple && coerced[key] != null) {
+                    const val = coerced[key];
+                    if (typeof val === 'string') {
+                        const n = Number(val);
+                        if (!isNaN(n) && val.trim() !== '') {
+                            coerced[key] = n;
+                        }
+                    }
                 }
             }
         }
         return coerced;
     }
     async read(collection, query, limit, skip, schemaDefinition, includePrivateFields, options) {
+        const cacheKey = await this.queryCache.generateKey(collection, 'read', {
+            query, limit, skip, schema: schemaDefinition?.modelName, includePrivateFields, options
+        });
+        const cached = await this.queryCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
         const repo = this.getRepository(collection);
         const isMongo = this.dataSource.options.type === 'mongodb';
         const resolvedQuery = await this.resolveNestedSearches(query);
         const where = this.transformQuery(resolvedQuery, schemaDefinition);
+        let order = options?.sort;
+        if (order && !isMongo) {
+            order = { ...order };
+            delete order._id;
+        }
         const findOptions = {
             where,
             take: limit,
             skip: skip,
-            order: options?.sort,
+            order,
         };
         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];
@@ -288,7 +541,15 @@ class NMAdapter {
             }
         }
         let results;
-        if (isMongo && findOptions.projection) {
+        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);
@@ -301,12 +562,34 @@ class NMAdapter {
             results = await cursor.toArray();
         }
         else {
-            results = await repo.find(findOptions);
+            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?.projection);
+            await this.hydrateRelations(mappedResults, schemaDefinition, options?.depth ?? 0, options);
         }
+        await this.queryCache.set(cacheKey, mappedResults);
         return mappedResults;
     }
     prepareResult(item) {
@@ -324,8 +607,35 @@ class NMAdapter {
             if (item.id != null)
                 item.id = String(item.id);
         }
+        // Apply image URL proxying/transformation
+        this.transformUrls(item);
         return item;
     }
+    transformUrls(obj) {
+        if (!obj || typeof obj !== 'object')
+            return;
+        for (const key in obj) {
+            if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                const val = obj[key];
+                if (typeof val === 'string') {
+                    obj[key] = this.formatUrlForRead(val);
+                }
+                else if (Array.isArray(val)) {
+                    for (let i = 0; i < val.length; i++) {
+                        if (typeof val[i] === 'string') {
+                            val[i] = this.formatUrlForRead(val[i]);
+                        }
+                        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 '';
@@ -358,8 +668,15 @@ class NMAdapter {
                 return this.convertToObjectId(extractedId);
         }
         try {
-            if (typeof val === 'string' && val.length === 24 && /^[0-9a-fA-F]{24}$/.test(val)) {
-                return new mongodb_1.ObjectId(val);
+            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;
         }
@@ -367,9 +684,87 @@ class NMAdapter {
             return val;
         }
     }
-    async hydrateRelations(results, schema, depth = 0, projection) {
+    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();
@@ -436,13 +831,59 @@ class NMAdapter {
         }
         // 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;
+            const t = String(a?.type || '').toLowerCase();
+            return (t === 'objectid' || t === 'ref') && (a?.ref || a?.refPath);
         });
+        const isHydratedObject = (val) => {
+            if (val == null)
+                return false;
+            if (typeof val !== 'object')
+                return false;
+            if (Array.isArray(val))
+                return false;
+            if (val instanceof mongodb_1.ObjectId)
+                return false;
+            if (typeof val.toHexString === 'function')
+                return false;
+            if (val.constructor && val.constructor.name === 'ObjectId')
+                return false;
+            if (val instanceof Date)
+                return false;
+            if (Buffer.isBuffer(val))
+                return false;
+            const keys = Object.keys(val);
+            const hasId = keys.includes('id') || keys.includes('_id');
+            const hasOtherKeys = keys.some(k => k !== 'id' && k !== '_id');
+            return hasId && hasOtherKeys;
+        };
         for (const [key, attr] of relFields) {
             hydrationPromises.push((async () => {
                 const hasRootProj = this.isExclusiveProjection(projection, schema);
@@ -450,58 +891,140 @@ class NMAdapter {
                 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();
+                const attrObj = isArray ? attr[0] : attr;
+                const refPathKey = attrObj.refPath ? String(attrObj.refPath) : undefined;
+                const staticRefModel = attrObj.ref ? String(attrObj.ref) : undefined;
+                // Group items by resolved target model name
+                const itemsByModel = new Map();
+                const resolveModelName = (raw) => {
+                    // Strictly accept only string enum values (no objects or unknown types)
+                    if (typeof raw !== 'string' || !raw.trim())
+                        return null;
+                    const nameStr = raw.trim();
+                    // Verify that refPathKey refers to an existing field in the schema
+                    const refPathAttr = schema.attributes[refPathKey];
+                    if (!refPathAttr)
+                        return null;
+                    const targetA = Array.isArray(refPathAttr) ? refPathAttr[0] : refPathAttr;
+                    const allowedEnums = targetA?.enum;
+                    // Verify that value is listed in the refPath field's enum array
+                    if (Array.isArray(allowedEnums) && allowedEnums.length > 0) {
+                        const isAllowed = allowedEnums.some(e => typeof e === 'string' && e.trim().toLowerCase() === nameStr.toLowerCase());
+                        if (!isAllowed)
+                            return null;
+                    }
+                    // Match case-insensitively against registered schemas
+                    const targetSchema = Object.values(this.registeredSchemas).find(s => s.modelName.toLowerCase() === nameStr.toLowerCase());
+                    return targetSchema ? targetSchema.modelName : null;
+                };
                 for (const item of results) {
-                    const val = item[key];
+                    let val = item[key];
                     if (val == null)
                         continue;
+                    // Determine target model for this specific item
+                    const targetModel = refPathKey ? resolveModelName(item[refPathKey]) : staticRefModel;
+                    if (!targetModel)
+                        continue;
+                    // Gracefully parse JSON-stringified relation data if stored in DB (as object or array)
+                    if (typeof val === 'string') {
+                        const trimmed = val.trim();
+                        if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+                            try {
+                                const parsed = JSON.parse(trimmed);
+                                if (parsed != null) {
+                                    item[key] = parsed;
+                                    val = parsed;
+                                }
+                            }
+                            catch (e) { }
+                        }
+                    }
+                    if (!itemsByModel.has(targetModel)) {
+                        itemsByModel.set(targetModel, []);
+                    }
+                    const group = itemsByModel.get(targetModel);
                     if (isArray && Array.isArray(val)) {
-                        val.forEach(v => { if (v != null)
-                            idsToFetch.add(v); });
+                        item[key] = val.map(v => {
+                            if (typeof v === 'string') {
+                                const trimmed = v.trim();
+                                if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+                                    try {
+                                        const parsed = JSON.parse(trimmed);
+                                        if (parsed != null)
+                                            return parsed;
+                                    }
+                                    catch (e) { }
+                                }
+                            }
+                            return v;
+                        });
+                        const mappedVal = item[key];
+                        mappedVal.forEach(v => {
+                            if (v != null && !isHydratedObject(v)) {
+                                group.push({ item, idVal: v });
+                            }
+                        });
                     }
                     else {
-                        idsToFetch.add(val);
+                        if (!isHydratedObject(val)) {
+                            group.push({ item, idVal: val });
+                        }
                     }
                 }
-                if (idsToFetch.size === 0)
+                if (itemsByModel.size === 0)
                     return;
-                let subProjection = undefined;
-                if (projection) {
+                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 = {};
+                                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)
+                for (const [targetModelName, entries] of itemsByModel.entries()) {
+                    const refLc = targetModelName.toLowerCase();
+                    const refRepo = this.repositories.get(refLc);
+                    if (!refRepo)
                         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;
+                    const idsToFetch = new Set();
+                    entries.forEach(e => idsToFetch.add(e.idVal));
+                    if (idsToFetch.size === 0)
+                        continue;
+                    const fetchedDocs = await this.read(targetModelName, { id: { $in: Array.from(idsToFetch) } }, idsToFetch.size, 0, this.registeredSchemas[targetModelName], 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 entries) {
+                        const val = item[key];
+                        if (val == null)
+                            continue;
+                        if (Array.isArray(val)) {
+                            item[key] = val.map(v => {
+                                if (isHydratedObject(v))
+                                    return v;
+                                return docMap.get(this.idToString(v)) || v;
+                            });
+                        }
+                        else {
+                            if (isHydratedObject(val)) {
+                                // Keep as-is
+                            }
+                            else {
+                                item[key] = docMap.get(this.idToString(val)) || val;
+                            }
+                        }
                     }
                 }
             })());
@@ -543,6 +1066,7 @@ class NMAdapter {
         await Promise.all(hydrationPromises);
     }
     async update(collection, targetId, data, schemaDefinition) {
+        await this.queryCache.invalidateCollection(collection);
         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.`);
         }
@@ -551,17 +1075,20 @@ class NMAdapter {
             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);
+        const cleanedData = this.cleanPayloadForStorage(data);
+        const coerced = this.coercePayloadForStorage(cleanedData, schemaDefinition);
         // Strip ID fields from data to prevent primary key conflicts
-        const { id: _unusedId, _id: _unusedRawId, ...updateData } = coerced;
+        const { id: _unusedId, _id: _unusedRawId, exId: _unusedExId, ...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)) {
+            // We look at the original cleaned data for nulls because coercePayloadForStorage strips them
+            for (const [k, v] of Object.entries(cleanedData)) {
                 if (k === 'id' || k === '_id')
                     continue;
                 if (v === null) {
@@ -572,6 +1099,8 @@ class NMAdapter {
                     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;
@@ -588,6 +1117,7 @@ class NMAdapter {
         return updated[0];
     }
     async delete(collection, targetId, schemaDefinition) {
+        await this.queryCache.invalidateCollection(collection);
         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.`);
         }
@@ -610,6 +1140,11 @@ class NMAdapter {
         return existing[0] || null;
     }
     async count(collection, query, schemaDefinition) {
+        const cacheKey = await this.queryCache.generateKey(collection, 'count', { query, schema: schemaDefinition?.modelName });
+        const cached = await this.queryCache.get(cacheKey);
+        if (cached !== null) {
+            return cached;
+        }
         const repo = this.getRepository(collection);
         const resolvedQuery = await this.resolveNestedSearches(query);
         const where = this.transformQuery(resolvedQuery, schemaDefinition);
@@ -620,8 +1155,45 @@ class NMAdapter {
         else {
             total = await repo.count({ where });
         }
+        await this.queryCache.set(cacheKey, total);
         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();
@@ -779,6 +1351,16 @@ class NMAdapter {
                 continue;
             }
             if ((0, utils_1.isPlainObject)(value)) {
+                if (!isMongo && Array.isArray(attr) && value.$in !== undefined) {
+                    const vals = Array.isArray(value.$in) ? value.$in : [value.$in];
+                    transformed[targetKey] = (0, typeorm_1.Raw)(alias => {
+                        return vals.map((v, i) => `${alias} LIKE :val_${key}_${i}`).join(' OR ');
+                    }, vals.reduce((acc, v, i) => {
+                        acc[`val_${key}_${i}`] = `%"${v}"%`;
+                        return acc;
+                    }, {}));
+                    continue;
+                }
                 const keys = Object.keys(value);
                 if (keys.some(k => k.startsWith('$'))) {
                     transformed[targetKey] = this.mapOperator(value, isMongo && isObjectIdField);
@@ -798,24 +1380,47 @@ class NMAdapter {
                         }
                     }
                     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;
-                            }));
+                        // Check if it is a simple-json relation array attribute in the SQL database
+                        if (Array.isArray(attr)) {
+                            if (Array.isArray(value)) {
+                                transformed[targetKey] = (0, typeorm_1.Raw)(alias => {
+                                    return value.map((v, i) => `${alias} LIKE :val_${key}_${i}`).join(' OR ');
+                                }, value.reduce((acc, v, i) => {
+                                    acc[`val_${key}_${i}`] = `%"${v}"%`;
+                                    return acc;
+                                }, {}));
+                            }
+                            else {
+                                transformed[targetKey] = (0, typeorm_1.Like)(`%"${value}"%`);
+                            }
                         }
                         else {
-                            const num = Number(value);
-                            transformed[targetKey] = !isNaN(num) ? num : value;
+                            // 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;
+                        const attrType = a && String(a.type || '').toLowerCase();
+                        const isStringField = attrType === 'string' || attrType === 'text';
+                        if (isStringField) {
+                            transformed[key] = value;
+                        }
+                        else {
+                            const num = Number(value);
+                            transformed[key] = !isNaN(num) ? num : value;
+                        }
                     }
                     else {
                         transformed[key] = value;
@@ -823,6 +1428,16 @@ class NMAdapter {
                 }
             }
         }
+        // Special handling for top-level $and in SQL (TypeORM expects flat object, not $and array)
+        if (!isMongo && transformed.$and && Array.isArray(transformed.$and)) {
+            const andPart = transformed.$and;
+            delete transformed.$and;
+            for (const sub of andPart) {
+                if ((0, utils_1.isPlainObject)(sub)) {
+                    Object.assign(transformed, sub);
+                }
+            }
+        }
         // 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;