apass-opensdk-hugong 1.0.5 → 1.0.7

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

@@ -1,69 +1,186 @@
-class Object_{
+class Object_ {
   #hg = null
-  constructor(hg){
+  constructor(hg) {
     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=>{
+  /**
+   * 清空表中满足条件的数据
+   * @param table  表名
+   * @param where  条件对象；省略时全部清空
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   */
+  async clearData(table, where, useSystemAuth = false) {
+    const object = application.data.object(table).select('_id').where(where ? where : { _id: application.operator.gte(0) })
+    if (useSystemAuth) {
+      object.useSystemAuth()
+    }
+    await object.findStream(async records => {
       this.#hg.log4('clear data len', records.length)
-      await application.data.object(table).batchDelete(records.map(it=>({_id: it._id})))
+      const object = application.data.object(table)
+      if (useSystemAuth) {
+        object.useSystemAuth()
+      }
+      await object.batchDelete(records.map(it => ({ _id: it._id })))
     })
   }
 
-  async findList(table,field,where,callback){
+  /**
+   * 查询列表
+   * @param table    表名
+   * @param field    需要返回的字段，默认 ['_id','_name']
+   * @param where    过滤条件
+   * @param callback 每批记录回调；提供时方法返回 void
+   * @param orderby  排序字段，默认 '_id'
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   * @returns        无 callback 时返回全部记录
+   */
+  async findList(table, fields, where, callback, orderby, useSystemAuth = false) {
     const list = []
-    await application.data.object(table).select(field || ['_id','_name']).where(where || {_id : application.operator.gte(0)}).findStream(async records=>{
-      if(callback){
-        this.#hg.log4('find all len', list.length)
+    const object = application.data.object(table).select(fields || ['_id', '_name']).where(where || { _id: application.operator.gte(0) }).orderByDesc(orderby || '_id')
+    if (useSystemAuth) {
+      object.useSystemAuth()
+    }
+    await object.findStream(async records => {
+      if (callback) {
+        this.#hg.log4('find all len', records.length)
         await callback(records)
-      }else{
-        this.#hg.log4('find all size', list.length)
+      } else {
+        this.#hg.log4('find all size', records.length)
         list.push(...records)
       }
     })
-    if(!callback){
+    if (!callback) {
       this.#hg.log4('find all len', list.length)
     }
     return list
   }
-  async findOne(table,field,where){
-    return await application.data.object(table).select(field || ['_id','_name']).where(where || {_id : application.operator.gte(0)}).findOne()
+  /**
+   * 查询单条记录
+   * @param table  表名
+   * @param field  需要返回的字段，默认 ['_id','_name']
+   * @param where  过滤条件
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   * @returns      记录对象或 null
+   */
+  async findOne(table, fields, where, useSystemAuth = false) {
+    const object = application.data.object(table).select(fields || ['_id', '_name']).where(where || { _id: application.operator.gte(0) })
+    if (useSystemAuth) {
+      object.useSystemAuth()
+    }
+    return await object.findOne()
   }
-  async findOneById(table,id,field){
-    return await application.data.object(table).select(field || ['_id','_name']).where({_id: id}).findOne()
+  /**
+   * 根据 ID 查询单条记录
+   * @param table  表名
+   * @param id     记录 ID
+   * @param fields 需要返回的字段，默认 ['_id','_name']
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   * @returns      记录对象或 null
+   */
+  async findOneById(table, id, fields, useSystemAuth = false) {
+    const object = application.data.object(table).select(fields || ['_id', '_name']).where({ _id: id })
+    if (useSystemAuth) {
+      object.useSystemAuth()
+    }
+    return await object.findOne()
   }
 
-  async batchCreate(table,list){
-    if(list.length){
-      return await application.data.object(table).batchCreate(list)
+  /**
+   * 批量创建记录
+   * @param table  表名
+   * @param list   记录列表
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   * @returns      创建的记录 ID 列表或 null
+   */
+  async batchCreate(table, list, useSystemAuth = false) {
+    if (list.length) {
+      const object = application.data.object(table)
+      if (useSystemAuth) {
+        object.useSystemAuth()
+      }
+      return await object.batchCreate(list)
     }
     return null
   }
-  async create(table,data){
-    return await application.data.object(table).create(data)
+  /**
+   * 创建单条记录
+   * @param table  表名
+   * @param data   记录数据
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   * @returns      创建的记录 ID 或 null
+   */
+  async create(table, data, useSystemAuth = false) {
+    const object = application.data.object(table)
+    if (useSystemAuth) {
+      object.useSystemAuth()
+    }
+    return await object.create(data)
   }
 
-  async batchUpdate(table,list){
-    if(list.length){
-      return application.data.object(table).batchUpdate(list)
+  /**
+   * 批量更新记录
+   * @param table  表名
+   * @param list   记录列表
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   * @returns      更新的记录 ID 列表或 null
+   */
+  async batchUpdate(table, list, useSystemAuth = false) {
+    if (list.length) {
+      const object = application.data.object(table)
+      if (useSystemAuth) {
+        object.useSystemAuth()
+      }
+      return await object.batchUpdate(list)
     }
     return null
   }
-  async update(table,data){
-    return application.data.object(table).update(data)
+  /**
+   * 更新单条记录
+   * @param table  表名
+   * @param data   记录数据
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   * @returns      更新的记录 ID 或 null
+   */
+  async update(table, data, useSystemAuth = false) {
+    const object = application.data.object(table)
+    if (useSystemAuth) {
+      object.useSystemAuth()
+    }
+    return await object.update(data)
   }
-
-  async delete(table,_id){
-    return application.data.object(table).delete(_id)
+  /**
+   * 删除单条记录
+   * @param table  表名
+   * @param _id    记录 ID
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   * @returns      删除的记录 ID 或 null
+   */
+  async deleteOne(table, _id, useSystemAuth = false) {
+    const object = application.data.object(table)
+    if (useSystemAuth) {
+      object.useSystemAuth()
+    }
+    return await object.delete(_id)
   }
-  async delete(table,_ids){
-    if(_ids.length){
-      return application.data.object(table).batchDelete(_ids)
+  /**
+   * 批量删除记录
+   * @param table  表名
+   * @param _ids   记录 ID 列表
+   * @param useSystemAuth 是否使用系统权限；默认 false
+   * @returns      删除的记录 ID 列表或 null
+   */
+  async deleteBatchByIds(table, _ids, useSystemAuth = false) {
+    if (_ids.length) {
+      const object = application.data.object(table)
+      if (useSystemAuth) {
+        object.useSystemAuth()
+      }
+      return await object.batchDelete(_ids)
     }
     return null
   }
-  
+
 
 }
 module.exports = Object_

package/index.d.ts

@@ -0,0 +1,79 @@
+declare module 'HG' {
+  import { AxiosRequestConfig, AxiosResponse } from 'axios';
+
+  export interface HGLogger {
+    log:   (...args: any[]) => void;
+    error: (...args: any[]) => void;
+    warn:  (...args: any[]) => void;
+  }
+
+  export interface MultilingualData {
+    zh?: string;
+    en?: string;
+  }
+
+  export default class HG {
+    constructor(logger: HGLogger);
+
+    /* 属性 */
+    readonly object: any;   // 对应 new Object_(this)
+    readonly utils: any;     // 对应 new Utils(this)
+    private _time: number | null;
+
+    /* 公有方法 */
+    setLogger(logger: HGLogger): Promise<void>;
+
+    /* 计时相关 */
+    timeRun<T = any>(fn?: () => T | Promise<T>): Promise<T>;
+    newTime(): void;
+    printTime(): void;
+
+    /* 工具方法 */
+    sleep(time?: number): Promise<void>;
+
+    /* 网络请求 */
+    request<T = any>(config: AxiosRequestConfig): Promise<T>;
+    axios<T = any>(config: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+
+    /* 多语言 */
+    toMultilingualByOpenPlatform(
+      zh: string | any[],
+      en?: string
+    ): application.constants.type.Multilingual;
+
+    toTextByMultilingual(
+      textArr: Array<{ language_code: string; text: string }>
+    ): string;
+
+    /* JSON 取值 */
+    toValue<T = any>(
+      obj: any,
+      path: string,
+      defaultValue?: T
+    ): T | undefined;
+
+    /* 数组辅助 */
+    listFind<T = any>(
+      list: T[],
+      key: keyof T,
+      target: any,
+      defValue?: T
+    ): T | undefined;
+
+    listMap<T = any, K extends keyof T = keyof T>(
+      list: T[],
+      key: K
+    ): Array<T[K]>;
+
+    /* 字符串转数字 */
+    textToFloat(textAmount: string | number | null | undefined, defValue?: number): number;
+
+    /* 日志 */
+    log(...arg: any[]): void;
+    log4(...arg: any[]): void;
+    log8(...arg: any[]): void;
+    logm(space: number, ...arg: any[]): void;
+    error(...arg: any[]): void;
+    warn(...arg: any[]): void;
+  }
+}

package/index.js

@@ -1,25 +1,14 @@
-const Users = require('./opensdk/users')
-const Document = require('./opensdk/document')
 const Utils = require('./utils/index')
-const Employee = require('./opensdk/employee')
-const Contract = require('./opensdk/contract')
 const Object_ = require('./apass/object_')
-class HG{
+class HG {
   #logger
-  #app_id
-  #app_secret
-  constructor(logger){
+  constructor(logger) {
     this.setLogger(logger)
-    this.users = new Users(this)
-    this.document = new Document(this)
-    this.employee = new Employee(this)
-    this.contract = new Contract(this)
     this.object = new Object_(this)
-    
     this.utils = new Utils(this)
     this._time = null
   }
-  setLogger(logger){
+  async setLogger(logger) {
     this.#logger = logger
   }
   /**
@@ -27,10 +16,10 @@ class HG{
    * @param {*} fn 
    * @returns 
    */
-  async timeRun(fn){
+  async timeRun(fn) {
     this.newTime()
     let result = null
-    if(fn){
+    if (fn) {
       result = await fn()
     }
     this.printTime()
@@ -41,16 +30,16 @@ class HG{
    * @param {*} time 毫秒
    * @returns 
    */
-  async sleep(time){
-    return new Promise((r)=>setTimeout(()=>{ this.log4(`sleep ${(time || 1000)/1000}s`);r();},time || 1000))
+  async sleep(time) {
+    return new Promise((r) => setTimeout(() => { this.log4(`sleep ${(time || 1000) / 1000}s`); r(); }, time || 1000))
   }
 
   /**
    * 时间计划-记录
    */
-  newTime(){
-    if(this._time){
-      this.log4('#time reset to before',(Date.now() - this._time)/1000, 's')
+  newTime() {
+    if (this._time) {
+      this.log4('#time reset to before', (Date.now() - this._time) / 1000, 's')
     }
     this.log4('#time reset')
     this._time = Date.now()
@@ -58,175 +47,107 @@ class HG{
   /**
    * 时间计划-打印耗时
    */
-  printTime(){
-    if(!this._time){
-      return this.#logger.error('#time Error','The time has not been initialized ')
+  printTime() {
+    if (!this._time) {
+      return this.#logger.error('#time Error', 'The time has not been initialized ')
     }
-    this.log4('#time',(Date.now() - this._time)/1000, 's')
+    this.log4('#time', (Date.now() - this._time) / 1000, 's')
   }
 
   /**
-   * 设置app_id
-   * @param {*} app_id 
-   * @param {*} app_secret 
-   */
-  setAppId(app_id,app_secret){
-    this.#app_id = app_id
-    this.#app_secret = app_secret
-  }
-
-  /**
-   * 开平token
+   * 统一网络请求(使用axios)
+   * @param {*} config 
    * @returns 
    */
-  async getToken(){
-    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
-  }
-
-  async requestGet(url, params, headers=true){
-    return this.request([url, params], null, headers, 'GET')
-  }
-
-  /**
-   * 统一网络请求
-   * @param {*} url 
-   * @param {*} params 
-   * @param {*} data 
-   * @param {*} headers 
-   * @param {*} method 
-   * @returns 
-   */
-  async request(url, data, headers = true, method = 'POST'){
-    let newHeaders = { 'Content-Type': 'application/json; charset=utf-8' }
-    if(typeof headers === 'boolean' && headers === true){
-      newHeaders['Authorization'] = `Bearer ${ await this.getToken() }`
-    }else{
-      newHeaders = { ...newHeaders,...(headers || {}) }
-    }
-    this.log4('req =',url,data,newHeaders)
-    let _url = url
-    let params = null
-    if(Array.isArray(url)){
-      _url = url[0]
-      params =  url[1]
-    }
-    return new Promise((r,s)=>{
+  async request(config) {
+    this.log4('req =', config)
+    return new Promise((r, s) => {
       const now = Date.now()
-      axios({ method, params, url: _url, data, headers: newHeaders}).then(response=>{
-        this.log8('resp =',(Date.now() - now) / 1000, 's',response.status, response.statusText,response.data)
+      axios(config).then(response => {
+        this.log8('resp =', (Date.now() - now) / 1000, 's', response.status, response.statusText, response.data)
         r(response.data)
-      }).catch(e=>{
-        console.log(e)
-        this.#logger.error('resp =',(Date.now() - now) / 1000, 's',e.response.data)
-        s(e.response.data)
+      }).catch(err => {
+        this.#logger.error('resp =', (Date.now() - now) / 1000, 's', err.response.data)
+        s(err.response.data)
       })
     })
   }
   /**
-   * 分页返回开放平台数据
-   * @param {*} url 
-   * @param {*} params 
-   * @param {*} callback callback(items) 结果回调（根据总数可能多次调用）- 可选
-   * @returns 如果callback为传递则一次性返回所有的数据
-   */
-  async paginatedSearchGet(url,params,callback){
-    return this.paginatedSearch(url, params, null, callback, 'GET')
-  }
-  /**
-   * 分页返回开放平台数据
-   * @param {*} url 
-   * @param {*} params 
-   * @param {*} data 
-   * @param {*} callback callback(items) 结果回调（根据总数可能多次调用）- 可选
-   * @returns 如果callback为传递则一次性返回所有的数据
+   * 直接调用axios
+   * @param {*} config 
+   * @returns 
    */
-   async paginatedSearch(url,params,data,callback,method='POST'){
-    let list =  []
-    let page_token = null
-    let has_more = false
-    do {
-      const result = await this.request([url, {...(params || {page_size: 100}), page_token}],data,true,method)
-      page_token = result.data.page_token
-      has_more = result.data.has_more
-      if(callback){
-          await callback(result.data.hasOwnProperty('items') ? result.data.items || [] : result.data)
-      }else{
-        if(result.data.hasOwnProperty('items')){
-          list.push(...(result.data.items || []))
-        }else{
-          list.push(result.data)
-        }
-      }
-    } while (has_more);
-    return list
+  axios(config) {
+    return axios(config)
   }
-
   /**
-   * 生成多语言对象
+   * 生成多语言对象(将开放平台返回的多语言对象转换为application.constants.type.Multilingual)
    * @param {*} zh 
    * @param {*} en 
    * @returns 
    */
-  toMultilingual(zh,en){
-    if(Array.isArray(zh)){
-      //开放平台一般返回内容
-      if(zh[0].hasOwnProperty('lang')){
-        const _zh = this.toSafeValue(zh.find(it=>it.lang == 'zh-CN'),'value')
-        const _en = this.toSafeValue(zh.find(it=>it.lang == 'en-US'),'value')
+  toMultilingualByOpenPlatform(zh, en) {
+    if (Array.isArray(zh)) {
+      if (zh[0].hasOwnProperty('lang')) {
+        const _zh = this.toValue(zh.find(it => it.lang == 'zh-CN'), 'value')
+        const _en = this.toValue(zh.find(it => it.lang == 'en-US'), 'value')
         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')
+      if (zh[0].hasOwnProperty('locale')) {
+        const _zh = this.toValue(zh.find(it => it.locale == 'zh_CN' || it.locale == 'zh-CN'), 'value')
+        const _en = this.toValue(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 })
   }
-
   /**
-   * 安全的取值
+   * 从多语言对象中获取中文
+   * @param {*} textArr 
+   * @returns 
+   */
+  toTextByMultilingual(textArr) {
+    if (!textArr || !textArr.length) return '--'
+    return textArr.find(it => it.language_code == '2052').text
+  }
+  /**
+   * 从JSON中根据路径获取值
    * @param {*} obj 
-   * @param {*} key 
-   * @param {*} defValue 
+   * @param {*} path 
+   * @param {*} defaultValue 
    * @returns 
    */
-  toSafeValue(obj,key,defValue){
-    const _obj = obj || {}
-    if(!_obj){
-      return defValue
-    }
-    if(!_obj.hasOwnProperty(key)){
-      return defValue
-    }
-    return _obj[key] || defValue
+  toValue(obj, path, defaultValue = undefined) {
+    return path.split('.').reduce((acc, key) => acc?.[key], obj) ?? defaultValue;
   }
-
-  listFind(list,key,target,defValue){
-    return list.find(it=>it[ key ] == target) || defValue
+  listFind(list, key, target, defValue) {
+    return list.find(it => it[key] == target) || defValue
   }
-  listMap(list,key){
-    return list.map(it=>it[ key ])
+  listMap(list, key) {
+    return list.map(it => it[key])
   }
-
-  textToFloat(textAmount,defValue = 0) {
+  textToFloat(textAmount, defValue = 0) {
     return parseFloat((textAmount || '').replace(/,/g, '') || defValue);
   }
 
-  log(...arg){
+  log(...arg) {
     this.#logger.log(...arg)
   }
-  log4(...arg){
-    this.logm(4,...arg)
+  log4(...arg) {
+    this.logm(4, ...arg)
   }
-  log8(...arg){
-    this.logm(8,...arg)
+  log8(...arg) {
+    this.logm(8, ...arg)
   }
-  logm(space,...arg){
+  logm(space, ...arg) {
     const result = ''.padEnd(space, "-");
-    this.#logger.log(result,...arg)
+    this.#logger.log(result, ...arg)
+  }
+  error(...arg) {
+    this.#logger.error(...arg)
+  }
+  warn(...arg) {
+    this.#logger.warn(...arg)
   }
-  
 }
 module.exports = HG

package/package.json

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

package/readme.md

@@ -1,56 +1,54 @@
 # apass-opensdk-hugong
 ## 简介
-apass-opensdk-hugong 是一个基于apass-opensdk的封装，提供了一些常用的功能
+apass-opensdk-hugong 是一个Nodejs的SDK，提供了一些常用的功能
 - 什么人可以使用这个SDK
-- 从事飞书低代码平台（APASS）开发人员.
+- 从事飞书低代码平台（APASS）开发人员.传统Nodejs开发人员.
 
 ## 安装
 
 ```
 在飞书低代码平台（云函数）依赖管理-右侧-搜索： apass-opensdk-hugong
-
-最近有同学私聊我说Apass无法安装1.0.0以上的包，解决思路： 先安装1.0.0版本，然后打开yarn.lock文件
-====== 找到这一行 =====
-apass-opensdk-hugong@1.0.0:
-  version "1.0.0"
-  resolved "https://registry.npmmirror.com/apass-opensdk-hugong/-/apass-opensdk-hugong-1.0.0.tgz#ef2d0a19e793358784cb764de4b885fd86befd66"
-  integrity sha512-Q8Gpo9v8a/2G43y/Lh2POyDEOcealFuUlGdqGSA9wyfjET4+LWs/PnzK9EB1YZCjQotW7cGO/9a0MiQ6Sgw1LA==
-====== 找到这一行 =====
-
-将版本改为最新的版本号后，然后保存，重写部署即可使用NPM源最新的版本
-修改后的yarn.lock文件如下， 一共三处地方：
-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==
 ```
 
 ## 如何使用
 ```
 const Hugong = require('apass-opensdk-hugong');
-初始化
+初始化（主函数内），函数外不需要入参logger
 const hg = new Hugong(logger)
+
+也可以单独初始化logger模块
+hg.setLogger(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]
 
 ```
-## 文件上传/下载
+## Apass相关，文件上传/下载
 
 ```
 1）从网络下载文件后上传到飞书租户空间，返回上传后的文件信息
@@ -61,18 +59,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读取正常
 ```
 
 ## 小工具/多语言
@@ -80,75 +85,12 @@ 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)
+生成多语言对象(将开放平台返回的多语言对象转换为application.constants.type.Multilingual)
+hg.toMultilingualByOpenPlatform([{ lang: 'en-US', value: 'Regular' },{ lang: 'zh-CN', value: '正式' }]) 
+hg.toMultilingualByOpenPlatform(zh,en)
 
 ```
 
-## 飞书人事
-
-搜索员工信息
-
-```
-设置appid和appsecret
-await hg.setAppId('cli_000000000','0000000000000')
-
-/**
-* 搜索员工信息
-* @param {*} params 
-* @param {*} data 
-* @param {*} callback callback(items) 结果回调（根据总数可能多次调用）- 可选
-* @returns 如果callback为传递则一次性返回所有的数据
-*/
-await hg.employee.search(params,data,callback)
-
-// 示例[具体参数请参考开放平台定义](https://open.feishu.cn/document/server-docs/corehr-v1/employee/search)
-await hg.employee.search({ page_size:100,user_id_type:'user_id',},{ /* 要查询的字段 */}, async (items)=>{
-    // do something 假设服务端有300条数据，每次返回100条，会调用3次, 如果希望一次性返回所有数据，callback传null即可
-})
-const list = await hg.employee.search(params,data) //这将一次性返回所有数据
-```
-## 开放平台分页获取所有数据
-
-所有的分页接口都可以使用
-
-```
-设置appid和appsecret
-await hg.setAppId('cli_000000000','0000000000000')
-
-/**
-* GET类型接口分页返回开放平台数据
-* @param {*} url 
-* @param {*} params 
-* @param {*} callback callback(items) 结果回调（根据总数可能多次调用）- 可选
-* @returns callback为null，则一次性返回所有的数据
-*/
-hg.paginatedSearchGet(url,params,callback)
-
-/**
-* POST接口分页返回开放平台数据
-* @param {*} url 
-* @param {*} params 
-* @param {*} data 
-* @param {*} callback callback(items) 结果回调（根据总数可能多次调用）- 可选
-* @returns callback为null，则一次性返回所有的数据
-*/
-await hg.paginatedSearch(url,params,data,callback)
-
-示例1
-const list = await hg.paginatedSearchGet(url, params, data)
-示例2
-await hg.paginatedSearchGet(url, params, async (items)=>{
-    // do something  假设服务端有300条数据，每次返回100条，会调用3次, 如果希望一次性返回所有数据，callback传null即可
-})
-```
-
-
-
 ## 交流学习
 
 从事飞书低代码平台（APASS）开发人员3年，欢迎交流学习

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

@@ -1,9 +1,9 @@
 const Url = require('./url')
 const File_ = require('./file_')
 const Date_ = require('./date_')
-class Utils{
+class Utils {
   #hg = null
-  constructor(hg){
+  constructor(hg) {
     this.#hg = hg
 
     this.url = new Url(hg)
@@ -18,13 +18,13 @@ class Utils{
    * @param {*} callback(item) 分割后回调(不传递则方法返回切割长度后的数组)
    * @returns 
    */
-   async splitArray(list, chunkSize, callback) {
+  async splitArray(list, chunkSize, callback) {
     const result = [];
     this.#hg.log4('splitArray len ', list.length)
     for (let i = 0; i < list.length; i += chunkSize) {
       const batch = list.slice(i, i + chunkSize)
-      this.#hg.log8('splitArray item ',i, i + chunkSize)
-      if(callback){
+      this.#hg.log8('splitArray item ', i, i + chunkSize)
+      if (callback) {
         await callback(batch)
         continue
       }
@@ -33,7 +33,7 @@ class Utils{
     return result;
   }
 
-  toMD5(data){
+  toMD5(data) {
     const crypto = require('crypto');
     const hash = crypto.createHash('md5');
     hash.update(data);
@@ -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

package/opensdk/contract.js

@@ -1,17 +0,0 @@
-class Contract{
-  #hg = null
-  constructor(hg){
-    this.#hg = hg
-  }
-  
-  /**
-   * 通过手机号或邮箱获取用户 ID
-   * @param {*} user_id_type  user_id、open_id、union_id
-   * @returns 
-   */
-  async batch_get_id(data,user_id_type){
-    return await this.#hg.request(`https://open.feishu.cn/open-apis/contact/v3/users/batch_get_id?user_id_type=${user_id_type || 'open_id'}`,data,true)
-  }
-
-}
-module.exports = Contract

package/opensdk/document.js

@@ -1,46 +0,0 @@
-class Document{
-  #hg = null
-  constructor(hg){
-    this.#hg = hg
-  }
-  /**
-   * 增加协作者权限 https://open.feishu.cn/document/server-docs/docs/permission/permission-member/create 
-   * @param {*} app_token app_token 多维表格 App 的唯一标识
-   * @param {*} type 文件类型 bitable：多维表格
-   * @param {*} data {
-        "member_type": "openchat",
-        "member_id": "oc_b962e8debdc37712a1d60bb97087a8e8",
-        "perm": "edit",
-        "perm_type": "container",
-        "type": "chat"
-      }
-   */
-  async permissions(app_token,type,data){
-    if(!type){ 
-      throw 'type is not empty'
-    }
-    return await this.#hg.request(`https://open.feishu.cn/open-apis/drive/v1/permissions/${app_token}/members?type=${type}&need_notification=false`,data,true)
-  }
-  /**
-   * 复制多维表格 https://open.feishu.cn/document/server-docs/docs/bitable-v1/app/copy
-   * @param {*} app_token 要复制的多维表格 App 的唯一标识
-   * @param {*} name 多维表格 App 名称。最长为 255 个字符
-   * @param {*} folder_token 文件夹
-   * @returns 
-   */
-  async copy(app_token,name,folder_token,without_content,time_zone){
-    return await this.#hg.request(`https://open.feishu.cn/open-apis/bitable/v1/apps/${app_token}/copy`,{ name,folder_token,without_content: without_content || false,time_zone: time_zone || 'Asia/Shanghai' },true)
-  }
-  /**
-   * 创建多维表格 https://open.feishu.cn/document/server-docs/docs/bitable-v1/app/create
-   * @param {*} name 多维表格 App 名称
-   * @param {*} folder_token 多维表格 App 归属文件夹
-   * @param {*} time_zone 
-   * @returns 
-   */
-  async create(name, folder_token, time_zone){
-    return await this.#hg.request('https://open.feishu.cn/open-apis/bitable/v1/apps',{ name, folder_token, time_zone: time_zone || 'Asia/Shanghai' },true)
-  }
-
-}
-module.exports = Document

package/opensdk/employee.js

@@ -1,18 +0,0 @@
-class Employee{
-  #hg = null
-  constructor(hg){
-    this.#hg = hg
-  }
-  
-  /**
-   * 搜索员工信息
-   * @param {*} params 
-   * @param {*} data 
-   * @param {*} callback(items) 结果回调（根据总数可能多次调用）
-   */
-  async search(params,data,callback){
-    return await this.#hg.paginatedSearch(`https://open.feishu.cn/open-apis/corehr/v2/employees/search`,params,data,callback)
-  }
-
-}
-module.exports = Employee

package/opensdk/users.js

@@ -1,17 +0,0 @@
-class Users{
-  #hg = null
-  constructor(hg){
-    this.#hg = hg
-  }
-  
-  /**
-   * 通过手机号或邮箱获取用户 ID
-   * @param {*} user_id_type  user_id、open_id、union_id
-   * @returns 
-   */
-  async batch_get_id(data,user_id_type){
-    return await this.#hg.request(`https://open.feishu.cn/open-apis/contact/v3/users/batch_get_id?user_id_type=${user_id_type || 'open_id'}`,data,true)
-  }
-
-}
-module.exports = Users