happy-rusty 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -0,0 +1,206 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.6.0] - 2025-12-18
+
+### Added
+- **Sync Primitives**: `Once<T>`, `Lazy<T>`, `LazyAsync<T>`, `Mutex<T>` for Rust-style synchronization
+- **Control Flow**: `ControlFlow<B, C>` with `Break` and `Continue` variants
+- `Symbol.toStringTag` property to all types for better type identification
+- Custom `toString()` method to all types for debugging
+- `isControlFlow()` type guard utility
+- `isNoneOr()` and `isNoneOrAsync()` methods for Option
+- `exports` field in package.json for modern Node.js module resolution
+- GitHub Pages workflow for automatic API documentation deployment
+- Immutability tests to verify `Object.freeze()` is working correctly
+- 100% test coverage
+- CHANGELOG.md with full version history
+
+### Changed
+- All instances are now frozen with `Object.freeze()` for runtime immutability
+- TypeDoc output format from Markdown to HTML for GitHub Pages compatibility
+- Migrated from Deno test to Vitest
+- Build process split into Vite (JS) and Rollup (dts)
+
+### Fixed
+- Symbol property syntax and duplicate declaration issues
+- Type inference improvements for `None` interface methods
+
+## [1.5.0] - 2024-08-11
+
+### Added
+- Async versions of methods: `isSomeAndAsync`, `isOkAndAsync`, `isErrAndAsync`, `unwrapOrElseAsync`, `andThenAsync`, `orElseAsync`
+- Async examples
+
+### Changed
+- Updated pnpm to v9.7.0
+- Updated ESLint configuration
+
+## [1.4.0] - 2024-08-05
+
+### Added
+- `Ok()` constructor without arguments (similar to Rust's `Ok(())`)
+- `RESULT_VOID` constant for void Result returns
+- `VoidResult<E>`, `VoidIOResult`, `AsyncVoidResult<E>`, `AsyncVoidIOResult` type aliases
+
+## [1.3.2] - 2024-08-04
+
+### Changed
+- Renamed `helpers` to `utils`
+- Improved `@example` annotations in JSDoc
+
+## [1.3.1] - 2024-08-03
+
+### Fixed
+- `map` methods now correctly return new objects instead of mutating
+
+### Changed
+- Updated Rollup to v4.20.0
+
+## [1.3.0] - 2024-08-01
+
+### Added
+- `RESULT_TRUE`, `RESULT_FALSE`, `RESULT_ZERO` constants
+
+### Fixed
+- Circular dependency issues
+
+### Changed
+- Reorganized code structure
+
+## [1.2.0] - 2024-08-01
+
+### Added
+- `isOption()` and `isResult()` type guard utilities
+- Custom string conversion for Option and Result
+
+### Changed
+- Replaced arrow functions with normal functions for better debug experience
+- Updated ESLint to v9
+
+## [1.1.2] - 2024-07-17
+
+### Added
+- `asOk<F>()` and `asErr<U>()` methods for type casting
+
+## [1.1.1] - 2024-07-13
+
+### Fixed
+- TypeDoc configuration issues
+
+### Changed
+- Updated dependencies
+
+## [1.1.0] - 2024-06-09
+
+### Added
+- `Option.filter()` method
+- Many new Option and Result APIs
+- Comprehensive code comments and documentation
+
+### Changed
+- Improved type inference
+- `Option.filter()` now returns `Option<T>` instead of boolean
+
+## [1.0.9] - 2024-05-14
+
+### Added
+- Documentation for exported symbols
+- README examples
+
+## [1.0.8] - 2024-05-13
+
+### Changed
+- Switched from npm to pnpm
+- Added GitHub Actions test workflow with Codecov
+
+## [1.0.7] - 2024-05-08
+
+### Changed
+- `Some` value type changed to `NonNullable<T>`
+
+### Fixed
+- Can now invoke `err()` from `Ok` variant
+
+## [1.0.6] - 2024-05-08
+
+### Added
+- Commonly used type exports
+
+### Changed
+- Set `type: "module"` in package.json
+- Build target set to ESNext
+
+## [1.0.5] - 2024-05-05
+
+### Changed
+- Throw `TypeError` instead of generic `Error`
+- Switched to Rollup for building
+- Added Bun support in CI
+
+## [1.0.4] - 2024-05-04
+
+### Added
+- Chinese README (`README.cn.md`)
+- JSR publishing workflow
+- npm publishing workflows
+
+### Changed
+- Replaced Parcel with Rollup for building
+- Replaced Jest with Bun test
+
+## [1.0.3] - 2024-04-27
+
+### Added
+- Installation and Examples sections in README
+
+### Changed
+- Force return const for better type inference
+
+## [1.0.2] - 2024-04-26
+
+### Added
+- JSR publishing support
+
+### Changed
+- Improved code comments
+
+## [1.0.1] - 2024-04-26
+
+### Changed
+- Replaced enum with const for better tree-shaking
+- Marked package as side-effect free
+
+## [1.0.0] - 2024-04-24
+
+### Added
+- Initial release
+- `Option<T>` type with `Some` and `None` variants
+- `Result<T, E>` type with `Ok` and `Err` variants
+- Full TypeScript support
+- Comprehensive API matching Rust's Option and Result
+
+[1.6.0]: https://github.com/JiangJie/happy-rusty/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/JiangJie/happy-rusty/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/JiangJie/happy-rusty/compare/v1.3.2...v1.4.0
+[1.3.2]: https://github.com/JiangJie/happy-rusty/compare/v1.3.1...v1.3.2
+[1.3.1]: https://github.com/JiangJie/happy-rusty/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/JiangJie/happy-rusty/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/JiangJie/happy-rusty/compare/v1.1.2...v1.2.0
+[1.1.2]: https://github.com/JiangJie/happy-rusty/compare/v1.1.1...v1.1.2
+[1.1.1]: https://github.com/JiangJie/happy-rusty/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/JiangJie/happy-rusty/compare/v1.0.9...v1.1.0
+[1.0.9]: https://github.com/JiangJie/happy-rusty/compare/v1.0.8...v1.0.9
+[1.0.8]: https://github.com/JiangJie/happy-rusty/compare/v1.0.7...v1.0.8
+[1.0.7]: https://github.com/JiangJie/happy-rusty/compare/v1.0.6...v1.0.7
+[1.0.6]: https://github.com/JiangJie/happy-rusty/compare/v1.0.5...v1.0.6
+[1.0.5]: https://github.com/JiangJie/happy-rusty/compare/v1.0.4...v1.0.5
+[1.0.4]: https://github.com/JiangJie/happy-rusty/compare/v1.0.3...v1.0.4
+[1.0.3]: https://github.com/JiangJie/happy-rusty/compare/v1.0.2...v1.0.3
+[1.0.2]: https://github.com/JiangJie/happy-rusty/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/JiangJie/happy-rusty/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/JiangJie/happy-rusty/releases/tag/v1.0.0

package/README.cn.md

@@ -1,47 +1,293 @@
-# 在 JavaScript 中使用 Rust 特性
+# happy-rusty
+
+将 Rust 的 `Option`、`Result` 和同步原语带入 JavaScript/TypeScript - 更好的错误处理和空值安全模式。
 
 [![NPM version](https://img.shields.io/npm/v/happy-rusty.svg)](https://npmjs.org/package/happy-rusty)
 [![NPM downloads](https://badgen.net/npm/dm/happy-rusty)](https://npmjs.org/package/happy-rusty)
 [![JSR Version](https://jsr.io/badges/@happy-js/happy-rusty)](https://jsr.io/@happy-js/happy-rusty)
 [![JSR Score](https://jsr.io/badges/@happy-js/happy-rusty/score)](https://jsr.io/@happy-js/happy-rusty/score)
-[![Build Status](https://github.com/jiangjie/happy-rusty/actions/workflows/test.yml/badge.svg)](https://github.com/jiangjie/happy-rusty/actions/workflows/test.yml)
+[![Build Status](https://github.com/JiangJie/happy-rusty/actions/workflows/test.yml/badge.svg)](https://github.com/JiangJie/happy-rusty/actions/workflows/test.yml)
 [![codecov](https://codecov.io/gh/JiangJie/happy-rusty/graph/badge.svg)](https://codecov.io/gh/JiangJie/happy-rusty)
 
 ---
 
-## 支持的特性
+[English](README.md)
+
+---
 
-- [Option](https://doc.rust-lang.org/core/option/index.html)
-- [Result](https://doc.rust-lang.org/core/result/index.html)
+## 特性
+
+- **Option<T>** - 表示可选值：每个 `Option` 要么是 `Some(T)`，要么是 `None`
+- **Result<T, E>** - 表示成功（`Ok(T)`）或失败（`Err(E)`）
+- **同步原语** - Rust 风格的 `Once<T>`、`Lazy<T>`、`LazyAsync<T>` 和 `Mutex<T>`
+- **控制流** - 用于短路操作的 `ControlFlow<B, C>`，包含 `Break` 和 `Continue`
+- **完整的 TypeScript 支持**，具有严格的类型推断
+- **异步支持** - 所有转换方法都有异步版本
+- **零依赖**
+- **运行时不可变** - 所有实例都通过 `Object.freeze()` 冻结
+- **跨运行时** - 支持 Node.js、Deno、Bun 和浏览器
 
 ## 安装
 
 ```sh
-# via pnpm
-pnpm add happy-rusty
-# or via yarn
+# npm
+npm install happy-rusty
+
+# yarn
 yarn add happy-rusty
-# or just from npm
-npm install --save happy-rusty
-# via JSR
-jsr add @happy-js/happy-rusty
-# for deno
+
+# pnpm
+pnpm add happy-rusty
+
+# JSR (Deno)
 deno add @happy-js/happy-rusty
-# for bun
+
+# JSR (Bun)
 bunx jsr add @happy-js/happy-rusty
 ```
 
-接下来就可以在代码里引用了。
+## 快速开始
 
 ```ts
 import { Some, None, Ok, Err } from 'happy-rusty';
+
+// Option - 处理可空值
+function findUser(id: number): Option<User> {
+    const user = database.get(id);
+    return user ? Some(user) : None;
+}
+
+const user = findUser(1)
+    .map(u => u.name)
+    .unwrapOr('Guest');
+
+// Result - 处理错误
+function parseJSON<T>(json: string): Result<T, Error> {
+    try {
+        return Ok(JSON.parse(json));
+    } catch (e) {
+        return Err(e as Error);
+    }
+}
+
+const config = parseJSON<Config>(jsonStr)
+    .map(c => c.settings)
+    .unwrapOrElse(err => {
+        console.error('解析失败:', err);
+        return defaultSettings;
+    });
+```
+
+## API 概览
+
+### Option&lt;T&gt;
+
+| 分类 | 方法 |
+|------|------|
+| **构造器** | `Some(value)`, `None` |
+| **查询** | `isSome()`, `isNone()`, `isSomeAnd(fn)` |
+| **提取** | `expect(msg)`, `unwrap()`, `unwrapOr(default)`, `unwrapOrElse(fn)` |
+| **转换** | `map(fn)`, `mapOr(default, fn)`, `mapOrElse(defaultFn, fn)`, `filter(fn)`, `flatten()` |
+| **布尔操作** | `and(other)`, `andThen(fn)`, `or(other)`, `orElse(fn)`, `xor(other)` |
+| **类型转换** | `okOr(err)`, `okOrElse(fn)`, `transpose()` |
+| **组合** | `zip(other)`, `zipWith(other, fn)`, `unzip()` |
+| **副作用** | `inspect(fn)` |
+| **比较** | `eq(other)` |
+
+### Result&lt;T, E&gt;
+
+| 分类 | 方法 |
+|------|------|
+| **构造器** | `Ok(value)`, `Ok()` (void), `Err(error)` |
+| **查询** | `isOk()`, `isErr()`, `isOkAnd(fn)`, `isErrAnd(fn)` |
+| **提取 Ok** | `expect(msg)`, `unwrap()`, `unwrapOr(default)`, `unwrapOrElse(fn)` |
+| **提取 Err** | `expectErr(msg)`, `unwrapErr()` |
+| **转换** | `map(fn)`, `mapErr(fn)`, `mapOr(default, fn)`, `mapOrElse(defaultFn, fn)`, `flatten()` |
+| **布尔操作** | `and(other)`, `andThen(fn)`, `or(other)`, `orElse(fn)` |
+| **类型转换** | `ok()`, `err()`, `transpose()` |
+| **类型断言** | `asOk<F>()`, `asErr<U>()` |
+| **副作用** | `inspect(fn)`, `inspectErr(fn)` |
+| **比较** | `eq(other)` |
+
+### 异步方法
+
+所有转换方法都有带 `Async` 后缀的异步变体：
+
+```ts
+// 异步 Option 方法
+isSomeAndAsync(asyncFn)
+unwrapOrElseAsync(asyncFn)
+andThenAsync(asyncFn)
+orElseAsync(asyncFn)
+
+// 异步 Result 方法
+isOkAndAsync(asyncFn)
+isErrAndAsync(asyncFn)
+unwrapOrElseAsync(asyncFn)
+andThenAsync(asyncFn)
+orElseAsync(asyncFn)
 ```
 
-## [示例](examples/main.ts)
+### 类型别名
+
+```ts
+// 常用模式的便捷类型别名
+type AsyncOption<T> = Promise<Option<T>>;
+type AsyncResult<T, E> = Promise<Result<T, E>>;
 
-- [Option](examples/option.ts)
+// 用于 I/O 操作
+type IOResult<T> = Result<T, Error>;
+type AsyncIOResult<T> = Promise<IOResult<T>>;
+
+// 用于 void 返回值
+type VoidResult<E> = Result<void, E>;
+type VoidIOResult = IOResult<void>;
+type AsyncVoidResult<E> = Promise<VoidResult<E>>;
+type AsyncVoidIOResult = Promise<VoidIOResult>;
+```
+
+### 工具函数
+
+```ts
+import { isOption, isResult, isControlFlow, promiseToAsyncResult } from 'happy-rusty';
+
+// 类型守卫
+if (isOption(value)) { /* ... */ }
+if (isResult(value)) { /* ... */ }
+if (isControlFlow(value)) { /* ... */ }
+
+// 将 Promise 转换为 Result
+const result = await promiseToAsyncResult(fetch('/api/data'));
+result.inspect(data => console.log(data))
+      .inspectErr(err => console.error(err));
+```
+
+### 常量
+
+```ts
+import { RESULT_TRUE, RESULT_FALSE, RESULT_ZERO, RESULT_VOID } from 'happy-rusty';
+
+// 可复用的不可变 Result 常量
+function validate(): Result<boolean, Error> {
+    return isValid ? RESULT_TRUE : RESULT_FALSE;
+}
+
+function doSomething(): Result<void, Error> {
+    // ...
+    return RESULT_VOID;
+}
+```
+
+### 同步原语
+
+```ts
+import { Once, Lazy, LazyAsync, Mutex } from 'happy-rusty';
+
+// Once - 一次性初始化（类似 Rust 的 OnceLock）
+const config = Once<Config>();
+config.set(loadConfig());           // 只能设置一次
+config.get();                       // Some(config) 或 None
+config.getOrInit(() => defaultCfg); // 获取或初始化
+
+// Lazy - 惰性初始化，在构造时提供初始化函数
+const expensive = Lazy(() => computeExpensiveValue());
+expensive.force();  // 首次访问时计算，之后缓存
+
+// LazyAsync - 异步惰性初始化
+const db = LazyAsync(async () => await Database.connect(url));
+await db.force();  // 只建立一次连接，并发调用会等待
+
+// Mutex - 异步互斥锁
+const state = Mutex({ count: 0 });
+await state.withLock(async (s) => {
+    s.count += 1;  // 独占访问
+});
+```
+
+### 控制流
+
+```ts
+import { Break, Continue, ControlFlow } from 'happy-rusty';
+
+// 短路操作
+function findFirst<T>(arr: T[], pred: (t: T) => boolean): Option<T> {
+    for (const item of arr) {
+        const flow = pred(item) ? Break(item) : Continue();
+        if (flow.isBreak()) {
+            return Some(flow.breakValue().unwrap());
+        }
+    }
+    return None;
+}
+
+// 带提前退出的自定义 fold
+function tryFold<T, Acc>(
+    arr: T[],
+    init: Acc,
+    f: (acc: Acc, item: T) => ControlFlow<Acc, Acc>
+): Acc {
+    let acc = init;
+    for (const item of arr) {
+        const flow = f(acc, item);
+        if (flow.isBreak()) return flow.breakValue().unwrap();
+        acc = flow.continueValue().unwrap();
+    }
+    return acc;
+}
+```
+
+## 示例
+
+- [Option 基础用法](examples/option.ts)
 - [AsyncOption](examples/option.async.ts)
-- [Result](examples/result.ts)
+- [Result 基础用法](examples/result.ts)
 - [AsyncResult](examples/result.async.ts)
+- [Once](examples/once.ts)
+- [Lazy](examples/lazy.ts)
+- [Mutex](examples/mutex.ts)
+- [ControlFlow](examples/control_flow.ts)
+
+## 文档
+
+完整的 API 文档请查看 [jiangjie.github.io/happy-rusty](https://jiangjie.github.io/happy-rusty/)。
+
+## 设计说明
+
+### 不可变性
+
+所有类型（`Option`、`Result`、`ControlFlow`、`Lazy`、`LazyAsync`、`Once`、`Mutex`、`MutexGuard`）都通过 `Object.freeze()` 实现**运行时不可变**。这可以防止意外修改方法或属性：
+
+```ts
+const some = Some(42);
+some.unwrap = () => 0;  // TypeError: Cannot assign to read only property
+```
+
+**为什么 TypeScript 接口没有使用 `readonly`？**
+
+我们有意在接口的方法签名中省略了 `readonly` 修饰符。虽然这看起来可能会降低类型安全性，但有以下几个原因：
+
+1. **继承兼容性** - `None` 类型继承自 `Option<never>`。TypeScript 的箭头函数属性语法（`readonly prop: () => T`）使用逆变参数检查，这会导致 `None`（参数为 `never`）与 `Option<T>` 不兼容。方法语法（`method(): T`）使用双变参数检查，使继承能够正常工作。
+
+2. **运行时保护已足够** - `Object.freeze()` 已经在运行时阻止了重新赋值。添加 `readonly` 只提供编译时检查，在已有运行时保护的情况下收益有限。
+
+3. **更简洁的 API** - 避免使用 `Mutable*` + `Readonly<>` 模式可以保持导出类型的简洁和文档的可读性。
+
+4. **测试验证不可变性** - 我们的测试套件明确验证了所有实例都被冻结并且会拒绝属性修改。
+
+## 为什么选择 happy-rusty？
+
+JavaScript 的 `null`/`undefined` 和 try-catch 模式会导致：
+- 未捕获的空引用错误
+- 遗忘的错误处理
+- 冗长的 try-catch 代码块
+- 不清晰的函数契约
+
+`happy-rusty` 提供了 Rust 久经考验的模式：
+- **显式可选性** - `Option<T>` 在类型中明确表示值的缺失
+- **显式错误** - `Result<T, E>` 强制考虑错误处理
+- **链式调用** - 无需嵌套 if-else 或 try-catch 即可转换值
+- **类型安全** - 完整的 TypeScript 支持，具有严格的类型推断
+
+## 许可证
 
-## [文档](docs/README.md)
+[GPL-3.0](LICENSE)