@epxing/utils 0.0.0-stage → 5.3.0-beta.2

package/API.md

@@ -0,0 +1,602 @@
+# @epxing/utils API
+
+独立的配置模型、日期、集合、占位符、DOM 与浏览器存储工具；根入口不需要安装 Vue 或 core。
+
+本页对应包版本 `5.3.0-beta.2`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
+
+## 安装与使用
+
+
+```sh
+pnpm add @epxing/utils@5.3.0-beta.2
+```
+
+
+```js
+import { cloneDeep, moment, resolvePlaceholders, storage, Page } from '@epxing/utils'
+import { nextMonth } from '@epxing/utils/date'
+
+const draft = cloneDeep({ name: '张三' })
+const date = moment('2026-10-22').add(1, 'day').format('YYYY-MM-DD')
+const text = resolvePlaceholders('用户：#{name}', [draft])
+storage.set('last-date', date)
+const page = new Page({ label: '员工列表' })
+```
+
+## 接入约定
+
+根入口没有 default 导出，请使用具名导入。日期纯函数的 month 使用 0–11。storage/cookie 操作的是 localStorage/sessionStorage；DOM 和存储方法在浏览器中调用。moment 是 Day.js 兼容层，兼容方法以本包类型声明为准。平台相关的 util、Meta、FieldFactory、PdfViewer 从 @epxing/core 导入。
+
+## 根入口完整导出
+
+| 导出名 | 形态 | 用途 | 参数 / 配置 / 事件 |
+| --- | --- | --- | --- |
+| `PLACEHOLDER_RE` | 对象 / 常量 | 匹配全部 #{path} 占位符的全局正则；复用 RegExp.test/exec 时注意 lastIndex。 | [详细参考](../../docs/revision/utils/api/placeholder.md) |
+| `lookup` | 函数 | 在一个对象中按点号/方括号路径读取，返回 { found, value }，保留 0、false、空串和 undefined 的存在语义。 | [详细参考](../../docs/revision/utils/api/placeholder.md) |
+| `resolveKey` | 函数 | 按 sources 的顺序查找第一个拥有路径的对象，返回 { found, value, index }。 | [详细参考](../../docs/revision/utils/api/placeholder.md) |
+| `resolvePlaceholders` | 函数 | 替换字符串中全部 #{path}；默认缺失值替换为空串，onMissing: keep 时保留占位符。 | [详细参考](../../docs/revision/utils/api/placeholder.md) |
+| `isDate` | 函数 | 判断输入是否可转换为有效日期，明确拒绝数组、null 和 undefined。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `getDayCountOfMonth` | 函数 | 返回指定年/月的天数；month 使用 0–11。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `getDayCountOfYear` | 函数 | 根据闰年规则返回 365 或 366。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `nextDate` | 函数 | 返回增加 amount 天后的新 Date，默认增加一天。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `nextMonth` | 函数 | 返回下个月的 Date，并把月末日期夹紧到目标月的有效天数。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `prevYear` | 函数 | 返回向前 amount 年的 Date，并夹紧月末日期。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `nextYear` | 函数 | 返回向后 amount 年的 Date，并夹紧月末日期。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `range` | 函数 | 生成从 0 到 n - 1 的整数数组。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `modifyDate` | 函数 | 替换年、月、日，保留时、分、秒和毫秒；月份从 0 开始。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `modifyTime` | 函数 | 替换时、分、秒，保留日期和毫秒。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `modifyWithTimeString` | 函数 | 用 HH:mm:ss 字符串替换时间；没有匹配时保留输入日期。 | [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `hasClass` | 函数 | 检查 DOM 元素是否具有单个 class；class 参数包含空格时抛错。 | [详细参考](../../docs/revision/utils/api/dom-helper.md) |
+| `arrayFindIndex` | 函数 | 返回第一个满足 pred 的数组元素下标，没有匹配时返回 -1。 | [详细参考](../../docs/revision/utils/api/dom-helper.md) |
+| `coerceTruthyValueToArray` | 函数 | 数组原样返回；其他真值包装为单项数组；假值返回空数组。 | [详细参考](../../docs/revision/utils/api/dom-helper.md) |
+| `cloneDeep` | 函数 | 深复制数据，适合隔离表单和页面配置。 | 见下方签名或接入约定 |
+| `isNil` | 函数 | 判断值是否为 null 或 undefined。 | 见下方签名或接入约定 |
+| `isEmpty` | 函数 | 按 lodash 语义判断集合、字符串或对象是否为空。 | 见下方签名或接入约定 |
+| `isObject` | 函数 | 判断是否为对象或函数；null 返回 false。 | 见下方签名或接入约定 |
+| `isEqual` | 函数 | 按 lodash 语义比较两个值的深层结构是否相等。 | 见下方签名或接入约定 |
+| `assignWith` | 函数 | 合并来源对象属性到目标对象，并允许自定义合并规则；会修改目标对象。 | 见下方签名或接入约定 |
+| `debounce` | 函数 | 创建防抖函数，支持 cancel/flush 及前沿、后沿调用选项。 | 见下方签名或接入约定 |
+| `throttle` | 函数 | 创建节流函数，支持 cancel/flush 及前沿、后沿调用选项。 | 见下方签名或接入约定 |
+| `get` | 函数 | 按属性路径读取值，未定义时可返回默认值。 | 见下方签名或接入约定 |
+| `set` | 函数 | 按属性路径写入值并返回目标对象；会修改目标对象。 | 见下方签名或接入约定 |
+| `Config` | 类 | 配置模型类；new Config() 后通过 set(config) 合并配置，对象浅合并、数组复制。 | [详细参考](../../docs/revision/utils/api/Config.md) |
+| `Page` | 类 | 页面配置模型类，封装页面标识、元数据及属性查询方法。 | [详细参考](../../docs/revision/utils/api/page.md) |
+| `placeholder` | 对象 / 常量 | 占位符工具集合，包含 PLACEHOLDER_RE、lookup、resolveKey、resolvePlaceholders。 | [详细参考](../../docs/revision/utils/api/placeholder.md) |
+| `storage` | 对象 / 常量 | 浏览器存储适配器，提供 get/set/remove，支持 session 与 expires 选项。 | [详细参考](../../docs/revision/utils/api/storage.md) |
+| `getXsrfToken` | 函数 | 从存储中读取 XSRF token。 | [详细参考](../../docs/revision/utils/api/storage.md) |
+| `setXsrfToken` | 函数 | 保存或清理 XSRF token。 | [详细参考](../../docs/revision/utils/api/storage.md) |
+| `cookie` | 对象 / 常量 | storage 的兼容别名，使用浏览器存储适配器。 | [详细参考](../../docs/revision/utils/api/storage.md) |
+| `moment` | 对象 / 常量 | 基于 Day.js 的 Moment 兼容工厂；支持 format/add/subtract/startOf/endOf/diff 等常用链式调用。 | [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+| `dateTime` | 对象 / 常量 | moment 的同一对象别名，适合新产品中明确表达日期工具用途。 | [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+| `createMoment` | 对象 / 常量 | 创建 Moment 兼容日期对象；moment/dateTime 的底层工厂。 | [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+| `lodash` | 对象 / 常量 | 集合工具对象，包含本包具名导出的十个 lodash-es 方法。 | 见下方签名或接入约定 |
+
+## 函数、类与工具对象
+
+签名中的 any 表示现有声明未进一步限定结构；源代码方法签名保留默认参数。异步结果与泛型以声明为准。
+
+### lookup
+
+在一个对象中按点号/方括号路径读取，返回 { found, value }，保留 0、false、空串和 undefined 的存在语义。
+
+```ts
+lookup(path: any, source: any): { found: boolean; value: any; }
+```
+
+[详细参考](../../docs/revision/utils/api/placeholder.md)，包括参数、返回值与运行约束。
+
+### resolveKey
+
+按 sources 的顺序查找第一个拥有路径的对象，返回 { found, value, index }。
+
+```ts
+resolveKey(path: string, sources?: object[]): { found: boolean; value: any; index: number; }
+```
+
+[详细参考](../../docs/revision/utils/api/placeholder.md)，包括参数、返回值与运行约束。
+
+### resolvePlaceholders
+
+替换字符串中全部 #{path}；默认缺失值替换为空串，onMissing: keep 时保留占位符。
+
+```ts
+resolvePlaceholders(text: string, sources?: object[], options?: { onMissing?: "empty" | "keep"; }): string
+```
+
+[详细参考](../../docs/revision/utils/api/placeholder.md)，包括参数、返回值与运行约束。
+
+### isDate
+
+判断输入是否可转换为有效日期，明确拒绝数组、null 和 undefined。
+
+```ts
+isDate(date: any): boolean
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### getDayCountOfMonth
+
+返回指定年/月的天数；month 使用 0–11。
+
+```ts
+getDayCountOfMonth(year: any, month: any): number
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### getDayCountOfYear
+
+根据闰年规则返回 365 或 366。
+
+```ts
+getDayCountOfYear(year: any): 366 | 365
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### nextDate
+
+返回增加 amount 天后的新 Date，默认增加一天。
+
+```ts
+nextDate(date: any, amount?: number): Date
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### nextMonth
+
+返回下个月的 Date，并把月末日期夹紧到目标月的有效天数。
+
+```ts
+nextMonth(date: any): Date
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### prevYear
+
+返回向前 amount 年的 Date，并夹紧月末日期。
+
+```ts
+prevYear(date: any, amount?: number): Date
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### nextYear
+
+返回向后 amount 年的 Date，并夹紧月末日期。
+
+```ts
+nextYear(date: any, amount?: number): Date
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### range
+
+生成从 0 到 n - 1 的整数数组。
+
+```ts
+range(n: any): any
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### modifyDate
+
+替换年、月、日，保留时、分、秒和毫秒；月份从 0 开始。
+
+```ts
+modifyDate(date: any, y: any, m: any, d: any): Date
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### modifyTime
+
+替换时、分、秒，保留日期和毫秒。
+
+```ts
+modifyTime(date: any, h: any, m: any, s: any): Date
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### modifyWithTimeString
+
+用 HH:mm:ss 字符串替换时间；没有匹配时保留输入日期。
+
+```ts
+modifyWithTimeString(date: any, time: any): any
+```
+
+[详细参考](../../docs/revision/utils/api/date-helper.md)，包括参数、返回值与运行约束。
+
+### hasClass
+
+检查 DOM 元素是否具有单个 class；class 参数包含空格时抛错。
+
+```ts
+hasClass(el: any, cls: any): any
+```
+
+[详细参考](../../docs/revision/utils/api/dom-helper.md)，包括参数、返回值与运行约束。
+
+### arrayFindIndex
+
+返回第一个满足 pred 的数组元素下标，没有匹配时返回 -1。
+
+```ts
+arrayFindIndex(arr: any, pred: any): number
+```
+
+[详细参考](../../docs/revision/utils/api/dom-helper.md)，包括参数、返回值与运行约束。
+
+### coerceTruthyValueToArray
+
+数组原样返回；其他真值包装为单项数组；假值返回空数组。
+
+```ts
+coerceTruthyValueToArray(val: any): any[]
+```
+
+[详细参考](../../docs/revision/utils/api/dom-helper.md)，包括参数、返回值与运行约束。
+
+### cloneDeep
+
+深复制数据，适合隔离表单和页面配置。
+
+```ts
+cloneDeep<T>(value: T): T
+```
+
+### isNil
+
+判断值是否为 null 或 undefined。
+
+```ts
+isNil(value: unknown): value is null
+```
+
+### isEmpty
+
+按 lodash 语义判断集合、字符串或对象是否为空。
+
+```ts
+isEmpty(value: unknown): boolean
+```
+
+### isObject
+
+判断是否为对象或函数；null 返回 false。
+
+```ts
+isObject(value: unknown): value is object
+```
+
+### isEqual
+
+按 lodash 语义比较两个值的深层结构是否相等。
+
+```ts
+isEqual(value: unknown, other: unknown): boolean
+```
+
+### assignWith
+
+合并来源对象属性到目标对象，并允许自定义合并规则；会修改目标对象。
+
+```ts
+assignWith<T extends object>(object: T, ...sources: any[]): T
+```
+
+### debounce
+
+创建防抖函数，支持 cancel/flush 及前沿、后沿调用选项。
+
+```ts
+debounce<T extends (...args: any[]) => any>(func: T, wait?: number, options?: { leading?: boolean; trailing?: boolean; maxWait?: number; }): T & { cancel(): void; flush(): ReturnType<T>; }
+```
+
+### throttle
+
+创建节流函数，支持 cancel/flush 及前沿、后沿调用选项。
+
+```ts
+throttle<T extends (...args: any[]) => any>(func: T, wait?: number, options?: { leading?: boolean; trailing?: boolean; maxWait?: number; }): T & { cancel(): void; flush(): ReturnType<T>; }
+```
+
+### get
+
+按属性路径读取值，未定义时可返回默认值。
+
+```ts
+get(object: unknown, path: string | (string | number)[], defaultValue?: any): any
+```
+
+### set
+
+按属性路径写入值并返回目标对象；会修改目标对象。
+
+```ts
+set<T extends object>(object: T, path: string | (string | number)[], value: any): T
+```
+
+### Config
+
+配置模型类；new Config() 后通过 set(config) 合并配置，对象浅合并、数组复制。
+
+```js
+new Config
+```
+
+| 方法 | 说明 |
+| --- | --- |
+| `set(config)` | 按属性路径写入值并返回目标对象；会修改目标对象。 |
+
+[详细参考](../../docs/revision/utils/api/Config.md)，包括参数、返回值与运行约束。
+
+### Page
+
+页面配置模型类，封装页面标识、元数据及属性查询方法。
+
+```js
+new Page(props)
+```
+
+| 方法 | 说明 |
+| --- | --- |
+| `getPageId()` | 返回页面 ID。 |
+| `getLabel()` | 返回页面标签字段。 |
+| `getMetaId()` | 返回页面绑定的元数据 ID。 |
+| `getFlag()` | 返回页面标识。 |
+| `getPagePath()` | 返回页面路径。 |
+| `getConfig()` | 返回页面配置。 |
+| `getKey()` | 返回页面对象的主键。 |
+| `getAttris()` | 返回页面字段属性。 |
+| `getIdLabelAttris()` | ID对应LAVEL |
+| `getNameLabelAttris()` | NAME对应LAVEL |
+| `getAttriNameById(attriId)` | 按属性 ID 查询字段名。 |
+| `getLabelByField(field)` | 取得字段显示标签。 |
+
+[详细参考](../../docs/revision/utils/api/page.md)，包括参数、返回值与运行约束。
+
+### placeholder
+
+占位符工具集合，包含 PLACEHOLDER_RE、lookup、resolveKey、resolvePlaceholders。
+
+| 方法 | 说明 |
+| --- | --- |
+| `lookup(path, source)` | 在一个对象中按点号/方括号路径读取，返回 { found, value }，保留 0、false、空串和 undefined 的存在语义。 |
+| `resolveKey(path, sources = [])` | 按 sources 的顺序查找第一个拥有路径的对象，返回 { found, value, index }。 |
+| `resolvePlaceholders(text, sources = [], options = {})` | 替换字符串中全部 #{path}；默认缺失值替换为空串，onMissing: keep 时保留占位符。 |
+
+[详细参考](../../docs/revision/utils/api/placeholder.md)，包括参数、返回值与运行约束。
+
+### storage
+
+浏览器存储适配器，提供 get/set/remove，支持 session 与 expires 选项。
+
+| 方法 | 说明 |
+| --- | --- |
+| `get(key)` | 读取指定键，过期数据按实现移除。 |
+| `set(key, value, options)` | 序列化并保存值，expires 可为天数或 Date。 |
+| `remove(key)` | 移除键及对应过期记录。 |
+
+[详细参考](../../docs/revision/utils/api/storage.md)，包括参数、返回值与运行约束。
+
+### getXsrfToken
+
+从存储中读取 XSRF token。
+
+```ts
+getXsrfToken(): string
+```
+
+[详细参考](../../docs/revision/utils/api/storage.md)，包括参数、返回值与运行约束。
+
+### setXsrfToken
+
+保存或清理 XSRF token。
+
+```ts
+setXsrfToken(token: any): void
+```
+
+[详细参考](../../docs/revision/utils/api/storage.md)，包括参数、返回值与运行约束。
+
+### cookie
+
+storage 的兼容别名，使用浏览器存储适配器。
+
+与 `storage` 共用实现，方法见该节。
+
+[详细参考](../../docs/revision/utils/api/storage.md)，包括参数、返回值与运行约束。
+
+### moment
+
+基于 Day.js 的 Moment 兼容工厂；支持 format/add/subtract/startOf/endOf/diff 等常用链式调用。
+
+```ts
+moment(input?: unknown, ...formatAndOptions: any[]): MomentLike
+```
+
+[详细参考](../../docs/revision/utils/api/moment-compat.md)，包括参数、返回值与运行约束。
+
+### dateTime
+
+moment 的同一对象别名，适合新产品中明确表达日期工具用途。
+
+```ts
+dateTime(input?: unknown, ...formatAndOptions: any[]): MomentLike
+```
+
+[详细参考](../../docs/revision/utils/api/moment-compat.md)，包括参数、返回值与运行约束。
+
+### createMoment
+
+创建 Moment 兼容日期对象；moment/dateTime 的底层工厂。
+
+```ts
+createMoment(input?: unknown, ...formatAndOptions: any[]): MomentLike
+```
+
+[详细参考](../../docs/revision/utils/api/moment-compat.md)，包括参数、返回值与运行约束。
+
+## 稳定子路径
+
+下表按实际 package.json 的公开入口列出。default 使用默认导入，其他名称使用具名导入；类型接口用 import type。
+
+| 导入路径 | 完整导出名 | 用途 / 详细说明 |
+| --- | --- | --- |
+| `@epxing/utils/config` | `default` | 配置模型类；new Config() 后通过 set(config) 合并配置，对象浅合并、数组复制。 [详细参考](../../docs/revision/utils/api/Config.md) |
+| `@epxing/utils/page` | `default` | 页面配置模型类，封装页面标识、元数据及属性查询方法。 [详细参考](../../docs/revision/utils/api/page.md) |
+| `@epxing/utils/placeholder` | `PLACEHOLDER_RE`、`lookup`、`resolveKey`、`resolvePlaceholders`、`default` | 占位符工具集合，包含 PLACEHOLDER_RE、lookup、resolveKey、resolvePlaceholders。 [详细参考](../../docs/revision/utils/api/placeholder.md) |
+| `@epxing/utils/storage` | `XSRF_TOKEN_KEY`、`getXsrfToken`、`setXsrfToken`、`clearXsrfToken`、`default` | 浏览器存储适配器，提供 get/set/remove，支持 session 与 expires 选项。 [详细参考](../../docs/revision/utils/api/storage.md) |
+| `@epxing/utils/date` | `isDate`、`getDayCountOfMonth`、`getDayCountOfYear`、`nextDate`、`nextMonth`、`prevYear`、`nextYear`、`range`、`modifyDate`、`modifyTime`、`modifyWithTimeString` | 判断输入是否可转换为有效日期，明确拒绝数组、null 和 undefined。 [详细参考](../../docs/revision/utils/api/date-helper.md) |
+| `@epxing/utils/dom` | `hasClass`、`arrayFindIndex`、`coerceTruthyValueToArray` | 检查 DOM 元素是否具有单个 class；class 参数包含空格时抛错。 [详细参考](../../docs/revision/utils/api/dom-helper.md) |
+| `@epxing/utils/date-time` | `READ_METHODS`、`WRITE_METHODS`、`DUAL_METHODS`、`PASSTHROUGH`、`UNSUPPORTED_FORMAT_TOKENS`、`preprocessFormat`、`createMoment`、`default`、`MomentLike`（类型）、`MomentFactory`（类型） | 基于 Day.js 的 Moment 兼容工厂；支持 format/add/subtract/startOf/endOf/diff 等常用链式调用。 [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+| `@epxing/utils/collection` | `cloneDeep`、`isNil`、`isEmpty`、`isObject`、`isEqual`、`assignWith`、`debounce`、`throttle`、`get`、`set`、`default` | 集合工具对象，包含本包具名导出的十个 lodash-es 方法。 |
+
+## 子路径补充导出
+
+本节列出仅在稳定子路径中提供的具名 API；从本节标题对应路径导入。
+
+### @epxing/utils/storage
+
+| 导出 / 调用签名 | 用途 | 详细接口 |
+| --- | --- | --- |
+| `XSRF_TOKEN_KEY` | 提供 get/set/remove 及过期规则，并维护 xsrf token。保留 cookie 风格 API，但不操作浏览器 Cookie。 | [详细参考](../../docs/revision/utils/api/storage.md) |
+| `clearXsrfToken(): void` | 提供 get/set/remove 及过期规则，并维护 xsrf token。保留 cookie 风格 API，但不操作浏览器 Cookie。 | [详细参考](../../docs/revision/utils/api/storage.md) |
+
+### @epxing/utils/date-time
+
+| 导出 / 调用签名 | 用途 | 详细接口 |
+| --- | --- | --- |
+| `READ_METHODS` | 以 dayjs 实现常用 Moment API、可变链式操作和 duration 补足，导出兼容方法/格式集合。罕用 token 与插件需专门确认。 | [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+| `WRITE_METHODS` | 以 dayjs 实现常用 Moment API、可变链式操作和 duration 补足，导出兼容方法/格式集合。罕用 token 与插件需专门确认。 | [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+| `DUAL_METHODS` | 以 dayjs 实现常用 Moment API、可变链式操作和 duration 补足，导出兼容方法/格式集合。罕用 token 与插件需专门确认。 | [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+| `PASSTHROUGH` | 以 dayjs 实现常用 Moment API、可变链式操作和 duration 补足，导出兼容方法/格式集合。罕用 token 与插件需专门确认。 | [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+| `UNSUPPORTED_FORMAT_TOKENS` | 以 dayjs 实现常用 Moment API、可变链式操作和 duration 补足，导出兼容方法/格式集合。罕用 token 与插件需专门确认。 | [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+| `preprocessFormat(format: string, milliseconds?: number, year?: number): string` | 以 dayjs 实现常用 Moment API、可变链式操作和 duration 补足，导出兼容方法/格式集合。罕用 token 与插件需专门确认。 | [详细参考](../../docs/revision/utils/api/moment-compat.md) |
+
+## 导出的 TypeScript 类型
+
+以下名称仅存在于类型系统，用 import type 导入，不作为运行时对象使用。
+
+### MomentLike
+
+```ts
+interface MomentLike {
+  format(format?: string): string
+  valueOf(): number
+  unix(): number
+  toDate(): Date
+  toISOString(): string | null
+  toJSON(): string | null
+  toString(): string
+  toArray(): number[]
+  toObject(): Record<string, number>
+  isValid(): boolean
+  clone(): MomentLike
+  diff(input?: unknown, unit?: string, precise?: boolean): number
+  isBefore(input?: unknown, unit?: string): boolean
+  isAfter(input?: unknown, unit?: string): boolean
+  isSame(input?: unknown, unit?: string): boolean
+  isSameOrBefore(input?: unknown, unit?: string): boolean
+  isSameOrAfter(input?: unknown, unit?: string): boolean
+  isBetween(start: unknown, end: unknown, unit?: string | null, inclusivity?: string): boolean
+  isLeapYear(): boolean
+  daysInMonth(): number
+  get(unit: string): number
+  from(input: unknown, withoutSuffix?: boolean): string
+  to(input: unknown, withoutSuffix?: boolean): string
+  fromNow(withoutSuffix?: boolean): string
+  toNow(withoutSuffix?: boolean): string
+  calendar(reference?: unknown, formats?: Record<string, string | ((...args: any[]) => string)>): string
+  utcOffset(): number
+  utcOffset(offset: number | string, keepLocalTime?: boolean): MomentLike
+  weekday(): number
+  weekday(value: number): MomentLike
+  isoWeekday(): number
+  isoWeekday(value: number): MomentLike
+  add(amount: number | Duration, unit?: string): this
+  subtract(amount: number | Duration, unit?: string): this
+  startOf(unit: string): this
+  endOf(unit: string): this
+  set(unit: string, value: number): this
+  set(values: Record<string, number>): this
+  local(): this
+  utc(keepLocalTime?: boolean): this
+  locale(): string
+  locale(name: string): this
+  year(): number
+  year(value: number): this
+  month(): number
+  month(value: number): this
+  date(): number
+  date(value: number): this
+  day(): number
+  day(value: number): this
+  hour(): number
+  hour(value: number): this
+  minute(): number
+  minute(value: number): this
+  second(): number
+  second(value: number): this
+  millisecond(): number
+  millisecond(value: number): this
+  quarter(): number
+  quarter(value: number): this
+  week(): number
+  week(value: number): this
+  isoWeek(): number
+  isoWeek(value: number): this
+  dayOfYear(): number
+  dayOfYear(value: number): this
+}
+```
+
+### MomentFactory
+
+```ts
+interface MomentFactory {
+  (input?: unknown, ...formatAndOptions: any[]): MomentLike
+  duration(input?: unknown, ...unit: any[]): Duration
+  locale(name?: string): string
+  isMoment(value: unknown): value is MomentLike
+  unix(seconds: number): MomentLike
+  utc(input?: unknown, ...formatAndOptions: any[]): MomentLike
+  max(...dates: (MomentLike | Dayjs | (MomentLike | Dayjs)[])[]): MomentLike
+  min(...dates: (MomentLike | Dayjs | (MomentLike | Dayjs)[])[]): MomentLike
+}
+```
+
+## 源码兼容与其他入口
+
+/src 路径保留给已有产品和源码级扩展，可能包含平台内部实现；新产品优先采用上方根导出与稳定子路径。通配符表示按实际文件名匹配，不代表所有源码都属于根入口。
+
+| 公开路径模式 | 实际目标 |
+| --- | --- |
+| `@epxing/utils/src` | `./dist/src/legacy.js` |
+| `@epxing/utils/src/*.css` | `./src/*.css` |
+| `@epxing/utils/src/*.scss` | `./src/*.scss` |
+| `@epxing/utils/src/*.png` | `./src/*.png` |
+| `@epxing/utils/src/*.svg` | `./src/*.svg` |
+| `@epxing/utils/src/*.jpg` | `./src/*.jpg` |
+| `@epxing/utils/src/*.gif` | `./src/*.gif` |
+| `@epxing/utils/src/*.woff` | `./src/*.woff` |
+| `@epxing/utils/src/*.woff2` | `./src/*.woff2` |
+| `@epxing/utils/src/*.ttf` | `./src/*.ttf` |
+| `@epxing/utils/src/*.js` | `./dist/src/*.js` |
+| `@epxing/utils/src/*.jsx` | `./dist/src/*.js` |
+| `@epxing/utils/src/*.vue` | `./dist/src/*.js` |
+| `@epxing/utils/src/*` | `./dist/src/*.js` |
+| `@epxing/utils/package.json` | `./package.json` |
+
+## 文档维护
+
+本页由 build/gen-package-api-docs.mjs 生成。修改公开入口并更新构建产物和类型声明后，在框架根运行 `pnpm docs:api`；`pnpm docs:api:check` 检查清单、类型、包内文档与站点镜像是否同步，同时验证页面编译和文档链接。用途和示例维护在 build/package-api-notes.mjs，组件和源码方法的详细参考位于 docs/revision。

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @epxing/utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[完整公开 API、导入方式与示例](./API.md)
+
+可独立安装的通用工具包。根入口不加载 Vue、core、store 或浏览器全局变量。
+
+```js
+import { Config, resolvePlaceholders, lookup, storage } from '@epxing/utils'
+import ConfigDefault from '@epxing/utils/config'
+import { resolvePlaceholders as resolve } from '@epxing/utils/placeholder'
+
+const config = new Config()
+config.set({ pageSize: 20 })
+resolvePlaceholders('#{user.name}:#{count}', [{ user: { name: 'EPX' }, count: 0 }])
+```
+
+常用纯工具也可具名导入：`cloneDeep/isNil/isEmpty/isObject/isEqual/assignWith/debounce/throttle/get/set`，或 `lodash` 常用子集对象。`moment/dateTime/createMoment` 与 `/date-time` 默认导出为同一个 dayjs 兼容日期函数；`cookie` 是 `storage` 的别名。
+
+稳定子路径：config、page、placeholder、storage、date、dom、date-time、collection。`/collection` 默认导出工具对象，并支持具名函数。浏览器存储工具在调用时访问浏览器；根入口可在 Node 中导入。类型声明随包发布，纯工具声明从实际 JS 生成。完整产品示例见 `docs/guide/getting-started/packages.md`。
+
+原根入口的运行时服务迁移至 `@epxing/core`：util、axios、http、GlobalMixin、FieldFactory、Meta、PdfViewer。旧 `/src` barrel 和 `/src/*` 转发入口仍可使用，使用这些兼容入口时安装 core；core 是可选 peer，纯工具消费方不需要它。`mermaid` 也是可选 peer，仅使用对应浏览器工具时需要安装。
+
+工作区构建：`pnpm --filter @epxing/utils build`。`pnpm pack/publish` 的 prepack 会重新构建 JS 和类型。此根入口调整包含主版本变更，发布前应用 Changesets。