happy-rusty 1.9.2 → 1.10.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.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
@@ -294,6 +303,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Full TypeScript support
 - Comprehensive API matching Rust's Option and Result
 
+[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.md

@@ -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
@@ -137,7 +137,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 +151,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 +169,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 +178,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);

package/dist/main.cjs

@@ -22,7 +22,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 *
 * @internal
 */
-const OptionKindSymbol = /* @__PURE__ */ Symbol("Option kind");
+const OptionKindSymbol = /*#__PURE__*/ Symbol("Option kind");
 //#endregion
 //#region src/core/option/guards.ts
 /**
@@ -67,7 +67,7 @@ function isOption(o) {
 *
 * @internal
 */
-const ResultKindSymbol = /* @__PURE__ */ Symbol("Result kind");
+const ResultKindSymbol = /*#__PURE__*/ Symbol("Result kind");
 //#endregion
 //#region src/core/result/guards.ts
 /**
@@ -102,8 +102,8 @@ function isResult(r) {
 * - `Err<T, E>(error)` - Creates a failed Result
 * - `None` interface - Type overrides for better type inference
 */
-const ASYNC_TRUE$1 = /* @__PURE__ */ Promise.resolve(true);
-const ASYNC_FALSE$1 = /* @__PURE__ */ Promise.resolve(false);
+const ASYNC_TRUE$1 = /*#__PURE__*/ Promise.resolve(true);
+const ASYNC_FALSE$1 = /*#__PURE__*/ Promise.resolve(false);
 /**
 * Creates an `Option<T>` representing the presence of a value.
 * This function is typically used to construct an `Option` that contains a value, indicating that the operation yielding the value was successful.
@@ -264,7 +264,7 @@ function Some(value) {
 * const name = None.unwrapOr('Anonymous'); // 'Anonymous'
 * ```
 */
-const None = /* @__PURE__ */ Object.freeze({
+const None = /*#__PURE__*/ Object.freeze({
 	[Symbol.toStringTag]: "Option",
 	[OptionKindSymbol]: "None",
 	*[Symbol.iterator]() {},
@@ -403,7 +403,7 @@ const None = /* @__PURE__ */ Object.freeze({
 * }
 * ```
 */
-const ASYNC_NONE = /* @__PURE__ */ Promise.resolve(None);
+const ASYNC_NONE = /*#__PURE__*/ Promise.resolve(None);
 function Ok(value) {
 	const ok = Object.freeze({
 		[Symbol.toStringTag]: "Result",
@@ -803,7 +803,7 @@ async function tryAsyncOption(task, ...args) {
 * const value: boolean = RESULT_TRUE.intoOk(); // Safe extraction
 * ```
 */
-const RESULT_TRUE = /* @__PURE__ */ Ok(true);
+const RESULT_TRUE = /*#__PURE__*/ Ok(true);
 /**
 * Result constant for `false`.
 * Can be used anywhere due to immutability.
@@ -818,7 +818,7 @@ const RESULT_TRUE = /* @__PURE__ */ Ok(true);
 * const value: boolean = RESULT_FALSE.intoOk(); // Safe extraction
 * ```
 */
-const RESULT_FALSE = /* @__PURE__ */ Ok(false);
+const RESULT_FALSE = /*#__PURE__*/ Ok(false);
 /**
 * Result constant for `0`.
 * Can be used anywhere due to immutability.
@@ -833,7 +833,7 @@ const RESULT_FALSE = /* @__PURE__ */ Ok(false);
 * const value: number = RESULT_ZERO.intoOk(); // Safe extraction
 * ```
 */
-const RESULT_ZERO = /* @__PURE__ */ Ok(0);
+const RESULT_ZERO = /*#__PURE__*/ Ok(0);
 /**
 * Result constant for `void` or `()`.
 * Can be used anywhere due to immutability.
@@ -848,7 +848,7 @@ const RESULT_ZERO = /* @__PURE__ */ Ok(0);
 * RESULT_VOID.intoOk(); // Safe extraction (returns undefined)
 * ```
 */
-const RESULT_VOID = /* @__PURE__ */ Ok();
+const RESULT_VOID = /*#__PURE__*/ Ok();
 //#endregion
 //#region src/core/result/extensions.ts
 /**
@@ -935,7 +935,7 @@ async function tryAsyncResult(task, ...args) {
 *
 * @internal
 */
-const ControlFlowKindSymbol = /* @__PURE__ */ Symbol("ControlFlow kind");
+const ControlFlowKindSymbol = /*#__PURE__*/ Symbol("ControlFlow kind");
 //#endregion
 //#region src/std/ops/control_flow.ts
 /**
@@ -1148,8 +1148,8 @@ function isControlFlow(cf) {
 * Supports rendezvous (capacity=0) for synchronous handoff between sender and receiver.
 *
 */
-const ASYNC_TRUE = /* @__PURE__ */ Promise.resolve(true);
-const ASYNC_FALSE = /* @__PURE__ */ Promise.resolve(false);
+const ASYNC_TRUE = /*#__PURE__*/ Promise.resolve(true);
+const ASYNC_FALSE = /*#__PURE__*/ Promise.resolve(false);
 /**
 * Creates a new MPMC channel with the specified capacity.
 *
@@ -2215,6 +2215,17 @@ function RwLock(value) {
 				if (released) return;
 				released = true;
 				releaseWrite();
+			},
+			downgrade() {
+				if (released) throw new Error("RwLockWriteGuard has been released");
+				released = true;
+				writer = false;
+				readers = 1;
+				while (readWaitQueue.length > 0) {
+					readers++;
+					readWaitQueue.shift()();
+				}
+				return createReadGuard();
 			}
 		});
 	}
@@ -2303,6 +2314,119 @@ function RwLock(value) {
 	});
 }
 //#endregion
+//#region src/std/sync/semaphore.ts
+/**
+* @module
+* Counting semaphore for limiting async concurrency.
+*
+* Inspired by [tokio's `Semaphore`](https://docs.rs/tokio/latest/tokio/sync/struct.Semaphore.html)
+* (Rust std does not include one). Unlike `Mutex<T>` which binds to a value,
+* `Semaphore` is a pure concurrency counter: it limits how many async
+* operations can run concurrently without protecting any data.
+*
+* **When to use `Semaphore` vs `Mutex<T>`:**
+* - Use `Mutex<T>` for exclusive access to a value (n=1, with data)
+* - Use `Semaphore` to limit concurrency to N (e.g. fetch rate limiting,
+*   connection pools, task queues)
+*
+* `Semaphore(1)` behaves like a `Mutex` without a value (a binary semaphore),
+* but `Mutex<T>` is preferred when you need to protect a value since the
+* guard provides typed access via `value`.
+*/
+/**
+* Creates a new `Semaphore` with the given capacity.
+*
+* @param permits - The maximum number of concurrent operations allowed.
+*                  Must be a non-negative integer. Use `0` to disallow any
+*                  concurrent acquire (acquire will wait forever).
+* @returns A new `Semaphore` instance.
+* @throws {RangeError} If `permits` is negative or not an integer.
+* @example
+* ```ts
+* // Limit to 5 concurrent operations
+* const sem = Semaphore(5);
+*
+* // Binary semaphore (equivalent to a value-less Mutex)
+* const binary = Semaphore(1);
+* ```
+*
+* @example
+* ```ts
+* // Task queue: process 2 jobs at a time
+* const sem = Semaphore(2);
+*
+* async function processJob(job: Job) {
+*     return sem.withPermit(async () => {
+*         return await runJob(job);
+*     });
+* }
+*
+* await Promise.all(jobs.map(processJob));
+* ```
+*/
+function Semaphore(permits) {
+	if (!Number.isInteger(permits) || permits < 0) throw new RangeError(`Semaphore capacity must be a non-negative integer, got ${permits}`);
+	const capacity = permits;
+	let available = permits;
+	const waitQueue = [];
+	function releasePermit() {
+		if (waitQueue.length > 0) waitQueue.shift()();
+		else available++;
+	}
+	function createPermit() {
+		let released = false;
+		return Object.freeze({
+			[Symbol.toStringTag]: "SemaphorePermit",
+			toString() {
+				return released ? "SemaphorePermit(<released>)" : "SemaphorePermit";
+			},
+			release() {
+				if (released) return;
+				released = true;
+				releasePermit();
+			}
+		});
+	}
+	function acquire() {
+		if (available > 0) {
+			available--;
+			return Promise.resolve(createPermit());
+		}
+		return new Promise((resolve) => {
+			waitQueue.push(() => {
+				resolve(createPermit());
+			});
+		});
+	}
+	function tryAcquire() {
+		if (available > 0) {
+			available--;
+			return Some(createPermit());
+		}
+		return None;
+	}
+	return Object.freeze({
+		[Symbol.toStringTag]: "Semaphore",
+		toString() {
+			return `Semaphore(${available}/${capacity})`;
+		},
+		capacity,
+		async withPermit(fn) {
+			const permit = await acquire();
+			try {
+				return await fn();
+			} finally {
+				permit.release();
+			}
+		},
+		acquire,
+		tryAcquire,
+		availablePermits() {
+			return available;
+		}
+	});
+}
+//#endregion
 exports.ASYNC_NONE = ASYNC_NONE;
 exports.Break = Break;
 exports.Channel = Channel;
@@ -2322,6 +2446,7 @@ exports.RESULT_TRUE = RESULT_TRUE;
 exports.RESULT_VOID = RESULT_VOID;
 exports.RESULT_ZERO = RESULT_ZERO;
 exports.RwLock = RwLock;
+exports.Semaphore = Semaphore;
 exports.Some = Some;
 exports.isControlFlow = isControlFlow;
 exports.isOption = isOption;