feat: added some tools

README.md

@@ -2,26 +2,18 @@
 
 > 实用程序库
 
-[Web端使用文档](https://aiden-fe.github.io/compass-helpers/browser/)
+[Web端使用文档](https://aiden-fe.github.io/compass-helpers/web/)
 
 [Node端使用文档](https://aiden-fe.github.io/compass-helpers/node/)
 
 ## Getting Started
 
-### 安装
+### web项目使用
 
 npm方式安装:
 
 `npm install @compass-aiden/helpers`
 
-浏览器script标签安装:
-
-通过jsdelivr或者unpkg直接script标签导入`dist/compass-helpers.umd.js`文件后,window.CompassHelpers即可访问到
-
-### 导入使用
-
-#### web项目
-
 ```typescript
 // 自动识别导入esm文件
 import { formatDate } from '@compass-aiden/helpers';
@@ -33,15 +25,29 @@ import { formatDate } from '@compass-aiden/helpers/esm';
 import '@compass-aiden/helpers/umd';
 ```
 
-#### node项目
+浏览器script标签安装:
+
+```html
+<!-- 请根据个人需求采用unpkg或者jsdelivr链接 -->
+<script src="https://unpkg.com/@compass-aiden/[email protected]/dist/compass-helpers.umd.js"></script>
+<script>
+  console.log(window.CompassHelpers.formatDate());
+</script>
+```
+
+### node项目使用
+
+npm方式安装:
+
+`npm install @compass-aiden/helpers`
 
 ```typescript
-// 自动识别导入cjs文件, 如果无法识别tsconfig 设置 { "module": "NodeNext", "moduleResolution": "NodeNext" }
+// 自动识别导入cjs文件, 如果无法识别为cjs导入, 可在tsconfig 设置 { "module": "NodeNext", "moduleResolution": "NodeNext" }或通过其他方式导入
 import { createFile } from '@compass-aiden/helpers';
 // 全量导入
 import * as allHelpers from '@compass-aiden/helpers';
 // 通过别名路径导入cjs文件
-import { createFile } from '@compass-aiden/helpers/node';
+import { createFile } from '@compass-aiden/helpers/cjs';
 // 自动导入cjs文件
 const { createFile } = require('@compass-aiden/helpers');
 ```
@@ -61,6 +67,27 @@ const { createFile } = require('@compass-aiden/helpers');
 - `pnpm test` 执行单元测试
 - `pnpm build:doc` 构建文档
 
+### 添加一个新的工具函数
+
+1. 请先确定该函数适用的平台 Web/Node/Common
+2. 通用函数请放入 `src/common-modules`
+3. Web平台函数放入 `src/web-modules`
+4. Node平台函数放入 `src/node-modules`
+5. 为函数添加一定的文档描述,如下示例
+
+```typescript
+// src/web-modules/example.ts
+
+/**
+ * @category Tools
+ */
+export default function example() {
+  console.log('可指定的category在 src/web.ts 或 src/node.ts 文件顶部声明');
+}
+```
+
+更多文档注解参考 [TypeDoc](https://typedoc.org/guides/overview/)
+
 ### Publish library
 
 1. 变更package.json内的version字段

examples/node-import/src/main.ts

@@ -3,7 +3,7 @@ import { AppModule } from './app.module';
 // tsconfig set { "module": "NodeNext", "moduleResolution": "NodeNext" }
 import { createFile } from '@compass-aiden/helpers'; // auto import cjs
 // import * as Helpers from '@compass-aiden/helpers'; // import all
-// import { createFile } from '@compass-aiden/helpers/node'; // import cjs
+// import { createFile } from '@compass-aiden/helpers/cjs'; // import cjs
 // const { createFile } = require('@compass-aiden/helpers'); // auto import cjs
 
 async function bootstrap() {

package.json

@@ -1,31 +1,31 @@
 {
   "name": "@compass-aiden/helpers",
   "type": "module",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "实用程序库",
   "main": "dist/compass-helpers.umd.js",
   "jsdelivr": "dist/compass-helpers.umd.js",
   "unpkg": "dist/compass-helpers.umd.js",
   "exports": {
     ".": {
       "types": {
-        "import": "./types/browser.es.d.ts",
+        "import": "./types/web.es.d.ts",
         "require": "./types/node.d.cts",
         "default": "./types/compass-helpers.umd.d.ts"
       },
-      "import": "./dist/browser.es.js",
+      "import": "./dist/web.es.js",
       "require": "./dist/node.cjs",
       "default": "./dist/compass-helpers.umd.js"
     },
     "./dist/*": "./dist/*",
     "./types/*": "./types/*",
-    "./node": {
+    "./cjs": {
       "types": "./types/node.d.cts",
       "default": "./dist/node.cjs"
     },
     "./esm": {
-      "types": "./types/browser.es.d.ts",
-      "default": "./dist/browser.es.js"
+      "types": "./types/web.es.d.ts",
+      "default": "./dist/web.es.js"
     },
     "./umd": {
       "types": "./types/compass-helpers.umd.d.ts",
@@ -57,11 +57,11 @@
     "lint": "eslint src --ext .ts,.js --fix",
     "format": "prettier --write src",
     "test": "jest --coverage",
-    "build:doc": "npm run build:doc-browser && npm run build:doc-node",
-    "build:doc-browser": "typedoc src/browser.ts --tsconfig tsconfig.browser.json --out docs/browser --name \"Compass helpers for browser platforms\"",
+    "build:doc": "npm run build:doc-web && npm run build:doc-node",
+    "build:doc-web": "typedoc src/web.ts --tsconfig tsconfig.web.json --out docs/web --name \"Compass helpers for web platforms\"",
     "build:doc-node": "typedoc src/node.ts --tsconfig tsconfig.node.json --out docs/node --name \"Compass helpers for node platforms\"",
     "prepare": "npx simple-git-hooks",
-    "clean": "rimraf dist && rimraf types && rimraf coverage"
+    "clean": "rimraf dist && rimraf types && rimraf coverage && rimraf docs && rimraf stats.html"
   },
   "simple-git-hooks": {
     "pre-commit": "npx pretty-quick --staged",

rollup.config.js

@@ -69,7 +69,7 @@ function getOutput(options = {}) {
 export default [
   // umd
   IS_PROD && {
-    input: 'src/browser.ts',
+    input: 'src/web.ts',
     output: getOutput({
       format: 'umd',
       file: 'dist/compass-helpers.umd.js',
@@ -82,7 +82,7 @@ export default [
     external: getExternal(),
     plugins: getPlugins({
       ts: {
-        tsconfig: './tsconfig.browser.json',
+        tsconfig: './tsconfig.web.json',
       },
       nodeResolve: { browser: true },
     }),
@@ -105,12 +105,12 @@ export default [
   },
   // browser
   {
-    input: 'src/browser.ts',
+    input: 'src/web.ts',
     output: getOutput(),
     external: getExternal(),
     plugins: getPlugins({
       ts: {
-        tsconfig: './tsconfig.browser.json',
+        tsconfig: './tsconfig.web.json',
       },
     }),
     watch: {

src/interfaces/index.ts

@@ -1,4 +1,7 @@
-/** 将类型递归变成可选属性 */
+/**
+ * 将类型递归变成可选属性
+ * @category Types
+ */
 export type DeepPartial<T> = {
   [P in keyof T]?: T[P] extends Array<infer U>
     ? Array<DeepPartial<U>>
@@ -9,7 +12,10 @@ export type DeepPartial<T> = {
         : T[P];
 };
 
-/** 将类型递归变成必填属性 */
+/**
+ * 将类型递归变成必填属性
+ * @category Types
+ */
 export type DeepRequired<T> = {
   [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
 };

src/node-modules/create-file.ts

@@ -8,7 +8,7 @@ import { writeFileSync } from 'fs';
  * @param options 配置项
  * @param options.cwd 执行路径, 默认process.cwd()
  * @param options.encoding 编码格式, 默认utf8
- * @category Tools
+ * @category Files
  */
 export default function createFile(
   filePath: string,

src/node-modules/create-folder.ts

@@ -6,7 +6,7 @@ import { stat, mkdirSync } from 'fs';
  * @param targetPath 目标路径
  * @param [options] 配置项
  * @param [options.cwd=process.cwd()] 执行路径
- * @category Tools
+ * @category Files
  */
 export default function createFolder(
   targetPath: string,

src/node-modules/index.ts

@@ -1,4 +1,8 @@
 import createFolder from './create-folder';
 import createFile from './create-file';
+import isCommandExists from './is-command-exists';
+import isFileOrFolderExists from './is-file-or-folder-exists';
+import requireModule from './require-module';
+import scanDependencyManager from './scan-dependency-manager';
 
-export { createFolder, createFile };
+export { createFolder, createFile, isCommandExists, isFileOrFolderExists, requireModule, scanDependencyManager };

src/node-modules/is-command-exists.ts

@@ -0,0 +1,18 @@
+import { execSync } from 'child_process';
+
+/**
+ * 命令是否存在
+ * @param command
+ * @category Tools
+ */
+export default function isCommandExists(command: string) {
+  try {
+    // 使用execSync执行命令，并捕获命令执行结果
+    execSync(`command -v ${command}`, { stdio: 'ignore' });
+    // 如果执行成功，返回true
+    return true;
+  } catch (error) {
+    // 如果执行失败，则捕获到错误，说明命令不存在，返回false
+    return false;
+  }
+}

src/node-modules/is-file-or-folder-exists.ts

@@ -0,0 +1,16 @@
+import { accessSync } from 'fs';
+
+/**
+ * @description 检查路径下文件或文件夹是否存在
+ * @param {string} p 文件或文件夹路径
+ * @returns {boolean}
+ * @category Files
+ */
+export default function isFileOrFolderExists(p: string): boolean {
+  try {
+    accessSync(p);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}

src/node-modules/require-module.ts

@@ -0,0 +1,11 @@
+import { createRequire } from 'module';
+
+/**
+ * @description 读取模块文件,类似require()函数
+ * @param filePath
+ * @category Files
+ */
+export default function requireModule(filePath: string) {
+  const requireFunc = createRequire(import.meta.url);
+  return requireFunc(filePath);
+}

src/node-modules/scan-dependency-manager.ts

@@ -0,0 +1,23 @@
+import { join } from 'path';
+import isFileOrFolderExists from './is-file-or-folder-exists';
+
+/**
+ * @description 扫描依赖管理器
+ * @category Tools
+ */
+export default function scanDependencyManager(opt?: { cwd?: string }): 'npm' | 'pnpm' | 'yarn' {
+  const { cwd } = {
+    cwd: opt?.cwd || process.cwd(),
+  };
+  let isPnpm = false;
+  isPnpm = isFileOrFolderExists(join(cwd, 'pnpm-lock.yaml'));
+  if (isPnpm) {
+    return 'pnpm';
+  }
+  let isYarn = false;
+  isYarn = isFileOrFolderExists(join(cwd, 'yarn.lock'));
+  if (isYarn) {
+    return 'yarn';
+  }
+  return 'npm';
+}

src/node.ts

@@ -1,3 +1,17 @@
+/**
+ * @categoryDescription Date
+ * 日期相关操作函数
+ * @categoryDescription Factories
+ * 工厂类辅助工具
+ * @categoryDescription Tools
+ * 辅助性的工具函数
+ * @categoryDescription Files
+ * 文件系统相关辅助函数
+ * @categoryDescription Types
+ * TS类型相关辅助
+ * @module
+ */
+
 export * from './common-modules/index';
 export * from './interfaces/index';
 export * from './node-modules/index';

src/web.ts

@@ -0,0 +1,15 @@
+/**
+ * @categoryDescription Date
+ * 日期相关操作函数
+ * @categoryDescription Factories
+ * 工厂类辅助工具
+ * @categoryDescription Tools
+ * 辅助性的工具函数
+ * @categoryDescription Types
+ * TS类型相关辅助
+ * @module
+ */
+
+export * from './common-modules/index';
+export * from './interfaces/index';
+export * from './web-modules/index';

tsconfig.json

@@ -20,7 +20,7 @@
     "plugins": [{ "transform": "@zerollup/ts-transform-paths" }]
   },
   "references": [
-    { "path": "./tsconfig.browser.json" },
+    { "path": "./tsconfig.web.json" },
     { "path": "./tsconfig.node.json" },
     { "path": "./tsconfig.test.json" }
   ]

tsconfig.browser.json → tsconfig.web.json

@@ -4,6 +4,6 @@
     "composite": true,
     "lib": ["ESNext", "DOM"]
   },
-  "include": ["src/browser.ts", "src/browser-modules/**/*.ts", "src/common-modules/**/*.ts", "src/interfaces/**/*.ts"],
+  "include": ["src/web.ts", "src/web-modules/**/*.ts", "src/common-modules/**/*.ts", "src/interfaces/**/*.ts"],
   "exclude": ["src/**/*.spec.ts"]
 }