happy-rusty 1.9.2 → 1.10.1

package/CHANGELOG.md

@@ -5,46 +5,83 @@ 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.10.1] - 2026-09-06
+
+### Fixed
+
+- **Channel**: `for await` leaving early (a `break`, an error thrown in the loop body, or an explicit `iterator.return()`) now cancels the pending `next()`. An abandoned iterator no longer holds its spot in the receive queue, so it cannot swallow a message intended for another consumer
+- **Channel**: a timeout callback firing after its waiter was already served no longer removes an unrelated waiter (`splice(-1, 1)` on a `-1` index)
+- **OnceAsync**: `set()` and `tryInsert()` return `Err` while a `getOrInit`/`getOrTryInit` attempt is in flight, instead of reporting `Ok` and then being overwritten by the attempt's result — matching Rust's `OnceLock::set` racing an in-progress `get_or_init`
+- **OnceAsync**: `wait()` no longer rejects when an initialization attempt fails. It keeps waiting until the cell is actually initialized, matching Rust's `OnceLock::wait`
+- **OnceAsync**: a caller joining a failed attempt retries with its own initializer, matching Rust's `get_or_try_init`. The in-flight slot is claimed synchronously, so a synchronously-executing initializer that re-enters joins the attempt instead of starting a second one
+
+### Chores
+
+- Migrated to the Vite+ unified toolchain (`vp check` for fmt + lint + type checking, `vp pack` for JS and `.d.ts` bundling), replacing ESLint and the previous build setup
+- Merged all CI gates into a single `ci.yml` job and added attw + publint verification of the tarball that is actually published
+- Upgraded devDependencies: `vite-plus` 0.3.0, `@vitest/coverage-v8` 4.1.11, `publint` 0.3.24
+
+## [1.10.0] - 2026-06-30
+
+### Added
+
+- **New Sync Primitive**: `Semaphore` - Counting semaphore for limiting async concurrency, with `acquire`/`tryAcquire`/`withPermit`/`availablePermits`. Inspired by tokio's `Semaphore` (Rust std does not include one). Useful for fetch rate limiting, connection pools, and task queues.
+- **New Method**: `RwLockWriteGuard.downgrade()` - Atomically converts a write guard to a read guard, releasing waiting readers while keeping pending writers waiting. Equivalent to Rust 1.92's `RwLockWriteGuard::downgrade`
+
+### Chores
+
+- Upgraded devDependencies: vite, vitest, @vitest/coverage-v8, @vitest/ui, eslint, rollup, typescript-eslint
+
 ## [1.9.2] - 2026-04-12
 
 ### Changed
+
 - **Performance**: Added `/*#__PURE__*/` annotations to all top-level function call expressions for better tree-shaking support in consumer bundlers
 
 ### Fixed
+
 - **Build**: Migrated `treeshake` config from deprecated `'smallest'` string to object form for Vite 8 (Rolldown) compatibility
 - **Build**: Added `topLevelVar: false` to output options to preserve `const` declarations in bundled output
 
 ### Chores
+
 - Upgraded devDependencies: vite, vitest, eslint, typedoc, typescript-eslint
 
 ## [1.9.1] - 2026-01-16
 
 ### Changed
+
 - **Performance**: `Channel` buffer replaced `Array` with `Queue` for O(1) shift operations
 
 ### Documentation
+
 - Added `@since` tags to all public APIs
 - Improved JSDoc consistency and formatting
 
 ### CI
+
 - Changed JSR publish to trigger on release instead of push to main
 
 ## [1.9.0] - 2026-01-04
 
 ### Added
+
 - **Try Extensions for Result**:
   - `andTryAsync<U>` - Like `andThenAsync`, but auto-catches exceptions/Promise rejections and converts them to `Err`
   - `orTryAsync<F>` - Like `orElseAsync`, but auto-catches exceptions in recovery logic
 
 ### Changed
+
 - **Performance**: `map()` and `mapErr()` now return `this` when the Result variant doesn't match, avoiding unnecessary object creation
 
 ### Removed
+
 - `promiseToAsyncResult()` - Use `tryAsyncResult()` instead (deprecated since v1.7.0)
 
 ## [1.8.0] - 2025-12-31
 
 ### Added
+
 - **New Sync Primitives**:
   - `OnceAsync<T>` - Async-first one-time initialization with concurrent call handling
   - `RwLock<T>` - Async read-write lock (multiple concurrent readers or single writer)
@@ -69,18 +106,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Rust Documentation Links** - All Rust-equivalent interfaces now link to official Rust docs via `@see` tags
 
 ### Changed
+
 - **Module Reorganization** - Source code restructured into `core/` (Option, Result) and `std/` (sync, ops) directories, mirroring Rust's stdlib organization
 - **Async Callback Types** - All async methods now accept `PromiseLike<T> | T` instead of just `Promise<T>`, allowing mixed sync/async callbacks
 - **Async Return Types** - Use `Awaited<T>` to properly flatten nested Promises in async method return types
 - **Internal Optimizations** - Cached Promise constants (`ASYNC_NONE`, etc.) for better runtime performance
 
 ### Fixed
+
 - `this` binding issue in `Once.getOrTryInitAsync`
 - Nested Promise flattening in async methods
 
 ## [1.7.1] - 2025-12-26
 
 ### Added
+
 - **Argument passing** - All `try*` functions now support passing arguments like `Promise.try`:
   - `tryOption(JSON.parse, jsonString)` instead of `tryOption(() => JSON.parse(jsonString))`
   - `tryResult(decodeURIComponent, str)` instead of `tryResult(() => decodeURIComponent(str))`
@@ -89,35 +129,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.7.0] - 2025-12-26
 
 ### Added
+
 - `tryOption()` - Capture synchronous exceptions as Option (success → Some, exception → None)
 - `tryAsyncOption()` - Capture async/Promise exceptions as Option
 - `tryResult()` - Capture synchronous exceptions as Result (success → Ok, exception → Err)
 - `tryAsyncResult()` - Capture async/Promise exceptions as Result
 
 ### Deprecated
+
 - `promiseToAsyncResult()` - Use `tryAsyncResult()` instead (same functionality, more consistent naming)
 
 ## [1.6.2] - 2025-12-25
 
 ### Changed
+
 - `promiseToAsyncResult` now accepts `PromiseLike<T>` instead of `Promise<T>` for broader compatibility with thenable objects
 - Use `AsyncResult` type alias in function signatures for consistency
 
 ### Removed
+
 - Removed unused `source` field from package.json (Parcel legacy)
 - Removed redundant `@internal` tags from private (non-exported) functions
 
 ## [1.6.1] - 2025-12-19
 
 ### Changed
+
 - License changed from GPL-3.0 to MIT for broader adoption and easier integration
 
 ### Added
+
 - Navigation links (GitHub, npm, JSR) in TypeDoc documentation header
 
 ## [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
@@ -131,28 +178,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
@@ -160,94 +212,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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
@@ -255,45 +327,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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.10.1]: https://github.com/JiangJie/happy-rusty/compare/v1.10.0...v1.10.1
+[1.10.0]: https://github.com/JiangJie/happy-rusty/compare/v1.9.2...v1.10.0
 [1.9.2]: https://github.com/JiangJie/happy-rusty/compare/v1.9.1...v1.9.2
 [1.9.1]: https://github.com/JiangJie/happy-rusty/compare/v1.9.0...v1.9.1
 [1.9.0]: https://github.com/JiangJie/happy-rusty/compare/v1.8.0...v1.9.0

package/README.cn.md

@@ -1,7 +1,7 @@
 # happy-rusty
 
 [![License](https://img.shields.io/npm/l/happy-rusty.svg)](LICENSE)
-[![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/ci.yml/badge.svg)](https://github.com/JiangJie/happy-rusty/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/JiangJie/happy-rusty/graph/badge.svg)](https://codecov.io/gh/JiangJie/happy-rusty)
 [![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)
@@ -84,37 +84,39 @@ const config = parseJSON<Config>(jsonStr)
 
 ### 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)` |
+| 分类         | 方法                                                                                   |
+| ------------ | -------------------------------------------------------------------------------------- |
+| **构造器**   | `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)` |
+| 分类         | 方法                                                                                   |
+| ------------ | -------------------------------------------------------------------------------------- |
+| **构造器**   | `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` 后缀的异步变体（如 `andThenAsync`、`mapAsync`、`unwrapOrElseAsync`）。
 
+异步变体遵循库的错误约定：回调被实际调用时，若其同步抛错，错误会在调用点同步抛出——与同步方法一致；只有回调返回 rejected Promise 时，错误才以 rejection 形式呈现。如需把抛出的异常转为 `Err`/`None` 值，请使用 `try*` 辅助函数（`tryResult`/`tryAsyncResult`/`tryOption`/`tryAsyncOption`），或在 `Result` 上使用 `andTryAsync`/`orTryAsync` 方法。
+
 ### 类型别名
 
 ```ts
@@ -195,12 +197,14 @@ some.unwrap = () => 0;  // TypeError: Cannot assign to read only property
 ## 为什么选择 happy-rusty？
 
 JavaScript 的 `null`/`undefined` 和 try-catch 模式会导致：
+
 - 未捕获的空引用错误
 - 遗忘的错误处理
 - 冗长的 try-catch 代码块
 - 不清晰的函数契约
 
 `happy-rusty` 提供了 Rust 久经考验的模式：
+
 - **显式可选性** - `Option<T>` 在类型中明确表示值的缺失
 - **显式错误** - `Result<T, E>` 强制考虑错误处理
 - **链式调用** - 无需嵌套 if-else 或 try-catch 即可转换值

package/README.md

@@ -1,7 +1,7 @@
 # happy-rusty
 
 [![License](https://img.shields.io/npm/l/happy-rusty.svg)](LICENSE)
-[![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/ci.yml/badge.svg)](https://github.com/JiangJie/happy-rusty/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/JiangJie/happy-rusty/graph/badge.svg)](https://codecov.io/gh/JiangJie/happy-rusty)
 [![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)
@@ -20,7 +20,7 @@ Rust's `Option`, `Result`, and sync primitives for JavaScript/TypeScript - Bette
 
 - **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>`, `OnceAsync<T>`, `Lazy<T>`, `LazyAsync<T>`, `Mutex<T>`, `RwLock<T>`, and `Channel<T>`
+- **Sync Primitives** - Rust-inspired `Once<T>`, `OnceAsync<T>`, `Lazy<T>`, `LazyAsync<T>`, `Mutex<T>`, `RwLock<T>`, `Semaphore`, and `Channel<T>`
 - **Control Flow** - `ControlFlow<B, C>` with `Break` and `Continue` for short-circuiting operations
 - **FnOnce** - One-time callable function wrappers (`FnOnce` and `FnOnceAsync`)
 - **Full TypeScript support** with strict type inference
@@ -84,37 +84,39 @@ const config = parseJSON<Config>(jsonStr)
 
 ### Option&lt;T&gt;
 
-| Category | Methods |
-|----------|---------|
-| **Constructors** | `Some(value)`, `None` |
-| **Querying** | `isSome()`, `isNone()`, `isSomeAnd(fn)` |
-| **Extracting** | `expect(msg)`, `unwrap()`, `unwrapOr(default)`, `unwrapOrElse(fn)` |
+| 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)` |
+| **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)` |
+| 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 (e.g., `andThenAsync`, `mapAsync`, `unwrapOrElseAsync`).
 
+Async variants follow the library's error convention: when the callback is invoked, a synchronous throw propagates synchronously at the call site — just like the sync methods — and only a callback that returns a rejected promise surfaces as a promise rejection. To capture thrown exceptions as `Err`/`None` values instead, use the `try*` helpers (`tryResult`/`tryAsyncResult`/`tryOption`/`tryAsyncOption`) or, on `Result`, the `andTryAsync`/`orTryAsync` methods.
+
 ### Type Aliases
 
 ```ts
@@ -137,7 +139,7 @@ const response = await tryAsyncResult(fetch, '/api/data');
 ### Sync Primitives
 
 ```ts
-import { Lazy, LazyAsync, Mutex, Channel } from 'happy-rusty';
+import { Lazy, LazyAsync, Mutex, Semaphore, Channel } from 'happy-rusty';
 
 // Lazy - compute once on first access
 const expensive = Lazy(() => computeExpensiveValue());
@@ -151,6 +153,10 @@ await db.force();  // Only one connection, concurrent calls wait
 const state = Mutex({ count: 0 });
 await state.withLock(async (s) => { s.count += 1; });
 
+// Semaphore - limit async concurrency (e.g. fetch rate limiting)
+const sem = Semaphore(10);
+await sem.withPermit(() => fetch(url));
+
 // Channel - MPMC async message passing
 const ch = Channel<string>(10);  // bounded capacity
 await ch.send('hello');
@@ -165,6 +171,7 @@ for await (const msg of ch) { console.log(msg); }
 - [Lazy](examples/std/sync/lazy.ts) / [LazyAsync](examples/std/sync/lazy_async.ts)
 - [Mutex](examples/std/sync/mutex.ts)
 - [RwLock](examples/std/sync/rwlock.ts)
+- [Semaphore](examples/std/sync/semaphore.ts)
 - [Channel](examples/std/sync/channel.ts)
 - [ControlFlow](examples/std/ops/control_flow.ts)
 - [FnOnce](examples/std/ops/fn_once.ts) / [FnOnceAsync](examples/std/ops/fn_once_async.ts)
@@ -173,7 +180,7 @@ for await (const msg of ch) { console.log(msg); }
 
 ### Immutability
 
-All types (`Option`, `Result`, `ControlFlow`, `Lazy`, `LazyAsync`, `Once`, `OnceAsync`, `Mutex`, `MutexGuard`, `RwLock`, `Channel`, `Sender`, `Receiver`, `FnOnce`, `FnOnceAsync`) are **immutable at runtime** via `Object.freeze()`. This prevents accidental modification of methods or properties:
+All types (`Option`, `Result`, `ControlFlow`, `Lazy`, `LazyAsync`, `Once`, `OnceAsync`, `Mutex`, `MutexGuard`, `RwLock`, `Semaphore`, `SemaphorePermit`, `Channel`, `Sender`, `Receiver`, `FnOnce`, `FnOnceAsync`) are **immutable at runtime** via `Object.freeze()`. This prevents accidental modification of methods or properties:
 
 ```ts
 const some = Some(42);
@@ -195,12 +202,14 @@ We intentionally omit `readonly` modifiers from method signatures in interfaces.
 ## 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