monsqlize 1.0.0

package/lib/logger.js

@@ -0,0 +1,224 @@
+/**
+ * 默认日志记录器工具类
+ * 提供标准的日志记录功能，支持不同级别的日志输出
+ *
+ * v2.0 新增功能：
+ * - traceId 支持（用于分布式追踪）
+ * - 结构化日志输出（JSON 格式）
+ * - 上下文信息（数据库、集合、操作等）
+ */
+
+const crypto = require('crypto');
+
+/**
+ * 生成唯一的 traceId
+ * @returns {string} 16 字符的唯一 ID
+ */
+function generateTraceId() {
+    return crypto.randomBytes(8).toString('hex');
+}
+
+/**
+ * 异步本地存储（用于在异步调用链中传递 traceId）
+ */
+let AsyncLocalStorage;
+try {
+    AsyncLocalStorage = require('async_hooks').AsyncLocalStorage;
+} catch (e) {
+    // Node.js < 12.17.0 不支持 AsyncLocalStorage
+    AsyncLocalStorage = null;
+}
+
+const traceStorage = AsyncLocalStorage ? new AsyncLocalStorage() : null;
+
+module.exports = class Logger {
+
+    /**
+     * 创建日志记录器实例
+     * @param {Object} [customLogger] - 自定义日志记录器
+     * @param {Function} customLogger.debug - debug级别日志方法
+     * @param {Function} customLogger.info - info级别日志方法
+     * @param {Function} customLogger.warn - warn级别日志方法
+     * @param {Function} customLogger.error - error级别日志方法
+     * @param {Object} [options] - 日志选项
+     * @param {boolean} [options.structured=false] - 是否使用结构化日志（JSON）
+     * @param {boolean} [options.enableTraceId=false] - 是否启用 traceId
+     * @returns {Object} 日志记录器对象
+     */
+    static create(customLogger, options = {}) {
+        if (customLogger && this.isValidLogger(customLogger)) {
+            // 如果提供自定义 logger，包装它以支持新特性
+            return this.wrapLogger(customLogger, options);
+        }
+
+        return this.createDefaultLogger(options);
+    }
+
+    /**
+     * 验证自定义日志记录器是否有效
+     * @param {Object} logger - 待验证的日志记录器
+     * @returns {boolean} 是否为有效的日志记录器
+     */
+    static isValidLogger(logger) {
+        const requiredMethods = ['debug', 'info', 'warn', 'error'];
+        return requiredMethods.every(method =>
+            typeof logger[method] === 'function'
+        );
+    }
+
+    /**
+     * 包装自定义 logger 以支持新特性
+     * @param {Object} baseLogger - 基础 logger
+     * @param {Object} options - 选项
+     * @returns {Object} 包装后的 logger
+     */
+    static wrapLogger(baseLogger, options = {}) {
+        const { structured = false, enableTraceId = false } = options;
+
+        const wrap = (level) => (msg, ...args) => {
+            const logData = this._prepareLogData(level, msg, args, { structured, enableTraceId });
+
+            if (structured) {
+                baseLogger[level](JSON.stringify(logData));
+            } else {
+                const prefix = enableTraceId && logData.traceId ? `[${logData.traceId}] ` : '';
+                baseLogger[level](`${prefix}${msg}`, ...args);
+            }
+        };
+
+        return {
+            debug: wrap('debug'),
+            info: wrap('info'),
+            warn: wrap('warn'),
+            error: wrap('error'),
+            // 暴露 traceId 管理方法
+            withTraceId: enableTraceId ? this.withTraceId : undefined,
+            getTraceId: enableTraceId ? this.getTraceId : undefined,
+        };
+    }
+
+    /**
+     * 准备日志数据
+     * @private
+     */
+    static _prepareLogData(level, msg, args, options) {
+        const logData = {
+            timestamp: new Date().toISOString(),
+            level: level.toUpperCase(),
+            message: msg,
+        };
+
+        // 添加 traceId
+        if (options.enableTraceId) {
+            const traceId = this.getTraceId();
+            if (traceId) logData.traceId = traceId;
+        }
+
+        // 处理额外参数（上下文信息）
+        if (args.length > 0) {
+            const context = args[0];
+            if (context && typeof context === 'object') {
+                logData.context = context;
+            }
+        }
+
+        return logData;
+    }
+
+    /**
+     * 创建默认的控制台日志记录器
+     * @param {Object} [options] - 日志选项
+     * @returns {Object} 默认日志记录器对象
+     */
+    static createDefaultLogger(options = {}) {
+        const { structured = false, enableTraceId = false } = options;
+
+        const createLogFn = (level, consoleFn) => {
+            return (msg, ...args) => {
+                const logData = this._prepareLogData(level, msg, args, { structured, enableTraceId });
+
+                if (structured) {
+                    consoleFn(JSON.stringify(logData));
+                } else {
+                    const prefix = enableTraceId && logData.traceId ? `[${logData.traceId}] ` : '';
+                    consoleFn(`[${level.toUpperCase()}] ${prefix}${msg}`, ...args);
+                }
+            };
+        };
+
+        return {
+            debug: createLogFn('debug', console.debug),
+            info: createLogFn('info', console.log),
+            warn: createLogFn('warn', console.warn),
+            error: createLogFn('error', console.error),
+            // 暴露 traceId 管理方法
+            withTraceId: enableTraceId ? this.withTraceId.bind(this) : undefined,
+            getTraceId: enableTraceId ? this.getTraceId.bind(this) : undefined,
+        };
+    }
+
+    /**
+     * 创建带时间戳的日志记录器
+     * @param {Object} [customLogger] - 自定义日志记录器
+     * @returns {Object} 带时间戳的日志记录器
+     */
+    static createWithTimestamp(customLogger) {
+        const baseLogger = this.create(customLogger);
+        const getTimestamp = () => new Date().toISOString();
+
+        return {
+            debug: (msg, ...args) => baseLogger.debug(`${getTimestamp()} ${msg}`, ...args),
+            info: (msg, ...args) => baseLogger.info(`${getTimestamp()} ${msg}`, ...args),
+            warn: (msg, ...args) => baseLogger.warn(`${getTimestamp()} ${msg}`, ...args),
+            error: (msg, ...args) => baseLogger.error(`${getTimestamp()} ${msg}`, ...args)
+        };
+    }
+
+    /**
+     * 创建静默日志记录器（不输出任何内容）
+     * @returns {Object} 静默日志记录器
+     */
+    static createSilent() {
+        const noop = () => {};
+        return {
+            debug: noop,
+            info: noop,
+            warn: noop,
+            error: noop
+        };
+    }
+
+    /**
+     * 在指定的 traceId 上下文中运行函数
+     * @param {Function} fn - 要执行的函数
+     * @param {string} [traceId] - 可选的 traceId，不提供则自动生成
+     * @returns {*} 函数执行结果
+     */
+    static withTraceId(fn, traceId = null) {
+        if (!traceStorage) {
+            // 不支持 AsyncLocalStorage，直接执行
+            return fn();
+        }
+
+        const id = traceId || generateTraceId();
+        return traceStorage.run(id, fn);
+    }
+
+    /**
+     * 获取当前上下文的 traceId
+     * @returns {string|null} traceId 或 null
+     */
+    static getTraceId() {
+        if (!traceStorage) return null;
+        return traceStorage.getStore() || null;
+    }
+
+    /**
+     * 生成新的 traceId
+     * @returns {string} 新的 traceId
+     */
+    static generateTraceId() {
+        return generateTraceId();
+    }
+}
+

package/lib/model/examples/test.js

@@ -0,0 +1,114 @@
+
+
+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

@@ -0,0 +1,44 @@
+// 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');
+
+/**
+ * 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，避免键过长与不稳定。
+ * @param {string} op
+ * @param {object} options
+ * @returns {object} 用于参与缓存键构造的 options 视图
+ */
+function mongoKeyBuilder(op, options) {
+    const opts = options || {};
+    if (op !== 'findPage') return opts;
+    const pipelineHash = crypto
+        .createHash('sha256')
+        .update(CacheFactory.stableStringify(opts.pipeline || []))
+        .digest('hex');
+    const { pipeline, ...rest } = opts;
+    return { ...rest, pipelineHash };
+}
+
+module.exports = { mongoSlowLogShaper, mongoKeyBuilder };

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

@@ -0,0 +1,32 @@
+/**
+ * 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

@@ -0,0 +1,27 @@
+/**
+ * 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

@@ -0,0 +1,52 @@
+/**
+ * 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

@@ -0,0 +1,31 @@
+/**
+ * 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

@@ -0,0 +1,38 @@
+/**
+ * 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

@@ -0,0 +1,24 @@
+/**
+ * 检查操作是否在事务中执行
+ * @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
+};
+