monsqlize 1.3.1 → 2.0.1

package/lib/model/examples/test.js

@@ -1,114 +0,0 @@
-
-
-module.exports = {
-
-    // 枚举配置
-    enums: {
-        role: ['admin', 'user'],
-        status: ['active', 'inactive']
-    },
-
-    // 定义model
-    schema:(sc)=>{
-        return {
-            username: sc.string().min(3).max(30).required(),
-            password: sc.string().pattern(/^[a-zA-Z0-9]{6,30}$/).required(),
-            age: sc.number().integer().min(0).default(18),   // 默认值
-            role: sc.string().valid('admin', 'user').default('user'),
-        };
-    },
-
-    // 自定义方法
-    methods: (model)=>{
-        return {
-            // 实例方法
-            instance: {
-                checkPassword(password) {
-                    return this.password === password;
-                },
-                async getPosts() {
-                    // return await model.find({ userId: this._id });
-                }
-            },
-            // 静态方法
-            static: {
-                findByName(name) {
-                    return this.find({ username: name });
-                }
-            }
-        };
-    },
-
-    // 支持操作前、后处理
-    hooks:(model)=>{
-        return {
-            find: {
-                before:(ctx,options)=>{},
-                after:(ctx,docs,result)=>{},
-            },
-            insert:{
-                before:async (ctx,docs)=>{
-                    // ctx.session = await model.startTransaction(); // ctx 里传递事务对象
-                    // return ctx.data;
-                },
-                after:async (ctx,docs,result)=>{
-                    // await ctx.session.commitTransaction();
-                },
-            },
-            update:{
-                before:(ctx,options)=>{},
-                after:(ctx,result)=>{},
-            },
-            delete:{
-                before:(ctx,options)=>{},
-                after:(ctx,result)=>{},
-            }
-        };
-    },
-
-    // 创建索引
-    indexes: [
-        { key: { username: 1 }, unique: true },     // 唯一索引
-        { key: { age: -1 } },                       // 普通索引，降序
-    ],
-
-    // 关系
-    relations: {
-        posts: {
-            type: 'hasMany',      // 一对多
-            target: 'Post',       // 目标模型
-            foreignKey: 'userId', // 外键字段（存在哪张表里）
-            localKey: '_id',      // 本表对应字段
-            as: 'posts',          // 实例访问属性 user.posts
-            cascade: false        // 是否级联删除/更新
-        },
-        profile: {
-            type: 'hasOne',       // 一对一
-            target: 'Profile',
-            foreignKey: 'userId',
-            localKey: '_id',
-            as: 'profile',        // 实例访问属性 user.profile
-            cascade: true,        // 删除用户时级联删除 profile
-            required: false       // 是否必须关联
-        },
-        roles: {                  // 多对多
-            type: 'manyToMany',
-            target: 'Role',
-            through: 'UserRole',  // 中间表
-            foreignKey: 'userId',
-            otherKey: 'roleId',
-            as: 'roles'
-        }
-    },
-
-    // 选项
-    options: {
-        timestamps: true,       // 自动维护 createdAt / updatedAt
-        softDelete: true,       // 启用 deletedAt 替代物理删除，deletedAt = null → 正常数据，deletedAt = Date → 已删除
-        sync: true,             // 启用 index 索引自动同步
-        version: true,          // 自动维护 __v 版本号
-    }
-
-    // 自动索引 / 慢查询统计 → 全局 ORM 层统一管理
-    // 恢复软删除 → 全局方法注入到每个启用 softDelete 的模型
-};

package/lib/mongodb/common/accessor-helpers.js

@@ -1,58 +0,0 @@
-// Mongo 适配器辅助工具：慢查询日志整形器（脱敏）和缓存键构建器
-// - mongoSlowLogShaper: 通过组合通用的元信息与 Mongo 的结构，生成安全的慢查询日志附加字段
-// - mongoKeyBuilder: 当 op==='findPage' 时，注入 pipelineHash（对 pipeline 进行 stableStringify 后再做 sha256）
-//并在键值材料中省略原始 pipeline，以保持键的简短和稳定
-
-
-const crypto = require('crypto');
-const CacheFactory = require('../../cache');
-const { buildCommonLogExtra } = require('../../common/shape-builders');
-const { shapeQuery, shapeProjection, shapeSort } = require('./shape');
-const { normalizeForCache } = require('../../utils/objectid-converter');
-
-/**
- * Mongo 专属：慢日志去敏形状构造器
- * @param {object} options - 原始调用选项（仅读取形状/标记，不含具体值）
- * @returns {object} 去敏后的形状对象（仅字段集合/标记位）
- */
-function mongoSlowLogShaper(options) {
-    const extra = buildCommonLogExtra(options);
-    if (options?.query)      extra.queryShape      = shapeQuery(options.query);
-    if (options?.projection) extra.projectionShape = shapeProjection(options.projection);
-    if (options?.sort)       extra.sortShape       = shapeSort(options.sort);
-    return extra;
-}
-
-/**
- * Mongo 专属：缓存键构造器
- * 仅在 findPage 时：对 pipeline 做稳定串行化并 sha256 → pipelineHash；
- * 同时从参与键的 options 中去除原始 pipeline，避免键过长与不稳定。
- *
- * ✅ v1.3.0 新增：标准化 ObjectId
- * - 将所有 ObjectId 实例转换为字符串
- * - 确保 ObjectId('xxx') 和 'xxx' 生成相同的缓存键
- * - 避免缓存失效和重复查询
- *
- * @param {string} op
- * @param {object} options
- * @returns {object} 用于参与缓存键构造的 options 视图
- */
-function mongoKeyBuilder(op, options) {
-    const opts = options || {};
-
-    // ✅ 标准化 options 中的 ObjectId（转为字符串）
-    // 确保查询缓存键一致性
-    const normalizedOpts = normalizeForCache(opts);
-
-    if (op !== 'findPage') return normalizedOpts;
-
-    // findPage 特殊处理：pipeline 转 hash
-    const pipelineHash = crypto
-        .createHash('sha256')
-        .update(CacheFactory.stableStringify(normalizedOpts.pipeline || []))
-        .digest('hex');
-    const { pipeline, ...rest } = normalizedOpts;
-    return { ...rest, pipelineHash };
-}
-
-module.exports = { mongoSlowLogShaper, mongoKeyBuilder };

package/lib/mongodb/common/agg-pipeline.js

@@ -1,32 +0,0 @@
-/**
- * Mongo 聚合分页管道构造器（方案 A：先分页后联表）
- * 流程：$match(query) → $match($expr-游标比较) → $sort(sort) → $limit(limit+1) → 页内 $lookup →
- *       若为 before 方向，再 $sort(反转) 恢复视觉顺序。
- */
-
-const { buildLexiExpr } = require('./lexicographic-expr');
-const { reverseSort } = require('./sort');
-
-/**
- * 构造方案 A 的聚合管道
- * @param {object} params
- * @param {object} [params.query]
- * @param {Record<string,1|-1>} params.sort - 查询阶段使用的排序（before 方向已反转）
- * @param {number} params.limit - 页大小
- * @param {{a:object,s:object}|null} [params.cursor] - 解析后的游标对象
- * @param {'after'|'before'|null} [params.direction]
- * @param {object[]} [params.lookupPipeline] - 页内联表等追加管道
- * @returns {object[]} 聚合管道数组
- */
-function buildPagePipelineA({ query = {}, sort, limit, cursor, direction, lookupPipeline = [] }) {
-    const pipeline = [];
-    if (query && Object.keys(query).length) pipeline.push({ $match: query });
-    if (cursor) pipeline.push({ $match: { $expr: buildLexiExpr(sort, cursor.a) } });
-    pipeline.push({ $sort: sort });
-    pipeline.push({ $limit: limit + 1 });
-    if (lookupPipeline && lookupPipeline.length) pipeline.push(...lookupPipeline);
-    if (direction === 'before') pipeline.push({ $sort: reverseSort(sort) });
-    return pipeline;
-}
-
-module.exports = { buildPagePipelineA };

package/lib/mongodb/common/iid.js

@@ -1,27 +0,0 @@
-/**
- * Mongo 实例指纹（iid）生成
- * 基于 uri/db 生成稳定短标识，用于缓存命名空间等
- */
-const crypto = require('crypto');
-
-function genInstanceId(databaseName, uri, explicitId) {
-    if (explicitId) return String(explicitId);
-    const safeDb = String(databaseName || '');
-    try {
-        const u = new URL(String(uri || ''));
-        const proto = (u.protocol || '').replace(':', '');
-        const host = u.hostname || '';
-        const port = u.port || (proto === 'mongodb+srv' ? 'srv' : '27017');
-        const rs = u.searchParams.get('replicaSet') || '';
-        const authSource = u.searchParams.get('authSource') || '';
-        const tls = u.searchParams.get('tls') || u.searchParams.get('ssl') || '';
-        const safe = `${proto}://${host}:${port}/${safeDb}?rs=${rs}&auth=${authSource}&tls=${tls}`;
-        const h = crypto.createHash('sha1').update(safe).digest('base64url').slice(0, 12);
-        return `mdb:${h}`;
-    } catch (_) {
-        const h = crypto.createHash('sha1').update(String(uri || '') + '|' + safeDb).digest('base64url').slice(0, 12);
-        return `mdb:${h}`;
-    }
-}
-
-module.exports = { genInstanceId };

package/lib/mongodb/common/lexicographic-expr.js

@@ -1,52 +0,0 @@
-/**
- * Mongo 专属：构造 $expr 的词典序比较表达式（lexicographic compare）
- * 场景：按复合排序键（含 `_id` 兜底）进行游标分页的"锚点之后/之前"过滤。
- * 例：sort={k1:1,k2:-1,_id:1}, anchor={k1:...,k2:...,_id:...}
- * 生成：{$or:[ {$gt:['$k1',a.k1]}, {$and:[{$eq:['$k1',a.k1]},{$lt:['$k2',a.k2]}]}, ...]}
- */
-
-const { ObjectId } = require('mongodb');
-
-/**
- * 转换锚点值，处理特殊类型
- * @param {any} value - 锚点值
- * @param {string} fieldName - 字段名
- * @returns {any} 转换后的值
- */
-function convertAnchorValue(value, fieldName) {
-    // 如果是 _id 字段且值是字符串，转换为 ObjectId
-    if (fieldName === '_id' && typeof value === 'string' && /^[0-9a-fA-F]{24}$/.test(value)) {
-        return new ObjectId(value);
-    }
-
-    // 如果值是 ISO 日期字符串，转换为 Date 对象
-    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/.test(value)) {
-        return new Date(value);
-    }
-
-    return value;
-}
-
-/**
- * 构造 $expr 词典序比较
- * @param {Record<string,1|-1>} sort - 稳定排序（含 `_id`）
- * @param {Record<string,any>} anchor - 锚点值对象
- * @returns {object} Mongo $expr 表达式对象
- */
-function buildLexiExpr(sort, anchor) {
-    const keys = Object.keys(sort || {});
-    const or = [];
-    for (let i = 0; i < keys.length; i++) {
-        const and = [];
-        for (let j = 0; j < i; j++) {
-            and.push({ $eq: [ `$${keys[j]}`, convertAnchorValue(anchor[keys[j]], keys[j]) ] });
-        }
-        const dir = sort[keys[i]];
-        const op = dir === 1 ? '$gt' : '$lt';
-        and.push({ [op]: [ `$${keys[i]}`, convertAnchorValue(anchor[keys[i]], keys[i]) ] });
-        or.push(and.length === 1 ? and[0] : { $and: and });
-    }
-    return { $or: or };
-}
-
-module.exports = { buildLexiExpr };

package/lib/mongodb/common/shape.js

@@ -1,31 +0,0 @@
-/**
- * Mongo 去敏形状构造
- * - shapeQuery: 仅输出字段名与运算符（以 '$' 代表），不含具体值
- * - shapeProjection: 将数组投影转为字段名数组，或对象投影的键名数组
- * - shapeSort: 仅输出排序键与 1/-1
- */
-
-function shapeQuery(input, maxKeys = 30, maxDepth = 3) {
-    const walk = (v, depth) => {
-        if (depth > maxDepth || v == null || typeof v !== 'object') return true; // 值用 true 表示
-        if (Array.isArray(v)) return v.length ? [walk(v[0], depth + 1)] : [];
-        const out = {};
-        let count = 0;
-        for (const k of Object.keys(v)) {
-            out[k] = k.startsWith('$') ? '$' : walk(v[k], depth + 1);
-            if (++count >= maxKeys) { out.__truncated__ = true; break; }
-        }
-        return out;
-    };
-    return walk(input, 0);
-}
-
-function shapeProjection(p) {
-    return Array.isArray(p) ? p.slice(0, 30) : Object.keys(p || {}).slice(0, 30);
-}
-
-function shapeSort(s) {
-    return Object.fromEntries(Object.entries(s || {}).slice(0, 30).map(([k, v]) => [k, v === -1 ? -1 : 1]));
-}
-
-module.exports = { shapeQuery, shapeProjection, shapeSort };

package/lib/mongodb/common/sort.js

@@ -1,38 +0,0 @@
-/**
- * Mongo 专属：稳定排序与锚点选择
- * - ensureStableSort：确保排序键（sort）末尾包含 `_id`（稳定排序兜底）。
- * - reverseSort：将排序方向整体反转（1 ↔ -1），用于 before 方向的查询阶段。
- * - pickAnchor：按排序键顺序从文档中提取锚点字段值对象（含 `_id`）。
- */
-
-/**
- * 确保排序对象包含稳定键 `_id`
- * @param {Record<string, 1|-1>|undefined} sort - 排序对象
- * @returns {Record<string, 1|-1>} 新的排序对象（若缺 `_id` 自动追加 `_id:1`）
- */
-function ensureStableSort(sort) {
-    const s = { ...(sort || {}) };
-    if (!('_id' in s)) s._id = 1;
-    return s;
-}
-
-/**
- * 反转排序方向（1 ↔ -1）
- * @param {Record<string, 1|-1>} sort
- * @returns {Record<string, 1|-1>}
- */
-function reverseSort(sort) {
-    const r = {}; for (const k of Object.keys(sort || {})) r[k] = sort[k] === 1 ? -1 : 1; return r;
-}
-
-/**
- * 提取锚点：按排序键顺序从文档取值（含 `_id`）
- * @param {any} doc - 文档
- * @param {Record<string, 1|-1>} sort - 稳定排序（含 `_id`）
- * @returns {Record<string, any>} 锚点值对象 { k1: v1, k2: v2, _id: id }
- */
-function pickAnchor(doc, sort) {
-    const a = {}; for (const k of Object.keys(sort || {})) a[k] = doc ? doc[k] : undefined; return a;
-}
-
-module.exports = { ensureStableSort, reverseSort, pickAnchor };

package/lib/mongodb/common/transaction-aware.js

@@ -1,24 +0,0 @@
-/**
- * 检查操作是否在事务中执行
- * @param {Object} options - 操作选项
- * @returns {boolean}
- */
-function isInTransaction(options) {
-    return !!(options && options.session && options.session.inTransaction && options.session.inTransaction());
-}
-
-/**
- * 从 session 中获取 Transaction 实例
- * @param {Object} session - MongoDB ClientSession
- * @returns {Transaction|null}
- */
-function getTransactionFromSession(session) {
-    if (!session) return null;
-    return session.__monSQLizeTransaction || null;
-}
-
-module.exports = {
-    isInTransaction,
-    getTransactionFromSession
-};
-

package/lib/mongodb/connect.js

@@ -1,233 +0,0 @@
-const { MongoClient } = require('mongodb');
-const { SSHTunnelManager } = require('../infrastructure/ssh-tunnel');
-const { parseUri } = require('../infrastructure/uri-parser');
-
-// 懒加载 MongoDB Memory Server（仅在需要时加载）
-let MongoMemoryServer;
-let MongoMemoryReplSet;
-let memoryServerInstance; // 单例实例
-
-function buildLogContext({ type, databaseName, defaults, config }) {
-    const scope = defaults?.namespace?.scope;
-    let uriHost;
-    try { uriHost = new URL(config?.uri || '').hostname; } catch (_) { uriHost = undefined; }
-    return { type, db: databaseName, scope, uriHost };
-}
-
-/**
- * 启动 MongoDB Memory Server（单例模式）
- * @param {Object} logger - 日志记录器
- * @param {Object} [memoryServerOptions] - Memory Server 配置选项
- * @returns {Promise<string>} 返回内存数据库的连接 URI
- */
-async function startMemoryServer(logger, memoryServerOptions = {}) {
-    if (memoryServerInstance) {
-        const uri = memoryServerInstance.getUri();
-        try { logger && logger.debug && logger.debug('📌 Using existing MongoDB Memory Server', { uri }); } catch (_) { }
-        return uri;
-    }
-
-    try {
-        // 检查是否需要副本集
-        const needsReplSet = memoryServerOptions?.instance?.replSet;
-
-        if (needsReplSet) {
-            // 使用副本集模式
-            if (!MongoMemoryReplSet) {
-                MongoMemoryReplSet = require('mongodb-memory-server').MongoMemoryReplSet;
-            }
-
-            try { logger && logger.info && logger.info('🚀 Starting MongoDB Memory Server (Replica Set)...', { replSet: needsReplSet }); } catch (_) { }
-
-            const replSetConfig = {
-                replSet: {
-                    name: needsReplSet,
-                    count: 1, // 单节点副本集（足以支持事务）
-                    storageEngine: 'wiredTiger'
-                },
-                binary: {
-                    version: '6.0.12'
-                }
-            };
-
-            memoryServerInstance = await MongoMemoryReplSet.create(replSetConfig);
-            const uri = memoryServerInstance.getUri();
-            try { logger && logger.info && logger.info('✅ MongoDB Memory Server (Replica Set) started', { uri, replSet: needsReplSet }); } catch (_) { }
-            return uri;
-        } else {
-            // 使用单实例模式
-            if (!MongoMemoryServer) {
-                MongoMemoryServer = require('mongodb-memory-server').MongoMemoryServer;
-            }
-
-            try { logger && logger.info && logger.info('🚀 Starting MongoDB Memory Server...'); } catch (_) { }
-
-            const defaultConfig = {
-                instance: {
-                    port: undefined,
-                    dbName: 'test_db',
-                    storageEngine: 'ephemeralForTest',
-                },
-                binary: {
-                    version: '6.0.12',
-                },
-            };
-
-            const config = {
-                ...defaultConfig,
-                ...memoryServerOptions,
-                instance: {
-                    ...defaultConfig.instance,
-                    ...(memoryServerOptions.instance || {})
-                },
-                binary: {
-                    ...defaultConfig.binary,
-                    ...(memoryServerOptions.binary || {})
-                }
-            };
-
-            memoryServerInstance = await MongoMemoryServer.create(config);
-            const uri = memoryServerInstance.getUri();
-            try { logger && logger.info && logger.info('✅ MongoDB Memory Server started', { uri }); } catch (_) { }
-            return uri;
-        }
-    } catch (err) {
-        try { logger && logger.error && logger.error('❌ Failed to start MongoDB Memory Server', err); } catch (_) { }
-        throw new Error(`Failed to start MongoDB Memory Server: ${err.message}`);
-    }
-}
-
-/**
- * 停止 MongoDB Memory Server
- * @param {Object} logger - 日志记录器
- */
-async function stopMemoryServer(logger) {
-    if (!memoryServerInstance) {
-        return;
-    }
-
-    try {
-        try { logger && logger.info && logger.info('🛑 Stopping MongoDB Memory Server...'); } catch (_) { }
-        await memoryServerInstance.stop();
-        memoryServerInstance = null;
-        try { logger && logger.info && logger.info('✅ MongoDB Memory Server stopped'); } catch (_) { }
-    } catch (err) {
-        try { logger && logger.warn && logger.warn('⚠️  Error stopping MongoDB Memory Server', err); } catch (_) { }
-        memoryServerInstance = null;
-    }
-}
-
-/**
- * 建立 MongoDB 连接（适配器内部使用）
- * @param {{ databaseName: string, config: { uri?: string, options?: object, useMemoryServer?: boolean, readPreference?: string, ssh?: object, remoteHost?: string, remotePort?: number, mongoHost?: string, mongoPort?: number }, logger: any, defaults: object, type?: string }} params
- * @returns {Promise<{ client: import('mongodb').MongoClient, db: any, sshTunnel?: any }>} 返回已连接的 client、默认 db 句柄（若可用）和 SSH 隧道实例（若使用）
- */
-async function connectMongo({ databaseName, config, logger, defaults, type = 'mongodb' }) {
-    let { uri, options = {}, useMemoryServer, memoryServerOptions, readPreference, ssh } = config || {};
-
-    let sshTunnel = null;
-    let effectiveUri = uri;
-
-    // ===== SSH 隧道逻辑 =====
-    if (ssh) {
-        logger?.info?.('🔐 Establishing SSH tunnel for MongoDB...');
-
-        // 解析MongoDB目标地址（优先级：显式配置 > URI解析）
-        let remoteHost = config.remoteHost || config.mongoHost;
-        let remotePort = config.remotePort || config.mongoPort;
-
-        if (!remoteHost || !remotePort) {
-            try {
-                const parsed = parseUri(uri);
-                remoteHost = parsed.host;
-                remotePort = parsed.port;
-            } catch (err) {
-                throw new Error('SSH tunnel requires remoteHost and remotePort, or a valid MongoDB URI');
-            }
-        }
-
-        // 使用SSH隧道管理器工厂
-        sshTunnel = SSHTunnelManager.create(ssh, remoteHost, remotePort, {
-            logger,
-            name: 'MongoDB'
-        });
-
-        try {
-            await sshTunnel.connect();
-
-            // 使用隧道URI
-            effectiveUri = sshTunnel.getTunnelUri('mongodb', uri);
-
-            logger?.info?.(`✅ MongoDB will connect via SSH tunnel: ${sshTunnel.getLocalAddress()}`);
-        } catch (err) {
-            logger?.error?.('❌ SSH tunnel connection failed', err);
-            throw err;
-        }
-    }
-    // ===== Memory Server 逻辑 =====
-    else if (useMemoryServer === true) {
-        try {
-            effectiveUri = await startMemoryServer(logger, memoryServerOptions);
-        } catch (err) {
-            // 如果启动内存服务器失败，且没有提供 uri，抛出错误
-            if (!effectiveUri) {
-                throw new Error('Failed to start Memory Server and no URI provided');
-            }
-            logger?.warn?.('Failed to start Memory Server, using provided URI', { uri: effectiveUri });
-        }
-    }
-
-    if (!effectiveUri) throw new Error('MongoDB connect requires config.uri or config.useMemoryServer');
-
-    // 🔑 合并 readPreference 到 MongoClient options
-    const clientOptions = { ...options };
-    if (readPreference) {
-        clientOptions.readPreference = readPreference;
-    }
-
-    const client = new MongoClient(effectiveUri, clientOptions);
-    try {
-        await client.connect();
-        let db = null;
-        try { db = client.db(databaseName); } catch (_) { db = null; }
-        const ctx = buildLogContext({ type, databaseName, defaults, config });
-        // try { logger && logger.info && logger.info('✅ MongoDB connected', ctx); } catch (_) {}
-        return { client, db, sshTunnel };
-    } catch (err) {
-        // 连接失败，清理SSH隧道
-        if (sshTunnel) {
-            await sshTunnel.close();
-        }
-        const ctx = buildLogContext({ type, databaseName, defaults, config });
-        logger?.error?.('❌ MongoDB connection failed', ctx, err);
-        throw err;
-    }
-}
-
-/**
- * 关闭 MongoDB 连接
- * @param {import('mongodb').MongoClient} client
- * @param {any} logger
- * @param {boolean} [stopMemory=false] - 是否同时停止内存服务器
- * @param {any} [sshTunnel=null] - SSH隧道实例（如果使用）
- */
-async function closeMongo(client, logger, stopMemory = false, sshTunnel = null) {
-    if (!client) return;
-    try { await client.close(); } catch (e) { try { logger && logger.warn && logger.warn('MongoDB close error', e && (e.stack || e)); } catch (_) { } }
-
-    // 关闭SSH隧道
-    if (sshTunnel) {
-        try {
-            await sshTunnel.close();
-        } catch (e) {
-            logger?.warn?.('SSH tunnel close error', e);
-        }
-    }
-
-    // 如果指定停止内存服务器
-    if (stopMemory) {
-        await stopMemoryServer(logger);
-    }
-}
-
-module.exports = { connectMongo, closeMongo, stopMemoryServer };