befly-shared 1.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,442 @@
+# Befly Shared
+
+Befly 框架的共享模块，包含跨包共享的工具函数、常量、类型定义和配置。
+
+## 安装
+
+```bash
+bun add befly-shared
+```
+
+## 类型定义
+
+### 响应类型
+
+```typescript
+import type { ResponseResult, PaginatedResult, ValidationResult } from 'befly-shared/types';
+
+// API 响应
+const result: ResponseResult<{ id: number }> = {
+    code: 0,
+    msg: '操作成功',
+    data: { id: 1 }
+};
+
+// 分页响应
+const list: PaginatedResult<User> = {
+    code: 0,
+    msg: '查询成功',
+    data: users,
+    total: 100,
+    page: 1,
+    limit: 10,
+    pages: 10
+};
+```
+
+### 常量
+
+```typescript
+import { ApiCode, ErrorMessages } from 'befly-shared/types';
+
+// 响应码
+ApiCode.SUCCESS; // 0
+ApiCode.FAIL; // 1
+ApiCode.UNAUTHORIZED; // 401
+ApiCode.FORBIDDEN; // 403
+ApiCode.NOT_FOUND; // 404
+ApiCode.SERVER_ERROR; // 500
+
+// 错误消息
+ErrorMessages.UNAUTHORIZED; // '请先登录'
+ErrorMessages.FORBIDDEN; // '无访问权限'
+ErrorMessages.TOKEN_EXPIRED; // 'Token 已过期'
+```
+
+### 配置类型
+
+```typescript
+import type { DatabaseConfig, RedisConfig } from 'befly-shared/types';
+
+const dbConfig: DatabaseConfig = {
+    type: 'mysql',
+    host: 'localhost',
+    port: 3306,
+    user: 'root',
+    password: 'password',
+    database: 'befly'
+};
+
+const redisConfig: RedisConfig = {
+    host: 'localhost',
+    port: 6379,
+    password: 'password',
+    db: 0
+};
+```
+
+### Redis 键和 TTL
+
+```typescript
+import { RedisKeys, RedisTTL } from 'befly-shared/redisKeys';
+
+// 生成 Redis 键
+RedisKeys.apisAll(); // 'befly:apis:all'
+RedisKeys.menusAll(); // 'befly:menus:all'
+RedisKeys.roleInfo('admin'); // 'befly:role:info:admin'
+RedisKeys.roleApis('admin'); // 'befly:role:apis:admin'
+RedisKeys.tableColumns('user'); // 'befly:table:columns:user'
+
+// TTL 配置（秒）
+RedisTTL.tableColumns; // 3600 (1小时)
+RedisTTL.roleApis; // 86400 (24小时)
+RedisTTL.roleInfo; // 86400 (24小时)
+RedisTTL.apisAll; // null (永久)
+RedisTTL.menusAll; // null (永久)
+```
+
+## 配置管理
+
+### mergeConfig
+
+加载并合并配置文件（矩阵搜索：dirs × files）。
+
+**参数：**
+
+- `dirs`: 目录数组（绝对路径）
+- `files`: 文件名数组（不含扩展名）
+- `required`: 是否必填，默认 `false`
+- `extensions`: 扩展名数组，默认 `['.js', '.ts', '.json']`
+
+**返回：** `Promise<Record<string, any>>`
+
+**示例：**
+
+```typescript
+import { mergeConfig } from 'befly-shared/scanConfig';
+
+const config = await mergeConfig({
+    dirs: ['/path/to/config1', '/path/to/config2'],
+    files: ['app', 'database'],
+    required: false
+});
+```
+
+### addonConfigMerge
+
+Addon 配置自动合并函数，自动读取 addon 的 `addon.config.js` 和项目 `config/` 目录下的同名配置文件进行合并。
+
+**参数：**
+
+- `options`: 合并选项（可选）
+
+**返回：** `Promise<Record<string, any>>`
+
+**示例：**
+
+```typescript
+import { addonConfigMerge } from 'befly-shared/scanConfig';
+
+// 在 @befly-addon/admin 包根目录文件中调用
+const config = await addonConfigMerge();
+// 自动读取：
+// 1. @befly-addon/admin/addon.config.js
+// 2. 项目根目录/config/admin.{js,ts,json}
+// 3. 合并后返回
+```
+
+## 字段名转换
+
+### keysToCamel
+
+将对象字段名转为小驼峰格式。
+
+**参数：**
+
+- `obj`: 源对象
+
+**返回：** `T`
+
+**示例：**
+
+```typescript
+import { keysToCamel } from 'befly-shared/keysToCamel';
+
+keysToCamel({ user_id: 123, user_name: 'John' });
+// { userId: 123, userName: 'John' }
+```
+
+### keysToSnake
+
+将对象字段名转为下划线格式。
+
+**参数：**
+
+- `obj`: 源对象
+
+**返回：** `T`
+
+**示例：**
+
+```typescript
+import { keysToSnake } from 'befly-shared/keysToSnake';
+
+keysToSnake({ userId: 123, userName: 'John' });
+// { user_id: 123, user_name: 'John' }
+```
+
+### arrayKeysToCamel
+
+批量将数组对象的字段名转为小驼峰格式。
+
+**参数：**
+
+- `arr`: 源数组
+
+**返回：** `T[]`
+
+**示例：**
+
+```typescript
+import { arrayKeysToCamel } from 'befly-shared/arrayKeysToCamel';
+
+arrayKeysToCamel([
+    { user_id: 1, user_name: 'John' },
+    { user_id: 2, user_name: 'Jane' }
+]);
+// [{ userId: 1, userName: 'John' }, { userId: 2, userName: 'Jane' }]
+```
+
+## 数据处理
+
+### arrayToTree
+
+将扁平数组转为树形结构。
+
+**参数：**
+
+- `items`: 数组
+- `options`: 配置项
+    - `idField`: 节点 id 字段名，默认 `'id'`
+    - `pidField`: 父节点 id 字段名，默认 `'pid'`
+    - `childrenField`: 子节点字段名，默认 `'children'`
+    - `rootPid`: 根节点的父 id，默认 `0`
+    - `mapFn`: 节点转换函数（可选）
+
+**返回：** `T[]`
+
+**示例：**
+
+```typescript
+import { arrayToTree } from 'befly-shared/arrayToTree';
+
+const items = [
+    { id: 1, pid: 0, name: '根节点' },
+    { id: 2, pid: 1, name: '子节点1' },
+    { id: 3, pid: 1, name: '子节点2' }
+];
+
+const tree = arrayToTree(items);
+// [
+//   {
+//     id: 1, pid: 0, name: '根节点',
+//     children: [
+//       { id: 2, pid: 1, name: '子节点1' },
+//       { id: 3, pid: 1, name: '子节点2' }
+//     ]
+//   }
+// ]
+```
+
+### fieldClear
+
+字段过滤和清理工具，支持字段挑选、排除、值保留、值排除等操作。
+
+**参数：**
+
+- `data`: 数据（对象或数组）
+- `options`: 配置项
+    - `pickKeys`: 只保留这些字段
+    - `omitKeys`: 排除这些字段
+    - `keepValues`: 只保留这些值
+    - `excludeValues`: 排除这些值
+    - `keepMap`: 强制保留的键值对（优先级最高）
+
+**返回：** `FieldClearResult<T>`
+
+**示例：**
+
+```typescript
+import { fieldClear } from 'befly-shared/fieldClear';
+
+// 只保留指定字段
+fieldClear({ id: 1, name: 'John', age: 30 }, { pickKeys: ['id', 'name'] });
+// { id: 1, name: 'John' }
+
+// 排除指定字段
+fieldClear({ id: 1, name: 'John', age: 30 }, { omitKeys: ['age'] });
+// { id: 1, name: 'John' }
+
+// 排除指定值
+fieldClear({ id: 1, name: null, age: undefined }, { excludeValues: [null, undefined] });
+// { id: 1 }
+```
+
+### pickFields
+
+挑选对象中的指定字段。
+
+**参数：**
+
+- `obj`: 源对象
+- `keys`: 字段名数组
+
+**返回：** `Partial<T>`
+
+**示例：**
+
+```typescript
+import { pickFields } from 'befly-shared/pickFields';
+
+pickFields({ id: 1, name: 'John', age: 30 }, ['id', 'name']);
+// { id: 1, name: 'John' }
+```
+
+## 文件扫描
+
+### scanFiles
+
+扫描指定目录下的文件。
+
+**参数：**
+
+- `dir`: 目录路径
+- `pattern`: Glob 模式，默认 `'**/*.{ts,js}'`
+- `ignoreUnderline`: 是否忽略下划线开头的文件/目录，默认 `true`
+
+**返回：** `Promise<ScanFileResult[]>`
+
+**示例：**
+
+```typescript
+import { scanFiles } from 'befly-shared/scanFiles';
+
+const files = await scanFiles('/path/to/dir', '**/*.ts');
+// [
+//   { filePath: '/path/to/dir/file1.ts', relativePath: 'file1', fileName: 'file1' },
+//   { filePath: '/path/to/dir/sub/file2.ts', relativePath: 'sub/file2', fileName: 'file2' }
+// ]
+```
+
+### scanViews
+
+扫描项目和所有 `@befly-addon` 包的 views 目录，用于 unplugin-vue-router 的 routesFolder 配置。
+
+**注意：** 此函数只能在 vite.config.js 中使用（Node.js 环境），不能在浏览器中使用。
+
+**返回：** 路由文件夹配置数组
+
+**示例：**
+
+```typescript
+import { scanViews } from 'befly-shared/scanViews';
+
+// 在 vite.config.js 中使用
+export default defineConfig({
+    plugins: [
+        VueRouter({
+            routesFolder: scanViews()
+        })
+    ]
+});
+```
+
+### scanAddons
+
+扫描所有可用的 addon，从 `node_modules/@befly-addon/` 加载。
+
+**参数：**
+
+- `cwd`: 项目根目录，默认 `process.cwd()`
+
+**返回：** `string[]` - addon 名称数组
+
+**示例：**
+
+```typescript
+import { scanAddons } from 'befly-shared/addonHelper';
+
+const addons = scanAddons();
+// ['admin', 'blog', 'shop']
+```
+
+## 路由处理
+
+### layouts
+
+自定义布局处理函数，根据文件名后缀判断使用哪个布局。
+
+**参数：**
+
+- `routes`: 原始路由配置
+- `inheritLayout`: 继承的布局名称（来自父级目录）
+
+**返回：** 处理后的布局配置
+
+**示例：**
+
+```typescript
+import { layouts } from 'befly-shared/layouts';
+
+// 根据文件名后缀判断布局：
+// - index.vue -> 默认布局
+// - login_n.vue -> n 布局
+// - admin_a.vue -> a 布局
+```
+
+## 性能工具
+
+### calcPerfTime
+
+计算性能时间差（支持纳秒级精度）。
+
+**参数：**
+
+- `startTime`: 开始时间（纳秒）
+- `endTime`: 结束时间（纳秒），默认 `Bun.nanoseconds()`
+
+**返回：** `string` - 格式化的时间字符串
+
+**示例：**
+
+```typescript
+import { calcPerfTime } from 'befly-shared/calcPerfTime';
+
+const start = Bun.nanoseconds();
+// ... 执行操作 ...
+const duration = calcPerfTime(start);
+// "12.34 毫秒" 或 "1.23 秒"
+```
+
+## Addon 辅助
+
+### addonHelper
+
+提供 addon 相关的辅助功能，包括扫描、路径解析等。
+
+**导出函数：**
+
+- `scanAddons(cwd?)`: 扫描所有可用的 addon
+- 其他辅助函数...
+
+## 类型定义
+
+所有类型定义自动生成到 `types/` 目录下，可直接导入使用：
+
+```typescript
+import type { LoadConfigOptions, MergeConfigOptions } from 'befly-shared/configTypes';
+```
+
+## License
+
+Apache-2.0