apaas-fed-client（Rollup，ESM/CJS）

一个面向 APaaS/FED 开发场景的工具库，内置 Excel 解析、多维表格（Bitable）数据解析、字段映射、管道式编排，以及飞书开放平台 SDK 的简化封装。构建产物同时支持 ESM 与 CommonJS (CJS)。

安装

npm install apaas-fed-client

构建与产物

• 构建：npm run build
• 产物：
  • dist/index.mjs（ESM）
  • dist/index.cjs（CJS）
  • SourceMap：dist/index.mjs.map、dist/index.cjs.map
• 包入口（package.json）：
  • main: dist/index.cjs
  • module: dist/index.mjs
  • exports: { import: "./dist/index.mjs", require: "./dist/index.cjs" }

快速使用

• ESM（浏览器或 Node，type: "module"）

import { ExcelParser, BitableParser, FieldMapper, Pipe, createBitableSDK } from 'apaas-fed-client'

• CommonJS（Node）

const { ExcelParser, BitableParser, FieldMapper, Pipe, createBitableSDK } = require('apaas-fed-client')

导出清单

• 函数
  • parseExcel(mappings, options)：返回 (filePath) => parsed 的解析器函数
  • createParser(options)：创建 ExcelParser 实例
  • parseBitableParser(mappings, options)：返回 (data) => parsed 的解析器函数
  • createBitableParser(options)：创建 BitableParser 实例
  • createBitableSDK(config, { filter })：创建读取 Bitable 的 SDK 工厂
• 类
  • ExcelParser：解析本地 Excel 文件为结构化对象
  • BitableParser：解析多维表格记录为结构化对象
  • FieldMapper：字段映射与类型/格式转换
  • Pipe：可配置重试/并行映射的管道式编排
  • BaseSDK：飞书开放平台基础封装
  • Bitable：基于 BaseSDK 的多维表格读取

使用示例

Excel 解析

import { ExcelParser } from 'apaas-fed-client'
const parser = new ExcelParser({})
const data = parser.parse('/path/to.xlsx', [{
  sheetName: 'Sheet1',
  objectName: 'people',
  fields: {
    Name: { name:'name', type:'string' },
    Age:  { name:'age',  type:'number' }
  }
}])
// data.people => [{ name:'Alice', age:30 }, { name:'Bob', age:25 }]

多维表格（Bitable）数据解析

import { BitableParser } from 'apaas-fed-client'
const parser = new BitableParser({})
const out = await parser.parse([
  { 姓名:'Alice', 年龄:30 },
  { 姓名:'Bob',   年龄:25 }
], [{
  objectName: 'rows',
  fields: {
    姓名: { name:'name', type:'string', primaryKey:true },
    年龄: { name:'age',  type:'number' }
  }
}])
// out.rows => { 'Alice': { name:'Alice', age:30 }, 'Bob': { name:'Bob', age:25 } }

字段映射（FieldMapper）规则

• type: string | number | date | option | user
• preprocess: trim | upper | lower
• format: 日期格式（支持 YYYY, DD, HH 等）
• primaryKey: 作为主键聚合对象
• optionMapping: 选项值映射（单选/多选）
• userMapping: 用户值映射到 { _id }

示例：

import { FieldMapper } from 'apaas-fed-client'
const fm = new FieldMapper({})
fm.applyFieldRules('  ab  ', { type:'string', preprocess:['upper'] }) // '  AB  '
fm.applyFieldRules('1,234',   { type:'number' })                      // 1234
fm.applyFieldRules('2024-01-02', { type:'date', format:'YYYY/MM/DD' })// '2024/01/02'
fm.applyFieldRules('完成', { type:'option', name:'状态' }, { optionMapping:{ 状态:{ 完成:'done' } } }) // 'done'
fm.applyFieldRules('alice', { type:'user' }, { userMapping:{ alice:'id_1' } }) // { _id:'id_1' }

管道（Pipe）

import { Pipe } from 'apaas-fed-client'
const p = new Pipe().pipe(v => v + 1).pipe(v => v * 2)
await p.run(2) // 6
await new Pipe().map(v => v * 3).run([1,2,3]) // [3,6,9]

飞书 SDK：读取多维表格

BaseSDK.createClient 需要飞书应用的 appId/appSecret 或运行环境可获取的租户 token。也可使用简化工厂：

import { createBitableSDK } from 'apaas-fed-client'
const read = await createBitableSDK(
  { appId:'xxx', appSecret:'yyy', auto:true, context:{}, logger:console, config:{} },
  { filter:{ status:'done' } }
)
const rows = await read({ tableaddress: 'https://foo/bitable/APP_TOKEN?table=TABLE_ID' })

支持知识库地址（wiki），内部会转换为文档 obj_token：

await read({ tableaddress: 'https://foo/wiki/SPACE_TOKEN?table=TABLE_ID' })

测试

• 需要先构建：npm run build
• 运行工具/导出测试：node tests/run.mjs
• 运行 Bitable 源测试（不依赖真实环境）：node tests/bitable-source.mjs

兼容性与注意事项

• Node：建议 >= 16，支持 ESM/CJS 双导出
• 浏览器直接 <script> 引入未提供 UMD，如需可提需求
• BaseSDK 涉及网络调用与运行环境（如 application.*），在本地/测试中请使用伪造客户端或 createBitableSDK 的自定义配置

许可证

MIT