apass-opensdk-hugong 1.0.4 → 1.0.6

package/apass/object_.d.ts

@@ -0,0 +1,86 @@
+// Object_.d.ts
+export = Object_;
+
+declare class Object_ {
+  constructor(hg: any);
+
+  /* ===== 查询 ===== */
+
+  /**
+   * 清空表中满足条件的数据
+   * @param table  表名
+   * @param where  条件对象；省略时全部清空
+   */
+  clearData(table: string, where?: any): Promise<void>;
+
+  /**
+   * 查询列表
+   * @param table    表名
+   * @param field    需要返回的字段，默认 ['_id','_name']
+   * @param where    过滤条件
+   * @param callback 每批记录回调；提供时方法返回 void
+   * @param orderby  排序字段，默认 '_id'
+   * @returns        无 callback 时返回全部记录
+   */
+  findList<T = any>(
+    table: string,
+    field?: string[] | null,
+    where?: any,
+    callback?: (records: T[]) => Promise<void> | void,
+    orderby?: string
+  ): Promise<T[] | void>;
+
+  /**
+   * 查询单条记录
+   */
+  findOne<T = any>(
+    table: string,
+    field?: string[] | null,
+    where?: any
+  ): Promise<T | null>;
+
+  /**
+   * 根据主键查询单条记录
+   */
+  findOneById<T = any>(
+    table: string,
+    id: string | number,
+    field?: string[] | null
+  ): Promise<T | null>;
+
+  /* ===== 写入 ===== */
+
+  /**
+   * 批量创建
+   */
+  batchCreate<T = any>(table: string, list: T[]): Promise<any>;
+
+  /**
+   * 创建单条记录
+   */
+  create<T = any>(table: string, data: T): Promise<any>;
+
+  /* ===== 更新 ===== */
+
+  /**
+   * 批量更新
+   */
+  batchUpdate<T = any>(table: string, list: T[]): Promise<any>;
+
+  /**
+   * 更新单条记录
+   */
+  update<T = any>(table: string, data: T): Promise<any>;
+
+  /* ===== 删除 ===== */
+
+  /**
+   * 删除单条记录（按 _id）
+   */
+  delete(table: string, _id: string | number): Promise<any>;
+
+  /**
+   * 批量删除（按 _ids）
+   */
+  delete(table: string, _ids: (string | number)[]): Promise<any>;
+}

package/apass/object_.js

@@ -4,21 +4,21 @@ class Object_{
     this.#hg = hg
   }
 
-  async clearData(table,id){
-    await application.data.object(table).select('_id').where({_id: id ? id : application.operator.gte(0)}).findStream(async records=>{
+  async clearData(table,where){
+    await application.data.object(table).select('_id').where( where ? where : {_id : application.operator.gte(0)}).findStream(async records=>{
       this.#hg.log4('clear data len', records.length)
       await application.data.object(table).batchDelete(records.map(it=>({_id: it._id})))
     })
   }
 
-  async findList(table,field,where,callback){
+  async findList(table,field,where,callback,orderby){
     const list = []
-    await application.data.object(table).select(field || ['_id','_name']).where(where || {_id : application.operator.gte(0)}).findStream(async records=>{
+    await application.data.object(table).select(field || ['_id','_name']).where(where || {_id : application.operator.gte(0)}).orderByDesc(orderby || '_id').findStream(async records=>{
       if(callback){
-        this.#hg.log4('find all len', list.length)
+        this.#hg.log4('find all len', records.length)
         await callback(records)
       }else{
-        this.#hg.log4('find all size', list.length)
+        this.#hg.log4('find all size', records.length)
         list.push(...records)
       }
     })
@@ -36,30 +36,30 @@ class Object_{
 
   async batchCreate(table,list){
     if(list.length){
-      return await application.data.object(table).batchCreate(list)
+      return await application.data.object(table).useSystemAuth().batchCreate(list)
     }
     return null
   }
   async create(table,data){
-    return await application.data.object(table).create(data)
+    return await application.data.object(table).useSystemAuth().create(data)
   }
 
   async batchUpdate(table,list){
     if(list.length){
-      return application.data.object(table).batchUpdate(list)
+      return application.data.object(table).useSystemAuth().batchUpdate(list)
     }
     return null
   }
   async update(table,data){
-    return application.data.object(table).update(data)
+    return application.data.object(table).useSystemAuth().update(data)
   }
 
   async delete(table,_id){
-    return application.data.object(table).delete(_id)
+    return application.data.object(table).useSystemAuth().delete(_id)
   }
   async delete(table,_ids){
     if(_ids.length){
-      return application.data.object(table).batchDelete(_ids)
+      return application.data.object(table).useSystemAuth().batchDelete(_ids)
     }
     return null
   }

package/index.d.ts

@@ -0,0 +1,90 @@
+// HG.d.ts
+export = HG;
+
+declare class HG {
+  constructor(logger: any);
+
+  /* ── 公开属性 ──────────────────────────── */
+  // users: import('./opensdk/users');
+  // document: import('./opensdk/document');
+  // employee: import('./opensdk/employee');
+  // contract: import('./opensdk/contract');
+  object: import('./apass/object_');
+  utils: import('./utils/index');
+  readonly _time: number | null;
+
+  /* ── 公开方法 ──────────────────────────── */
+  setLogger(logger: any): Promise<void>;
+  initEnvAppId(): Promise<void>;
+  timeRun<T = any>(fn?: () => Promise<T>): Promise<T | null>;
+  sleep(time?: number): Promise<void>;
+
+  newTime(): void;
+  printTime(): void;
+
+  setAppId(app_id: string, app_secret: string): void;
+  getToken(): Promise<string>;
+
+  requestGet(url: string, params?: any, headers?: any): Promise<any>;
+  request(
+    url: string | [string, any],
+    data?: any,
+    headers?: any,
+    method?: string
+  ): Promise<any>;
+
+  paginatedSearchGet(
+    url: string,
+    params?: any,
+    callback?: (items: any[]) => Promise<void> | void
+  ): Promise<any[]>;
+
+  paginatedSearch(
+    url: string,
+    params?: any,
+    data?: any,
+    callback?: (items: any[]) => Promise<void> | void,
+    method?: string
+  ): Promise<any[]>;
+
+  toMultilingual(
+    zh: string | any[],
+    en?: string
+  ): any;
+
+  toText(textArr: Array<{ language_code: number; text: string }>): string;
+
+  toSafeValue<T = any>(
+    obj: Record<string, any> | null | undefined,
+    key: string,
+    defValue?: T
+  ): T;
+
+  listFind<T = any>(
+    list: T[],
+    key: keyof T,
+    target: any,
+    defValue?: T
+  ): T;
+
+  listMap<T = any>(list: T[], key: keyof T): any[];
+
+  textToFloat(textAmount?: string, defValue?: number): number;
+
+  toValue<T = any>(
+    obj: Record<string, any>,
+    path: string,
+    fallback?: T
+  ): T;
+
+  /* ── 日志工具 ──────────────────────────── */
+  log(...args: any[]): void;
+  log4(...args: any[]): void;
+  log8(...args: any[]): void;
+  logm(space: number, ...args: any[]): void;
+  error(...args: any[]): void;
+  warn(...args: any[]): void;
+
+  /* ── 语言转换 ──────────────────────────── */
+  toLanguageByList(list: any[]): any[];
+}

package/index.js

@@ -10,10 +10,6 @@ class HG{
   #app_secret
   constructor(logger){
     this.setLogger(logger)
-    this._time = null
-  }
-  setLogger(logger){
-    this.#logger = logger
     this.users = new Users(this)
     this.document = new Document(this)
     this.employee = new Employee(this)
@@ -21,6 +17,16 @@ class HG{
     this.object = new Object_(this)
     
     this.utils = new Utils(this)
+    this._time = null
+  }
+  async setLogger(logger){
+    this.#logger = logger
+    await this.initEnvAppId()
+  }
+  async initEnvAppId(){
+    this.#app_id = await application.globalVar.getVar('app_id')
+    this.#app_secret =await application.globalVar.getVar('app_secret')
+    this.log4(`app_id=${this.#app_id}，app_secret=${this.#app_secret}`)
   }
   /**
    * 运行函数
@@ -70,7 +76,7 @@ class HG{
    * @param {*} app_id 
    * @param {*} app_secret 
    */
-  setAppId(app_id,app_secret){
+   setAppId(app_id,app_secret){
     this.#app_id = app_id
     this.#app_secret = app_secret
   }
@@ -80,6 +86,9 @@ class HG{
    * @returns 
    */
   async getToken(){
+    if(!this.#app_id){
+      await this.initEnvAppId()
+    }
     const result = await this.request('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal',{ app_id: this.#app_id, app_secret: this.#app_secret},false)
     return result.tenant_access_token
   }
@@ -177,14 +186,19 @@ class HG{
         return new application.constants.type.Multilingual({ zh: _zh || _en, en: _en || _zh })
       }
       if(zh[0].hasOwnProperty('locale')){
-        const _zh = this.toSafeValue(zh.find(it=>it.locale == 'zh_CN'),'value')
-        const _en = this.toSafeValue(zh.find(it=>it.locale == 'en_US'),'value')
+        const _zh = this.toSafeValue(zh.find(it=>it.locale == 'zh_CN' || it.locale == 'zh-CN'),'value')
+        const _en = this.toSafeValue(zh.find(it=>it.locale == 'en_US' || it.locale == 'en-US'),'value')
         return new application.constants.type.Multilingual({ zh: _zh || _en, en: _en || _zh })
       }
     }
     return new application.constants.type.Multilingual({ zh: zh || en, en: en || zh })
   }
 
+  toText(textArr){
+    if(!textArr || !textArr.length) return '--'
+    return textArr.find(it=>it.language_code == '2052').text
+  }
+
   /**
    * 安全的取值
    * @param {*} obj 
@@ -214,6 +228,18 @@ class HG{
     return parseFloat((textAmount || '').replace(/,/g, '') || defValue);
   }
 
+
+  /**
+   * 从JSON中进行取值
+   * @param {*} obj 
+   * @param {*} path 
+   * @param {*} fallback 
+   * @returns 
+   */
+  toValue(obj, path, fallback = undefined) {  
+    return path.split('.').reduce((acc, key) => acc?.[key], obj) ?? fallback;
+  }
+
   log(...arg){
     this.#logger.log(...arg)
   }
@@ -227,6 +253,61 @@ class HG{
     const result = ''.padEnd(space, "-");
     this.#logger.log(result,...arg)
   }
+  error(...arg){
+    this.#logger.error(...arg)
+  }
+  warn(...arg){
+    this.#logger.warn(...arg)
+  }
+
+  toLanguageByList(list){
+    // 定义语言代码映射
+    const languageMap = {
+      1033: "en_us",
+      2052: "zh_cn"
+    };
+    // 递归处理函数
+    const processJson = (data) => {
+      const result = [];
+
+      data.forEach(item => {
+        const newItem = {};
+        for (const key in item) {
+          const value = item[key];
+          if (Array.isArray(value)) {
+            // 如果是数组，处理数组中的每个对象
+            const newList = value.map(entry => {
+              if (entry.language_code in languageMap) {
+                return { [languageMap[entry.language_code]]: entry.text };
+              }
+              return null; // 如果 language_code 不在映射中，则忽略
+            }).filter(Boolean); // 过滤掉 null 值
+            if (newList.length > 0) {
+              newItem[key] = newList.reduce((obj,item)=>({...obj, ...item}),{});
+            }
+          } else if (typeof value === 'object' && value !== null) {
+            // 如果是对象，递归处理
+            const processedValue = processJson([value])[0];
+            //console.log('processedValue',processedValue)
+            if (Object.keys(processedValue).length > 0) {
+              newItem[key] = processedValue;
+            }
+          }else{
+            newItem[key] = value
+          }
+        }
+        if (Object.keys(newItem).length > 0) {
+          result.push(newItem);
+        }
+      });
+      return result;
+    };
+    // 调用处理函数
+    const processedData = processJson(list);
+    return processedData
+  }
+
+
   
 }
 module.exports = HG

package/opensdk/employee.js

@@ -14,5 +14,21 @@ class Employee{
     return await this.#hg.paginatedSearch(`https://open.feishu.cn/open-apis/corehr/v2/employees/search`,params,data,callback)
   }
 
+  /**
+   * 批量查询员工薪资档案
+   * @param {*} _id 
+   * @param {*} user_id 
+   */
+   async archives_query(effective_start_date,effective_end_date,user_id_list,user_id_type){
+    return await this.#hg.paginatedSearch(`https://open.feishu.cn/open-apis/compensation/v1/archives/query`, {
+      page_size, 
+      user_id_type: 'people_corehr_id',
+    },{
+      user_id_list,
+      effective_start_date,
+      effective_end_date,
+    })
+  }
+
 }
 module.exports = Employee

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "apass-opensdk-hugong",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "飞书Apass低代码平台-飞书开放平台-相关的接口整合和常用的方法整合",
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/readme.md

@@ -23,13 +23,32 @@ apass-opensdk-hugong@1.0.3:
   version "1.0.3"
   resolved "https://registry.npmmirror.com/apass-opensdk-hugong/-/apass-opensdk-hugong-1.0.3.tgz#ef2d0a19e793358784cb764de4b885fd86befd66"
   integrity sha512-Q8Gpo9v8a/2G43y/Lh2POyDEOcealFuUlGdqGSA9wyfjET4+LWs/PnzK9EB1YZCjQotW7cGO/9a0MiQ6Sgw1LA==
+
+
+======
+package.json
+{
+  "dependencies": {
+    "apass-opensdk-hugong": "1.0.0"
+  }
+}
+//改成
+{
+  "dependencies": {
+    "apass-opensdk-hugong": "1.0.5"
+  }
+}
+部署后刷新页面即可生效
 ```
 
 ## 如何使用
 ```
 const Hugong = require('apass-opensdk-hugong');
-初始化
+初始化（主函数内），函数外不需要入参logger
 const hg = new Hugong(logger)
+
+如果在外部初始化后需要在函数中初始化logger模块
+hg.setLogger(logger)
 ```
 ## 常用
 ```
@@ -37,17 +56,26 @@ const hg = new Hugong(logger)
 hg.newTime()
 hg.printTime()
 
+安全的取值
+hg.toValue({....},'a.b.c','default value')
+
 线程睡眠(毫秒)
 await hg.sleep(2000)
 
-支持将数组分割成指定长度分段数组 
-第一种用法，一次性返还分割后的数组
-const list = hg.utils.splitArray([], 50) 输出  [ [50],[50] ]
-
-第二种用法，每次输出50条 处理完成后继续下次执行
-await hg.utils.splitArray([], 10, async (items)=>{
-    // do something
-})
+数组操作
+1）生成指定范围的数组
+const rangeValue = hg.utils.range(5,50, 3)
+out=[ 5, 8, 11, 14, 17, 20, 23, 26, 29, 32, 35, 38, 41, 44, 47, 50 ]
+2）数组分块
+const chunkValue = hg.utils.chunkAll(rangeValue, 5)
+out=[ [ 5, 8, 11, 14, 17 ], [ 20, 23, 26, 29, 32 ], [ 35, 38, 41, 44, 47 ], [ 50 ] ]
+数组分块输出1
+hg.utils.splitArray([....], 5) 输出  [ [50],[50] ]
+out=[ [ 5, 8, 11, 14, 17 ], [ 20, 23, 26, 29, 32 ], [ 35, 38, 41, 44, 47 ], [ 50 ] ]
+数组分块输出2，每次输出50条 处理完成后继续下次执行
+await hg.utils.splitArray([...], 10, async (items)=>{ // do something  })
+移除重复项
+hg.utils.unique([1,2,3,1,2,3]) // [1,2,3]
 
 ```
 ## 文件上传/下载
@@ -61,18 +89,25 @@ await hg.utils.file.downloadFileToUpload(url,{ Authorization: `...`})
 saveDataToEnv(data，path) 
 
 1）从飞书租户空间下载文件到本地环境中
-file_info={ id, mime_type, name, ...}
-file_path=存储地址可选,不填写则默认当前时间戳
+  file_info={ id, mime_type, ...}
+  file_path=存储地址可选,不填写则默认当前时间戳
 await hg.utils.file.downloadFileToTmp(fileInfo,file_path)
+如果是token文件
+file_info={ token, mime_type, ...}
+await hg.utils.file.downloadFileByToeknToTmp(file_info，file_path)
 
 2）解析csv文件,file_path必须是本地环境的文件路径 /tep/aaa.csv 可以使用上面的方法downloadFileToTmp下载文件到本地环境中
 await hg.utils.file.csvRead(file_path,callback)
 示例1 读取完成后返回数组
 const list = await hg.utils.file.csvRead(file_path)
-示例2 读取完成后回调
+示例2 读取完成后回调， 超过5000条建议使用此方法防止内存溢出
 await hg.utils.file.csvRead(file_path,async (row)=>{
     // do something
 })
+
+3）解析excel文件,file_path必须是本地环境的文件路径 /tep/aaa.xlsx 可以使用上面的方法downloadFileToTmp下载文件到本地环境中
+const list = hg.utils.file.xlsxReaderAll(file_path)
+list是excel所有的内容，建议小文件使用(10M以下)，如果是大文件10M以上转换成csv使用上面的方法，亲自测试10万条csv读取正常
 ```
 
 ## 小工具/多语言
@@ -84,8 +119,7 @@ await hg.utils.file.csvRead(file_path,async (row)=>{
 hg.toMultilingual([{ lang: 'en-US', value: 'Regular' },{ lang: 'zh-CN', value: '正式' }]) 常用于开放平台返回的多语言数据转换
 hg.toMultilingual(zh,en)
 
-安全的取值
-hg.toSafeValue(obj={},key,defValue)
+
 
 ```
 

package/utils/date_.d.ts

@@ -0,0 +1,35 @@
+// Date_.d.ts
+export = Date_;
+
+declare class Date_ {
+  constructor(hg: any);
+
+  /**
+   * 把日期字符串解析成时间戳（毫秒）
+   */
+  dateStringToTimestamp(dateString: string): number;
+
+  /**
+   * 返回 moment-timezone 实例（已默认 Asia/Shanghai）
+   */
+  moment(date?: string | number | Date): import('moment-timezone').Moment;
+
+  /**
+   * 当前时间按指定格式输出（默认 YYYY-MM-DD HH:mm:ss）
+   */
+  nowFormat(format?: string): string;
+
+  /**
+   * 把起止日期按指定月份跨度拆分成若干段
+   */
+  splitDateRange(
+    startDate: string,
+    endDate: string,
+    splitMonths: number
+  ): Array<{
+    begin: string;  // yyyy-mm-dd
+    end: string;    // yyyy-mm-dd
+    len: number;    // 实际月份数
+    days: number;   // 实际天数
+  }>;
+}

package/utils/date_.js

@@ -4,10 +4,17 @@ class Date_{
   constructor(hg){
     this.#hg = hg
   }
-  moment(){
+
+  dateStringToTimestamp(dateString){
+    const timestamp = Date.parse(dateString);
+    //this.#hg.log4(`dateString=${dateString}, timestamp=${timestamp}`)
+    return timestamp
+  }
+  
+  moment(date){
     const moment = require('moment-timezone');
     moment.tz.setDefault("Asia/Shanghai");
-    return moment()
+    return moment(date || Date.now())
   }
   nowFormat(format) {
     const moment = require('moment-timezone');

package/utils/file_.d.ts

@@ -0,0 +1,77 @@
+// File_.d.ts
+export = File_;
+
+declare class File_ {
+  constructor(hg: any);
+
+  /** 生成当前时间文件夹名：yyyy-MM-dd_HH-mm-ss */
+  getCurrentTimeFolderName(): string;
+
+  /**
+   * 网络下载文件并上传到租户空间
+   * @param url 网络文件地址
+   * @param header 可选请求头
+   * @returns 上传后的文件信息
+   */
+  downloadFileToUpload(
+    url: string,
+    header?: Record<string, string>
+  ): Promise<FileInfo>;
+
+  /**
+   * 下载租户空间的文件到环境 tmp 目录
+   * @param file_info 文件元数据
+   * @param file_path 本地存储路径（可选）
+   * @returns 本地文件路径
+   */
+  downloadFileToTmp(
+    file_info: FileInfo,
+    file_path?: string
+  ): Promise<string>;
+
+  /**
+   * 使用 token 下载文件到环境 tmp 目录
+   * @param file_info 必须包含 token 与 mime_type
+   * @param file_path 本地存储路径（可选）
+   * @returns 本地文件路径
+   */
+  downloadFileByToeknToTmp(
+    file_info: Pick<FileInfo, 'token' | 'mime_type'>,
+    file_path?: string
+  ): Promise<string>;
+
+  /**
+   * 将数据追加写入文件
+   * @param data 写入内容
+   * @param fileName 文件名（可选）
+   */
+  saveDataToEnv(data: string, fileName?: string): void;
+
+  /**
+   * 读取 CSV 文件（依赖 csv-parser）
+   * @param path 文件路径
+   * @param callback 每行回调，返回 void 时一次性返回所有行
+   * @returns 无回调时返回全部行
+   */
+  csvRead<T = Record<string, any>>(
+    path: string,
+    callback: (row: T, index: number) => void
+  ): Promise<void>;
+  csvRead<T = Record<string, any>>(path: string): Promise<T[]>;
+
+  /**
+   * 读取 Excel 文件（依赖 xlsx@0.18.5）
+   * @param filePath 文件路径
+   * @returns 工作表第一页的全部数据
+   */
+  xlsxReaderAll(filePath: string): any[];
+}
+
+/* ── 依赖类型 ─────────────────────────────── */
+interface FileInfo {
+  id?: string;
+  token?: string;
+  mime_type: string;
+  name?: string;
+  [key: string]: any;
+}

package/utils/file_.js

@@ -41,6 +41,13 @@ class File_{
     this.#hg.log4(`download success, path=` + _file_path)
     return _file_path
   }
+  async downloadFileByToeknToTmp(file_info, file_path){
+    this.#hg.log4(`download input=${ JSON.stringify(file_info)}`)
+    const _file_path = file_path || `/tmp/${Date.now()}.${ file_info.mime_type }`
+    await application.resources.file.download(file_info.token, _file_path);
+    this.#hg.log4(`download success, path=` + _file_path)
+    return _file_path
+  }
   /**
    * 写入文件
    * @param {*} data 写入的内容
@@ -50,7 +57,7 @@ class File_{
     fs.writeFileSync(fileName || `${ Date.now() }.txt`,data, { flag: 'a' })
   }
   /**
-   * 读取Excel文件（需要安装依赖：csv-parser）
+   * 读取csv文件（需要安装依赖：csv-parser）
    * @param {*} path 
    * @param {*} callback(row) 每一行的回调
    * @returns  callback为null时，返回全部读取的结果list
@@ -59,10 +66,11 @@ class File_{
     const csv = require('csv-parser');
     return await new Promise((resolve, reject) => {
       const list = []
+      let index = 0
       fs.createReadStream(path).pipe(csv())
       .on('data', (row) => {
         if(callback){
-          callback(row)
+          callback(row,index++)
         }else{
           list.push(row)
         }
@@ -76,14 +84,26 @@ class File_{
     })
   }
 
-  async excelReader(path,callback){
+  /**
+   * 读取Excel文件（需要安装依赖：xlsx@0.18.5）
+   * @param {*} filePath 
+   * @returns 返回文件内容
+   */
+  xlsxReaderAll(filePath){
     const XLSX = require('xlsx');
-    const stream = fs.createReadStream(path.join(__dirname, 'example.xlsx'));
-    const workbook = XLSX.read(stream, { type: 'buffer' });
-    const sheetName = workbook.SheetNames[0];
-    const worksheet = workbook.Sheets[sheetName];
-    const data = XLSX.utils.sheet_to_json(worksheet);
-    console.log(data);
+    let data = []
+    try {
+      const buffer = fs.readFileSync(filePath)
+      const workbook = XLSX.read(buffer, { type: 'buffer' });
+      const sheetName = workbook.SheetNames[0];
+      this.#hg.log4('Sheet Name:', sheetName);
+      const worksheet = workbook.Sheets[sheetName];
+      data = XLSX.utils.sheet_to_json(worksheet);
+      this.#hg.log4('Data:', data);
+    } catch (error) {
+      this.#hg.error('xlsxReaderAll - Error parsing Excel file:', error);
+    }
+    return data
   }
 }
 module.exports = File_

package/utils/index.d.ts

@@ -0,0 +1,44 @@
+
+// Utils.d.ts
+export = Utils;
+
+declare class Utils {
+  constructor(hg: any);
+
+  /** 网络/文件/日期 子模块 */
+  readonly url: import('./url');
+  readonly file: import('./file_');
+  readonly date: import('./date_');
+
+  /**
+   * 数组分块（支持同步/异步回调）
+   * @param list      原始数组
+   * @param chunkSize 每块长度
+   * @param callback  每块回调；如提供，则整体返回 void
+   * @returns         无回调时返回分块后的二维数组
+   */
+  splitArray<T = any>(
+    list: T[],
+    chunkSize: number,
+    callback?: (batch: T[]) => Promise<void> | void
+  ): Promise<T[][] | void>;
+
+  /** 计算字符串 MD5 */
+  toMD5(data: string): string;
+
+  /** 按区域与币种格式化金额 */
+  formatCurrency(
+    amount: number,
+    locale?: string,
+    currency?: string
+  ): string;
+
+  /** 将数组按固定大小分块（同步） */
+  chunkAll<T = any>(arr: T[], size: number): T[][];
+
+  /** 生成指定步长的数值范围数组 */
+  range(start: number, end: number, step?: number): number[];
+
+  /** 数组去重 */
+  unique<T = any>(arr: T[]): T[];
+}

package/utils/index.js

@@ -42,5 +42,48 @@ class Utils{
     return md5Hash
   }
 
+
+  /**
+   * 格式化货币
+   * @param {*} amount 
+   * @param {*} locale 
+   * @param {*} currency 
+   * @returns 
+   */
+   formatCurrency(amount, locale = 'en-US', currency = 'USD') {  
+    return new Intl.NumberFormat(locale, { style: 'currency',    currency,  }).format(amount);
+  }
+
+  /**
+   * 分块数组
+   * @param {*} arr 
+   * @param {*} size 
+   * @returns 
+   */
+  chunkAll(arr, size) {  
+    return Array.from({ length: Math.ceil(arr.length / size) }, (_, i) => arr.slice(i * size, i * size + size));
+  }
+
+
+  /**
+   * 范围生成器
+   * @param {*} start 
+   * @param {*} end 
+   * @param {*} step 
+   * @returns 
+   */
+  range(start, end, step = 1) {  
+    return Array.from({ length: (end - start) / step + 1 }, (_, i) => start + i * step);
+  }
+  
+  /**
+   * 移除重复项
+   * @param {*} arr 
+   * @returns 
+   */
+  unique(arr) {
+    return [...new Set(arr)];
+  }
+
 }
 module.exports = Utils