@pawover/kit 0.6.0 → 0.8.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,145 @@
-# 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 检查 |
+
+## 发布
+
+发布由 [Changesets](https://changesets.dev) + GitHub Actions 全自动驱动，无需手动登录 npm 或运行发布命令。
+
+**日常流程**：改动代码后运行 `pnpm changeset`，按提示选择受影响的包与版本级别并填写变更说明，将生成的 `.changeset/*.md` 随 PR 一起提交。合并到 `main` 后：
+
+1. CI 自动创建 / 更新 **Version Packages** PR（内含各包版本号与 CHANGELOG）
+2. 合并该 PR 后自动构建，并按拓扑序发布（`types` / `zod` / `eslint-rules` → `utils` → `hooks` → 根包 `@pawover/kit`）
+3. 自动打 git tag 并生成 GitHub Release
+
+**版本策略**：各包独立版本。子包版本变化时，依赖它的包（含根包）自动随同提升——任何子包发布必伴随根包发布（CI 有硬校验守卫）。
+
+**当前阶段**：处于 alpha pre 模式，所有包以 `X.Y.Z-alpha.N` 发布到 `alpha` dist-tag。转正时运行 `pnpm pre:exit` 并删除 CI 中的 `NPM_CONFIG_TAG` 环境变量。
+
+**应急手动发布**（一般不使用）：
+
+```bash
+pnpm build && pnpm postbuild   # 构建并同步 entry/metadata.json
+pnpm publish --access public --tag alpha   # 根包
+pnpm --filter @pawover/kit-types public    # 单个子包
+```
+
+## 测试
+
+- **单元测试**：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";