@cloudcome/utils-uni 1.3.1 → 1.5.0

package/dist/cloud.mjs

@@ -1,25 +1,96 @@
-import { useRequest } from "@cloudcome/utils-vue/request";
-function createUseCloudObject(objectName, options) {
-  const server = (options == null ? void 0 : options._mockServer) || uniCloud.importObject(objectName, options);
-  const useCloudObject = (caller, options2) => {
-    return useRequest(async (...inputs) => {
-      const result = await caller(server, ...inputs);
-      if (!result.errCode) return result.data;
-      throw new Error(result.errMsg || "请求失败");
-    }, options2);
+import { errorAssign, errorNormalize } from "@cloudcome/utils-core/error";
+import { p as parseCloudObjectOutput } from "./_helpers.mjs";
+import { objectDefaults } from "@cloudcome/utils-core/object";
+import { tryFlatten } from "@cloudcome/utils-core/try";
+import { isFunction } from "@cloudcome/utils-core/type";
+function createCloudObjectError(message, code) {
+  return errorAssign(new Error(message), {
+    errCode: code,
+    errMsg: message
+  });
+}
+async function respondCloudObject(fn, requestId) {
+  try {
+    const data = await fn();
+    return {
+      requestId,
+      data,
+      errCode: 0,
+      errMsg: ""
+    };
+  } catch (err) {
+    const err2 = errorNormalize(err);
+    return {
+      requestId,
+      // @ts-ignore
+      data: null,
+      errCode: err2.errCode || -1,
+      errMsg: err2.errMsg || err2.message || ""
+    };
+  }
+}
+function buildCloudObjectExposeCreator(options) {
+  const buildOptions = objectDefaults(options || {}, {
+    requiredUserErrCode: "uni-id-check-token-failed",
+    requiredUserErrMsg: "需要登录后才能进行此操作"
+  });
+  const createCloudObjectExpose = (arg0, arg1, arg2) => {
+    const optionsSource = isFunction(arg0) ? arg1 : arg2;
+    const createOptions = objectDefaults(optionsSource || {}, {
+      requiredUser: false
+    });
+    return async function(input) {
+      return await respondCloudObject(async () => {
+        var _a, _b;
+        const user = await parseAppendUser(this, options == null ? void 0 : options.uniIdCloudObject);
+        const append = {
+          options: createOptions,
+          user
+        };
+        const context = Object.assign(this, append);
+        if (createOptions.requiredUser && !user.id) {
+          throw createCloudObjectError(buildOptions.requiredUserErrMsg, buildOptions.requiredUserErrCode);
+        }
+        if (isFunction(arg0)) {
+          return await arg0(context);
+        }
+        const parsed = arg0.safeParse(input);
+        if (!parsed.success) {
+          console.log(parsed.error.issues);
+          const issue0 = (_b = (_a = parsed.error) == null ? void 0 : _a.issues) == null ? void 0 : _b[0];
+          if ((issue0 == null ? void 0 : issue0.code) === "custom") throw issue0.message;
+          throw new Error("请求数据不正确");
+        }
+        return await arg1(context, parsed.data);
+      }, this.getUniCloudRequestId());
+    };
   };
-  return useCloudObject;
+  return createCloudObjectExpose;
 }
-function useCloudDatabase(caller, options) {
-  const db = (options == null ? void 0 : options._mockDatabase) || uniCloud.database();
-  return useRequest(async (...inputs) => {
-    const { result } = await caller(db, ...inputs);
-    if (!result.errCode) return result;
-    throw new Error(result.errMsg || "请求失败");
-  }, options);
+async function parseAppendUser(objectThis, uniIdCloudObject) {
+  const appendUser = {
+    id: "",
+    role: [],
+    permission: [],
+    isAdmin: false
+  };
+  if (!uniIdCloudObject) return appendUser;
+  const uniId = uniIdCloudObject.createInstance({
+    clientInfo: objectThis.getClientInfo()
+  });
+  const [err1, user] = await tryFlatten(uniId.checkToken(objectThis.getUniIdToken() || ""));
+  if (!user) return appendUser;
+  const [err2, userData] = tryFlatten(() => parseCloudObjectOutput(user));
+  if (!userData) return appendUser;
+  appendUser.id = userData.uid || "";
+  appendUser.role = userData.role || [];
+  appendUser.permission = userData.permission || [];
+  appendUser.isAdmin = appendUser.role.includes("admin") && appendUser.permission.length === 0;
+  return appendUser;
 }
 export {
-  createUseCloudObject,
-  useCloudDatabase
+  buildCloudObjectExposeCreator,
+  createCloudObjectError,
+  respondCloudObject
 };
 //# sourceMappingURL=cloud.mjs.map

package/dist/cloud.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cloud.mjs","sources":["../src/cloud.ts"],"sourcesContent":["import type { AnyArray } from '@cloudcome/utils-core/types';\nimport {\n  type UseRequestOptions,\n  type UseRequestOutput,\n  type UseRequestOutputFilled,\n  useRequest,\n} from '@cloudcome/utils-vue/request';\n\ntype ImportObject = UniCloudNamespace.UniCloud['importObject'];\ntype ImportObjectArgs = Parameters<ImportObject>;\n\nexport type UniCloudObjectOutput<T> = {\n  errCode?: number | string;\n  errMsg?: string;\n  data: T;\n};\n\nexport type UniCloudObjectServer<O> = Record<string, (...inputs: unknown[]) => Promise<UniCloudObjectOutput<O>>>;\n\nexport type CreateUseCloudObjectOptions = ImportObjectArgs[1] & {\n  /**\n   * 模拟云对象，用于单元测试\n   * @private\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: <explanation>\n  _mockServer?: any;\n};\n\nexport type UseCloudObject = {\n  <I extends AnyArray, O>(\n    caller: (server: UniCloudObjectServer<O>, ...inputs: I) => Promise<UniCloudObjectOutput<O>>,\n    options: Omit<UseRequestOptions<I, O>, 'placeholder'> & { placeholder: () => O },\n  ): UseRequestOutputFilled<I, O>;\n  <I extends AnyArray, O>(\n    caller: (server: UniCloudObjectServer<O>, ...inputs: I) => Promise<UniCloudObjectOutput<O>>,\n    options?: UseRequestOptions<I, O>,\n  ): UseRequestOutput<I, O>;\n};\n\n/**\n * 创建一个用于调用云对象的hook工厂函数\n * @param objectName 云对象名称，用于导入对应的云对象\n * @param options 导入云对象时的可选配置参数\n * @returns 返回一个函数，该函数可以用于创建云对象调用hook\n */\nexport function createUseCloudObject(objectName: ImportObjectArgs[0], options?: CreateUseCloudObjectOptions) {\n  const server = options?._mockServer || uniCloud.importObject(objectName, options);\n  const useCloudObject: UseCloudObject = (caller, options) => {\n    // 使用请求hook处理云对象调用\n    return useRequest(async (...inputs) => {\n      const result = await caller(server, ...inputs);\n      if (!result.errCode) return result.data;\n      throw new Error(result.errMsg || '请求失败');\n    }, options);\n  };\n\n  return useCloudObject;\n}\n\nexport type UniCloudDatabaseOutput<T> = {\n  result: T & {\n    errCode?: number | string;\n    errMsg?: string;\n  };\n};\n\nexport type UseCloudDatabaseOptions<I extends AnyArray, O> = UseRequestOptions<I, O> & {\n  /**\n   * 模拟数据库，用于单元测试\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: <explanation>\n  _mockDatabase?: any;\n};\n\n/**\n * 创建一个用于调用云数据库的hook\n * @param caller 调用云数据库的函数，接收数据库实例和输入参数，返回Promise\n * @param options 配置选项\n * @returns 返回一个请求hook，用于处理云数据库调用\n */\nexport function useCloudDatabase<I extends AnyArray, O>(\n  caller: (db: UniCloud.Database, ...inputs: I) => Promise<UniCloudDatabaseOutput<O>>,\n  options: Omit<UseCloudDatabaseOptions<I, O>, 'placeholder'> & { placeholder: () => O },\n): UseRequestOutputFilled<I, O>;\nexport function useCloudDatabase<I extends AnyArray, O>(\n  caller: (db: UniCloud.Database, ...inputs: I) => Promise<UniCloudDatabaseOutput<O>>,\n  options?: UseCloudDatabaseOptions<I, O>,\n): UseRequestOutput<I, O>;\nexport function useCloudDatabase<I extends AnyArray, O>(\n  caller: (db: UniCloud.Database, ...inputs: I) => Promise<UniCloudDatabaseOutput<O>>,\n  options?: UseCloudDatabaseOptions<I, O>,\n): UseRequestOutput<I, O> {\n  // 获取数据库实例，优先使用模拟数据库（用于测试），否则使用uniCloud数据库\n  const db = options?._mockDatabase || uniCloud.database();\n  return useRequest(async (...inputs: I) => {\n    const { result } = await caller(db, ...inputs);\n    if (!result.errCode) return result;\n    throw new Error(result.errMsg || '请求失败');\n  }, options);\n}\n"],"names":["options"],"mappings":";AA6CgB,SAAA,qBAAqB,YAAiC,SAAuC;AAC3G,QAAM,UAAS,mCAAS,gBAAe,SAAS,aAAa,YAAY,OAAO;AAC1E,QAAA,iBAAiC,CAAC,QAAQA,aAAY;AAEnD,WAAA,WAAW,UAAU,WAAW;AACrC,YAAM,SAAS,MAAM,OAAO,QAAQ,GAAG,MAAM;AAC7C,UAAI,CAAC,OAAO,QAAS,QAAO,OAAO;AACnC,YAAM,IAAI,MAAM,OAAO,UAAU,MAAM;AAAA,OACtCA,QAAO;AAAA,EACZ;AAEO,SAAA;AACT;AA+BgB,SAAA,iBACd,QACA,SACwB;AAExB,QAAM,MAAK,mCAAS,kBAAiB,SAAS,SAAS;AAChD,SAAA,WAAW,UAAU,WAAc;AACxC,UAAM,EAAE,OAAO,IAAI,MAAM,OAAO,IAAI,GAAG,MAAM;AACzC,QAAA,CAAC,OAAO,QAAgB,QAAA;AAC5B,UAAM,IAAI,MAAM,OAAO,UAAU,MAAM;AAAA,KACtC,OAAO;AACZ;"}
+{"version":3,"file":"cloud.mjs","sources":["../src/cloud/error.ts","../src/cloud/respond.ts","../src/cloud/expose.ts"],"sourcesContent":["import { errorAssign } from '@cloudcome/utils-core/error';\n\nexport function createCloudObjectError(message: string, code?: number | string) {\n  return errorAssign(new Error(message), {\n    errCode: code,\n    errMsg: message,\n  });\n}\n","import { errorNormalize } from '@cloudcome/utils-core/error';\nimport type { MaybePromise } from '@cloudcome/utils-core/types';\nimport type { UniCloudObjectOutput } from './object';\n\nexport async function respondCloudObject<O>(\n  fn: () => MaybePromise<O>,\n  requestId?: string,\n): Promise<UniCloudObjectOutput<O>> {\n  try {\n    const data = await fn();\n\n    return {\n      requestId,\n      data,\n      errCode: 0,\n      errMsg: '',\n    };\n  } catch (err) {\n    const err2 = errorNormalize(err as Error & { errCode?: number | string; errMsg?: string });\n\n    return {\n      requestId,\n      // @ts-ignore\n      data: null,\n      errCode: err2.errCode || -1,\n      errMsg: err2.errMsg || err2.message || '',\n    };\n  }\n}\n","import { parseCloudObjectOutput } from '@/_helpers';\nimport { objectDefaults } from '@cloudcome/utils-core/object';\nimport { tryFlatten } from '@cloudcome/utils-core/try';\nimport { isFunction } from '@cloudcome/utils-core/type';\nimport type { MaybePromise } from '@cloudcome/utils-core/types';\nimport type z from 'zod';\nimport type { ZodObject } from 'zod';\nimport { createCloudObjectError } from './error';\nimport type { UniCloudObject, UniCloudObjectThis } from './object';\nimport { respondCloudObject } from './respond';\nimport type { UniIdCloudObject } from './uni-id';\n\nexport type UniCloudObjectThisAppendUser = {\n  id: string;\n  role: string[];\n  permission: string[];\n  isAdmin: boolean;\n};\n\nexport type UniCloudObjectThisAppend = {\n  options: Required<CreateCloudObjectOptions>;\n  user: UniCloudObjectThisAppendUser;\n};\n\nexport type UniCloudObjectContext = UniCloudObjectThis & UniCloudObjectThisAppend;\n\n/**\n * 构建云函数暴露创建器的选项配置\n * 用于配置云函数暴露创建器的行为，目前支持传入UniIdCloudObject实例\n */\nexport type BuildCloudExposeCreatorOptions = {\n  /**\n   * 可选的UniIdCloudObject实例\n   * 用于处理用户身份验证和权限管理相关功能\n   */\n  uniIdCloudObject?: UniIdCloudObject;\n\n  /**\n   * 需要用户登录态的错误码\n   * @default 'uni-id-check-token-failed'\n   */\n  requiredUserErrCode?: number | string;\n\n  /**\n   * 需要用户登录态的错误消息\n   * @default '需要登录后才能进行此操作'\n   */\n  requiredUserErrMsg?: string;\n};\n\nexport type CreateCloudObjectOptions = {\n  /**\n   * 是否需要用户登录态\n   * @default false\n   */\n  requiredUser?: boolean;\n};\n\nexport type CreateCloudObjectExpose = {\n  <S extends ZodObject, O>(\n    schema: S,\n    fn: (context: UniCloudObjectContext, input: z.infer<S>) => MaybePromise<O>,\n    options?: CreateCloudObjectOptions,\n  ): UniCloudObject<z.infer<S>, O>;\n  <O>(\n    fn: (context: UniCloudObjectContext) => MaybePromise<O>,\n    options?: CreateCloudObjectOptions,\n  ): UniCloudObject<void, O>;\n};\n\nexport function buildCloudObjectExposeCreator(options?: BuildCloudExposeCreatorOptions) {\n  const buildOptions = objectDefaults(options || {}, {\n    requiredUserErrCode: 'uni-id-check-token-failed',\n    requiredUserErrMsg: '需要登录后才能进行此操作',\n  }) as Required<BuildCloudExposeCreatorOptions>;\n\n  // @ts-ignore\n  const createCloudObjectExpose: CreateCloudObjectExpose = (arg0, arg1, arg2) => {\n    // 选项来源\n    const optionsSource = (isFunction(arg0) ? arg1 : arg2) as CreateCloudObjectOptions | undefined;\n    // 设置默认选项值\n    const createOptions = objectDefaults(optionsSource || {}, {\n      requiredUser: false,\n    }) as Required<CreateCloudObjectOptions>;\n\n    return async function (input) {\n      // 处理云函数响应逻辑\n      return await respondCloudObject(async () => {\n        // 构建附加的上下文信息\n        const user = await parseAppendUser(this, options?.uniIdCloudObject);\n        const append: UniCloudObjectThisAppend = {\n          options: createOptions,\n          user: user,\n        };\n        const context = Object.assign(this, append) as UniCloudObjectContext;\n\n        if (createOptions.requiredUser && !user.id) {\n          throw createCloudObjectError(buildOptions.requiredUserErrMsg, buildOptions.requiredUserErrCode);\n        }\n\n        // 无入参\n        if (isFunction(arg0)) {\n          return await arg0(context);\n        }\n\n        // 单入参\n        // 验证输入数据\n        const parsed = arg0.safeParse(input);\n\n        if (!parsed.success) {\n          console.log(parsed.error.issues);\n\n          const issue0 = parsed.error?.issues?.[0];\n\n          // 处理验证错误\n          if (issue0?.code === 'custom') throw issue0.message;\n          throw new Error('请求数据不正确');\n        }\n\n        return await arg1(context, parsed.data);\n      }, this.getUniCloudRequestId());\n    };\n  };\n\n  return createCloudObjectExpose;\n}\n\nasync function parseAppendUser(\n  objectThis: UniCloudObjectThis,\n  uniIdCloudObject?: UniIdCloudObject,\n): Promise<UniCloudObjectThisAppendUser> {\n  const appendUser: UniCloudObjectThisAppendUser = {\n    id: '',\n    role: [],\n    permission: [],\n    isAdmin: false,\n  };\n\n  if (!uniIdCloudObject) return appendUser;\n\n  const uniId = uniIdCloudObject.createInstance({\n    clientInfo: objectThis.getClientInfo(),\n  });\n\n  // 忽略错误1\n  const [err1, user] = await tryFlatten(uniId.checkToken(objectThis.getUniIdToken() || ''));\n  if (!user) return appendUser;\n\n  // 忽略错误2\n  const [err2, userData] = tryFlatten(() => parseCloudObjectOutput(user));\n  if (!userData) return appendUser;\n\n  appendUser.id = userData.uid || '';\n  appendUser.role = userData.role || [];\n  appendUser.permission = userData.permission || [];\n  appendUser.isAdmin = appendUser.role.includes('admin') && appendUser.permission.length === 0;\n\n  return appendUser;\n}\n"],"names":[],"mappings":";;;;;AAEgB,SAAA,uBAAuB,SAAiB,MAAwB;AAC9E,SAAO,YAAY,IAAI,MAAM,OAAO,GAAG;AAAA,IACrC,SAAS;AAAA,IACT,QAAQ;AAAA,EAAA,CACT;AACH;ACHsB,eAAA,mBACpB,IACA,WACkC;AAC9B,MAAA;AACI,UAAA,OAAO,MAAM,GAAG;AAEf,WAAA;AAAA,MACL;AAAA,MACA;AAAA,MACA,SAAS;AAAA,MACT,QAAQ;AAAA,IACV;AAAA,WACO,KAAK;AACN,UAAA,OAAO,eAAe,GAA6D;AAElF,WAAA;AAAA,MACL;AAAA;AAAA,MAEA,MAAM;AAAA,MACN,SAAS,KAAK,WAAW;AAAA,MACzB,QAAQ,KAAK,UAAU,KAAK,WAAW;AAAA,IACzC;AAAA,EAAA;AAEJ;AC0CO,SAAS,8BAA8B,SAA0C;AACtF,QAAM,eAAe,eAAe,WAAW,IAAI;AAAA,IACjD,qBAAqB;AAAA,IACrB,oBAAoB;AAAA,EAAA,CACrB;AAGD,QAAM,0BAAmD,CAAC,MAAM,MAAM,SAAS;AAE7E,UAAM,gBAAiB,WAAW,IAAI,IAAI,OAAO;AAEjD,UAAM,gBAAgB,eAAe,iBAAiB,IAAI;AAAA,MACxD,cAAc;AAAA,IAAA,CACf;AAED,WAAO,eAAgB,OAAO;AAErB,aAAA,MAAM,mBAAmB,YAAY;;AAE1C,cAAM,OAAO,MAAM,gBAAgB,MAAM,mCAAS,gBAAgB;AAClE,cAAM,SAAmC;AAAA,UACvC,SAAS;AAAA,UACT;AAAA,QACF;AACA,cAAM,UAAU,OAAO,OAAO,MAAM,MAAM;AAE1C,YAAI,cAAc,gBAAgB,CAAC,KAAK,IAAI;AAC1C,gBAAM,uBAAuB,aAAa,oBAAoB,aAAa,mBAAmB;AAAA,QAAA;AAI5F,YAAA,WAAW,IAAI,GAAG;AACb,iBAAA,MAAM,KAAK,OAAO;AAAA,QAAA;AAKrB,cAAA,SAAS,KAAK,UAAU,KAAK;AAE/B,YAAA,CAAC,OAAO,SAAS;AACX,kBAAA,IAAI,OAAO,MAAM,MAAM;AAE/B,gBAAM,UAAS,kBAAO,UAAP,mBAAc,WAAd,mBAAuB;AAGtC,eAAI,iCAAQ,UAAS,SAAU,OAAM,OAAO;AACtC,gBAAA,IAAI,MAAM,SAAS;AAAA,QAAA;AAG3B,eAAO,MAAM,KAAK,SAAS,OAAO,IAAI;AAAA,MAAA,GACrC,KAAK,sBAAsB;AAAA,IAChC;AAAA,EACF;AAEO,SAAA;AACT;AAEA,eAAe,gBACb,YACA,kBACuC;AACvC,QAAM,aAA2C;AAAA,IAC/C,IAAI;AAAA,IACJ,MAAM,CAAC;AAAA,IACP,YAAY,CAAC;AAAA,IACb,SAAS;AAAA,EACX;AAEI,MAAA,CAAC,iBAAyB,QAAA;AAExB,QAAA,QAAQ,iBAAiB,eAAe;AAAA,IAC5C,YAAY,WAAW,cAAc;AAAA,EAAA,CACtC;AAGD,QAAM,CAAC,MAAM,IAAI,IAAI,MAAM,WAAW,MAAM,WAAW,WAAW,cAAmB,KAAA,EAAE,CAAC;AACpF,MAAA,CAAC,KAAa,QAAA;AAGZ,QAAA,CAAC,MAAM,QAAQ,IAAI,WAAW,MAAM,uBAAuB,IAAI,CAAC;AAClE,MAAA,CAAC,SAAiB,QAAA;AAEX,aAAA,KAAK,SAAS,OAAO;AACrB,aAAA,OAAO,SAAS,QAAQ,CAAC;AACzB,aAAA,aAAa,SAAS,cAAc,CAAC;AACrC,aAAA,UAAU,WAAW,KAAK,SAAS,OAAO,KAAK,WAAW,WAAW,WAAW;AAEpF,SAAA;AACT;"}

package/dist/database/db.d.ts

@@ -0,0 +1,182 @@
+import { AnyObject, LowercaseStartString } from '@cloudcome/utils-core/types';
+import { UniClientDatabaseOutput, UniCloudDatabaseOutput } from './types';
+type DbSelectPositive = {
+    [key: LowercaseStartString]: true;
+};
+type DbSelectNegative = {
+    _id?: false;
+};
+export type DbSelect = Omit<DbSelectPositive, '_id'> & DbSelectNegative;
+export type DbOrder = Record<string, 'asc' | 'desc'>;
+export type DbRecord<S extends Record<string, boolean>> = {
+    [K in keyof S as S[K] extends true ? K : never]: unknown;
+};
+/**
+ * 数据库操作符命令
+ */
+export declare const dbCmd: UniCloud.QueryCommand;
+/**
+ * 数据库聚合操作符命令
+ */
+export declare const dbAgg: UniCloud.AggregateCommand;
+export type DbOptions = {
+    /**
+     * 集合名称
+     */
+    collection: string;
+    /**
+     * 事务对象，用于事务操作
+     */
+    transaction?: any;
+    /**
+     * 模拟数据库，用于单元测试
+     */
+    _mockDatabase?: any;
+};
+export declare class Db {
+    #private;
+    /**
+     * 构造函数，初始化数据库集合引用
+     * @param collection 集合名称
+     * @param _mockDatabase 模拟数据库，用于单元测试
+     */
+    constructor(options: DbOptions);
+    /**
+     * 创建聚合操作实例
+     * @returns 聚合操作实例
+     */
+    aggregate(): UniCloud.AggregateReference;
+    /**
+     * 设置查询条件
+     * @param where 查询条件对象
+     * @returns 当前Db实例，支持链式执行
+     */
+    where(where: AnyObject): this;
+    /**
+     * 指定要返回的字段
+     * @param fields 要返回的字段对象，true表示返回，false表示不返回
+     * @returns 当前Db实例，支持链式执行
+     */
+    select(fields: DbSelect): this;
+    /**
+     * 设置排序规则
+     * @param order 排序规则对象，key为字段名，value为"asc"或"desc"
+     * @returns 当前Db实例，支持链式执行
+     */
+    order(order: DbOrder): this;
+    /**
+     * 跳过指定数量的记录
+     * @param skip 要跳过的记录数
+     * @returns 当前Db实例，支持链式执行
+     */
+    skip(skip: number): this;
+    /**
+     * 限制返回的记录数量
+     * @param limit 最大返回记录数
+     * @returns 当前Db实例，支持链式执行
+     */
+    limit(limit: number): this;
+    /**
+     * 创建新记录
+     * @param data 要创建的数据
+     * @returns 创建结果
+     */
+    create(data: AnyObject): Promise<{
+        id: string;
+    } | Omit<{
+        id: string;
+    } & {
+        code?: number | string;
+        errCode?: number | string;
+        errMsg?: string;
+        message?: string;
+    }, "errCode" | "errMsg" | "code" | "message">>;
+    /**
+     * 执行查询操作
+     * @returns 查询结果
+     */
+    query<T>(): Promise<{
+        data: T[];
+    } | Omit<{
+        data: T[];
+    } & {
+        code?: number | string;
+        errCode?: number | string;
+        errMsg?: string;
+        message?: string;
+    }, "errCode" | "errMsg" | "code" | "message">>;
+    /**
+     * 只查询一条，自动添加 limit(1) 条件
+     * @param ignoreMiss 是否忽略没有匹配到记录
+     * @returns 查询结果
+     */
+    queryOne<T>(): Promise<T>;
+    queryOne<T>(ignoreMiss: false): Promise<T>;
+    queryOne<T>(ignoreMiss: true): Promise<T | undefined>;
+    /**
+     * 获取匹配记录的数量
+     * @returns 记录总数
+     */
+    count(): Promise<{
+        total: number;
+    } | Omit<{
+        total: number;
+    } & {
+        code?: number | string;
+        errCode?: number | string;
+        errMsg?: string;
+        message?: string;
+    }, "errCode" | "errMsg" | "code" | "message">>;
+    /**
+     * 更新记录
+     * @param data 要更新的数据
+     * @returns 更新结果
+     */
+    update(data: AnyObject): Promise<{
+        updated: number;
+    } | Omit<{
+        updated: number;
+    } & {
+        code?: number | string;
+        errCode?: number | string;
+        errMsg?: string;
+        message?: string;
+    }, "errCode" | "errMsg" | "code" | "message">>;
+    /**
+     * 删除记录
+     * @returns 删除结果
+     */
+    remove(): Promise<{
+        deleted: number;
+    } | Omit<{
+        deleted: number;
+    } & {
+        code?: number | string;
+        errCode?: number | string;
+        errMsg?: string;
+        message?: string;
+    }, "errCode" | "errMsg" | "code" | "message">>;
+}
+/**
+ * 数据库操作对象
+ */
+export declare const db: {
+    /**
+     * 获取指定名称的数据库集合实例
+     * @param collection 集合名称
+     * @returns Db类实例，用于执行数据库操作
+     */
+    collection(collection: string): Db;
+};
+/**
+ * 解析数据库执行结果
+ * @param res 客户端、云端响应结果
+ * @returns 处理后的结果
+ */
+export declare function parseDatabaseOutput<T>(res: UniClientDatabaseOutput<T> | UniCloudDatabaseOutput<T>): T | Omit<T & {
+    code?: number | string;
+    errCode?: number | string;
+    errMsg?: string;
+    message?: string;
+}, "errCode" | "errMsg" | "code" | "message">;
+export {};

package/dist/database/fns.d.ts

@@ -0,0 +1,73 @@
+import { AnyObject } from '@cloudcome/utils-core/types';
+import { Db, DbSelect } from './db';
+/**
+ * 数据库 upsert 操作的配置选项
+ *
+ * @template W - 查询条件类型
+ * @template S - 查询返回字段类型
+ * @template C - 创建数据类型
+ * @template U - 更新数据类型
+ * @template R - 查询结果类型
+ */
+export type DbUpsertOptions<W extends AnyObject, S extends DbSelect, C extends AnyObject, U extends AnyObject, R extends AnyObject> = {
+    /** 集合名称 */
+    collection: string;
+    /** 查询条件 */
+    where: W;
+    /** 查询返回字段 */
+    select?: S;
+    /** 创建数据 */
+    create: C;
+    /**
+     * 更新数据，可以是对象或根据查询结果生成更新对象的函数
+     * @param row 查询到的文档数据，仅在传入函数时可用
+     */
+    update: U | ((row: R) => U);
+    /** 创建前回调函数 */
+    onBeforeCreate?: () => unknown;
+    /**
+     * 创建后回调函数
+     * @param id 创建的文档ID
+     */
+    onAfterCreate?: (id: string) => unknown;
+    /**
+     * 更新前回调函数
+     * @param row 查询到的文档
+     */
+    onBeforeUpdate?: (row: R) => unknown;
+    /** 更新后回调函数 */
+    onAfterUpdate?: () => unknown;
+    /** 用于测试的模拟数据库实例 */
+    _mockDb?: (collection: string) => any;
+};
+export declare function dbUpsert<W extends AnyObject, S extends DbSelect, C extends AnyObject, U extends AnyObject, R extends AnyObject>(options: DbUpsertOptions<W, S, C, U, R>): Promise<{
+    updated: number;
+} | {
+    id: string;
+}>;
+type _TransactionDb = {
+    startTransaction: () => Promise<_Transaction>;
+};
+type _Transaction = {
+    commit: () => Promise<unknown>;
+    rollback: () => Promise<unknown>;
+};
+/**
+ * 在数据库事务中执行操作
+ *
+ * @template T - 事务操作返回值类型
+ * @param transact - 事务执行函数，接收事务数据库实例作为参数
+ * @param _mockDatabase - 用于测试的模拟数据库实例
+ * @returns 事务操作的返回结果
+ *
+ * @example
+ * ```typescript
+ * const result = await dbTransaction(async (ta) => {
+ *   const user = await ta.collection('users').create({ name: 'John' });
+ *   const order = await ta.collection('orders').create({ userId: user.id, amount: 100 });
+ *   return { user, order };
+ * });
+ * ```
+ */
+export declare function dbTransaction<T>(transact: (ta: Db) => Promise<T>, _mockDatabase?: _TransactionDb): Promise<T>;
+export {};

package/dist/database/types.d.ts

@@ -0,0 +1,9 @@
+export type UniClientDatabaseOutput<T> = {
+    result: T & {
+        code?: number | string;
+        errCode?: number | string;
+        errMsg?: string;
+        message?: string;
+    };
+};
+export type UniCloudDatabaseOutput<T> = T;