happy-rusty 1.5.0 → 1.6.1

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)
+[MIT](LICENSE)

package/README.md

@@ -1,53 +1,293 @@
-# Use Rust features in JavaScript happily
+# happy-rusty
+
+Rust's `Option`, `Result`, and sync primitives for JavaScript/TypeScript - Better error handling and null-safety patterns.
 
 [![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)
 
 ---
 
-## [中文](README.cn.md)
+[中文](README.cn.md)
 
 ---
 
-## Supported
+## Features
 
-- [Option](https://doc.rust-lang.org/core/option/index.html)
-- [Result](https://doc.rust-lang.org/core/result/index.html)
+- **Option<T>** - Represents an optional value: every `Option` is either `Some(T)` or `None`
+- **Result<T, E>** - Represents either success (`Ok(T)`) or failure (`Err(E)`)
+- **Sync Primitives** - Rust-inspired `Once<T>`, `Lazy<T>`, `LazyAsync<T>`, and `Mutex<T>`
+- **Control Flow** - `ControlFlow<B, C>` with `Break` and `Continue` for short-circuiting operations
+- **Full TypeScript support** with strict type inference
+- **Async support** - Async versions of all transformation methods
+- **Zero dependencies**
+- **Runtime immutability** - All instances are frozen with `Object.freeze()`
+- **Cross-runtime** - Works in Node.js, Deno, Bun, and browsers
 
 ## Installation
 
 ```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
 ```
 
-then import to your code.
+## Quick Start
 
 ```ts
 import { Some, None, Ok, Err } from 'happy-rusty';
+
+// Option - handling nullable values
+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 - handling errors
+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('Parse failed:', err);
+        return defaultSettings;
+    });
+```
+
+## API Overview
+
+### Option&lt;T&gt;
+
+| Category | Methods |
+|----------|---------|
+| **Constructors** | `Some(value)`, `None` |
+| **Querying** | `isSome()`, `isNone()`, `isSomeAnd(fn)` |
+| **Extracting** | `expect(msg)`, `unwrap()`, `unwrapOr(default)`, `unwrapOrElse(fn)` |
+| **Transforming** | `map(fn)`, `mapOr(default, fn)`, `mapOrElse(defaultFn, fn)`, `filter(fn)`, `flatten()` |
+| **Boolean ops** | `and(other)`, `andThen(fn)`, `or(other)`, `orElse(fn)`, `xor(other)` |
+| **Converting** | `okOr(err)`, `okOrElse(fn)`, `transpose()` |
+| **Combining** | `zip(other)`, `zipWith(other, fn)`, `unzip()` |
+| **Side effects** | `inspect(fn)` |
+| **Comparison** | `eq(other)` |
+
+### Result&lt;T, E&gt;
+
+| Category | Methods |
+|----------|---------|
+| **Constructors** | `Ok(value)`, `Ok()` (void), `Err(error)` |
+| **Querying** | `isOk()`, `isErr()`, `isOkAnd(fn)`, `isErrAnd(fn)` |
+| **Extracting Ok** | `expect(msg)`, `unwrap()`, `unwrapOr(default)`, `unwrapOrElse(fn)` |
+| **Extracting Err** | `expectErr(msg)`, `unwrapErr()` |
+| **Transforming** | `map(fn)`, `mapErr(fn)`, `mapOr(default, fn)`, `mapOrElse(defaultFn, fn)`, `flatten()` |
+| **Boolean ops** | `and(other)`, `andThen(fn)`, `or(other)`, `orElse(fn)` |
+| **Converting** | `ok()`, `err()`, `transpose()` |
+| **Type casting** | `asOk<F>()`, `asErr<U>()` |
+| **Side effects** | `inspect(fn)`, `inspectErr(fn)` |
+| **Comparison** | `eq(other)` |
+
+### Async Methods
+
+All transformation methods have async variants with `Async` suffix:
+
+```ts
+// Async Option methods
+isSomeAndAsync(asyncFn)
+unwrapOrElseAsync(asyncFn)
+andThenAsync(asyncFn)
+orElseAsync(asyncFn)
+
+// Async Result methods
+isOkAndAsync(asyncFn)
+isErrAndAsync(asyncFn)
+unwrapOrElseAsync(asyncFn)
+andThenAsync(asyncFn)
+orElseAsync(asyncFn)
+```
+
+### Type Aliases
+
+```ts
+// Convenient type aliases for common patterns
+type AsyncOption<T> = Promise<Option<T>>;
+type AsyncResult<T, E> = Promise<Result<T, E>>;
+
+// For I/O operations
+type IOResult<T> = Result<T, Error>;
+type AsyncIOResult<T> = Promise<IOResult<T>>;
+
+// For void returns
+type VoidResult<E> = Result<void, E>;
+type VoidIOResult = IOResult<void>;
+type AsyncVoidResult<E> = Promise<VoidResult<E>>;
+type AsyncVoidIOResult = Promise<VoidIOResult>;
 ```
 
-Enjoy the happiness.
+### Utility Functions
+
+```ts
+import { isOption, isResult, isControlFlow, promiseToAsyncResult } from 'happy-rusty';
+
+// Type guards
+if (isOption(value)) { /* ... */ }
+if (isResult(value)) { /* ... */ }
+if (isControlFlow(value)) { /* ... */ }
+
+// Convert Promise to Result
+const result = await promiseToAsyncResult(fetch('/api/data'));
+result.inspect(data => console.log(data))
+      .inspectErr(err => console.error(err));
+```
+
+### Constants
+
+```ts
+import { RESULT_TRUE, RESULT_FALSE, RESULT_ZERO, RESULT_VOID } from 'happy-rusty';
 
-## [Examples](examples/main.ts)
+// Reusable immutable Result constants
+function validate(): Result<boolean, Error> {
+    return isValid ? RESULT_TRUE : RESULT_FALSE;
+}
 
-- [Option](examples/option.ts)
+function doSomething(): Result<void, Error> {
+    // ...
+    return RESULT_VOID;
+}
+```
+
+### Sync Primitives
+
+```ts
+import { Once, Lazy, LazyAsync, Mutex } from 'happy-rusty';
+
+// Once - one-time initialization (like Rust's OnceLock)
+const config = Once<Config>();
+config.set(loadConfig());           // Set once
+config.get();                       // Some(config) or None
+config.getOrInit(() => defaultCfg); // Get or initialize
+
+// Lazy - lazy initialization with initializer at construction
+const expensive = Lazy(() => computeExpensiveValue());
+expensive.force();  // Compute on first access, cached thereafter
+
+// LazyAsync - async lazy initialization
+const db = LazyAsync(async () => await Database.connect(url));
+await db.force();  // Only one connection, concurrent calls wait
+
+// Mutex - async mutual exclusion
+const state = Mutex({ count: 0 });
+await state.withLock(async (s) => {
+    s.count += 1;  // Exclusive access
+});
+```
+
+### Control Flow
+
+```ts
+import { Break, Continue, ControlFlow } from 'happy-rusty';
+
+// Short-circuit operations
+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;
+}
+
+// Custom fold with early exit
+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;
+}
+```
+
+## Examples
+
+- [Option basics](examples/option.ts)
 - [AsyncOption](examples/option.async.ts)
-- [Result](examples/result.ts)
+- [Result basics](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)
+
+## Documentation
+
+Full API documentation is available at [jiangjie.github.io/happy-rusty](https://jiangjie.github.io/happy-rusty/).
+
+## Design Notes
+
+### Immutability
+
+All types (`Option`, `Result`, `ControlFlow`, `Lazy`, `LazyAsync`, `Once`, `Mutex`, `MutexGuard`) are **immutable at runtime** via `Object.freeze()`. This prevents accidental modification of methods or properties:
+
+```ts
+const some = Some(42);
+some.unwrap = () => 0;  // TypeError: Cannot assign to read only property
+```
+
+**Why no `readonly` in TypeScript interfaces?**
+
+We intentionally omit `readonly` modifiers from method signatures in interfaces. While this might seem to reduce type safety, there are compelling reasons:
+
+1. **Inheritance compatibility** - The `None` type extends `Option<never>`. TypeScript's arrow function property syntax (`readonly prop: () => T`) uses contravariant parameter checking, which causes `None` (with `never` parameters) to be incompatible with `Option<T>`. Method syntax (`method(): T`) uses bivariant checking, allowing the inheritance to work correctly.
+
+2. **Runtime protection is sufficient** - `Object.freeze()` already prevents reassignment at runtime. Adding `readonly` only provides compile-time checking, which offers marginal benefit when runtime protection exists.
+
+3. **Cleaner API** - Avoiding the `Mutable*` + `Readonly<>` pattern keeps the exported types clean and documentation readable.
+
+4. **Testing validates immutability** - Our test suite explicitly verifies that all instances are frozen and reject property modifications.
+
+## Why happy-rusty?
+
+JavaScript's `null`/`undefined` and try-catch patterns lead to:
+- Uncaught null reference errors
+- Forgotten error handling
+- Verbose try-catch blocks
+- Unclear function contracts
+
+`happy-rusty` provides Rust's battle-tested patterns:
+- **Explicit optionality** - `Option<T>` makes absence visible in types
+- **Explicit errors** - `Result<T, E>` forces error handling consideration
+- **Method chaining** - Transform values without nested if-else or try-catch
+- **Type safety** - Full TypeScript support with strict type inference
+
+## License
 
-## [Docs](docs/README.md)
+[MIT](LICENSE)