@pawover/kit 0.5.1 → 0.7.0

package/README.en.md

@@ -0,0 +1,123 @@
+# pawover-kit
+
+[![npm version](https://img.shields.io/npm/v/@pawover/kit.svg)](https://www.npmjs.com/package/@pawover/kit)
+[![Node version](https://img.shields.io/badge/node-%3E%3D22.20.0-brightgreen.svg)](https://nodejs.org)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> An open-source TypeScript toolkit: type utilities, static utility classes, React / Alova hooks, ESLint rulesets and Zod schemas, ready to use with complete type definitions.
+
+pawover-kit is a pnpm monorepo made of 5 independently publishable packages. The root package `@pawover/kit` re-exports every subpackage, while each subpackage can also be installed and used on its own.
+
+## Features
+
+- **Type-only utilities** `@pawover/kit-types`: no runtime code, providing `AnyObject`, `TreeLike`, the `AnyFunction` family, `AdvancedRecord`, `ApiNameCheck` and more
+- **Static utility classes** `@pawover/kit-utils`: 14+ utility classes covering arrays, strings, objects, trees, currency, dates, math and more
+- **React / Alova hooks** `@pawover/kit-hooks`: `useMount`, `useUnmount`, `useLatest`, `useResponsive`, `useTitle` and Alova request hooks
+- **ESLint rulesets** `@pawover/kit-eslint-rules`: 9 rule groups (javascript / typescript / react / reactHooks / vue / stylistic / antfu / imports / importsSort) plus `GLOB_EXCLUDE` and `createRules`
+- **Zod v4 schemas** `@pawover/kit-zod`: common validators for id, string, number, boolean, bigint and more
+- Dual ESM / CJS builds with full type declarations
+- `development` export condition so bundlers can use the source directly in development
+
+## Packages
+
+| Package | Description | Import path |
+| :--- | :--- | :--- |
+| `@pawover/kit-types` | Type-only utilities (no runtime code) | `@pawover/kit/types`, React types via `@pawover/kit/types/react` |
+| `@pawover/kit-utils` | Static utility classes | `@pawover/kit/utils` (also `./math` and `./vite` subpaths) |
+| `@pawover/kit-hooks` | React + Alova hooks | `@pawover/kit/hooks/react`, `@pawover/kit/hooks/alova` |
+| `@pawover/kit-eslint-rules` | ESLint rulesets | `@pawover/kit/eslint-rules` |
+| `@pawover/kit-zod` | Zod v4 schemas | `@pawover/kit/zod` |
+
+> [!NOTE]
+> The root export of `@pawover/kit-hooks` is empty. Always import from the `@pawover/kit/hooks/react` or `@pawover/kit/hooks/alova` subpaths.
+
+## Installation
+
+Install the umbrella package:
+
+```bash
+npm install @pawover/kit
+```
+
+Or install individual subpackages:
+
+```bash
+npm install @pawover/kit-types
+npm install @pawover/kit-utils
+npm install @pawover/kit-hooks
+npm install @pawover/kit-eslint-rules
+npm install @pawover/kit-zod
+```
+
+> [!WARNING]
+> `alova`, `mathjs`, `react`, `vite` and `zod` are optional peer dependencies: install them yourself when using the related features (for example `alova` and `react` are required for `@pawover/kit/hooks/alova`).
+
+## Quick start
+
+```ts
+import { TypeUtil } from "@pawover/kit/utils";
+import { useMount } from "@pawover/kit/hooks/react";
+import { useAlovaRequest } from "@pawover/kit/hooks/alova";
+import type { AnyObject } from "@pawover/kit/types";
+import eslintRules from "@pawover/kit/eslint-rules";
+import { id } from "@pawover/kit/zod";
+
+// Type utilities
+const obj: AnyObject = { a: 1, b: "2" };
+
+// Static utility classes
+TypeUtil.isString("hello"); // true
+
+// React hooks
+useMount(() => {
+  console.log("mounted");
+});
+
+// ESLint rulesets (flat config)
+export default [
+  { ignores: eslintRules.GLOB_EXCLUDE },
+  { files: ["**/*.ts"], rules: { ...eslintRules.javascript, ...eslintRules.typescript } },
+];
+
+// Zod schemas
+id.parse("abc"); // "abc"
+```
+
+## Requirements
+
+- Node.js >= 22.20.0
+- pnpm >= 11
+
+## Development
+
+```bash
+git clone https://github.com/pawover/pawover-kit.git
+cd pawover-kit
+pnpm install
+```
+
+Common commands:
+
+| Command | Description |
+| :--- | :--- |
+| `pnpm test` | Run all vitest suites (801 tests / 31 files, node + jsdom environments) |
+| `pnpm test:types` | Type-check the test files |
+| `pnpm test:ci` | Full CI pipeline: type check → tests → build → smoke → pack check |
+| `pnpm build` | Build every subpackage with turbo (tsdown emits ESM/CJS builds and type declarations) |
+| `pnpm check` | Run types / eslint / format checks in parallel |
+
+## Testing
+
+- **Unit tests**: vitest with two projects (node environment for utils / zod / eslint-rules, jsdom environment for hooks)
+- **Type tests**: type-level API tests ending with `.test.type.ts` under `test/types/`, fully checked by `test:types`
+- **Smoke tests**: verify every dist entry is importable after the build
+
+## Build pipeline
+
+```
+tsdown (build:source) → metadata extraction (build:metadata) → turbo build
+```
+
+- **tsdown** produces the bundles and type declarations
+- **metadata.ts** extracts the runtime exports of utils / hooks into `dist/metadata.json`
+- Every subpath export ships a `"development": "./src/index.ts"` alias so dev toolchains can consume the source directly

package/README.md

@@ -1 +1,123 @@
-# pawover-kit
+# pawover-kit
+
+[![npm version](https://img.shields.io/npm/v/@pawover/kit.svg)](https://www.npmjs.com/package/@pawover/kit)
+[![Node version](https://img.shields.io/badge/node-%3E%3D22.20.0-brightgreen.svg)](https://nodejs.org)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> 一个基于 TypeScript 的开源工具包合集：类型工具、静态工具类、React / Alova Hooks、ESLint 规则集与 Zod Schema，开箱即用、类型完备。
+
+pawover-kit 是一个 pnpm 单体仓库（monorepo），由 5 个独立可发布的子包组成。根包 `@pawover/kit` 聚合重新导出所有子包，也可以按需单独安装使用。
+
+## 特性
+
+- **纯类型工具** `@pawover/kit-types`：无运行时代码，提供 `AnyObject`、`TreeLike`、`AnyFunction` 族、`AdvancedRecord`、`ApiNameCheck` 等常用类型
+- **静态工具类** `@pawover/kit-utils`：数组、字符串、对象、树、货币、日期、数学等 14+ 个工具类
+- **React / Alova Hooks** `@pawover/kit-hooks`：`useMount`、`useUnmount`、`useLatest`、`useResponsive`、`useTitle` 与 Alova 请求系列 Hooks
+- **ESLint 规则集** `@pawover/kit-eslint-rules`：9 大规则组（javascript / typescript / react / reactHooks / vue / stylistic / antfu / imports / importsSort）+ `GLOB_EXCLUDE` + `createRules`
+- **Zod v4 Schema** `@pawover/kit-zod`：id、string、number、boolean、bigint 等常用校验器
+- ESM / CJS 双格式产物，附带完整类型声明
+- `development` 导出条件，开发环境可直接使用源码，方便调试
+
+## 包结构
+
+| 包 | 说明 | 导入路径 |
+| :--- | :--- | :--- |
+| `@pawover/kit-types` | 纯类型工具包（无运行时代码） | `@pawover/kit/types`，react 相关类型见 `@pawover/kit/types/react` |
+| `@pawover/kit-utils` | 静态工具类 | `@pawover/kit/utils`（另有 `./math`、`./vite` 子路径） |
+| `@pawover/kit-hooks` | React + Alova Hooks | `@pawover/kit/hooks/react`、`@pawover/kit/hooks/alova` |
+| `@pawover/kit-eslint-rules` | ESLint 规则集 | `@pawover/kit/eslint-rules` |
+| `@pawover/kit-zod` | Zod v4 Schema | `@pawover/kit/zod` |
+
+> [!NOTE]
+> `@pawover/kit-hooks` 的根导出为空，请始终从 `@pawover/kit/hooks/react` 或 `@pawover/kit/hooks/alova` 子路径导入。
+
+## 安装
+
+使用根包聚合导入：
+
+```bash
+npm install @pawover/kit
+```
+
+或按需安装单个子包：
+
+```bash
+npm install @pawover/kit-types
+npm install @pawover/kit-utils
+npm install @pawover/kit-hooks
+npm install @pawover/kit-eslint-rules
+npm install @pawover/kit-zod
+```
+
+> [!WARNING]
+> `alova`、`mathjs`、`react`、`vite`、`zod` 为可选 peer 依赖：使用对应功能前需自行安装（如使用 `@pawover/kit/hooks/alova` 需要 `alova` 与 `react`）。
+
+## 快速开始
+
+```ts
+import { TypeUtil } from "@pawover/kit/utils";
+import { useMount } from "@pawover/kit/hooks/react";
+import { useAlovaRequest } from "@pawover/kit/hooks/alova";
+import type { AnyObject } from "@pawover/kit/types";
+import eslintRules from "@pawover/kit/eslint-rules";
+import { id } from "@pawover/kit/zod";
+
+// 类型工具
+const obj: AnyObject = { a: 1, b: "2" };
+
+// 静态工具类
+TypeUtil.isString("hello"); // true
+
+// React Hook
+useMount(() => {
+  console.log("mounted");
+});
+
+// ESLint 规则集（flat config）
+export default [
+  { ignores: eslintRules.GLOB_EXCLUDE },
+  { files: ["**/*.ts"], rules: { ...eslintRules.javascript, ...eslintRules.typescript } },
+];
+
+// Zod Schema
+id.parse("abc"); // "abc"
+```
+
+## 环境要求
+
+- Node.js >= 22.20.0
+- pnpm >= 11
+
+## 开发
+
+```bash
+git clone https://github.com/pawover/pawover-kit.git
+cd pawover-kit
+pnpm install
+```
+
+常用命令：
+
+| 命令 | 说明 |
+| :--- | :--- |
+| `pnpm test` | vitest 全量运行（801 条测试 / 31 个文件，node + jsdom 双环境） |
+| `pnpm test:types` | 测试文件的类型检查 |
+| `pnpm test:ci` | 完整 CI 流程：类型检查 → 测试 → 构建 → 冒烟 → pack 检查 |
+| `pnpm build` | turbo 构建全部子包（tsdown 生成 ESM/CJS 双格式与类型声明） |
+| `pnpm check` | 并行运行 types / eslint / format 检查 |
+
+## 测试
+
+- **单元测试**：vitest 双项目（node 环境覆盖 utils / zod / eslint-rules，jsdom 环境覆盖 hooks）
+- **类型测试**：`test/types/` 下以 `.test.type.ts` 结尾的类型级 API 测试，由 `test:types` 全量检查
+- **冒烟测试**：构建后验证所有 dist 产物可正常导入
+
+## 构建流水线
+
+```
+tsdown (build:source) → metadata 提取 (build:metadata) → turbo build
+```
+
+- **tsdown** 负责打包与类型声明生成
+- **metadata.ts** 提取 utils / hooks 的运行时导出名，写入 `dist/metadata.json`
+- 所有子路径导出均带 `"development": "./src/index.ts"` 别名，开发工具链可直接使用源码

package/entry/eslint-rules.cjs

@@ -0,0 +1 @@
+module.exports = require("@pawover/kit-eslint-rules");

package/entry/eslint-rules.d.cts

@@ -0,0 +1 @@
+export type * from './eslint-rules.d.ts';

package/entry/eslint-rules.d.ts

@@ -0,0 +1,2 @@
+export * from "@pawover/kit-eslint-rules";
+export { default } from "@pawover/kit-eslint-rules";

package/entry/eslint-rules.js

@@ -0,0 +1,2 @@
+export * from "@pawover/kit-eslint-rules";
+export { default } from "@pawover/kit-eslint-rules";

package/entry/hooks-alova.cjs

@@ -0,0 +1 @@
+module.exports = require("@pawover/kit-hooks/alova");

package/entry/hooks-alova.d.cts

@@ -0,0 +1 @@
+export type * from './hooks-alova.d.ts';

package/entry/hooks-alova.d.ts

@@ -0,0 +1 @@
+export * from "@pawover/kit-hooks/alova";

package/entry/hooks-alova.js

@@ -0,0 +1 @@
+export * from "@pawover/kit-hooks/alova";

package/entry/hooks-react.cjs

@@ -0,0 +1 @@
+module.exports = require("@pawover/kit-hooks/react");

package/entry/hooks-react.d.cts

@@ -0,0 +1 @@
+export type * from './hooks-react.d.ts';

package/entry/hooks-react.d.ts

@@ -0,0 +1 @@
+export * from "@pawover/kit-hooks/react";

package/entry/hooks-react.js

@@ -0,0 +1 @@
+export * from "@pawover/kit-hooks/react";

package/entry/index.cjs

@@ -0,0 +1 @@
+module.exports = require("@pawover/kit-utils");

package/entry/index.d.cts

@@ -0,0 +1 @@
+export type * from './index.d.ts';

package/entry/index.d.ts

@@ -0,0 +1 @@
+export * from "@pawover/kit-utils";

package/entry/index.js

@@ -0,0 +1 @@
+export * from "@pawover/kit-utils";

package/entry/math.cjs

@@ -0,0 +1 @@
+module.exports = require("@pawover/kit-utils/math");

package/entry/math.d.cts

@@ -0,0 +1 @@
+export type * from './math.d.ts';

package/entry/math.d.ts

@@ -0,0 +1 @@
+export * from "@pawover/kit-utils/math";

package/entry/math.js

@@ -0,0 +1 @@
+export * from "@pawover/kit-utils/math";

package/entry/types-react.cjs

@@ -0,0 +1 @@
+module.exports = require("@pawover/kit-types/react");

package/entry/types-react.d.cts

@@ -0,0 +1 @@
+export type * from './types-react.d.ts';

package/entry/types-react.d.ts

@@ -0,0 +1 @@
+export * from "@pawover/kit-types/react";

package/entry/types-react.js

@@ -0,0 +1 @@
+export * from "@pawover/kit-types/react";

package/entry/types.cjs

@@ -0,0 +1 @@
+module.exports = require("@pawover/kit-types");

package/entry/types.d.cts

@@ -0,0 +1 @@
+export type * from './types.d.ts';

package/entry/types.d.ts

@@ -0,0 +1 @@
+export * from "@pawover/kit-types";

package/entry/types.js

@@ -0,0 +1 @@
+export * from "@pawover/kit-types";

package/entry/vite.cjs

@@ -0,0 +1 @@
+module.exports = require("@pawover/kit-utils/vite");

package/entry/vite.d.cts

@@ -0,0 +1 @@
+export type * from './vite.d.ts';

package/entry/vite.d.ts

@@ -0,0 +1 @@
+export * from "@pawover/kit-utils/vite";

package/entry/vite.js

@@ -0,0 +1 @@
+export * from "@pawover/kit-utils/vite";

package/entry/zod.cjs

@@ -0,0 +1 @@
+module.exports = require("@pawover/kit-zod");

package/entry/zod.d.cts

@@ -0,0 +1 @@
+export type * from './zod.d.ts';

package/entry/zod.d.ts

@@ -0,0 +1 @@
+export * from "@pawover/kit-zod";

package/entry/zod.js

@@ -0,0 +1 @@
+export * from "@pawover/kit-zod";

package/package.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/pawover"
   },
   "description": "一个基于 TypeScript 的开发工具包",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "type": "module",
   "engines": {
     "node": ">=22.20.0"
@@ -27,133 +27,147 @@
     "url": "git+https://github.com/pawover/pawover-kit.git"
   },
   "license": "MIT",
-  "main": "./packages/utils/dist/index.cjs",
-  "module": "./packages/utils/dist/index.js",
-  "types": "./packages/utils/dist/index.d.ts",
+  "main": "./entry/index.cjs",
+  "module": "./entry/index.js",
+  "types": "./entry/index.d.ts",
   "files": [
-    "packages/utils/dist",
-    "packages/hooks/dist",
-    "packages/zod/dist"
+    "entry"
   ],
   "exports": {
     ".": {
       "import": {
-        "types": "./packages/utils/dist/index.d.ts",
-        "default": "./packages/utils/dist/index.js"
+        "types": "./entry/index.d.ts",
+        "default": "./entry/index.js"
       },
       "require": {
-        "types": "./packages/utils/dist/index.d.cts",
-        "default": "./packages/utils/dist/index.cjs"
+        "types": "./entry/index.d.cts",
+        "default": "./entry/index.cjs"
       }
     },
-    "./math": {
+    "./utils": {
       "import": {
-        "types": "./packages/utils/dist/math.d.ts",
-        "default": "./packages/utils/dist/math.js"
+        "types": "./entry/index.d.ts",
+        "default": "./entry/index.js"
       },
       "require": {
-        "types": "./packages/utils/dist/math.d.cts",
-        "default": "./packages/utils/dist/math.cjs"
+        "types": "./entry/index.d.cts",
+        "default": "./entry/index.cjs"
       }
     },
-    "./vite": {
+    "./math": {
       "import": {
-        "types": "./packages/utils/dist/vite.d.ts",
-        "default": "./packages/utils/dist/vite.js"
+        "types": "./entry/math.d.ts",
+        "default": "./entry/math.js"
       },
       "require": {
-        "types": "./packages/utils/dist/vite.d.cts",
-        "default": "./packages/utils/dist/vite.cjs"
+        "types": "./entry/math.d.cts",
+        "default": "./entry/math.cjs"
       }
     },
-    "./metadata.json": "./packages/utils/dist/metadata.json",
-    "./utils": {
+    "./vite": {
       "import": {
-        "types": "./packages/utils/dist/index.d.ts",
-        "default": "./packages/utils/dist/index.js"
+        "types": "./entry/vite.d.ts",
+        "default": "./entry/vite.js"
       },
       "require": {
-        "types": "./packages/utils/dist/index.d.cts",
-        "default": "./packages/utils/dist/index.cjs"
+        "types": "./entry/vite.d.cts",
+        "default": "./entry/vite.cjs"
       }
     },
     "./utils/math": {
       "import": {
-        "types": "./packages/utils/dist/math.d.ts",
-        "default": "./packages/utils/dist/math.js"
+        "types": "./entry/math.d.ts",
+        "default": "./entry/math.js"
       },
       "require": {
-        "types": "./packages/utils/dist/math.d.cts",
-        "default": "./packages/utils/dist/math.cjs"
+        "types": "./entry/math.d.cts",
+        "default": "./entry/math.cjs"
       }
     },
     "./utils/vite": {
       "import": {
-        "types": "./packages/utils/dist/vite.d.ts",
-        "default": "./packages/utils/dist/vite.js"
+        "types": "./entry/vite.d.ts",
+        "default": "./entry/vite.js"
       },
       "require": {
-        "types": "./packages/utils/dist/vite.d.cts",
-        "default": "./packages/utils/dist/vite.cjs"
+        "types": "./entry/vite.d.cts",
+        "default": "./entry/vite.cjs"
       }
     },
-    "./utils/*": {
+    "./hooks/react": {
       "import": {
-        "types": "./packages/utils/dist/*",
-        "default": "./packages/utils/dist/*"
+        "types": "./entry/hooks-react.d.ts",
+        "default": "./entry/hooks-react.js"
       },
-      "require": "./packages/utils/dist/*"
+      "require": {
+        "types": "./entry/hooks-react.d.cts",
+        "default": "./entry/hooks-react.cjs"
+      }
     },
     "./hooks/alova": {
       "import": {
-        "types": "./packages/hooks/dist/alova.d.ts",
-        "default": "./packages/hooks/dist/alova.js"
+        "types": "./entry/hooks-alova.d.ts",
+        "default": "./entry/hooks-alova.js"
       },
       "require": {
-        "types": "./packages/hooks/dist/alova.d.cts",
-        "default": "./packages/hooks/dist/alova.cjs"
+        "types": "./entry/hooks-alova.d.cts",
+        "default": "./entry/hooks-alova.cjs"
       }
     },
-    "./hooks/react": {
+    "./hooks/metadata.json": "./entry/hooks-metadata.json",
+    "./zod": {
       "import": {
-        "types": "./packages/hooks/dist/react.d.ts",
-        "default": "./packages/hooks/dist/react.js"
+        "types": "./entry/zod.d.ts",
+        "default": "./entry/zod.js"
       },
       "require": {
-        "types": "./packages/hooks/dist/react.d.cts",
-        "default": "./packages/hooks/dist/react.cjs"
+        "types": "./entry/zod.d.cts",
+        "default": "./entry/zod.cjs"
       }
     },
-    "./hooks/*": {
+    "./types": {
       "import": {
-        "types": "./packages/hooks/dist/*",
-        "default": "./packages/hooks/dist/*"
+        "types": "./entry/types.d.ts",
+        "default": "./entry/types.js"
       },
-      "require": "./packages/hooks/dist/*"
+      "require": {
+        "types": "./entry/types.d.cts",
+        "default": "./entry/types.cjs"
+      }
     },
-    "./zod": {
+    "./types/react": {
       "import": {
-        "types": "./packages/zod/dist/index.d.ts",
-        "default": "./packages/zod/dist/index.js"
+        "types": "./entry/types-react.d.ts",
+        "default": "./entry/types-react.js"
       },
       "require": {
-        "types": "./packages/zod/dist/index.d.cts",
-        "default": "./packages/zod/dist/index.cjs"
+        "types": "./entry/types-react.d.cts",
+        "default": "./entry/types-react.cjs"
       }
     },
-    "./zod/*": {
+    "./eslint-rules": {
       "import": {
-        "types": "./packages/zod/dist/*",
-        "default": "./packages/zod/dist/*"
+        "types": "./entry/eslint-rules.d.ts",
+        "default": "./entry/eslint-rules.js"
       },
-      "require": "./packages/zod/dist/*"
-    }
+      "require": {
+        "types": "./entry/eslint-rules.d.cts",
+        "default": "./entry/eslint-rules.cjs"
+      }
+    },
+    "./metadata.json": "./entry/metadata.json"
+  },
+  "dependencies": {
+    "@pawover/kit-eslint-rules": "0.0.0-alpha.3",
+    "@pawover/kit-hooks": "0.0.0-alpha.3",
+    "@pawover/kit-utils": "0.0.0-alpha.3",
+    "@pawover/kit-types": "0.0.0-alpha.3",
+    "@pawover/kit-zod": "0.0.0-alpha.3"
   },
   "devDependencies": {
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@eslint-react/eslint-plugin": "^5.18.2",
-    "@pawover/eslint-rules": "^0.2.3",
     "@playwright/test": "^1.62.1",
     "@stylistic/eslint-plugin": "^6.0.0-beta.5",
     "@testing-library/react": "^16.3.2",
@@ -225,6 +239,7 @@
     "test:types": "tsc -p test/tsconfig.json --noEmit",
     "test:smoke": "node test/scripts/smoke.mjs",
     "test:ci": "pnpm test:types && pnpm test && pnpm build && pnpm test:smoke && pnpm check:pack",
+    "postbuild": "node scripts/sync-entry.ts",
     "build": "turbo build",
     "build:force": "turbo build --force",
     "build:package": "turbo build:package && pnpm package",