@cloudcome/utils-uni 1.7.1 → 1.9.0

package/dist/cloud/expose.d.ts

@@ -33,6 +33,13 @@ export type BuildCloudExposeCreatorOptions = {
      * @default '需要登录后才能进行此操作'
      */
     requiredUserErrMsg?: string;
+    /**
+     * 响应附加数据函数
+     * 用于在云对象响应中添加额外的上下文信息
+     * @param objectThis 云对象上下文
+     * @returns 返回要附加到响应中的数据对象
+     */
+    respondAppend?: (objectThis: UniCloudObjectThis) => AnyObject;
 };
 export type CreateCloudObjectOptions = {
     /**
@@ -45,4 +52,36 @@ export type CreateCloudObjectExpose = {
     <S extends ZodObject, O>(schema: S, fn: (context: UniCloudObjectContext, input: z.infer<S>) => MaybePromise<O>, options?: CreateCloudObjectOptions): UniCloudObject<z.infer<S>, O>;
     <O>(fn: (context: UniCloudObjectContext) => MaybePromise<O>, options?: CreateCloudObjectOptions): UniCloudObject<void, O>;
 };
+/**
+ * 构建云对象暴露创建器
+ *
+ * 该函数用于创建一个云对象暴露函数，可以处理用户身份验证、输入验证和错误处理等通用逻辑
+ *
+ * @param options 构建选项配置
+ * @param options.uniIdCloudObject 可选的UniIdCloudObject实例，用于处理用户身份验证和权限管理
+ * @param options.requiredUserErrCode 需要用户登录态时的错误码，默认为 'uni-id-check-token-failed'
+ * @param options.requiredUserErrMsg 需要用户登录态时的错误消息，默认为 '需要登录后才能进行此操作'
+ *
+ * @returns 返回一个云对象暴露创建函数，支持两种重载形式：
+ * 1. 无输入参数的形式：(fn, options) => UniCloudObject
+ * 2. 有输入验证的形式：(schema, fn, options) => UniCloudObject
+ *
+ * @example
+ * // 无输入参数的使用方式
+ * const expose = buildCloudObjectExposeCreator();
+ * export default expose(async (context) => {
+ *   // 业务逻辑
+ * });
+ *
+ * @example
+ * // 有输入验证的使用方式
+ * const expose = buildCloudObjectExposeCreator();
+ * const schema = z.object({
+ *   name: z.string().min(1)
+ * });
+ *
+ * export default expose(schema, async (context, input) => {
+ *   // 业务逻辑，input类型已自动推断
+ * });
+ */
 export declare function buildCloudObjectExposeCreator(options?: BuildCloudExposeCreatorOptions): CreateCloudObjectExpose;

package/dist/cloud/object.d.ts

@@ -124,7 +124,6 @@ export type UniCloudObjectThis = {
     getHttpInfo: () => HttpInfo | undefined;
 };
 export type UniCloudObjectOutput<T> = {
-    requestId?: string;
     errCode?: number | string;
     errMsg?: string;
     data: T;

package/dist/cloud/respond.d.ts

@@ -1,3 +1,24 @@
 import { MaybePromise } from '@cloudcome/utils-core/types';
 import { UniCloudObjectOutput } from './object';
-export declare function respondCloudObject<O>(fn: () => MaybePromise<O>, requestId?: string): Promise<UniCloudObjectOutput<O>>;
+/**
+ * 处理云函数响应结果，统一返回格式
+ * @param fn - 执行函数，可以返回任意类型的值或Promise
+ * @param append - 需要附加到响应结果中的额外字段
+ * @returns 统一格式的云函数响应结果
+ *
+ * @example
+ * ```typescript
+ * // 成功情况
+ * const result = await respondCloudObject(async () => {
+ *   return { name: 'test', value: 123 };
+ * });
+ * // 返回: { errCode: 0, errMsg: '', data: { name: 'test', value: 123 } }
+ *
+ * // 失败情况
+ * const result = await respondCloudObject(() => {
+ *   throw new Error('操作失败');
+ * });
+ * // 返回: { errCode: -1, errMsg: '操作失败', data: null }
+ * ```
+ */
+export declare function respondCloudObject<O>(fn: () => MaybePromise<O>, append?: AnyObject): Promise<UniCloudObjectOutput<O>>;

package/dist/cloud.cjs

@@ -11,32 +11,33 @@ function createCloudObjectError(message, code) {
     errMsg: message
   });
 }
-async function respondCloudObject(fn, requestId) {
+async function respondCloudObject(fn, append) {
   try {
     const data = await fn();
     return {
-      requestId,
-      data,
       errCode: 0,
-      errMsg: ""
+      errMsg: "",
+      data,
+      ...append
     };
   } catch (err) {
     console.error("respondCloudObject error");
     console.error(err);
     const err2 = error.errorNormalize(err);
     return {
-      requestId,
+      errCode: err2.errCode || -1,
+      errMsg: err2.errMsg || err2.message || "",
       // @ts-ignore
       data: null,
-      errCode: err2.errCode || -1,
-      errMsg: err2.errMsg || err2.message || ""
+      ...append
     };
   }
 }
 function buildCloudObjectExposeCreator(options) {
   const buildOptions = object.objectDefaults(options || {}, {
     requiredUserErrCode: "uni-id-check-token-failed",
-    requiredUserErrMsg: "需要登录后才能进行此操作"
+    requiredUserErrMsg: "需要登录后才能进行此操作",
+    respondAppend: () => ({})
   });
   const createCloudObjectExpose = (arg0, arg1, arg2) => {
     const optionsSource = type.isFunction(arg0) ? arg1 : arg2;
@@ -65,7 +66,7 @@ function buildCloudObjectExposeCreator(options) {
           throw new Error("请求数据不正确");
         }
         return await arg1(context, parsed.data);
-      }, this.getUniCloudRequestId());
+      }, buildOptions.respondAppend(this));
     };
   };
   return createCloudObjectExpose;

package/dist/cloud.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"cloud.cjs","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    console.error('respondCloudObject error');\n    console.error(err);\n\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":["errorAssign","errorNormalize","objectDefaults","isFunction","tryFlatten","parseCloudObjectOutput"],"mappings":";;;;;;;AAEgB,SAAA,uBAAuB,SAAiB,MAAwB;AAC9E,SAAOA,kBAAY,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;AACZ,YAAQ,MAAM,0BAA0B;AACxC,YAAQ,MAAM,GAAG;AAEX,UAAA,OAAOC,qBAAe,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;ACuCO,SAAS,8BAA8B,SAA0C;AACtF,QAAM,eAAeC,OAAAA,eAAe,WAAW,IAAI;AAAA,IACjD,qBAAqB;AAAA,IACrB,oBAAoB;AAAA,EAAA,CACrB;AAGD,QAAM,0BAAmD,CAAC,MAAM,MAAM,SAAS;AAE7E,UAAM,gBAAiBC,KAAA,WAAW,IAAI,IAAI,OAAO;AAEjD,UAAM,gBAAgBD,OAAAA,eAAe,iBAAiB,IAAI;AAAA,MACxD,cAAc;AAAA,IAAA,CACf;AAED,WAAO,eAAgB,OAAO;AAErB,aAAA,MAAM,mBAAmB,YAAY;AAE1C,cAAM,OAAO,MAAM,gBAAgB,MAAM,SAAS,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,YAAAC,KAAAA,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,SAAS,OAAO,OAAO,SAAS,CAAC;AAGvC,cAAI,QAAQ,SAAS,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,MAAMC,KAAA,WAAW,MAAM,WAAW,WAAW,cAAmB,KAAA,EAAE,CAAC;AACpF,MAAA,CAAC,KAAa,QAAA;AAGZ,QAAA,CAAC,MAAM,QAAQ,IAAIA,gBAAW,MAAMC,SAAAA,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;;;;"}
+{"version":3,"file":"cloud.cjs","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\n/**\n * 处理云函数响应结果，统一返回格式\n * @param fn - 执行函数，可以返回任意类型的值或Promise\n * @param append - 需要附加到响应结果中的额外字段\n * @returns 统一格式的云函数响应结果\n *\n * @example\n * ```typescript\n * // 成功情况\n * const result = await respondCloudObject(async () => {\n *   return { name: 'test', value: 123 };\n * });\n * // 返回: { errCode: 0, errMsg: '', data: { name: 'test', value: 123 } }\n *\n * // 失败情况\n * const result = await respondCloudObject(() => {\n *   throw new Error('操作失败');\n * });\n * // 返回: { errCode: -1, errMsg: '操作失败', data: null }\n * ```\n */\nexport async function respondCloudObject<O>(\n  fn: () => MaybePromise<O>,\n  append?: AnyObject,\n): Promise<UniCloudObjectOutput<O>> {\n  try {\n    const data = await fn();\n\n    return {\n      errCode: 0,\n      errMsg: '',\n      data,\n      ...append,\n    };\n  } catch (err) {\n    console.error('respondCloudObject error');\n    console.error(err);\n\n    const err2 = errorNormalize(err as Error & { errCode?: number | string; errMsg?: string });\n\n    return {\n      errCode: err2.errCode || -1,\n      errMsg: err2.errMsg || err2.message || '',\n      // @ts-ignore\n      data: null,\n      ...append,\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  /**\n   * 响应附加数据函数\n   * 用于在云对象响应中添加额外的上下文信息\n   * @param objectThis 云对象上下文\n   * @returns 返回要附加到响应中的数据对象\n   */\n  respondAppend?: (objectThis: UniCloudObjectThis) => AnyObject;\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\n/**\n * 构建云对象暴露创建器\n *\n * 该函数用于创建一个云对象暴露函数，可以处理用户身份验证、输入验证和错误处理等通用逻辑\n *\n * @param options 构建选项配置\n * @param options.uniIdCloudObject 可选的UniIdCloudObject实例，用于处理用户身份验证和权限管理\n * @param options.requiredUserErrCode 需要用户登录态时的错误码，默认为 'uni-id-check-token-failed'\n * @param options.requiredUserErrMsg 需要用户登录态时的错误消息，默认为 '需要登录后才能进行此操作'\n *\n * @returns 返回一个云对象暴露创建函数，支持两种重载形式：\n * 1. 无输入参数的形式：(fn, options) => UniCloudObject\n * 2. 有输入验证的形式：(schema, fn, options) => UniCloudObject\n *\n * @example\n * // 无输入参数的使用方式\n * const expose = buildCloudObjectExposeCreator();\n * export default expose(async (context) => {\n *   // 业务逻辑\n * });\n *\n * @example\n * // 有输入验证的使用方式\n * const expose = buildCloudObjectExposeCreator();\n * const schema = z.object({\n *   name: z.string().min(1)\n * });\n *\n * export default expose(schema, async (context, input) => {\n *   // 业务逻辑，input类型已自动推断\n * });\n */\nexport function buildCloudObjectExposeCreator(options?: BuildCloudExposeCreatorOptions) {\n  const buildOptions = objectDefaults(options || {}, {\n    requiredUserErrCode: 'uni-id-check-token-failed',\n    requiredUserErrMsg: '需要登录后才能进行此操作',\n    respondAppend: () => ({}),\n  }) as Required<BuildCloudExposeCreatorOptions>;\n\n  // @ts-ignore\n  const createCloudObjectExpose: CreateCloudObjectExpose = (arg0, arg1, arg2) => {\n    // 确定选项来源：如果arg0是函数，则选项在arg1；否则在arg2\n    const optionsSource = (isFunction(arg0) ? arg1 : arg2) as CreateCloudObjectOptions | undefined;\n\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        // 如果需要用户登录态但用户未登录，则抛出错误\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        const parsed = arg0.safeParse(input);\n\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        // 执行业务逻辑函数，传入上下文和验证后的数据\n        return await arg1(context, parsed.data);\n      }, buildOptions.respondAppend(this));\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":["errorAssign","errorNormalize","objectDefaults","isFunction","tryFlatten","parseCloudObjectOutput"],"mappings":";;;;;;;AAEgB,SAAA,uBAAuB,SAAiB,MAAwB;AAC9E,SAAOA,kBAAY,IAAI,MAAM,OAAO,GAAG;AAAA,IACrC,SAAS;AAAA,IACT,QAAQ;AAAA,EAAA,CACT;AACH;ACkBsB,eAAA,mBACpB,IACA,QACkC;AAC9B,MAAA;AACI,UAAA,OAAO,MAAM,GAAG;AAEf,WAAA;AAAA,MACL,SAAS;AAAA,MACT,QAAQ;AAAA,MACR;AAAA,MACA,GAAG;AAAA,IACL;AAAA,WACO,KAAK;AACZ,YAAQ,MAAM,0BAA0B;AACxC,YAAQ,MAAM,GAAG;AAEX,UAAA,OAAOC,qBAAe,GAA6D;AAElF,WAAA;AAAA,MACL,SAAS,KAAK,WAAW;AAAA,MACzB,QAAQ,KAAK,UAAU,KAAK,WAAW;AAAA;AAAA,MAEvC,MAAM;AAAA,MACN,GAAG;AAAA,IACL;AAAA,EAAA;AAEJ;AC0DO,SAAS,8BAA8B,SAA0C;AACtF,QAAM,eAAeC,OAAAA,eAAe,WAAW,IAAI;AAAA,IACjD,qBAAqB;AAAA,IACrB,oBAAoB;AAAA,IACpB,eAAe,OAAO,CAAC;AAAA,EAAA,CACxB;AAGD,QAAM,0BAAmD,CAAC,MAAM,MAAM,SAAS;AAE7E,UAAM,gBAAiBC,KAAA,WAAW,IAAI,IAAI,OAAO;AAGjD,UAAM,gBAAgBD,OAAAA,eAAe,iBAAiB,IAAI;AAAA,MACxD,cAAc;AAAA,IAAA,CACf;AAED,WAAO,eAAgB,OAAO;AAErB,aAAA,MAAM,mBAAmB,YAAY;AAE1C,cAAM,OAAO,MAAM,gBAAgB,MAAM,SAAS,gBAAgB;AAClE,cAAM,SAAmC;AAAA,UACvC,SAAS;AAAA,UACT;AAAA,QACF;AACA,cAAM,UAAU,OAAO,OAAO,MAAM,MAAM;AAG1C,YAAI,cAAc,gBAAgB,CAAC,KAAK,IAAI;AAC1C,gBAAM,uBAAuB,aAAa,oBAAoB,aAAa,mBAAmB;AAAA,QAAA;AAI5F,YAAAC,KAAAA,WAAW,IAAI,GAAG;AACb,iBAAA,MAAM,KAAK,OAAO;AAAA,QAAA;AAIrB,cAAA,SAAS,KAAK,UAAU,KAAK;AAG/B,YAAA,CAAC,OAAO,SAAS;AACX,kBAAA,IAAI,OAAO,MAAM,MAAM;AAE/B,gBAAM,SAAS,OAAO,OAAO,SAAS,CAAC;AAGvC,cAAI,QAAQ,SAAS,SAAU,OAAM,OAAO;AACtC,gBAAA,IAAI,MAAM,SAAS;AAAA,QAAA;AAI3B,eAAO,MAAM,KAAK,SAAS,OAAO,IAAI;AAAA,MAAA,GACrC,aAAa,cAAc,IAAI,CAAC;AAAA,IACrC;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,MAAMC,KAAA,WAAW,MAAM,WAAW,WAAW,cAAmB,KAAA,EAAE,CAAC;AACpF,MAAA,CAAC,KAAa,QAAA;AAGZ,QAAA,CAAC,MAAM,QAAQ,IAAIA,gBAAW,MAAMC,SAAAA,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/cloud.mjs

@@ -9,32 +9,33 @@ function createCloudObjectError(message, code) {
     errMsg: message
   });
 }
-async function respondCloudObject(fn, requestId) {
+async function respondCloudObject(fn, append) {
   try {
     const data = await fn();
     return {
-      requestId,
-      data,
       errCode: 0,
-      errMsg: ""
+      errMsg: "",
+      data,
+      ...append
     };
   } catch (err) {
     console.error("respondCloudObject error");
     console.error(err);
     const err2 = errorNormalize(err);
     return {
-      requestId,
+      errCode: err2.errCode || -1,
+      errMsg: err2.errMsg || err2.message || "",
       // @ts-ignore
       data: null,
-      errCode: err2.errCode || -1,
-      errMsg: err2.errMsg || err2.message || ""
+      ...append
     };
   }
 }
 function buildCloudObjectExposeCreator(options) {
   const buildOptions = objectDefaults(options || {}, {
     requiredUserErrCode: "uni-id-check-token-failed",
-    requiredUserErrMsg: "需要登录后才能进行此操作"
+    requiredUserErrMsg: "需要登录后才能进行此操作",
+    respondAppend: () => ({})
   });
   const createCloudObjectExpose = (arg0, arg1, arg2) => {
     const optionsSource = isFunction(arg0) ? arg1 : arg2;
@@ -63,7 +64,7 @@ function buildCloudObjectExposeCreator(options) {
           throw new Error("请求数据不正确");
         }
         return await arg1(context, parsed.data);
-      }, this.getUniCloudRequestId());
+      }, buildOptions.respondAppend(this));
     };
   };
   return createCloudObjectExpose;

package/dist/cloud.mjs.map

@@ -1 +1 @@
-{"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    console.error('respondCloudObject error');\n    console.error(err);\n\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;AACZ,YAAQ,MAAM,0BAA0B;AACxC,YAAQ,MAAM,GAAG;AAEX,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;ACuCO,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,SAAS,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,SAAS,OAAO,OAAO,SAAS,CAAC;AAGvC,cAAI,QAAQ,SAAS,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;"}
+{"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\n/**\n * 处理云函数响应结果，统一返回格式\n * @param fn - 执行函数，可以返回任意类型的值或Promise\n * @param append - 需要附加到响应结果中的额外字段\n * @returns 统一格式的云函数响应结果\n *\n * @example\n * ```typescript\n * // 成功情况\n * const result = await respondCloudObject(async () => {\n *   return { name: 'test', value: 123 };\n * });\n * // 返回: { errCode: 0, errMsg: '', data: { name: 'test', value: 123 } }\n *\n * // 失败情况\n * const result = await respondCloudObject(() => {\n *   throw new Error('操作失败');\n * });\n * // 返回: { errCode: -1, errMsg: '操作失败', data: null }\n * ```\n */\nexport async function respondCloudObject<O>(\n  fn: () => MaybePromise<O>,\n  append?: AnyObject,\n): Promise<UniCloudObjectOutput<O>> {\n  try {\n    const data = await fn();\n\n    return {\n      errCode: 0,\n      errMsg: '',\n      data,\n      ...append,\n    };\n  } catch (err) {\n    console.error('respondCloudObject error');\n    console.error(err);\n\n    const err2 = errorNormalize(err as Error & { errCode?: number | string; errMsg?: string });\n\n    return {\n      errCode: err2.errCode || -1,\n      errMsg: err2.errMsg || err2.message || '',\n      // @ts-ignore\n      data: null,\n      ...append,\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  /**\n   * 响应附加数据函数\n   * 用于在云对象响应中添加额外的上下文信息\n   * @param objectThis 云对象上下文\n   * @returns 返回要附加到响应中的数据对象\n   */\n  respondAppend?: (objectThis: UniCloudObjectThis) => AnyObject;\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\n/**\n * 构建云对象暴露创建器\n *\n * 该函数用于创建一个云对象暴露函数，可以处理用户身份验证、输入验证和错误处理等通用逻辑\n *\n * @param options 构建选项配置\n * @param options.uniIdCloudObject 可选的UniIdCloudObject实例，用于处理用户身份验证和权限管理\n * @param options.requiredUserErrCode 需要用户登录态时的错误码，默认为 'uni-id-check-token-failed'\n * @param options.requiredUserErrMsg 需要用户登录态时的错误消息，默认为 '需要登录后才能进行此操作'\n *\n * @returns 返回一个云对象暴露创建函数，支持两种重载形式：\n * 1. 无输入参数的形式：(fn, options) => UniCloudObject\n * 2. 有输入验证的形式：(schema, fn, options) => UniCloudObject\n *\n * @example\n * // 无输入参数的使用方式\n * const expose = buildCloudObjectExposeCreator();\n * export default expose(async (context) => {\n *   // 业务逻辑\n * });\n *\n * @example\n * // 有输入验证的使用方式\n * const expose = buildCloudObjectExposeCreator();\n * const schema = z.object({\n *   name: z.string().min(1)\n * });\n *\n * export default expose(schema, async (context, input) => {\n *   // 业务逻辑，input类型已自动推断\n * });\n */\nexport function buildCloudObjectExposeCreator(options?: BuildCloudExposeCreatorOptions) {\n  const buildOptions = objectDefaults(options || {}, {\n    requiredUserErrCode: 'uni-id-check-token-failed',\n    requiredUserErrMsg: '需要登录后才能进行此操作',\n    respondAppend: () => ({}),\n  }) as Required<BuildCloudExposeCreatorOptions>;\n\n  // @ts-ignore\n  const createCloudObjectExpose: CreateCloudObjectExpose = (arg0, arg1, arg2) => {\n    // 确定选项来源：如果arg0是函数，则选项在arg1；否则在arg2\n    const optionsSource = (isFunction(arg0) ? arg1 : arg2) as CreateCloudObjectOptions | undefined;\n\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        // 如果需要用户登录态但用户未登录，则抛出错误\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        const parsed = arg0.safeParse(input);\n\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        // 执行业务逻辑函数，传入上下文和验证后的数据\n        return await arg1(context, parsed.data);\n      }, buildOptions.respondAppend(this));\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;ACkBsB,eAAA,mBACpB,IACA,QACkC;AAC9B,MAAA;AACI,UAAA,OAAO,MAAM,GAAG;AAEf,WAAA;AAAA,MACL,SAAS;AAAA,MACT,QAAQ;AAAA,MACR;AAAA,MACA,GAAG;AAAA,IACL;AAAA,WACO,KAAK;AACZ,YAAQ,MAAM,0BAA0B;AACxC,YAAQ,MAAM,GAAG;AAEX,UAAA,OAAO,eAAe,GAA6D;AAElF,WAAA;AAAA,MACL,SAAS,KAAK,WAAW;AAAA,MACzB,QAAQ,KAAK,UAAU,KAAK,WAAW;AAAA;AAAA,MAEvC,MAAM;AAAA,MACN,GAAG;AAAA,IACL;AAAA,EAAA;AAEJ;AC0DO,SAAS,8BAA8B,SAA0C;AACtF,QAAM,eAAe,eAAe,WAAW,IAAI;AAAA,IACjD,qBAAqB;AAAA,IACrB,oBAAoB;AAAA,IACpB,eAAe,OAAO,CAAC;AAAA,EAAA,CACxB;AAGD,QAAM,0BAAmD,CAAC,MAAM,MAAM,SAAS;AAE7E,UAAM,gBAAiB,WAAW,IAAI,IAAI,OAAO;AAGjD,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,SAAS,gBAAgB;AAClE,cAAM,SAAmC;AAAA,UACvC,SAAS;AAAA,UACT;AAAA,QACF;AACA,cAAM,UAAU,OAAO,OAAO,MAAM,MAAM;AAG1C,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;AAIrB,cAAA,SAAS,KAAK,UAAU,KAAK;AAG/B,YAAA,CAAC,OAAO,SAAS;AACX,kBAAA,IAAI,OAAO,MAAM,MAAM;AAE/B,gBAAM,SAAS,OAAO,OAAO,SAAS,CAAC;AAGvC,cAAI,QAAQ,SAAS,SAAU,OAAM,OAAO;AACtC,gBAAA,IAAI,MAAM,SAAS;AAAA,QAAA;AAI3B,eAAO,MAAM,KAAK,SAAS,OAAO,IAAI;AAAA,MAAA,GACrC,aAAa,cAAc,IAAI,CAAC;AAAA,IACrC;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

@@ -1,5 +1,5 @@
-import { AnyObject, HasProperty, IsEmptyObject, IsOnlyProperty } from '@cloudcome/utils-core/types';
-import { UniClientDatabaseOutput, UniCloudDatabaseOutput } from './types';
+import { AnyObject, HasProperty, IsEmptyObject, IsOnlyProperty, MergeIntersection } from '@cloudcome/utils-core/types';
+import { UniClientDatabaseOutput, UniCloudDatabaseOutput, UniDatabaseCommand } from './types';
 export type DbWhere<T> = {
     [K in keyof T]?: unknown;
 };
@@ -16,18 +16,23 @@ S & {
 type _DbQuery<T, S extends Record<keyof T, boolean>> = {
     [K in keyof T as S[K] extends true ? K : never]: T[K];
 };
-export type DbQuery<T, S extends DbSelect<T>> = _DbQuery<T, _DbFields<T, S>>;
+export type DbQuery<T, S extends DbSelect<T>, R> = _DbQuery<T, _DbFields<T, S>> & R;
+export type DbForeign<T, S extends DbSelect<T>, R, J extends DbJoinType, A> = Record<A & string, J extends '1:1' ? DbQuery<T, S, R> : DbQuery<T, S, R>[]>;
 export type DbCreate<T> = Partial<T>;
 export type DbUpdate<T> = Partial<T>;
 export type DbOrder<T> = Record<keyof T, 'asc' | 'desc'>;
 /**
  * 数据库操作符命令
  */
-export declare const dbCmd: UniCloud.QueryCommand;
+export declare const dbCmd: UniDatabaseCommand;
 /**
  * 数据库聚合操作符命令
  */
-export declare const dbAgg: UniCloud.AggregateCommand;
+export declare const dbAgg: UniCloud.AggregateCommand & {
+    pipeline: () => UniCloud.AggregateReference & {
+        done: () => unknown;
+    };
+};
 export type DbOptions = {
     /**
      * 数据表名称
@@ -42,7 +47,58 @@ export type DbOptions = {
      */
     _mockDatabase?: any;
 };
-export declare class Db<T, S extends DbSelect<T> = Record<string, never>> {
+/**
+ * 数据库关联类型
+ * - '1:1': 一对一关联，返回值 1 个
+ * - '1:n': 一对多关联，返回值 n 个
+ * - 'n:1': 多对一关联，返回值 n 个
+ */
+export type DbJoinType = '1:1' | '1:n' | 'n:1';
+export type DbLookupOptions<J extends DbJoinType, L, F, A> = {
+    /**
+     * 关联类型
+     */
+    type: J;
+    /**
+     * 主表字段
+     */
+    localField: keyof L & string;
+    /**
+     * 关联表字段
+     */
+    foreignField: keyof F & string;
+    /**
+     * 关联数据在结果中的字段名
+     */
+    as: A;
+};
+export type DbLookup = {
+    /**
+     * 关联表
+     */
+    table: Db<unknown>;
+    /**
+     * 关联类型
+     */
+    type: DbJoinType;
+    /**
+     * 主表字段
+     */
+    localField: string;
+    /**
+     * 关联表字段
+     */
+    foreignField: string;
+    /**
+     * 关联表名称
+     */
+    from: string;
+    /**
+     * 关联数据在结果中的字段名
+     */
+    as: string;
+};
+export declare class Db<T, S extends DbSelect<T> = {}, R extends AnyObject = {}> {
     #private;
     /**
      * 构造函数，初始化数据库集合引用
@@ -50,8 +106,9 @@ export declare class Db<T, S extends DbSelect<T> = Record<string, never>> {
      * @param _mockDatabase 模拟数据库，用于单元测试
      */
     constructor(options: DbOptions);
+    get table(): string;
     /**
-     * 创建聚合操作实例
+     * 获取聚合操作实例
      * @returns 聚合操作实例
      */
     aggregate(): UniCloud.AggregateReference;
@@ -72,7 +129,7 @@ export declare class Db<T, S extends DbSelect<T> = Record<string, never>> {
      * @param fields 要返回的字段对象，true表示返回，false表示不返回
      * @returns 当前Db实例，支持链式调用
      */
-    select<U extends DbSelect<T>>(fields: U): Db<T, U>;
+    select<U extends DbSelect<T>>(fields: U): Db<T, S & U, R>;
     /**
      * 设置排序规则
      * @param order 排序规则对象，key为字段名，value为"asc"或"desc"
@@ -91,30 +148,32 @@ export declare class Db<T, S extends DbSelect<T> = Record<string, never>> {
      * @returns 当前Db实例，支持链式调用
      */
     limit(limit: number): this;
-    /**
-     * 创建新记录
-     * @param data 要创建的数据
-     * @returns 创建结果
-     */
-    create(data: DbCreate<T>): Promise<string>;
+    get hasLookup(): boolean;
+    lookup<FT, FS extends DbSelect<FT>, FR extends AnyObject, J extends DbJoinType, A extends string>(table: Db<FT, FS, FR>, lookup: DbLookupOptions<J, T, FT, A>): Db<T, S, MergeIntersection<R & DbForeign<FT, FS, FR, J, A>>>;
     /**
      * 执行查询操作
      * @returns 查询结果
      */
-    query(): Promise<_DbQuery<T, _DbFields<T, S>>[]>;
+    query(): Promise<DbQuery<T, S, R>[]>;
     /**
      * 只查询一条，自动添加 limit(1) 条件
      * @param ignoreMiss 是否忽略没有匹配到记录
      * @returns 查询结果
      */
-    queryOne(): Promise<DbQuery<T, S>>;
-    queryOne(ignoreMiss: false): Promise<DbQuery<T, S>>;
-    queryOne(ignoreMiss: true): Promise<DbQuery<T, S> | undefined>;
+    queryOne(): Promise<DbQuery<T, S, R>>;
+    queryOne(ignoreMiss: false): Promise<DbQuery<T, S, R>>;
+    queryOne(ignoreMiss: true): Promise<DbQuery<T, S, R> | undefined>;
     /**
      * 获取匹配记录的数量
      * @returns 记录总数
      */
     count(): Promise<number>;
+    /**
+     * 创建新记录
+     * @param data 要创建的数据
+     * @returns 创建结果
+     */
+    create(data: DbCreate<T>): Promise<string>;
     /**
      * 更新记录
      * @param data 要更新的数据
@@ -127,6 +186,9 @@ export declare class Db<T, S extends DbSelect<T> = Record<string, never>> {
      */
     remove(): Promise<number>;
 }
+export type DbProxy<T, S extends DbSelect<T> = {}, R extends AnyObject = {}> = Db<T, S, R> & {
+    _isProxy: true;
+};
 /**
  * 数据库操作对象
  */
@@ -136,7 +198,7 @@ export declare const db: {
      * @param name 数据表名称
      * @returns Db类实例，用于执行数据库操作
      */
-    table<T>(name: string): Db<T>;
+    table<T, S extends DbSelect<T> = {}, R extends AnyObject = {}>(name: string): DbProxy<T>;
 };
 /**
  * 解析数据库执行结果

package/dist/database/fns.d.ts

@@ -1,18 +1,8 @@
-import { Db, DbCreate, DbQuery, DbSelect, DbUpdate, DbWhere } from './db';
-/**
- * 数据库 upsert 操作的配置选项
- *
- * @template W - 查询条件类型
- * @template S - 查询返回字段类型
- * @template C - 创建数据类型
- * @template U - 更新数据类型
- * @template R - 查询结果类型
- */
-export type DbUpsertOptions<T, W extends DbWhere<T>, S extends DbSelect<T>, C extends DbCreate<T>, U extends DbUpdate<T>> = {
-    /** 集合名称 */
-    collection: string;
+import { AnyObject } from '@cloudcome/utils-core/types';
+import { Db, DbCreate, DbProxy, DbQuery, DbSelect, DbUpdate, DbWhere } from './db';
+export type DbUpsertOptions<T, S extends DbSelect<T>, C extends DbCreate<T>, U extends DbUpdate<T>> = {
     /** 查询条件 */
-    where: W;
+    where: DbWhere<T>;
     /** 查询返回字段 */
     select?: S;
     /** 创建数据 */
@@ -21,7 +11,7 @@ export type DbUpsertOptions<T, W extends DbWhere<T>, S extends DbSelect<T>, C ex
      * 更新数据，可以是对象或根据查询结果生成更新对象的函数
      * @param row 查询到的文档数据，仅在传入函数时可用
      */
-    update: U | ((row: DbQuery<T, S>) => U);
+    update: U | ((exist: DbQuery<T, S, {}>) => U);
     /** 创建前回调函数 */
     onBeforeCreate?: () => unknown;
     /**
@@ -31,38 +21,49 @@ export type DbUpsertOptions<T, W extends DbWhere<T>, S extends DbSelect<T>, C ex
     onAfterCreate?: (id: string) => unknown;
     /**
      * 更新前回调函数
-     * @param row 查询到的文档
+     * @param exist 查询到的原始文档数据
+     * @returns 如果返回 false，则取消更新操作
+     */
+    onBeforeUpdate?: (exist: DbQuery<T, S, {}>) => false | unknown;
+    /**
+     * 更新后回调函数
+     * @param updateData 实际更新的数据
+     * @param exist 查询到的原始文档数据
      */
-    onBeforeUpdate?: (row: DbQuery<T, S>) => unknown;
-    /** 更新后回调函数 */
-    onAfterUpdate?: () => unknown;
+    onAfterUpdate?: (updateData: U, exist: DbQuery<T, S, {}>) => unknown;
     /** 用于测试的模拟数据库实例 */
-    _mockDb?: (collection: string) => any;
-};
-export declare function dbUpsert<T, W extends DbWhere<T>, S extends DbSelect<T>, C extends DbCreate<T>, U extends DbUpdate<T>>(options: DbUpsertOptions<T, W, S, C, U>): Promise<string | number>;
-type _TransactionDb = {
-    startTransaction: () => Promise<_Transaction>;
+    _mockDbInstance?: any;
 };
-type _Transaction = {
-    commit: () => Promise<unknown>;
-    rollback: () => Promise<unknown>;
+/**
+ * 数据库 upsert 操作的返回结果类型
+ */
+export type DbUpsertOutput = {
+    /** 操作的文档ID */
+    id: string;
+    /** 是否为创建操作 */
+    created: boolean;
+    /** 是否为更新操作 */
+    updated: boolean;
 };
+export declare function dbUpsert<T, S extends DbSelect<T>, C extends DbCreate<T>, U extends DbUpdate<T>>(dbProxy: DbProxy<T>, options: DbUpsertOptions<T, S, C, U>): Promise<DbUpsertOutput>;
+type _WithTransaction = <T, S extends DbSelect<T>, R extends AnyObject>(table: DbProxy<T, S, R>) => Db<T, S, R>;
 /**
  * 在数据库事务中执行操作
  *
  * @template T - 事务操作返回值类型
- * @param transact - 事务执行函数，接收事务数据库实例作为参数
- * @param _mockDatabase - 用于测试的模拟数据库实例
+ * @param transacting - 事务执行函数，接收事务数据库实例作为参数
+ * @param _mockDatabase - 用于测试的模拟数据库对象
+ * @param _mockDbInstance - 用于测试的模拟数据库实例
  * @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 });
+ * 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 };
  * });
  * ```
  */
-export declare function dbTransaction<T, S extends DbSelect<T> = {}>(transact: (ta: Db<T, S>) => Promise<unknown>, _mockDatabase?: _TransactionDb): Promise<unknown>;
+export declare function dbTransaction<K>(transacting: (withTransaction: _WithTransaction) => Promise<K>, _mockDatabase?: any, _mockDbInstance?: any): Promise<K>;
 export {};

package/dist/database/test.d.ts

@@ -0,0 +1 @@
+export {};