happy-rusty 1.9.2 → 1.10.1

package/dist/{main.cjs → mod.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
 /**
@@ -90,6 +90,19 @@ function isResult(r) {
 	return r != null && typeof r === "object" && ResultKindSymbol in r;
 }
 //#endregion
+//#region src/internal/constants.ts
+/**
+* @module
+* Internal cached Promise constants for async method optimization.
+*
+* Shared by `core/prelude.ts` and `std/sync/channel.ts` to avoid duplicate allocations.
+* Not re-exported from `src/mod.ts`; consumers cannot import these.
+*/
+/** Cached `Promise<true>` for reuse by async predicate short-circuit branches. */
+const ASYNC_TRUE = /*#__PURE__*/ Promise.resolve(true);
+/** Cached `Promise<false>` for reuse by async predicate short-circuit branches. */
+const ASYNC_FALSE = /*#__PURE__*/ Promise.resolve(false);
+//#endregion
 //#region src/core/prelude.ts
 /**
 * @module
@@ -102,8 +115,6 @@ 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);
 /**
 * 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.
@@ -140,13 +151,15 @@ function Some(value) {
 			return predicate(value);
 		},
 		isSomeAndAsync(predicate) {
-			return Promise.resolve(predicate(value));
+			const r = predicate(value);
+			return typeof r === "boolean" ? r ? ASYNC_TRUE : ASYNC_FALSE : Promise.resolve(r);
 		},
 		isNoneOr(predicate) {
 			return predicate(value);
 		},
 		isNoneOrAsync(predicate) {
-			return Promise.resolve(predicate(value));
+			const r = predicate(value);
+			return typeof r === "boolean" ? r ? ASYNC_TRUE : ASYNC_FALSE : Promise.resolve(r);
 		},
 		expect(_msg) {
 			return value;
@@ -198,9 +211,8 @@ function Some(value) {
 			return other.isSome() ? Some(fn(value, other.unwrap())) : None;
 		},
 		unzip() {
-			const tuple = value;
-			if (!Array.isArray(tuple) || tuple.length !== 2) throw new TypeError(`Option::unzip() requires a 2-element tuple, received ${Array.isArray(tuple) ? `array with ${tuple.length} elements` : typeof tuple}`);
-			const [a, b] = tuple;
+			if (!Array.isArray(value) || value.length !== 2) throw new TypeError(`Option::unzip() requires a 2-element tuple, received ${Array.isArray(value) ? `array with ${value.length} elements` : typeof value}`);
+			const [a, b] = value;
 			return [Some(a), Some(b)];
 		},
 		reduce(other, fn) {
@@ -264,7 +276,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]() {},
@@ -281,13 +293,13 @@ const None = /* @__PURE__ */ Object.freeze({
 		return false;
 	},
 	isSomeAndAsync(_predicate) {
-		return ASYNC_FALSE$1;
+		return ASYNC_FALSE;
 	},
 	isNoneOr(_predicate) {
 		return true;
 	},
 	isNoneOrAsync(_predicate) {
-		return ASYNC_TRUE$1;
+		return ASYNC_TRUE;
 	},
 	expect(msg) {
 		throw new TypeError(msg);
@@ -403,7 +415,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",
@@ -424,13 +436,14 @@ function Ok(value) {
 			return predicate(value);
 		},
 		isOkAndAsync(predicate) {
-			return Promise.resolve(predicate(value));
+			const r = predicate(value);
+			return typeof r === "boolean" ? r ? ASYNC_TRUE : ASYNC_FALSE : Promise.resolve(r);
 		},
 		isErrAnd(_predicate) {
 			return false;
 		},
 		isErrAndAsync(_predicate) {
-			return ASYNC_FALSE$1;
+			return ASYNC_FALSE;
 		},
 		expect(_msg) {
 			return value;
@@ -570,13 +583,14 @@ function Err(error) {
 			return false;
 		},
 		isOkAndAsync(_predicate) {
-			return ASYNC_FALSE$1;
+			return ASYNC_FALSE;
 		},
 		isErrAnd(predicate) {
 			return predicate(error);
 		},
 		isErrAndAsync(predicate) {
-			return Promise.resolve(predicate(error));
+			const r = predicate(error);
+			return typeof r === "boolean" ? r ? ASYNC_TRUE : ASYNC_FALSE : Promise.resolve(r);
 		},
 		expect(msg) {
 			throw new TypeError(`${msg}: ${error}`);
@@ -803,7 +817,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 +832,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 +847,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 +862,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 +949,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 +1162,6 @@ 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);
 /**
 * Creates a new MPMC channel with the specified capacity.
 *
@@ -1195,7 +1207,7 @@ const ASYNC_FALSE = /* @__PURE__ */ Promise.resolve(false);
 *
 * // Multiple producers
 * async function logFromService(name: string) {
-*     const sender = logs.sender();
+*     const sender = logs.sender;
 *     await sender.send(`[${name}] Started`);
 *     // ... do work ...
 *     await sender.send(`[${name}] Finished`);
@@ -1203,7 +1215,7 @@ const ASYNC_FALSE = /* @__PURE__ */ Promise.resolve(false);
 *
 * // Single consumer writing to file
 * async function writeLogsToFile() {
-*     const receiver = logs.receiver();
+*     const receiver = logs.receiver;
 *     for await (const log of receiver) {
 *         await fs.appendFile('app.log', log + '\n');
 *     }
@@ -1282,7 +1294,7 @@ function Channel(capacity = Infinity) {
 			sendWaitQueue.push(waiter);
 			const timeoutId = setTimeout(() => {
 				const index = sendWaitQueue.indexOf(waiter);
-				sendWaitQueue.splice(index, 1);
+				if (index >= 0) sendWaitQueue.splice(index, 1);
 				resolve(false);
 			}, ms);
 			const originalResolve = waiter.resolve;
@@ -1304,23 +1316,61 @@ function Channel(capacity = Infinity) {
 			receiveWaitQueue.push(wrappedWaiter);
 			const timeoutId = setTimeout(() => {
 				const index = receiveWaitQueue.indexOf(wrappedWaiter);
-				receiveWaitQueue.splice(index, 1);
+				if (index >= 0) receiveWaitQueue.splice(index, 1);
 				resolve(None);
 			}, ms);
 		});
 	}
 	function asyncIterator() {
-		return { async next() {
-			const result = await receive();
-			if (result.isNone()) return {
-				done: true,
-				value: void 0
-			};
-			return {
-				done: false,
-				value: result.unwrap()
-			};
-		} };
+		let finished = false;
+		const parked = /* @__PURE__ */ new Set();
+		return {
+			[Symbol.asyncIterator]() {
+				return this;
+			},
+			next() {
+				if (finished) return Promise.resolve({
+					done: true,
+					value: void 0
+				});
+				const result = tryReceive();
+				if (result.isSome()) return Promise.resolve({
+					done: false,
+					value: result.unwrap()
+				});
+				if (closed) return Promise.resolve({
+					done: true,
+					value: void 0
+				});
+				return new Promise((resolve) => {
+					const waiter = (value) => {
+						parked.delete(waiter);
+						if (value.isNone()) resolve({
+							done: true,
+							value: void 0
+						});
+						else resolve({
+							done: false,
+							value: value.unwrap()
+						});
+					};
+					parked.add(waiter);
+					receiveWaitQueue.push(waiter);
+				});
+			},
+			return() {
+				finished = true;
+				for (const waiter of parked) {
+					receiveWaitQueue.splice(receiveWaitQueue.indexOf(waiter), 1);
+					waiter(None);
+				}
+				parked.clear();
+				return Promise.resolve({
+					done: true,
+					value: void 0
+				});
+			}
+		};
 	}
 	function createSender() {
 		return Object.freeze({
@@ -1983,21 +2033,73 @@ function OnceAsync() {
 		for (const waiter of waiters) waiter(val);
 		waiters = [];
 	}
+	/**
+	* Claims the in-flight slot for a fresh initialization attempt.
+	*
+	* The joinable `pendingPromise` is created *before* the caller invokes its
+	* initializer, so a synchronously-executing initializer that re-enters
+	* through `getOrInit`/`getOrTryInit` (or calls `set`/`tryInsert`) sees the
+	* slot as taken and joins/waits instead of starting a second attempt.
+	*
+	* The marker is cleared as soon as the attempt settles, and this handler is
+	* registered first so it runs before any waiter's retry handler — a retry
+	* must observe the cell as free to start a fresh attempt.
+	*/
+	function claimAttempt() {
+		let commit;
+		let fail;
+		const attempt = new Promise((resolve, reject) => {
+			commit = (val) => resolve(val);
+			fail = (reason) => reject(reason);
+		});
+		pendingPromise = attempt;
+		const clear = () => {
+			if (pendingPromise === attempt) pendingPromise = void 0;
+		};
+		attempt.then(clear, clear);
+		return {
+			attempt,
+			commit,
+			fail,
+			clear
+		};
+	}
 	function getOrTryInit(fn) {
 		if (initialized) return resolvedResultPromise ??= Promise.resolve(Ok(value));
 		if (pendingPromise) return pendingPromise.then(() => Ok(value), () => getOrTryInit(fn));
-		const resultPromise = Promise.resolve(fn());
-		pendingPromise = resultPromise.then((result) => {
-			if (result.isOk()) {
-				const val = result.unwrap();
-				setValue(val);
-				return val;
-			}
-			throw result;
-		}).finally(() => {
-			pendingPromise = void 0;
-		});
-		return pendingPromise.then(() => resultPromise, () => resultPromise);
+		const { attempt, commit, fail, clear } = claimAttempt();
+		let resultPromise;
+		try {
+			resultPromise = Promise.resolve(fn());
+			resultPromise.then((result) => {
+				if (result.isOk()) {
+					const val = result.unwrap();
+					setValue(val);
+					commit(val);
+				} else fail(result);
+			}, fail).catch(fail);
+		} catch (error) {
+			fail(error);
+			clear();
+			throw error;
+		}
+		return attempt.then(() => resultPromise, () => resultPromise);
+	}
+	function getOrInit(fn) {
+		if (initialized) return resolvedPromise ??= Promise.resolve(value);
+		if (pendingPromise) return pendingPromise.then(() => resolvedPromise ??= Promise.resolve(value), () => getOrInit(fn));
+		const { attempt, commit, fail, clear } = claimAttempt();
+		try {
+			Promise.resolve(fn()).then((result) => {
+				setValue(result);
+				commit(result);
+			}, fail).catch(fail);
+		} catch (error) {
+			fail(error);
+			clear();
+			throw error;
+		}
+		return attempt;
 	}
 	return Object.freeze({
 		[Symbol.toStringTag]: "OnceAsync",
@@ -2008,26 +2110,16 @@ function OnceAsync() {
 			return initialized ? Some(value) : None;
 		},
 		set(newValue) {
-			if (initialized) return Err(newValue);
+			if (initialized || pendingPromise !== void 0) return Err(newValue);
 			setValue(newValue);
 			return RESULT_VOID;
 		},
 		tryInsert(newValue) {
-			if (initialized) return Err([value, newValue]);
+			if (initialized || pendingPromise !== void 0) return Err([initialized ? value : void 0, newValue]);
 			setValue(newValue);
 			return Ok(newValue);
 		},
-		getOrInit(fn) {
-			if (initialized) return resolvedPromise ??= Promise.resolve(value);
-			if (pendingPromise) return pendingPromise;
-			pendingPromise = Promise.resolve(fn()).then((result) => {
-				setValue(result);
-				return result;
-			}).finally(() => {
-				pendingPromise = void 0;
-			});
-			return pendingPromise;
-		},
+		getOrInit,
 		getOrTryInit,
 		take() {
 			if (!initialized) return None;
@@ -2043,7 +2135,6 @@ function OnceAsync() {
 		},
 		wait() {
 			if (initialized) return resolvedPromise ??= Promise.resolve(value);
-			if (pendingPromise) return pendingPromise;
 			return new Promise((resolve) => {
 				waiters.push(resolve);
 			});
@@ -2215,6 +2306,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 +2405,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 +2537,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;
@@ -2331,4 +2547,4 @@ exports.tryAsyncResult = tryAsyncResult;
 exports.tryOption = tryOption;
 exports.tryResult = tryResult;
 
-//# sourceMappingURL=main.cjs.map
+//# sourceMappingURL=mod.cjs.map