ansuko 1.3.3 → 1.3.4

package/README.zh.md

@@ -1,6 +1,6 @@
 # ansuko
 
-一个现代化的 JavaScript/TypeScript 实用工具库，以实用、直观的行为扩展 lodash。
+在lodash基础上扩展、提供实用且直观易懂的现代JavaScript/TypeScript工具库。
 
 [English](./README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh.md)
 
@@ -12,8 +12,6 @@
 - **ansuko = underscore → low dash → lodash** - 延续这个系列
 - **スコ (suko)** - 日文俚语，意为"喜欢"或"最爱"
 
-这个库修复了 lodash 的不直观行为，并添加了强大的工具来消除常见的 JavaScript 困扰。
-
 ## 安装
 
 ```bash
@@ -32,40 +30,40 @@ npm install ansuko
 
 ## 核心理念
 
-ansuko 通过直观的行为消除常见的 JavaScript 困扰：
+ansuko以直观的语法,解决了JavaScript中常见的痛点。
 
-### 修复 lodash 的怪异行为
+### 修正 lodash 的非常规行为
 
 ```typescript
 // ❌ lodash（不直观）
-_.isEmpty(0)           // true  - 0 真的"空"吗？
-_.isEmpty(true)        // true  - true "空"吗？
-_.castArray(null)      // [null] - 为什么保留 null？
+_.isEmpty(0)           // true  - 0真的为「空」吗？
+_.isEmpty(true)        // true  - true算「空」吗？
+_.castArray(null)      // [null] - 为何保留null？
 
 // ✅ ansuko（直观）
-_.isEmpty(0)           // false - 数字不为空
+_.isEmpty(0)           // false - 数值不为空
 _.isEmpty(true)        // false - 布尔值不为空
-_.castArray(null)      // []    - 干净的空数组
+_.castArray(null)      // []    - 得到空数组
 ```
 
 ### 安全的 JSON 处理
 
 ```typescript
-// ❌ 标准 JSON（烦人）
-JSON.stringify('hello')  // '"hello"'  - 额外的引号！
-JSON.parse(badJson)      // 抛出错误  - 需要 try-catch
-
-// ✅ ansuko（流畅）
-_.jsonStringify('hello')     // null     - 不是对象
-_.jsonStringify({ a: 1 })    // '{"a":1}' - 干净
-_.parseJSON(badJson)         // null     - 无异常
-_.parseJSON('{ a: 1, }')     // {a:1}    - 支持 JSON5！
+// ❌ 标准 JSON（繁琐）
+JSON.stringify('hello')  // '"hello"'  - 多余的引号
+JSON.parse(badJson)      // throws    - 必须用try-catch
+
+// ✅ ansuko（简洁直观）
+_.jsonStringify('hello')     // null     - 非对象不序列化
+_.jsonStringify({ a: 1 })    // '{"a":1}' - 结构简洁
+_.parseJSON(badJson)         // null     - 不抛异常
+_.parseJSON('{ a: 1, }')     // {a:1}    - 支持JSON5！
 ```
 
-### Promise 感知的后备
+### 支持Promise的回滚
 
 ```typescript
-// ❌ 冗长的模式
+// ❌ 冗长写法
 const data = await fetchData()
 const result = data ? data : await fetchBackup()
 
@@ -79,7 +77,7 @@ const result = await _.valueOr(
 ### 智能比较
 
 ```typescript
-// ❌ 冗长的三元表达式地狱
+// ❌ 三元运算符地狱
 const value = a === b ? a : (a == null && b == null ? a : defaultValue)
 
 // ✅ ansuko（可读）
@@ -88,40 +86,40 @@ const value = _.equalsOr(a, b, defaultValue)  // null == undefined
 
 ## 主要特性
 
-### 增强的 lodash 函数
+### 增强型lodash函数
 
-- **`isEmpty`** - 检查是否为空（数字和布尔值不为空）
-- **`castArray`** - 转换为数组，null/undefined 返回 `[]`
-- 所有 lodash 函数仍然可用：`size`、`isNil`、`debounce`、`isEqual`、`keys`、`values`、`has` 等
+- **`isEmpty`** - 检查是否为空（数字和布尔值不视为空）
+- **`castArray`** - 转换为数组，若为null/undefined 则返回 `[]`
+- 支持所有lodash函数：`size`、`isNil`、`debounce`、`isEqual`、`keys`、`values`、`has` 等
 
-### 值处理与控制流
+### 数值处理与流控制
 
-- **`valueOr`** - 获取值或默认值，支持 Promise/函数
-- **`emptyOr`** - 如果为空返回 null，否则应用回调或返回值
-- **`hasOr`** - 检查路径是否存在，如果缺失则返回默认值（支持深度路径和 Promise）
-- **`equalsOr`** - 比较并后备，具有直观的 nil 处理（支持 Promise）
-- **`changes`** - 跟踪对象差异用于数据库更新（支持深度路径如 `profile.tags[1]` 和排除模式）
-- **`swallow`** - 执行函数，出错时返回 undefined（同步/异步支持）
-- **`swallowMap`** - 映射数组，将错误视为 undefined（可选紧凑模式过滤错误）
+- **`valueOr`** - 支持Promise和函数，获取目标值或默认值
+- **`emptyOr`** - 若为空则返回null，否则应用回调或返回值
+- **`hasOr`** - 检查路径是否存在，不存在则返回默认值（支持深层路径及 Promise）
+- **`equalsOr`** - 支持Promise的比较与回退，具备直观的Nil处理机制
+- **`changes`** - 用于数据库更新的对象差分追踪（支持 profile.tags[1]等深层路径及排除模式）`和排除模式）
+- **`swallow`** - 执行函数并在报错时返回undefined（支持同步/异步）
+- **`swallowMap`** - 将错误处理为undefined的数组map（支持compact模式排除错误项）
 
 ### 类型转换与验证
 
-- **`toNumber`** - 解析数字，支持逗号/全角，无效时返回 `null`
-- **`toBool`** - 智能布尔值转换（"yes"/"no"/"true"/"false"/数字），可配置未检测处理
-- **`boolIf`** - 带后备的安全布尔值转换
+- **`toNumber`** - 解析包含逗号、全角字符的数字，无效时返回null
+- **`toBool`** - 智能布尔值转换（支持 "yes"/"no"/"true"/"false"/数字），可配置未检测到时的行为检测处理
+- **`boolIf`** - 带有回退机制的安全布尔值转换
 - **`isValidStr`** - 非空字符串验证
 
 ### JSON 处理
 
-- **`parseJSON`** - 无需 try-catch 的安全 JSON/JSON5 解析（支持注释和尾随逗号）
-- **`jsonStringify`** - 仅字符串化有效对象，防止意外的字符串包装
+- **`parseJSON`** - 无需try-catch的安全JSON/JSON5解析（支持注释及末尾逗号）
+- **`jsonStringify`** - 仅字符串化有效对象，防止字符串被重复包裹
 
 ### 数组工具
 
 - **`arrayDepth`** - 返回数组的嵌套深度（非数组：0，空数组：1）
 - **`castArray`** - 转换为数组，nil 变为 `[]`（而非 `[null]`）
 
-### 日文文本（插件：`ansuko/plugins/ja`）
+### 日语文本处理（插件：`ansuko/plugins/ja`）
 
 - **`kanaToFull`** - 半角片假名 → 全角（例如 `ｶﾞｷﾞ` → `ガギ`）
 - **`kanaToHalf`** - 全角 → 半角片假名（浊音拆分：`ガギ` → `ｶﾞｷﾞ`）
@@ -129,53 +127,51 @@ const value = _.equalsOr(a, b, defaultValue)  // null == undefined
 - **`hiraToKana`** - 平假名 → 片假名
 - **`toHalfWidth`** - 全角 → 半角，可选连字符标准化
 - **`toFullWidth`** - 半角 → 全角，可选连字符标准化
-- **`haifun`** - 将各种连字符标准化为单一字符
+- **`haifun`** - 将各种形式的连字符统一正规化
 
-### 地理工具（插件：`ansuko/plugins/geo`）
+### Geo地理空间工具（插件：`ansuko/plugins/geo`）
 
-- **`toGeoJson`** - 通用 GeoJSON 转换器，具有自动检测功能（从高维度到低维度尝试）
-- **`toPointGeoJson`** - 将坐标/对象转换为 Point GeoJSON
-- **`toPolygonGeoJson`** - 将外环转换为 Polygon（验证闭合环）
-- **`toLineStringGeoJson`** - 将坐标转换为 LineString（检查自相交）
-- **`toMultiPointGeoJson`** - 将多个点转换为 MultiPoint
-- **`toMultiPolygonGeoJson`** - 将多个多边形转换为 MultiPolygon
-- **`toMultiLineStringGeoJson`** - 将多条线转换为 MultiLineString
-- **`unionPolygon`** - 将多个 Polygon/MultiPolygon 合并为单个几何
-- **`parseToTerraDraw`** - 将 GeoJSON 转换为 Terra Draw 兼容的要素
-- **`mZoomInterpolate`** - 将缩放对象转换为 MapBox 插值表达式
-- **`mProps`** - 将 camelCase 属性转换为 MapBox 兼容格式（处理 minzoom、visibility 等特殊情况）
+- **`toGeoJson`** - 具备自动检测功能的通用GeoJSON转换器（按高维到低维顺序尝试）
+- **`toPointGeoJson`** - 将坐标或对象转换为Point GeoJSON
+- **`toPolygonGeoJson`** - 将外环转换为Polygon（验证闭合环）
+- **`toLineStringGeoJson`** - 将坐标转换为LineString（检查自相交）
+- **`toMultiPointGeoJson`** - 将多个点转换为MultiPoint
+- **`toMultiPolygonGeoJson`** - 将多个多边形转换为MultiPolygon
+- **`toMultiLineStringGeoJson`** - 将多条线转换为MultiLineString
+- **`unionPolygon`** - 将多个Polygon/MultiPolygon合并为单一几何体
+- **`parseToTerraDraw`** - 将GeoJSON转换为兼容Terra Draw的Feature
+- **`mZoomInterpolate`** - 将缩放对象转换为MapBox插值表达式
+- **`mProps`** - 将（camelCase）属性转换为MapBox兼容格式（处理minzoom、visibility等特殊情况）
 
-### 原型扩展（插件：`ansuko/plugins/prototype`）
+### Prototype原型扩展（插件：`ansuko/plugins/prototype`）
 
-- **`Array.prototype.notMap`** - 使用否定谓词映射 → 布尔数组
-- **`Array.prototype.notFilter`** - 通过否定谓词过滤（不匹配的项）
+- **`Array.prototype.notMap`** - 使用谓词取反进行map，返回布尔数组
+- **`Array.prototype.notFilter`** - 使用谓词取反进行filter（筛选不匹配的项）
 
 ### 时间工具
 
-- **`waited`** - 通过 N 个动画帧延迟执行（比 `setTimeout` 更适合 React/DOM）
+- **`waited`** - 延迟N个动画帧后执行（在 React/DOM 環境下比`setTimeout`更优）
 
 ## 插件架构
 
-ansuko 使用最小核心 + 插件架构来保持你的包大小小：
-
-- **核心**（~20KB）：改进 lodash 的基本工具
-- **日文插件**（~5KB）：仅在需要日文文本处理时加载
-- **地理插件**（~100KB 含 @turf/turf）：仅为 GIS 应用加载
-- **原型插件**（~1KB）：仅在需要数组原型扩展时加载
+ansuko使用最小核心 + 插件架构来保持你的包大小小：
 
-这意味着你只为使用的功能付费！
+- **核心**（约 20KB）：在 lodash 上增强的必备工具
+- **日文插件**（约 5KB）：仅在需要日文文本处理时引入
+- **Geo 插件**（约 100KB，含 @turf/turf）：面向 GIS 应用
+- **Prototype 插件**（约 1KB）：仅在需要扩展 Array.prototype 时引入
 
 ```typescript
-// 最小包 - 仅核心
+// 最小打包：仅核心
 import _ from 'ansuko'  // ~20KB
 
-// 需要时添加日文支持
+// 按需加入日文支持
 import jaPlugin from 'ansuko/plugins/ja'
-_.extend(jaPlugin)  // +5KB
+const extended = _.extend(jaPlugin)  // +5KB
 
-// 为地图应用添加 GIS 功能
+// 地图类应用再挂载 GIS
 import geoPlugin from 'ansuko/plugins/geo'
-_.extend(geoPlugin)  // +100KB
+const full = extended.extend(geoPlugin)  // +100KB
 ```
 
 ## 快速开始
@@ -289,37 +285,37 @@ extended.toPointGeoJson([139.7, 35.6])
 
 ## 文档
 
-详细信息请参阅：
+更多详细信息，请参阅：
 
-- **[API 参考](./docs/API.zh.md)** - 带示例的完整 API 文档
-- **[使用指南](./docs/Guide.zh.md)** - 实际示例和模式
+- **[API 参考](./docs/API.zh.md)** - 包含示例的完整API文档
+- **[使用指南](./docs/Guide.zh.md)** - 实际使用案例与设计模式
 
-## TypeScript 支持
+## 支持TypeScript 
 
-完整的 TypeScript 支持，包含类型定义。所有函数都完全类型化，支持泛型。
+完美支持TypeScript，包含完整的类型定义。所有函数均支持泛型，并经过严格的类型标注。
 
-## 为什么不只使用 lodash？
+## 为什么仅有lodash还不够？
 
-lodash 很优秀，但有一些[社区批评](https://github.com/lodash/lodash/issues)的怪异行为：
+lodash很优秀，但存在一些[被社区广为诟病](https://github.com/lodash/lodash/issues)的怪癖：
 
-### 修复的行为
+### 已修正的部分
 
-1. **`_.isEmpty(true)` 返回 `true`** - 布尔值真的"空"吗？
-2. **`_.isEmpty(1)` 返回 `true`** - 数字 1 "空"吗？
-3. **`_.castArray(null)` 返回 `[null]`** - 为什么在数组中包含 null？
+1. **`_.isEmpty(true)` 返回 `true`** - 布尔值真的为"空"吗？
+2. **`_.isEmpty(1)` 返回 `true`** - 数字1怎么能为"空"呢？
+3. **`_.castArray(null)` 返回 `[null]`** - 为什么要把null包含在数组里？
 
-### lodash 中缺少的添加工具
+### lodash中没有的工具函数
 
-4. **无安全的 JSON 解析** - 总是需要 try-catch 块
-5. **无内置的比较与后备** - 到处都是冗长的三元表达式模式
-6. **无 Promise 感知的值解析** - 手动 Promise 处理变得混乱
-7. **无对象差异跟踪** - 需要外部库进行数据库更新
-8. **`JSON.stringify("hello")` 添加引号** - 那些 `'"hello"'` 引号很烦人
+4. **无安全的 JSON 解析** - 总是需要写重复的try-catch代码块
+5. **无内置的比较与后备** - 代码中到处充斥着冗余的三元运算符
+6. **无 Promise 感知的值解析** - 手动处理Promise逻辑非常繁琐
+7. **无对象差异跟踪** - 进行数据库更新操作时往往需要引入额外库
+8. **`JSON.stringify("hello")` 会添加多余引号 —— 生成 `'"hello"'`这种带引号的繁琐字符串
 
-### 实际示例
+### 实际使用案例
 
 ```typescript
-// lodash 的常见模式（冗长且容易出错）
+// lodash的常见写法（冗长且易错）
 let data
 try {
   const cached = cache.get(id)
@@ -333,7 +329,7 @@ try {
   data = defaultValue
 }
 
-// ansuko 的相同逻辑（简洁且安全）
+// ansuko的实现逻辑（简洁且安全）
 const data = await _.valueOr(
   () => cache.get(id),
   () => api.fetch(id),
@@ -341,13 +337,13 @@ const data = await _.valueOr(
 )
 ```
 
-ansuko 保持与 lodash 的 **100% 兼容性**，同时修复这些问题并为现代 JavaScript 开发添加强大的工具。
+ansuko在修正上述问题的同时，为现代JavaScript开发增添了强大的工具函数，并保持了与Lodash的100%兼容性。
 
 ## 依赖项
 
 - **`lodash`** - 核心工具函数
-- **`json5`** - 增强的 JSON 解析，支持注释和尾随逗号
-- **`@turf/turf`** - 地理空间分析（由地理插件使用）
+- **`json5`** - 支持注释和末尾逗号的扩展JSON解析
+- **`@turf/turf`** - 地理空间分析（用于geo插件）
 
 ## 从源代码构建
 
@@ -356,10 +352,10 @@ npm install
 npm run build
 ```
 
-这将在 `dist` 目录中生成编译后的 JavaScript 和类型定义。
+执行后将在`dist`目录下生成编译后的JavaScript文件和类型定义。
 
-## 开发
-由 Sera 开发，Claude（Anthropic）协助文档编写、代码审查和技术讨论。
+## 开发相关
+因为不太擅长写测试和文档，所以一直在使用Claude进行头脑风暴并辅助编写文档。
 
 ## 许可证
 
@@ -371,4 +367,4 @@ Naoto Sera
 
 ---
 
-无论中日国际形势如何，我认为开源软件（OSS）应始终保持和平。也衷心希望您能有同样的想法。
+技术无国界，开源即和平。无论世界如何变迁，愿代码始终纯粹。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ansuko",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "A modern JavaScript/TypeScript utility library that extends lodash with practical, intuitive behaviors. Fixes lodash quirks, adds Promise support, Japanese text processing, and GeoJSON utilities.",
   "keywords": [
     "lodash",