wssf-kage-js 1.0.1 → 1.0.2

package/README.md

@@ -1,339 +1,131 @@
-# Kage.js
+# Kage.js (`wssf-kage-js`)
 
-一个现代化的 JavaScript/TypeScript 工具库，类似于 lodash，提供了丰富的数组、对象、字符串、函数和数学运算工具方法。
+面向 **前端与 AI 业务** 的 TypeScript 函数式工具集合：柯里化、组合、高阶拦截、纯函数、惰性/记忆化、中间件、策略、Option 等 **24 类常见函数模式**，便于组合提示词流水线、鉴权与降级、数据变换等逻辑。
 
-## ✨ 特性
+- **运行时零依赖**（`dependencies` 为空）
+- 发布物仅含 `dist`（CJS + ESM + `.d.ts`），支持按需 `import`
 
-- 🚀 **完整的 TypeScript 支持** - 提供完整的类型定义
-- 📦 **模块化设计** - 支持按需导入，减小打包体积
-- 🧪 **完善的测试** - 100% 测试覆盖率
-- 🔧 **零依赖** - 不依赖任何第三方库
-- 📝 **详细的文档** - 每个函数都有清晰的注释
+> npm 页面展示的是本 README。更完整的说明、分节示例见仓库内 [**Docusaurus 文档**](https://github.com/hezihua/Kage_js/tree/main/docs)（`pnpm run docs:dev` 本地预览）。
 
-## 📦 安装
+## 安装
 
 ```bash
 npm install wssf-kage-js
-```
-
-或使用 yarn:
-
-```bash
-yarn add wssf-kage-js
-```
-
-或使用 pnpm:
-
-```bash
+# 或
 pnpm add wssf-kage-js
 ```
 
-## 🚀 快速开始
+## 快速开始
 
-```typescript
-import { chunk, camelCase, debounce, range } from 'wssf-kage-js';
+### 柯里化与普通工具（`curry`、`pipe`、`debounce` …）
 
-// 数组操作
-chunk([1, 2, 3, 4, 5], 2);
-// => [[1, 2], [3, 4], [5]]
+```ts
+import { curry, pipe, debounce } from 'wssf-kage-js';
 
-// 字符串操作
-camelCase('hello-world');
-// => 'helloWorld'
+const add = (a: number, b: number, c: number) => a + b + c;
+curry(add)(1)(2)(3); // => 6
 
-// 函数工具
-const debouncedFn = debounce(() => console.log('执行'), 1000);
+pipe<string>((s) => s.trim(), (s) => s.toUpperCase())('  hi  '); // => 'HI'
 
-// 数学运算
-range(5);
-// => [0, 1, 2, 3, 4]
+const onResize = debounce(200)(() => console.log('resize'));
 ```
 
-## 📚 API 文档
-
-### 函数模式总览
-
-项目已经内置 24 类常见函数模式，包括柯里化、高阶函数、组合函数、纯函数、惰性函数、记忆化函数、中间件函数、生成器函数等。
-
-- 总览文档: [FUNCTION_TYPES.md](./FUNCTION_TYPES.md)
-- Docusaurus 文档骨架: [docs/intro.md](./docs/intro.md)
-- 示例入口: [examples.ts](./examples.ts)
-
-### 语言检查 (Lang)
-
-判断数据类型的工具函数。
-
-```typescript
-import { isNil, isArray, isObject, isEmpty } from 'wssf-kage-js';
-
-isNil(null);           // => true
-isArray([1, 2, 3]);    // => true
-isObject({});          // => true
-isEmpty([]);           // => true
-```
-
-**可用方法:**
-- `isNil(value)` - 检查是否为 null 或 undefined
-- `isArray(value)` - 检查是否为数组
-- `isObject(value)` - 检查是否为对象
-- `isFunction(value)` - 检查是否为函数
-- `isString(value)` - 检查是否为字符串
-- `isNumber(value)` - 检查是否为数字
-- `isBoolean(value)` - 检查是否为布尔值
-- `isEmpty(value)` - 检查是否为空
-
-### 数组操作 (Array)
-
-强大的数组处理工具。
-
-```typescript
-import { chunk, uniq, flatten, shuffle } from 'wssf-kage-js';
-
-// 分块
-chunk([1, 2, 3, 4, 5], 2);
-// => [[1, 2], [3, 4], [5]]
+### 组合与 Prompt / 意图流水线（`compose.ts`）
 
-// 去重
-uniq([1, 2, 2, 3, 3]);
-// => [1, 2, 3]
+```ts
+import { sanitizePrompt, routeIntent, withFallback } from 'wssf-kage-js';
 
-// 扁平化
-flatten([1, [2, 3], [4]]);
-// => [1, 2, 3, 4]
+sanitizePrompt('  <b>x</b>  ');
+routeIntent({ text: '美元汇率' });
 
-// 随机打乱
-shuffle([1, 2, 3, 4, 5]);
-// => [3, 1, 5, 2, 4] (随机顺序)
-```
-
-**可用方法:**
-- `head(array)` - 获取第一个元素
-- `last(array)` - 获取最后一个元素
-- `tail(array)` - 获取除第一个元素外的所有元素
-- `uniq(array)` - 数组去重
-- `uniqBy(array, iteratee)` - 根据迭代函数去重
-- `flatten(array)` - 浅层扁平化
-- `flattenDeep(array)` - 深度扁平化
-- `chunk(array, size)` - 分块数组
-- `compact(array)` - 过滤假值
-- `difference(array, values)` - 数组差集
-- `intersection(array, ...arrays)` - 数组交集
-- `sum(array)` - 数组求和
-- `sumBy(array, iteratee)` - 根据迭代函数求和
-- `shuffle(array)` - 随机打乱
-- `sample(array)` - 随机取一个元素
-- `sampleSize(array, n)` - 随机取 n 个元素
-
-### 对象操作 (Object)
-
-灵活的对象处理方法。
-
-```typescript
-import { get, set, merge, pick, omit } from 'wssf-kage-js';
-
-const obj = { a: { b: { c: 3 } } };
-
-// 获取嵌套属性
-get(obj, 'a.b.c');
-// => 3
-
-// 设置嵌套属性
-set(obj, 'a.b.d', 4);
-// => { a: { b: { c: 3, d: 4 } } }
-
-// 合并对象
-merge({ a: 1 }, { b: 2 });
-// => { a: 1, b: 2 }
-
-// 选取属性
-pick({ a: 1, b: 2, c: 3 }, ['a', 'c']);
-// => { a: 1, c: 3 }
-
-// 排除属性
-omit({ a: 1, b: 2, c: 3 }, ['b']);
-// => { a: 1, c: 3 }
-```
-
-**可用方法:**
-- `cloneDeep(value)` - 深度克隆
-- `get(obj, path, defaultValue)` - 获取嵌套属性
-- `set(obj, path, value)` - 设置嵌套属性
-- `merge(target, ...sources)` - 合并对象
-- `pick(obj, keys)` - 选取属性
-- `omit(obj, keys)` - 排除属性
-- `keys(obj)` - 获取所有键
-- `values(obj)` - 获取所有值
-- `entries(obj)` - 获取键值对
-- `invert(obj)` - 反转键值
-- `mapValues(obj, iteratee)` - 映射对象值
-
-### 字符串操作 (String)
-
-丰富的字符串处理工具。
-
-```typescript
-import { camelCase, snakeCase, kebabCase, truncate } from 'wssf-kage-js';
-
-// 驼峰命名
-camelCase('hello-world');
-// => 'helloWorld'
-
-// 蛇形命名
-snakeCase('helloWorld');
-// => 'hello_world'
-
-// 短横线命名
-kebabCase('helloWorld');
-// => 'hello-world'
-
-// 截断字符串
-truncate('hello world', { length: 8 });
-// => 'hello...'
-```
-
-**可用方法:**
-- `capitalize(str)` - 首字母大写
-- `camelCase(str)` - 驼峰命名
-- `snakeCase(str)` - 蛇形命名
-- `kebabCase(str)` - 短横线命名
-- `trim(str, chars)` - 去除空格
-- `truncate(str, options)` - 截断字符串
-- `words(str)` - 分词
-- `repeat(str, n)` - 重复字符串
-- `padStart(str, length, chars)` - 左侧填充
-- `padEnd(str, length, chars)` - 右侧填充
-
-### 函数工具 (Function)
-
-高阶函数和函数式编程工具。
-
-```typescript
-import { debounce, throttle, once, memoize, curry } from 'wssf-kage-js';
-
-// 防抖
-const debouncedFn = debounce(() => {
-  console.log('执行');
-}, 1000);
-
-// 节流
-const throttledFn = throttle(() => {
-  console.log('执行');
-}, 1000);
-
-// 只执行一次
-const onceFn = once(() => {
-  console.log('只执行一次');
+const safe = withFallback('降级文案')(async () => {
+  throw new Error('fail');
 });
-
-// 记忆化
-const memoizedFn = memoize((x) => x * 2);
-
-// 柯里化
-const add = (a, b, c) => a + b + c;
-const curriedAdd = curry(add);
-curriedAdd(1)(2)(3); // => 6
+await safe();
 ```
 
-**可用方法:**
-- `debounce(func, wait, options)` - 防抖
-- `throttle(func, wait, options)` - 节流
-- `once(func)` - 只执行一次
-- `delay(func, wait, ...args)` - 延迟执行
-- `memoize(func, resolver)` - 记忆化
-- `curry(func, arity)` - 柯里化
-- `compose(...funcs)` - 函数组合
-- `pipe(...funcs)` - 管道函数
-
-### 数学运算 (Math)
-
-常用的数学计算工具。
+### 纯函数与闭包
 
-```typescript
-import { range, random, clamp, mean, max, min } from 'wssf-kage-js';
+```ts
+import { normalizeText, sumNumbers, createCounter } from 'wssf-kage-js';
 
-// 生成数字范围
-range(5);
-// => [0, 1, 2, 3, 4]
+normalizeText('  Hello  ');
+sumNumbers([1, 2, 3]);
 
-range(1, 5);
-// => [1, 2, 3, 4]
-
-range(0, 10, 2);
-// => [0, 2, 4, 6, 8]
-
-// 随机数
-random(1, 10);
-// => 7 (随机)
-
-// 限制范围
-clamp(15, 1, 10);
-// => 10
-
-// 求平均值
-mean([1, 2, 3, 4, 5]);
-// => 3
+const c = createCounter(0);
+c.increment();
 ```
 
-**可用方法:**
-- `range(start, end, step)` - 生成数字范围
-- `random(min, max, floating)` - 生成随机数
-- `clamp(number, min, max)` - 限制数字范围
-- `ceil(number, precision)` - 向上取整
-- `floor(number, precision)` - 向下取整
-- `round(number, precision)` - 四舍五入
-- `mean(array)` - 求平均值
-- `max(array)` - 求最大值
-- `min(array)` - 求最小值
-- `maxBy(array, iteratee)` - 根据迭代函数求最大值
-- `minBy(array, iteratee)` - 根据迭代函数求最小值
-
-## 🧪 测试
+### 异步与生成器
 
-```bash
-# 运行测试
-npm test
+```ts
+import { asyncMap, retryAsync, createRange, streamChunks } from 'wssf-kage-js';
 
-# 观察模式
-npm run test:watch
+await asyncMap([1, 2], async (n) => n * 2);
+await retryAsync(async () => 'ok', 2);
 
-# 生成覆盖率报告
-npm run test:coverage
-```
+[...createRange(1, 3)];
 
-## 📖 生成 API 文档
+for await (const x of streamChunks(['a', 'b'], 0)) {
+  console.log(x);
+}
+```
 
-本项目使用 TypeDoc 从源代码自动生成 API 文档：
+## 导出结构（与源码目录对应）
+
+| 模块 | 代表能力 / 符号 |
+|------|------------------|
+| `currying` | `curry`、`compose`、`pipe`、`get`/`set`、`map`/`filter`/`reduce`、`debounce`、`throttle`、`logger`、`request`、`validate` … |
+| `compose` | `composePipe`、`sanitizePrompt`、`safetyGate`、`routeIntent`、`tokenManager`、`buildPrompt`、`dataPipeline`、`processSearchList` … |
+| `higherOrder` | `withPermission`、`withPerformance`、`withTokenAudit`、`withFallback`、`withSanitizer`、`withLock`、`withAuditTrail`、`withUIFormat` |
+| `pureFunction` | `sumNumbers`、`normalizeText`、`calculateWeightedScore` |
+| `closureFunction` | `createCounter`、`createAccumulator` |
+| `partialFunction` | `partial`、`partialRight` |
+| `decoratorFunction` | `withLogging`、`withRetry` |
+| `middlewareFunction` | `runMiddleware`、`createLogMiddleware` |
+| `strategyFunction` | `createStrategyRunner`、`financeStrategy`、`codingStrategy`、`defaultStrategy` |
+| `guardFunction` | `assertDefined`、`assertNonEmptyArray`、`isRecord` |
+| `predicateFunction` | `isNonEmptyString`、`isPositiveNumber`、`andPredicate`、`orPredicate` |
+| `transformerFunction` | `toUserViewModel`、`transformCollection` |
+| `reducerFunction` | `counterReducer`、`reduceItems` |
+| `recursiveFunction` / `tailRecursiveFunction` | `factorialRecursive`、`flattenTree`、`factorialTailRecursive`、`sumTailRecursive` |
+| `lazyFunction` | `deferValue`、`createOnceResolver`、`mapLazyValue` |
+| `memoizedFunction` | `memoizeUnary`、`clearMemoizedCache` |
+| `callbackFunction` | `mapWithCallback`、`forEachWithCallback`、`createDelayedCallback` |
+| `asyncFunction` | `delay`、`asyncMap`、`retryAsync` |
+| `generatorFunction` / `asyncGeneratorFunction` | `createRange`、`iterateWords`、`streamChunks`、`collectAsyncGenerator` |
+| `factoryFunction` | `createFormatter`、`createThresholdChecker` |
+| `pointFreeFunction` | `mapValues`、`filterValues`、`joinWith`、`pointFreeUserNames` |
+| `monadFunction` | `some`、`none`、`mapOption`、`flatMapOption`、`getOptionOrElse` |
+
+完整分节说明与「每函数一例」见仓库 [**`docs/function-types/`**](https://github.com/hezihua/Kage_js/tree/main/docs/function-types)。
+
+## 本地开发与文档
 
 ```bash
-# 生成文档
-npm run docs
-
-# 观察模式（开发时使用）
-npm run docs:watch
+pnpm install
+pnpm run build          # 产出 dist/
+pnpm test               # 测试（若已配置）
+pnpm run docs:dev       # Docusaurus 文档站
+pnpm run docs:site:build
 ```
 
-生成的文档位于 `docs/` 目录，在浏览器中打开 `docs/index.html` 即可查看。
+TypeDoc 默认输出目录为 `typedoc-html/`（见 `typedoc.json`），与文档站 Markdown 源码分离。
 
-详细的文档编写指南请参考 [DOCS_GUIDE.md](./DOCS_GUIDE.md)。
+## 许可证
 
-## 🔨 构建
+MIT
 
-```bash
-npm run build
-```
+## 更新日志
 
-## 📄 许可证
+### 1.0.2
 
-MIT License
+- 修正 npm README：与当前 `src` 导出一致，移除不存在的 lodash 式 API 描述。
 
-## 🤝 贡献
+### 1.0.1
 
-欢迎提交 Issue 和 Pull Request！
+- 发版指向 npm 官方 `registry`；安装仍可使用国内镜像（见仓库 `.npmrc` 说明）。
 
-## 📝 更新日志
+### 1.0.0
 
-### 1.0.0 (2024-01-16)
-- 🎉 首次发布
-- ✨ 支持数组、对象、字符串、函数和数学运算工具
-- 📝 完善的 TypeScript 类型定义
-- 🧪 完整的测试覆盖
+- 首次公开发布。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wssf-kage-js",
-  "version": "1.0.1",
-  "description": "一个现代化的 JavaScript 工具库，类似 lodash",
+  "version": "1.0.2",
+  "description": "TypeScript 函数式工具：柯里化、组合、高阶拦截、纯函数、中间件等 24 类模式，面向前端与 AI 流水线",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
@@ -14,16 +14,16 @@
   },
   "homepage": "https://github.com/hezihua/Kage_js#readme",
   "keywords": [
-    "utility",
-    "lodash",
     "functional",
-    "array",
-    "object",
-    "string",
     "typescript",
-    "helpers",
-    "utils",
-    "tools"
+    "currying",
+    "compose",
+    "higher-order",
+    "middleware",
+    "prompt",
+    "ai",
+    "utilities",
+    "fp"
   ],
   "author": "hezihua <2283462371@qq.com>",
   "license": "MIT",