@cloudcome/utils-uni 1.31.0 → 1.32.0

package/dist/database.cjs

@@ -1,637 +1,704 @@
-"use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const type = require("@cloudcome/utils-core/type");
-const _helpers = require("./_helpers.cjs");
-const error = require("./error.cjs");
-const object = require("@cloudcome/utils-core/object");
-const _try = require("@cloudcome/utils-core/try");
-class DbBaseCommand {
-  constructor(_command, _parameter, _options) {
-    this._command = _command;
-    this._parameter = _parameter;
-    this._options = _options;
-  }
-  _isQuery = false;
-  _isMutate = false;
-  static getValue(cmd, db) {
-    if (cmd._options?.rewriteValue) {
-      return cmd._options.rewriteValue(db, cmd._parameter);
-    }
-    return db.command[cmd._command].call(
-      db.command,
-      cmd._options?.formatParameter?.(db) || cmd._parameter
-    );
-  }
-  static getExpression(cmd, fieldName) {
-    return {
-      [`$${cmd._command}`]: [fieldName, cmd._parameter]
-    };
-  }
-  static isQueryCommand(cmd) {
-    return cmd._isQuery;
-  }
-  static isMutateCommand(cmd) {
-    return cmd._isMutate;
-  }
-}
-class DbQueryCommand extends DbBaseCommand {
-  _isQuery = true;
-}
-class DbMutateCommand extends DbBaseCommand {
-  _isMutate = true;
-}
-const dbQuery = {
-  /**
-   * 等于操作符
-   * @param value 比较值
-   * @returns DbQueryCommand 查询命令对象
-   */
-  eq: (value) => new DbQueryCommand("eq", value),
-  /**
-   * 不等于操作符
-   * @param value 比较值
-   * @returns DbQueryCommand 查询命令对象
-   */
-  neq: (value) => new DbQueryCommand("neq", value),
-  /**
-   * 大于操作符
-   * @param value 比较值
-   * @returns DbQueryCommand 查询命令对象
-   */
-  gt: (value) => new DbQueryCommand("gt", value),
-  /**
-   * 大于等于操作符
-   * @param value 比较值
-   * @returns DbQueryCommand 查询命令对象
-   */
-  gte: (value) => new DbQueryCommand("gte", value),
-  /**
-   * 小于操作符
-   * @param value 比较值
-   * @returns DbQueryCommand 查询命令对象
-   */
-  lt: (value) => new DbQueryCommand("lt", value),
-  /**
-   * 小于等于操作符
-   * @param value 比较值
-   * @returns DbQueryCommand 查询命令对象
-   */
-  lte: (value) => new DbQueryCommand("lte", value),
-  /**
-   * 包含在数组中操作符
-   * @param value 值数组
-   * @returns DbQueryCommand 查询命令对象
-   */
-  in: (value) => new DbQueryCommand("in", value),
-  /**
-   * 不包含在数组中操作符
-   * @param value 值数组
-   * @returns DbQueryCommand 查询命令对象
-   */
-  nin: (value) => new DbQueryCommand("nin", value),
-  /**
-   * 数组长度匹配操作符
-   * @param size 数组长度
-   * @returns DbQueryCommand 查询命令对象
-   */
-  size: (size) => new DbQueryCommand("size", size),
-  /**
-   * 正则表达式匹配操作符
-   * @param regExp 正则表达式
-   * @returns DbQueryCommand 查询命令对象
-   */
-  regExp: (regExp) => new DbQueryCommand("regExp", regExp, {
-    rewriteValue: (db, parameter) => parameter
-  }),
-  /**
-   * 逻辑与操作符
-   * @param conditions 查询条件参数
-   * @returns DbQueryCommand 查询命令对象
-   */
-  and: (conditions) => new DbQueryCommand("and", conditions, {
-    formatParameter: (db) => conditions.map((c) => DbBaseCommand.getValue(c, db))
-  }),
-  /**
-   * 逻辑或操作符
-   * @param conditions 查询条件参数
-   * @returns DbQueryCommand 查询命令对象
-   */
-  or: (conditions) => new DbQueryCommand("or", conditions, {
-    formatParameter: (db) => conditions.map((c) => DbBaseCommand.getValue(c, db))
-  })
+const require__helpers = require("./_helpers.cjs");
+const require_cloud = require("./cloud.cjs");
+let _cloudcome_utils_core_type = require("@cloudcome/utils-core/type");
+let _cloudcome_utils_core_object = require("@cloudcome/utils-core/object");
+let _cloudcome_utils_core_try = require("@cloudcome/utils-core/try");
+//#region src/database/_command.class.ts
+var DbBaseCommand = class {
+	_isQuery = false;
+	_isMutate = false;
+	constructor(_command, _parameter, _options) {
+		this._command = _command;
+		this._parameter = _parameter;
+		this._options = _options;
+	}
+	static getValue(cmd, db) {
+		if (cmd._options?.rewriteValue) return cmd._options.rewriteValue(db, cmd._parameter);
+		return db.command[cmd._command].call(db.command, cmd._options?.formatParameter?.(db) || cmd._parameter);
+	}
+	static getExpression(cmd, fieldName) {
+		return { [`$${cmd._command}`]: [fieldName, cmd._parameter] };
+	}
+	static isQueryCommand(cmd) {
+		return cmd._isQuery;
+	}
+	static isMutateCommand(cmd) {
+		return cmd._isMutate;
+	}
+};
+var DbQueryCommand = class extends DbBaseCommand {
+	_isQuery = true;
 };
-const dbMutate = {
-  /**
-   * 数值增加操作符
-   * @param value 增加的数值
-   * @returns DbMutateCommand 变更命令对象
-   */
-  inc: (value) => new DbMutateCommand("inc", value),
-  /**
-   * 数值乘法操作符
-   * @param value 乘数
-   * @returns DbMutateCommand 变更命令对象
-   */
-  mul: (value) => new DbMutateCommand("mul", value),
-  /**
-   * 设置字段值操作符
-   * @param value 设置的值
-   * @returns DbMutateCommand 变更命令对象
-   */
-  set: (value) => new DbMutateCommand("set", value),
-  /**
-   * 向数组末尾添加元素操作符
-   * @param value 添加的值
-   * @returns DbMutateCommand 变更命令对象
-   */
-  push: (value) => new DbMutateCommand("push", value),
-  /**
-   * 向数组开头添加元素操作符
-   * @param value 添加的值
-   * @returns DbMutateCommand 变更命令对象
-   */
-  unshift: (value) => new DbMutateCommand("unshift", value),
-  /**
-   * 从数组末尾移除元素操作符
-   * @returns DbMutateCommand 变更命令对象
-   */
-  pop: () => new DbMutateCommand("pop", void 0),
-  /**
-   * 从数组开头移除元素操作符
-   * @returns DbMutateCommand 变更命令对象
-   */
-  shift: () => new DbMutateCommand("shift", void 0),
-  /**
-   * 移除字段操作符
-   * @returns DbMutateCommand 变更命令对象
-   */
-  remove: () => new DbMutateCommand("remove", void 0)
+var DbMutateCommand = class extends DbBaseCommand {
+	_isMutate = true;
 };
-const dbAgg = uniCloud.database().command.aggregate;
-const db0 = uniCloud.database();
-let gid = 0;
-class Db {
-  _host;
-  /**
-   * 是否为事务环境
-   * - 查询条件只能是 id
-   * - 不能聚合操作
-   */
-  _isTransaction = false;
-  _options;
-  /**
-   * 构造函数，初始化数据库集合引用
-   * @param collection 数据表名称
-   * @param _mockDatabase 模拟数据库，用于单元测试
-   */
-  constructor(options) {
-    this._options = options;
-    this._host = options._mockDatabase || options.transaction?.collection(options.table) || db0.collection(options.table);
-    this._isTransaction = !!options.transaction;
-  }
-  /**
-   * 创建一个新的数据库实例，可选是否移除事务
-   * @param withoutTransaction 是否移除事务，默认 false
-   * @returns 新的数据库实例
-   */
-  clone(withoutTransaction) {
-    return new Db({ ...this._options, transaction: withoutTransaction ? null : this._options.transaction });
-  }
-  get table() {
-    return this._options.table;
-  }
-  get options() {
-    return this._options;
-  }
-  get isTransaction() {
-    return this._isTransaction;
-  }
-  /**
-   * 获取聚合操作实例
-   * @returns 聚合操作实例
-   */
-  aggregate() {
-    return this._host.aggregate();
-  }
-  _hasWhere = void 0;
-  _hasWhereId = void 0;
-  _where = {};
-  _doWhere(where, from) {
-    if (this._hasWhere) throw new Error(`已调用过一次 db.${_toWhereMethod(this._hasWhere)} 了`);
-    const realWhere = object.objectFilter(where, (value) => value !== void 0);
-    const whereKeys = Object.keys(realWhere);
-    const isWhereId = whereKeys.length === 1 && "_id" in realWhere && (type.isString(realWhere._id) || type.isNumber(realWhere._id));
-    if (isWhereId && this._hasLimit) {
-      throw new Error(`db.${_toWhereIdMethod(from)} 方法不能与 db.limit() 方法同时调用`);
-    }
-    this._hasWhere = from;
-    this._where = realWhere;
-    if (isWhereId) this._hasWhereId = from;
-    return this;
-  }
-  /**
-   * 设置查询条件
-   * @param where 查询条件对象
-   * @returns 当前Db实例，支持链式调用
-   */
-  where(where) {
-    return this._doWhere(where, "where");
-  }
-  /**
-   * 获取当前查询条件
-   * @param plain 是否返回原始查询条件对象，默认 false
-   * @returns 当前查询条件对象
-   */
-  getWhere(plain) {
-    return plain ? object.objectOmit(this._where, Object.keys(this._lookupAs)) : this._where;
-  }
-  /**
-   * 根据ID设置查询条件
-   * @param id 记录ID
-   * @returns 当前Db实例，支持链式调用
-   */
-  whereId(id) {
-    return this._doWhere({ _id: id }, "whereId");
-  }
-  _hasSelect = 0;
-  _select = {};
-  /**
-   * 指定要返回的字段
-   * @param fields 要返回的字段对象，true表示返回，false表示不返回
-   * @returns 当前Db实例，支持链式调用
-   */
-  select(fields) {
-    if (this._hasSelect) throw new Error("db.select() 方法只能调用一次");
-    this._hasSelect++;
-    this._select = fields;
-    return this;
-  }
-  _hasOrder = 0;
-  _order = {};
-  /**
-   * 设置排序规则
-   * @param order 排序规则对象，key为字段名，value为"asc"或"desc"
-   * @returns 当前Db实例，支持链式调用
-   */
-  order(order) {
-    this._hasOrder++;
-    this._order = order;
-    return this;
-  }
-  _hasSkip = 0;
-  _skip = 0;
-  /**
-   * 跳过指定数量的记录
-   * @param skip 要跳过的记录数
-   * @returns 当前Db实例，支持链式调用
-   */
-  skip(skip) {
-    if (this._hasSkip) throw new Error("db.skip() 方法只能调用一次");
-    this._hasSkip++;
-    this._skip = skip;
-    return this;
-  }
-  _hasLimit = 0;
-  _limit = 0;
-  /**
-   * 限制返回的记录数量
-   * @param limit 最大返回记录数
-   * @returns 当前Db实例，支持链式调用
-   */
-  limit(limit) {
-    if (this._hasLimit) throw new Error("db.limit() 方法只能调用一次");
-    if (this._hasWhereId) {
-      throw new Error(`db.limit() 方法不能与 ${_toWhereIdMethod(this._hasWhereId)} 方法同时调用`);
-    }
-    this._hasLimit++;
-    this._limit = limit;
-    return this;
-  }
-  _hasLookup = 0;
-  get hasLookup() {
-    return this._hasLookup > 0;
-  }
-  _lookups = [];
-  lookup(table, lookup) {
-    table._hasLookup++;
-    this._hasLookup++;
-    this._lookups.push({
-      ...lookup,
-      table
-    });
-    return this;
-  }
-  _aggregated = false;
-  _lookupAs = {};
-  _endAggregate(aggRef) {
-    if (this._aggregated) throw new Error(`相同的数据表实例(${this.table})不能重复使用`);
-    this._aggregated = true;
-    let returnAggRef = aggRef;
-    const aggSelect = {};
-    let hasAggUnselect = 0;
-    const aggUnselect = {};
-    for (const { relation: type2, as, foreignField, localField, table, unselect } of this._lookups) {
-      const letName = `let${gid++}`;
-      let pipeline = dbAgg.pipeline();
-      pipeline = pipeline.match({
-        $expr: {
-          $and: [
-            type2 === "n:1" ? { $in: [`$${foreignField}`, `$$${letName}`] } : { $eq: [`$${foreignField}`, `$$${letName}`] }
-          ]
-        }
-      });
-      pipeline = table._endAggregate(pipeline);
-      pipeline = pipeline.done();
-      returnAggRef = returnAggRef.lookup({
-        let: {
-          [letName]: `$${localField}`
-        },
-        as,
-        from: table.table,
-        pipeline
-      });
-      if (type2 === "1:1") {
-        returnAggRef = returnAggRef.unwind({
-          path: `$${as}`,
-          preserveNullAndEmptyArrays: true
-        });
-      }
-      if (unselect) {
-        hasAggUnselect++;
-        aggUnselect[as] = false;
-      } else {
-        aggSelect[as] = true;
-      }
-      this._lookupAs[as] = true;
-    }
-    if (this._hasWhere) returnAggRef = returnAggRef.match(_mapCommandRaw(this._where));
-    if (this._hasOrder) returnAggRef = returnAggRef.sort(object.objectMap(this._order, (v) => v === "asc" ? 1 : -1));
-    if (this._hasSkip) returnAggRef = returnAggRef.skip(this._skip);
-    if (this._hasLimit) returnAggRef = returnAggRef.limit(this._limit);
-    if (this._hasSelect) {
-      returnAggRef = returnAggRef.project(_mergeSelect({ ...this._select, ...aggSelect }, this._order));
-    } else if (hasAggUnselect) {
-      returnAggRef = returnAggRef.project(aggUnselect);
-    }
-    return returnAggRef;
-  }
-  _endHost(action) {
-    if (this._hasWhere) {
-      if ((action === "update" || action === "remove") && this._isTransaction) {
-        this._host = this._host.doc(this._where._id);
-      } else {
-        this._host = this._host.where(_mapCommandRaw(this._where));
-      }
-    }
-    if (this._hasSelect) {
-      this._host = this._host.field(_mergeSelect(this._select, this._order));
-    }
-    if (this._hasOrder) {
-      object.objectEach(this._order, (val, key) => {
-        this._host = this._host.orderBy(key, val);
-      });
-    }
-    if (this._hasSkip) this._host = this._host.skip(this._skip);
-    if (this._hasLimit && action === "query") this._host = this._host.limit(this._limit);
-    else if (this._hasWhereId && action === "query") this._host = this._host.limit(1);
-  }
-  /**
-   * 执行查询操作
-   * @returns 查询结果
-   */
-  async many() {
-    try {
-      if (this._isTransaction) throw new Error("db.many() 方法不支持事务模式");
-      let res;
-      if (this._hasLookup) {
-        const aggRef = this.aggregate();
-        this._endAggregate(aggRef);
-        res = await aggRef.end();
-      } else {
-        this._endHost("query");
-        res = await this._host.get();
-      }
-      const { data } = _helpers.parseDatabaseOutput(res);
-      return data;
-    } catch (err) {
-      const dbErr = err;
-      throw this._options.parseError?.(dbErr) || dbErr;
-    }
-  }
-  /**
-   * 只查询一条，自动添加 limit(1) 条件
-   * 如果没有匹配到记录，会抛出错误
-   * @returns 查询结果
-   */
-  async firstOrThrow() {
-    if (this._isTransaction) throw new Error("db.firstOrThrow() 方法不支持事务模式");
-    if (this._hasLimit) throw new Error("db.firstOrThrow() 方法不支持 limit 条件");
-    if (!this._hasWhereId) this.limit(1);
-    const data = await this.many();
-    const res = data.at(0);
-    if (!res) throw error.createCloudObjectError("查询数据为空", "firstOrThrow");
-    return res;
-  }
-  /**
-   * 只查询一条，自动添加 limit(1) 条件
-   * 如果没有匹配到记录，返回 null
-   * @returns 查询结果或 null
-   */
-  async firstOrNull() {
-    if (this._isTransaction) throw new Error("db.firstOrNull() 方法不支持事务模式");
-    if (this._hasLimit) throw new Error("db.firstOrNull() 方法不支持 limit 条件");
-    if (!this._hasWhereId) this.limit(1);
-    const data = await this.many();
-    return data.at(0) || null;
-  }
-  /**
-   * 获取匹配记录的数量
-   * @returns 记录总数
-   */
-  async count() {
-    if (this._isTransaction) throw new Error("db.count() 方法不支持事务模式");
-    if (this._hasLookup) throw new Error("db.count() 方法不支持 lookup 聚合");
-    if (this._hasSelect) throw new Error("db.count() 方法不支持 select 条件");
-    if (this._hasOrder) throw new Error("db.count() 方法不支持 order 条件");
-    if (this._hasSkip) throw new Error("db.count() 方法不支持 skip 条件");
-    if (this._hasLimit) throw new Error("db.count() 方法不支持 limit 条件");
-    try {
-      this._endHost("count");
-      const res = await this._host.count();
-      const { total } = _helpers.parseDatabaseOutput(res);
-      return total;
-    } catch (err) {
-      const dbErr = err;
-      throw this._options.parseError?.(dbErr) || dbErr;
-    }
-  }
-  /**
-   * 创建新记录
-   * @param data 要创建的数据
-   * @returns 创建结果
-   */
-  async create(data) {
-    if (this._hasLookup) throw new Error("db.create() 方法不支持 lookup 聚合");
-    if (this._hasWhere) throw new Error("db.create() 方法不支持 where 条件");
-    if (this._hasSelect) throw new Error("db.create() 方法不支持 select 条件");
-    if (this._hasOrder) throw new Error("db.create() 方法不支持 order 条件");
-    if (this._hasSkip) throw new Error("db.create() 方法不支持 skip 条件");
-    if (this._hasLimit) throw new Error("db.create() 方法不支持 limit 条件");
-    try {
-      this._endHost("create");
-      const res = await this._host.add(data);
-      const { id } = _helpers.parseDatabaseOutput(res);
-      return id;
-    } catch (err) {
-      const dbErr = err;
-      throw this._options.parseError?.(dbErr) || dbErr;
-    }
-  }
-  /**
-   * 更新记录
-   * @param data 要更新的数据
-   * @returns 更新结果
-   */
-  async update(data) {
-    if (this._hasLookup) throw new Error("db.update() 方法不支持 lookup 聚合");
-    if (!this._hasWhere) throw new Error("设置 where 条件后才能执行 db.update() 方法");
-    if (this._hasSelect) throw new Error("db.update() 方法不支持 select 条件");
-    if (this._hasOrder) throw new Error("db.update() 方法不支持 order 条件");
-    if (this._hasSkip) throw new Error("db.update() 方法不支持 skip 条件");
-    if (this._hasLimit) throw new Error("db.update() 方法不支持 limit 条件");
-    if (this._isTransaction && !this._hasWhereId) throw new Error("事务模式下 db.update() 的 where 条件必须是 _id");
-    try {
-      this._endHost("update");
-      const res = await this._host.update(object.objectOmit(_mapCommandRaw(data), ["_id"]));
-      const { updated } = _helpers.parseDatabaseOutput(res);
-      return updated;
-    } catch (err) {
-      const dbErr = err;
-      throw this._options.parseError?.(dbErr) || dbErr;
-    }
-  }
-  /**
-   * 删除记录
-   * @returns 删除结果
-   */
-  async remove() {
-    if (this._hasLookup) throw new Error("db.remove() 方法不支持 lookup 聚合");
-    if (!this._hasWhere) throw new Error("设置 where 条件后才能执行 db.remove() 方法");
-    if (this._hasSelect) throw new Error("db.remove() 方法不支持 select 条件");
-    if (this._hasOrder) throw new Error("db.remove() 方法不支持 order 条件");
-    if (this._hasSkip) throw new Error("db.remove() 方法不支持 skip 条件");
-    if (this._hasLimit) throw new Error("db.remove() 方法不支持 limit 条件");
-    if (this._isTransaction && !this._hasWhereId) throw new Error("事务模式下 db.remove() 的 where 条件必须是 _id");
-    try {
-      this._endHost("remove");
-      const res = await this._host.remove();
-      const { deleted } = _helpers.parseDatabaseOutput(res);
-      return deleted;
-    } catch (err) {
-      const dbErr = err;
-      throw this._options.parseError?.(dbErr) || dbErr;
-    }
-  }
+//#endregion
+//#region src/database/command.ts
+/**
+* 数据库查询命令对象，提供各种查询操作符
+*/
+var dbQuery = {
+	/**
+	* 等于操作符
+	* @param value 比较值
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	eq: (value) => new DbQueryCommand("eq", value),
+	/**
+	* 不等于操作符
+	* @param value 比较值
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	neq: (value) => new DbQueryCommand("neq", value),
+	/**
+	* 大于操作符
+	* @param value 比较值
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	gt: (value) => new DbQueryCommand("gt", value),
+	/**
+	* 大于等于操作符
+	* @param value 比较值
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	gte: (value) => new DbQueryCommand("gte", value),
+	/**
+	* 小于操作符
+	* @param value 比较值
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	lt: (value) => new DbQueryCommand("lt", value),
+	/**
+	* 小于等于操作符
+	* @param value 比较值
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	lte: (value) => new DbQueryCommand("lte", value),
+	/**
+	* 包含在数组中操作符
+	* @param value 值数组
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	in: (value) => new DbQueryCommand("in", value),
+	/**
+	* 不包含在数组中操作符
+	* @param value 值数组
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	nin: (value) => new DbQueryCommand("nin", value),
+	/**
+	* 数组长度匹配操作符
+	* @param size 数组长度
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	size: (size) => new DbQueryCommand("size", size),
+	/**
+	* 正则表达式匹配操作符
+	* @param regExp 正则表达式
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	regExp: (regExp) => new DbQueryCommand("regExp", regExp, { rewriteValue: (_db, parameter) => parameter }),
+	/**
+	* 逻辑与操作符
+	* @param conditions 查询条件参数
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	and: (conditions) => new DbQueryCommand("and", conditions, { formatParameter: (db) => conditions.map((c) => DbBaseCommand.getValue(c, db)) }),
+	/**
+	* 逻辑或操作符
+	* @param conditions 查询条件参数
+	* @returns DbQueryCommand 查询命令对象
+	*/
+	or: (conditions) => new DbQueryCommand("or", conditions, { formatParameter: (db) => conditions.map((c) => DbBaseCommand.getValue(c, db)) })
+};
+/**
+* 数据库变更命令对象，提供各种数据更新操作符
+*/
+var dbMutate = {
+	/**
+	* 数值增加操作符
+	* @param value 增加的数值
+	* @returns DbMutateCommand 变更命令对象
+	*/
+	inc: (value) => new DbMutateCommand("inc", value),
+	/**
+	* 数值乘法操作符
+	* @param value 乘数
+	* @returns DbMutateCommand 变更命令对象
+	*/
+	mul: (value) => new DbMutateCommand("mul", value),
+	/**
+	* 设置字段值操作符
+	* @param value 设置的值
+	* @returns DbMutateCommand 变更命令对象
+	*/
+	set: (value) => new DbMutateCommand("set", value),
+	/**
+	* 向数组末尾添加元素操作符
+	* @param value 添加的值
+	* @returns DbMutateCommand 变更命令对象
+	*/
+	push: (value) => new DbMutateCommand("push", value),
+	/**
+	* 向数组开头添加元素操作符
+	* @param value 添加的值
+	* @returns DbMutateCommand 变更命令对象
+	*/
+	unshift: (value) => new DbMutateCommand("unshift", value),
+	/**
+	* 从数组末尾移除元素操作符
+	* @returns DbMutateCommand 变更命令对象
+	*/
+	pop: () => new DbMutateCommand("pop", void 0),
+	/**
+	* 从数组开头移除元素操作符
+	* @returns DbMutateCommand 变更命令对象
+	*/
+	shift: () => new DbMutateCommand("shift", void 0),
+	/**
+	* 移除字段操作符
+	* @returns DbMutateCommand 变更命令对象
+	*/
+	remove: () => new DbMutateCommand("remove", void 0)
+};
+//#endregion
+//#region src/database/each.ts
+/**
+* 遍历表中的每一行数据并执行回调函数
+*
+* 采用分批查询策略，每批查询 100 条记录，通过 skip/limit 实现分页遍历，
+* 避免一次性加载大量数据导致内存溢出。
+*
+* 迭代器按顺序串行执行，即每一行数据的迭代器完成后才会处理下一行。
+*
+* @template T - 数据行类型
+* @param table 数据库表代理对象
+* @param where 查询条件
+* @param iterator 对每一行数据执行的异步迭代器函数
+* @param maxCount 最大遍历数量，默认值为 Number.MAX_SAFE_INTEGER。
+*   注意：由于分批查询机制（每批 100 条），实际遍历的行数可能略大于 maxCount，
+*   例如 maxCount=150 时，会分两批查询（0-99、100-199），实际遍历 200 行。
+* @example
+* ```ts
+* // 遍历所有状态为 active 的用户
+* await dbEach(userTable, { status: 'active' }, async (user) => {
+*   await sendEmail(user.email);
+* });
+*
+* // 限制最多遍历 500 条记录
+* await dbEach(orderTable, { status: 'pending' }, async (order) => {
+*   await processOrder(order);
+* }, 500);
+* ```
+*/
+async function dbEach(table, where, iterator, maxCount = Number.MAX_SAFE_INTEGER) {
+	const count = Math.min(await table.where(where).count(), maxCount);
+	const limit = 100;
+	for (let skip = 0; skip < count; skip += limit) {
+		const rows = await table.where(where).limit(limit).skip(skip).many();
+		for (const row of rows) await iterator(row);
+	}
+}
+//#endregion
+//#region src/database/paging.ts
+/**
+* 数据库分页查询函数
+* @template T - 数据类型
+* @param queryDb - 数据库查询实例
+* @returns 包含数据列表和总数的对象
+*/
+async function dbPaging(queryDb) {
+	const where = queryDb.getWhere(true);
+	const countDb = queryDb.clone();
+	return {
+		list: await queryDb.many(),
+		total: await countDb.where(where).count()
+	};
 }
+//#endregion
+//#region src/database/_db.class.ts
+/**
+* 数据库聚合操作符命令
+*/
+var dbAgg = uniCloud.database().command.aggregate;
+var db0 = uniCloud.database();
+var gid = 0;
+/**
+* 数据库类
+* @template D1 - 主表数据
+* @template S1 - 主表筛选
+* @template D2 - 副表数据
+* @template W2 - 副表查询
+*/
+var Db = class Db {
+	_host;
+	/**
+	* 是否为事务环境
+	* - 查询条件只能是 id
+	* - 不能聚合操作
+	*/
+	_isTransaction = false;
+	_options;
+	/**
+	* 构造函数，初始化数据库集合引用
+	* @param collection 数据表名称
+	* @param _mockDatabase 模拟数据库，用于单元测试
+	*/
+	constructor(options) {
+		this._options = options;
+		this._host = options._mockDatabase || options.transaction?.collection(options.table) || db0.collection(options.table);
+		this._isTransaction = !!options.transaction;
+	}
+	/**
+	* 创建一个新的数据库实例，可选是否移除事务
+	* @param withoutTransaction 是否移除事务，默认 false
+	* @returns 新的数据库实例
+	*/
+	clone(withoutTransaction) {
+		return new Db({
+			...this._options,
+			transaction: withoutTransaction ? null : this._options.transaction
+		});
+	}
+	get table() {
+		return this._options.table;
+	}
+	get options() {
+		return this._options;
+	}
+	get isTransaction() {
+		return this._isTransaction;
+	}
+	/**
+	* 获取聚合操作实例
+	* @returns 聚合操作实例
+	*/
+	aggregate() {
+		return this._host.aggregate();
+	}
+	_hasWhere = void 0;
+	_hasWhereId = void 0;
+	_where = {};
+	_doWhere(where, from) {
+		if (this._hasWhere) throw new Error(`已调用过一次 db.${_toWhereMethod(this._hasWhere)} 了`);
+		const realWhere = (0, _cloudcome_utils_core_object.objectFilter)(where, (value) => value !== void 0);
+		const isWhereId = Object.keys(realWhere).length === 1 && "_id" in realWhere && ((0, _cloudcome_utils_core_type.isString)(realWhere._id) || (0, _cloudcome_utils_core_type.isNumber)(realWhere._id));
+		if (isWhereId && this._hasLimit) throw new Error(`db.${_toWhereIdMethod(from)} 方法不能与 db.limit() 方法同时调用`);
+		this._hasWhere = from;
+		this._where = realWhere;
+		if (isWhereId) this._hasWhereId = from;
+		return this;
+	}
+	/**
+	* 设置查询条件
+	* @param where 查询条件对象
+	* @returns 当前Db实例，支持链式调用
+	*/
+	where(where) {
+		return this._doWhere(where, "where");
+	}
+	/**
+	* 获取当前查询条件
+	* @param plain 是否返回原始查询条件对象，默认 false
+	* @returns 当前查询条件对象
+	*/
+	getWhere(plain) {
+		return plain ? (0, _cloudcome_utils_core_object.objectOmit)(this._where, Object.keys(this._lookupAs)) : this._where;
+	}
+	/**
+	* 根据ID设置查询条件
+	* @param id 记录ID
+	* @returns 当前Db实例，支持链式调用
+	*/
+	whereId(id) {
+		return this._doWhere({ _id: id }, "whereId");
+	}
+	_hasSelect = 0;
+	_select = {};
+	/**
+	* 指定要返回的字段
+	* @param fields 要返回的字段对象，true表示返回，false表示不返回
+	* @returns 当前Db实例，支持链式调用
+	*/
+	select(fields) {
+		if (this._hasSelect) throw new Error("db.select() 方法只能调用一次");
+		this._hasSelect++;
+		this._select = fields;
+		return this;
+	}
+	_hasOrder = 0;
+	_order = {};
+	/**
+	* 设置排序规则
+	* @param order 排序规则对象，key为字段名，value为"asc"或"desc"
+	* @returns 当前Db实例，支持链式调用
+	*/
+	order(order) {
+		this._hasOrder++;
+		this._order = order;
+		return this;
+	}
+	_hasSkip = 0;
+	_skip = 0;
+	/**
+	* 跳过指定数量的记录
+	* @param skip 要跳过的记录数
+	* @returns 当前Db实例，支持链式调用
+	*/
+	skip(skip) {
+		if (this._hasSkip) throw new Error("db.skip() 方法只能调用一次");
+		this._hasSkip++;
+		this._skip = skip;
+		return this;
+	}
+	_hasLimit = 0;
+	_limit = 0;
+	/**
+	* 限制返回的记录数量
+	* @param limit 最大返回记录数
+	* @returns 当前Db实例，支持链式调用
+	*/
+	limit(limit) {
+		if (this._hasLimit) throw new Error("db.limit() 方法只能调用一次");
+		if (this._hasWhereId) throw new Error(`db.limit() 方法不能与 ${_toWhereIdMethod(this._hasWhereId)} 方法同时调用`);
+		this._hasLimit++;
+		this._limit = limit;
+		return this;
+	}
+	_hasLookup = 0;
+	get hasLookup() {
+		return this._hasLookup > 0;
+	}
+	_lookups = [];
+	lookup(table, lookup) {
+		table._hasLookup++;
+		this._hasLookup++;
+		this._lookups.push({
+			...lookup,
+			table
+		});
+		return this;
+	}
+	_aggregated = false;
+	_lookupAs = {};
+	_endAggregate(aggRef) {
+		if (this._aggregated) throw new Error(`相同的数据表实例(${this.table})不能重复使用`);
+		this._aggregated = true;
+		let returnAggRef = aggRef;
+		let _hasAggSelect = 0;
+		const aggSelect = {};
+		let hasAggUnselect = 0;
+		const aggUnselect = {};
+		for (const { relation: type, as, foreignField, localField, table, unselect } of this._lookups) {
+			const letName = `let${gid++}`;
+			let pipeline = dbAgg.pipeline();
+			pipeline = pipeline.match({ $expr: { $and: [type === "n:1" ? { $in: [`$${foreignField}`, `$$${letName}`] } : { $eq: [`$${foreignField}`, `$$${letName}`] }] } });
+			pipeline = table._endAggregate(pipeline);
+			pipeline = pipeline.done();
+			returnAggRef = returnAggRef.lookup({
+				let: { [letName]: `$${localField}` },
+				as,
+				from: table.table,
+				pipeline
+			});
+			if (type === "1:1") returnAggRef = returnAggRef.unwind({
+				path: `$${as}`,
+				preserveNullAndEmptyArrays: true
+			});
+			if (unselect) {
+				hasAggUnselect++;
+				aggUnselect[as] = false;
+			} else {
+				_hasAggSelect++;
+				aggSelect[as] = true;
+			}
+			this._lookupAs[as] = true;
+		}
+		if (this._hasWhere) returnAggRef = returnAggRef.match(_mapCommandRaw(this._where));
+		if (this._hasOrder) returnAggRef = returnAggRef.sort((0, _cloudcome_utils_core_object.objectMap)(this._order, (v) => v === "asc" ? 1 : -1));
+		if (this._hasSkip) returnAggRef = returnAggRef.skip(this._skip);
+		if (this._hasLimit) returnAggRef = returnAggRef.limit(this._limit);
+		if (this._hasSelect) returnAggRef = returnAggRef.project(_mergeSelect({
+			...this._select,
+			...aggSelect
+		}, this._order));
+		else if (hasAggUnselect) returnAggRef = returnAggRef.project(aggUnselect);
+		return returnAggRef;
+	}
+	_endHost(action) {
+		if (this._hasWhere) if ((action === "update" || action === "remove") && this._isTransaction) this._host = this._host.doc(this._where._id);
+		else this._host = this._host.where(_mapCommandRaw(this._where));
+		if (this._hasSelect) this._host = this._host.field(_mergeSelect(this._select, this._order));
+		if (this._hasOrder) (0, _cloudcome_utils_core_object.objectEach)(this._order, (val, key) => {
+			this._host = this._host.orderBy(key, val);
+		});
+		if (this._hasSkip) this._host = this._host.skip(this._skip);
+		if (this._hasLimit && action === "query") this._host = this._host.limit(this._limit);
+		else if (this._hasWhereId && action === "query") this._host = this._host.limit(1);
+	}
+	/**
+	* 执行查询操作
+	* @returns 查询结果
+	*/
+	async many() {
+		try {
+			if (this._isTransaction) throw new Error("db.many() 方法不支持事务模式");
+			let res;
+			if (this._hasLookup) {
+				const aggRef = this.aggregate();
+				this._endAggregate(aggRef);
+				res = await aggRef.end();
+			} else {
+				this._endHost("query");
+				res = await this._host.get();
+			}
+			const { data } = require__helpers.parseDatabaseOutput(res);
+			return data;
+		} catch (err) {
+			const dbErr = err;
+			throw this._options.parseError?.(dbErr) || dbErr;
+		}
+	}
+	/**
+	* 只查询一条，自动添加 limit(1) 条件
+	* 如果没有匹配到记录，会抛出错误
+	* @returns 查询结果
+	*/
+	async firstOrThrow() {
+		if (this._isTransaction) throw new Error("db.firstOrThrow() 方法不支持事务模式");
+		if (this._hasLimit) throw new Error("db.firstOrThrow() 方法不支持 limit 条件");
+		if (!this._hasWhereId) this.limit(1);
+		const res = (await this.many()).at(0);
+		if (!res) throw require_cloud.createCloudObjectError("查询数据为空", "firstOrThrow");
+		return res;
+	}
+	/**
+	* 只查询一条，自动添加 limit(1) 条件
+	* 如果没有匹配到记录，返回 null
+	* @returns 查询结果或 null
+	*/
+	async firstOrNull() {
+		if (this._isTransaction) throw new Error("db.firstOrNull() 方法不支持事务模式");
+		if (this._hasLimit) throw new Error("db.firstOrNull() 方法不支持 limit 条件");
+		if (!this._hasWhereId) this.limit(1);
+		return (await this.many()).at(0) || null;
+	}
+	/**
+	* 获取匹配记录的数量
+	* @returns 记录总数
+	*/
+	async count() {
+		if (this._isTransaction) throw new Error("db.count() 方法不支持事务模式");
+		if (this._hasLookup) throw new Error("db.count() 方法不支持 lookup 聚合");
+		if (this._hasSelect) throw new Error("db.count() 方法不支持 select 条件");
+		if (this._hasOrder) throw new Error("db.count() 方法不支持 order 条件");
+		if (this._hasSkip) throw new Error("db.count() 方法不支持 skip 条件");
+		if (this._hasLimit) throw new Error("db.count() 方法不支持 limit 条件");
+		try {
+			this._endHost("count");
+			const { total } = require__helpers.parseDatabaseOutput(await this._host.count());
+			return total;
+		} catch (err) {
+			const dbErr = err;
+			throw this._options.parseError?.(dbErr) || dbErr;
+		}
+	}
+	/**
+	* 创建新记录
+	* @param data 要创建的数据
+	* @returns 创建结果
+	*/
+	async create(data) {
+		if (this._hasLookup) throw new Error("db.create() 方法不支持 lookup 聚合");
+		if (this._hasWhere) throw new Error("db.create() 方法不支持 where 条件");
+		if (this._hasSelect) throw new Error("db.create() 方法不支持 select 条件");
+		if (this._hasOrder) throw new Error("db.create() 方法不支持 order 条件");
+		if (this._hasSkip) throw new Error("db.create() 方法不支持 skip 条件");
+		if (this._hasLimit) throw new Error("db.create() 方法不支持 limit 条件");
+		try {
+			this._endHost("create");
+			const { id } = require__helpers.parseDatabaseOutput(await this._host.add(data));
+			return id;
+		} catch (err) {
+			const dbErr = err;
+			throw this._options.parseError?.(dbErr) || dbErr;
+		}
+	}
+	/**
+	* 更新记录
+	* @param data 要更新的数据
+	* @returns 更新结果
+	*/
+	async update(data) {
+		if (this._hasLookup) throw new Error("db.update() 方法不支持 lookup 聚合");
+		if (!this._hasWhere) throw new Error("设置 where 条件后才能执行 db.update() 方法");
+		if (this._hasSelect) throw new Error("db.update() 方法不支持 select 条件");
+		if (this._hasOrder) throw new Error("db.update() 方法不支持 order 条件");
+		if (this._hasSkip) throw new Error("db.update() 方法不支持 skip 条件");
+		if (this._hasLimit) throw new Error("db.update() 方法不支持 limit 条件");
+		if (this._isTransaction && !this._hasWhereId) throw new Error("事务模式下 db.update() 的 where 条件必须是 _id");
+		try {
+			this._endHost("update");
+			const { updated } = require__helpers.parseDatabaseOutput(await this._host.update((0, _cloudcome_utils_core_object.objectOmit)(_mapCommandRaw(data), ["_id"])));
+			return updated;
+		} catch (err) {
+			const dbErr = err;
+			throw this._options.parseError?.(dbErr) || dbErr;
+		}
+	}
+	/**
+	* 删除记录
+	* @returns 删除结果
+	*/
+	async remove() {
+		if (this._hasLookup) throw new Error("db.remove() 方法不支持 lookup 聚合");
+		if (!this._hasWhere) throw new Error("设置 where 条件后才能执行 db.remove() 方法");
+		if (this._hasSelect) throw new Error("db.remove() 方法不支持 select 条件");
+		if (this._hasOrder) throw new Error("db.remove() 方法不支持 order 条件");
+		if (this._hasSkip) throw new Error("db.remove() 方法不支持 skip 条件");
+		if (this._hasLimit) throw new Error("db.remove() 方法不支持 limit 条件");
+		if (this._isTransaction && !this._hasWhereId) throw new Error("事务模式下 db.remove() 的 where 条件必须是 _id");
+		try {
+			this._endHost("remove");
+			const { deleted } = require__helpers.parseDatabaseOutput(await this._host.remove());
+			return deleted;
+		} catch (err) {
+			const dbErr = err;
+			throw this._options.parseError?.(dbErr) || dbErr;
+		}
+	}
+};
 function _toWhereMethod(whereFrom) {
-  return whereFrom === "where" ? "where({...})" : "whereId(id)";
+	return whereFrom === "where" ? "where({...})" : "whereId(id)";
 }
 function _toWhereIdMethod(whereFrom) {
-  return whereFrom === "where" ? "where({ _id })" : "whereId(id)";
+	return whereFrom === "where" ? "where({ _id })" : "whereId(id)";
 }
 function _mapCommandRaw(data) {
-  const map = (val) => {
-    if (!type.isObject(val)) return val;
-    if (val instanceof DbBaseCommand) return DbBaseCommand.getValue(val, db0);
-    return object.objectMap(val, map);
-  };
-  return object.objectMap(data, map);
+	const map = (val) => {
+		if (!(0, _cloudcome_utils_core_type.isObject)(val)) return val;
+		if (val instanceof DbBaseCommand) return DbBaseCommand.getValue(val, db0);
+		return (0, _cloudcome_utils_core_object.objectMap)(val, map);
+	};
+	return (0, _cloudcome_utils_core_object.objectMap)(data, map);
 }
 function _mapOrderSelect(order) {
-  return object.objectMap(order, (val, key) => true);
+	return (0, _cloudcome_utils_core_object.objectMap)(order, (_val, _key) => true);
 }
 function _mergeSelect(select, order) {
-  const noSelect = Object.keys(select).length === 0;
-  if (noSelect) return select;
-  const onlyOmitId = Object.keys(select).length === 1 && "_id" in select && select._id === false;
-  if (onlyOmitId) return select;
-  return {
-    ...select,
-    ..._mapOrderSelect(order)
-  };
+	if (Object.keys(select).length === 0) return select;
+	if (Object.keys(select).length === 1 && "_id" in select && select._id === false) return select;
+	return {
+		...select,
+		..._mapOrderSelect(order)
+	};
 }
+//#endregion
+//#region src/database/proxy.ts
+/**
+* 创建一个数据库代理对象，用于延迟实例化数据库操作类
+* @template D1 - 主表数据
+* @template S1 - 主表筛选
+* @param name - 数据库表名
+* @returns 返回一个代理对象，该对象会将属性访问转发到实际的数据库操作实例
+*/
 function dbProxy(name, options) {
-  return new Proxy(
-    {},
-    {
-      get(target, prop) {
-        if (prop === "_isProxy") return true;
-        const table = new Db({ table: name, ...options });
-        const tableProp = prop;
-        const ref = table[tableProp];
-        return type.isFunction(ref) ? ref.bind(table) : ref;
-      }
-    }
-  );
+	return new Proxy({}, { get(_target, prop) {
+		if (prop === "_isProxy") return true;
+		const table = new Db({
+			table: name,
+			...options
+		});
+		const ref = table[prop];
+		return (0, _cloudcome_utils_core_type.isFunction)(ref) ? ref.bind(table) : ref;
+	} });
+}
+//#endregion
+//#region src/database/transaction.ts
+/**
+* 在数据库事务中执行操作
+*
+* @template K - 事务操作返回值类型
+* @param transacting - 事务执行函数，接收事务数据库实例作为参数
+* @param _mockDatabase - 用于测试的模拟数据库对象
+* @param _mockDbInstance - 用于测试的模拟数据库实例
+* @returns 事务操作的返回结果
+*
+* @example
+* ```typescript
+* const result = await dbTransaction(async (withTransaction) => {
+*   const userId = await withTransaction(db.table('user')).create({ name: 'John' });
+*   const order = await withTransaction(db.table('orders')).create({ userId, amount: 100 });
+*   return { user, order };
+* });
+* ```
+*/
+async function dbTransaction(transacting, _mockDatabase, _mockDbInstance) {
+	const [err1, transaction] = await (0, _cloudcome_utils_core_try.tryFlatten)((_mockDatabase || uniCloud.database()).startTransaction());
+	if (err1) throw err1;
+	const withTransaction = (db) => {
+		return _mockDbInstance || new Db({
+			...db.options,
+			transaction
+		});
+	};
+	const [err2, result] = await (0, _cloudcome_utils_core_try.tryFlatten)(async () => {
+		const result = await transacting(withTransaction);
+		await transaction.commit();
+		return result;
+	});
+	if (err2) {
+		await (0, _cloudcome_utils_core_try.tryFlatten)(transaction.rollback());
+		throw err2;
+	}
+	return result;
 }
+//#endregion
+//#region src/database/upsert.ts
 async function dbUpsert(db, options) {
-  const { create, update, onBeforeCreate, onAfterCreate, onBeforeUpdate, onAfterUpdate, _mockDbInstance } = options;
-  const _mutateDb = _mockDbInstance || db.clone();
-  const _queryDb = _mockDbInstance || db.clone(true);
-  const exist = await _queryDb.where(db.getWhere(true)).firstOrNull();
-  if (exist) {
-    const skipUpdate = await onBeforeUpdate?.(exist) === false;
-    if (skipUpdate) {
-      return { id: exist._id, updated: false, created: false };
-    }
-    const updateData = type.isFunction(update) ? update(exist) : update;
-    await _mutateDb.whereId(exist._id).update(updateData);
-    onAfterUpdate?.(updateData, exist);
-    return { id: exist._id, updated: true, created: false };
-  }
-  await onBeforeCreate?.();
-  const createdId = await _mutateDb.create(create);
-  await onAfterCreate?.(createdId);
-  return { id: createdId, updated: false, created: true };
+	const { create, update, onBeforeCreate, onAfterCreate, onBeforeUpdate, onAfterUpdate, _mockDbInstance } = options;
+	const _mutateDb = _mockDbInstance || db.clone();
+	const exist = await (_mockDbInstance || db.clone(true)).where(db.getWhere(true)).firstOrNull();
+	if (exist) {
+		if (await onBeforeUpdate?.(exist) === false) return {
+			id: exist._id,
+			updated: false,
+			created: false
+		};
+		const updateData = (0, _cloudcome_utils_core_type.isFunction)(update) ? update(exist) : update;
+		await _mutateDb.whereId(exist._id).update(updateData);
+		onAfterUpdate?.(updateData, exist);
+		return {
+			id: exist._id,
+			updated: true,
+			created: false
+		};
+	}
+	await onBeforeCreate?.();
+	const createdId = await _mutateDb.create(create);
+	await onAfterCreate?.(createdId);
+	return {
+		id: createdId,
+		updated: false,
+		created: true
+	};
 }
+//#endregion
+//#region src/database/unique.ts
 async function dbUnique(db, options) {
-  const { id, created } = await dbUpsert(db, {
-    ...options,
-    // @ts-ignore
-    update: {},
-    onBeforeUpdate: () => false
-  });
-  return { id, created };
-}
-async function dbTransaction(transacting, _mockDatabase, _mockDbInstance) {
-  const transactionDb = _mockDatabase || uniCloud.database();
-  const [err1, transaction] = await _try.tryFlatten(transactionDb.startTransaction());
-  if (err1) throw err1;
-  const withTransaction = (db) => {
-    return _mockDbInstance || new Db({ ...db.options, transaction });
-  };
-  const [err2, result] = await _try.tryFlatten(async () => {
-    const result2 = await transacting(withTransaction);
-    await transaction.commit();
-    return result2;
-  });
-  if (err2) {
-    await _try.tryFlatten(transaction.rollback());
-    throw err2;
-  }
-  return result;
-}
-async function dbPaging(queryDb) {
-  const where = queryDb.getWhere(true);
-  const countDb = queryDb.clone();
-  const list = await queryDb.many();
-  const total = await countDb.where(where).count();
-  return {
-    list,
-    total
-  };
+	const { id, created } = await dbUpsert(db, {
+		...options,
+		update: {},
+		onBeforeUpdate: () => false
+	});
+	return {
+		id,
+		created
+	};
 }
-exports.parseDatabaseOutput = _helpers.parseDatabaseOutput;
+//#endregion
+exports.dbEach = dbEach;
 exports.dbMutate = dbMutate;
 exports.dbPaging = dbPaging;
 exports.dbProxy = dbProxy;
@@ -639,4 +706,6 @@ exports.dbQuery = dbQuery;
 exports.dbTransaction = dbTransaction;
 exports.dbUnique = dbUnique;
 exports.dbUpsert = dbUpsert;
-//# sourceMappingURL=database.cjs.map
+exports.parseDatabaseOutput = require__helpers.parseDatabaseOutput;
+
+//# sourceMappingURL=database.cjs.map