happy-rusty 1.5.0 → 1.6.0

package/dist/types.d.ts

@@ -1,9 +1,36 @@
 /**
- * Symbol for Option kind: `Some` or `None`.
+ * @fileoverview
+ * Internal symbols used to identify `Option` and `Result` type variants.
+ *
+ * These symbols are used as property keys to distinguish between `Some`/`None` and `Ok`/`Err` variants.
+ * They provide a reliable way to identify the variant of an `Option` or `Result` instance without
+ * relying on method calls or duck typing.
+ *
+ * Note: These symbols are internal implementation details and are not exported as part of the public API.
+ * Use the `isOption` and `isResult` utility functions for type checking instead.
+ */
+/**
+ * A unique symbol used as a property key to identify the variant of an `Option` instance.
+ *
+ * When accessed on an `Option`, returns `'Some'` if the Option contains a value,
+ * or `'None'` if it represents the absence of a value.
+ *
+ * This symbol is used internally by the `isOption` utility function to verify
+ * that an object is a valid `Option` instance.
+ *
+ * @internal
  */
 declare const OptionKindSymbol: unique symbol;
 /**
- * Symbol for Result kind: `Ok` or `Err`.
+ * A unique symbol used as a property key to identify the variant of a `Result` instance.
+ *
+ * When accessed on a `Result`, returns `'Ok'` if the Result represents success,
+ * or `'Err'` if it represents failure.
+ *
+ * This symbol is used internally by the `isResult` utility function to verify
+ * that an object is a valid `Result` instance.
+ *
+ * @internal
  */
 declare const ResultKindSymbol: unique symbol;
 
@@ -30,15 +57,31 @@ pub enum Option<T> {
  */
 interface Option<T> {
     /**
-     * [object Option].
+     * The well-known symbol `Symbol.toStringTag` used by `Object.prototype.toString()`.
+     * Returns `'Option'` so that `Object.prototype.toString.call(option)` produces `'[object Option]'`.
+     *
+     * This enables reliable type identification even across different execution contexts (e.g., iframes, different module instances).
      *
-     * @private
+     * @example
+     * ```ts
+     * const x = Some(5);
+     * console.log(Object.prototype.toString.call(x)); // '[object Option]'
+     * ```
+     *
+     * @internal
      */
     readonly [Symbol.toStringTag]: 'Option';
     /**
-     * Identify `Some` or `None`.
+     * A unique symbol property used to identify the variant of this `Option`.
+     * Returns `'Some'` if the Option contains a value, or `'None'` if it represents absence.
+     *
+     * This is used internally by the `isOption` utility function to verify that an object is a valid `Option` instance,
+     * and to distinguish between `Some` and `None` variants without calling methods.
      *
-     * @private
+     * Note: The symbol itself is not exported as part of the public API.
+     * Use the `isOption` utility function or the `isSome()`/`isNone()` methods for type checking.
+     *
+     * @internal
      */
     readonly [OptionKindSymbol]: 'Some' | 'None';
     /**
@@ -46,21 +89,81 @@ interface Option<T> {
      */
     /**
      * Returns `true` if the Option is a `Some` value.
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * console.log(x.isSome()); // true
+     *
+     * const y = None;
+     * console.log(y.isSome()); // false
+     * ```
      */
     isSome(): boolean;
     /**
      * Returns `true` if the Option is a `None` value.
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * console.log(x.isNone()); // false
+     *
+     * const y = None;
+     * console.log(y.isNone()); // true
+     * ```
      */
     isNone(): boolean;
     /**
      * Returns `true` if the Option is a `Some` value and the predicate returns `true` for the contained value.
      * @param predicate - A function that takes the contained value and returns a boolean.
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * console.log(x.isSomeAnd(v => v > 1)); // true
+     * console.log(x.isSomeAnd(v => v > 5)); // false
+     * ```
      */
     isSomeAnd(predicate: (value: T) => boolean): boolean;
     /**
      * Asynchronous version of `isSomeAnd`.
+     * @param predicate - An async function that takes the contained value and returns a `Promise<boolean>`.
+     * @returns A promise that resolves to `true` if the Option is `Some` and the predicate resolves to `true`.
+     * @see isSomeAnd
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * await x.isSomeAndAsync(async v => v > 1); // true
+     * ```
      */
     isSomeAndAsync(predicate: (value: T) => Promise<boolean>): Promise<boolean>;
+    /**
+     * Returns `true` if the Option is `None`, or the predicate returns `true` for the contained value.
+     * @param predicate - A function that takes the contained value and returns a boolean.
+     * @see isSomeAnd
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * console.log(x.isNoneOr(v => v > 1)); // true
+     * console.log(x.isNoneOr(v => v > 5)); // false
+     *
+     * const y = None;
+     * console.log(y.isNoneOr(v => v > 5)); // true (always true for None)
+     * ```
+     */
+    isNoneOr(predicate: (value: T) => boolean): boolean;
+    /**
+     * Asynchronous version of `isNoneOr`.
+     * @param predicate - An async function that takes the contained value and returns a `Promise<boolean>`.
+     * @returns A promise that resolves to `true` if the Option is `None` or the predicate resolves to `true`.
+     * @see isNoneOr
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * await x.isNoneOrAsync(async v => v > 1); // true
+     *
+     * const y = None;
+     * await y.isNoneOrAsync(async v => v > 5); // true
+     * ```
+     */
+    isNoneOrAsync(predicate: (value: T) => Promise<boolean>): Promise<boolean>;
     /**
      * These methods extract the contained value in an `Option<T>` when it is the `Some` variant:
      */
@@ -68,25 +171,67 @@ interface Option<T> {
      * Returns the contained `Some` value, with a provided error message if the value is a `None`.
      * @param msg - The error message to provide if the value is a `None`.
      * @throws {TypeError} Throws an error with the provided message if the Option is a `None`.
+     * @see unwrap
+     * @example
+     * ```ts
+     * const x = Some(5);
+     * console.log(x.expect('value should exist')); // 5
+     *
+     * const y = None;
+     * y.expect('value should exist'); // throws TypeError: value should exist
+     * ```
      */
     expect(msg: string): T;
     /**
      * Returns the contained `Some` value.
      * @throws {TypeError} Throws an error if the value is a `None`.
+     * @see expect
+     * @see unwrapOr
+     * @example
+     * ```ts
+     * const x = Some(5);
+     * console.log(x.unwrap()); // 5
+     *
+     * const y = None;
+     * y.unwrap(); // throws TypeError
+     * ```
      */
     unwrap(): T;
     /**
      * Returns the contained `Some` value or a provided default.
      * @param defaultValue - The value to return if the Option is a `None`.
+     * @see unwrapOrElse
+     * @example
+     * ```ts
+     * const x = Some(5);
+     * console.log(x.unwrapOr(10)); // 5
+     *
+     * const y = None;
+     * console.log(y.unwrapOr(10)); // 10
+     * ```
      */
     unwrapOr(defaultValue: T): T;
     /**
      * Returns the contained `Some` value or computes it from a closure.
      * @param fn - A function that returns the default value.
+     * @see unwrapOr
+     * @example
+     * ```ts
+     * const x = None;
+     * console.log(x.unwrapOrElse(() => 10)); // 10
+     * ```
      */
     unwrapOrElse(fn: () => T): T;
     /**
      * Asynchronous version of `unwrapOrElse`.
+     * @param fn - An async function that returns a `Promise<T>` as the default value.
+     * @returns A promise that resolves to the contained value or the result of the async function.
+     * @see unwrapOrElse
+     * @example
+     * ```ts
+     * const x = None;
+     * await x.unwrapOrElseAsync(async () => 10); // 10
+     * ```
      */
     unwrapOrElseAsync(fn: () => Promise<T>): Promise<T>;
     /**
@@ -96,23 +241,49 @@ interface Option<T> {
      * Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(err)`.
      * @typeParam E - The type of the error value in the `Err` variant of the resulting `Result`.
      * @param error - The error value to use if the Option is a `None`.
+     * @see okOrElse
+     * @example
+     * ```ts
+     * const x = Some(5);
+     * console.log(x.okOr('error').isOk()); // true
+     *
+     * const y = None;
+     * console.log(y.okOr('error').unwrapErr()); // 'error'
+     * ```
      */
     okOr<E>(error: E): Result<T, E>;
     /**
      * Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(err())`.
      * @typeParam E - The type of the error value in the `Err` variant of the resulting `Result`.
      * @param err - A function that returns the error value.
+     * @see okOr
+     * @example
+     * ```ts
+     * const x = None;
+     * console.log(x.okOrElse(() => 'error').unwrapErr()); // 'error'
+     * ```
      */
     okOrElse<E>(err: () => E): Result<T, E>;
     /**
      * Transposes an `Option` of a `Result` into a `Result` of an `Option`.
-     * @typeParam T - The type of the success value in the `Ok` variant of the `Result`.
+     * @typeParam U - The type of the success value in the `Ok` variant of the `Result`.
      * @typeParam E - The type of the error value in the `Err` variant of the `Result`.
      * @returns `Ok` containing `Some` if the Option is a `Some` containing `Ok`,
      *          `Err` containing the error if the Option is a `Some` containing `Err`,
      *          `Ok` containing `None` if the Option is `None`.
+     * @example
+     * ```ts
+     * const x = Some(Ok(5));
+     * console.log(x.transpose().unwrap().unwrap()); // 5
+     *
+     * const y = Some(Err('error'));
+     * console.log(y.transpose().unwrapErr()); // 'error'
+     *
+     * const z: Option<Result<number, string>> = None;
+     * console.log(z.transpose().unwrap().isNone()); // true
+     * ```
      */
-    transpose<T, E>(this: Option<Result<T, E>>): Result<Option<T>, E>;
+    transpose<U, E>(this: Option<Result<U, E>>): Result<Option<U>, E>;
     /**
      * These methods transform the `Some` variant:
      */
@@ -121,17 +292,41 @@ interface Option<T> {
      * - `Some(t)` if predicate returns `true` (where `t` is the wrapped value), and
      * - `None` if predicate returns `false`.
      * @param predicate - A function that takes the contained value and returns a boolean.
+     * @example
+     * ```ts
+     * const x = Some(4);
+     * console.log(x.filter(v => v > 2).isSome()); // true
+     * console.log(x.filter(v => v > 5).isNone()); // true
+     * ```
      */
     filter(predicate: (value: T) => boolean): Option<T>;
     /**
-     * Converts from `Option<Option<T>>` to `Option<T>`.
+     * Converts from `Option<Option<U>>` to `Option<U>`.
+     * @typeParam U - The type of the value contained in the inner `Option`.
      * @returns `None` if the Option is `None`, otherwise returns the contained `Option`.
+     * @example
+     * ```ts
+     * const x = Some(Some(5));
+     * console.log(x.flatten().unwrap()); // 5
+     *
+     * const y = Some(None);
+     * console.log(y.flatten().isNone()); // true
+     * ```
      */
-    flatten<T>(this: Option<Option<T>>): Option<T>;
+    flatten<U>(this: Option<Option<U>>): Option<U>;
     /**
      * Maps an `Option<T>` to `Option<U>` by applying a function to a contained value.
      * @typeParam U - The type of the value returned by the map function.
      * @param fn - A function that takes the contained value and returns a new value.
+     * @see andThen
+     * @example
+     * ```ts
+     * const x = Some(5);
+     * console.log(x.map(v => v * 2).unwrap()); // 10
+     *
+     * const y = None;
+     * console.log(y.map(v => v * 2).isNone()); // true
+     * ```
      */
     map<U>(fn: (value: T) => U): Option<U>;
     /**
@@ -139,6 +334,15 @@ interface Option<T> {
      * @typeParam U - The type of the value returned by the map function or the default value.
      * @param defaultValue - The value to return if the Option is `None`.
      * @param fn - A function that takes the contained value and returns a new value.
+     * @see mapOrElse
+     * @example
+     * ```ts
+     * const x = Some(5);
+     * console.log(x.mapOr(0, v => v * 2)); // 10
+     *
+     * const y = None;
+     * console.log(y.mapOr(0, v => v * 2)); // 0
+     * ```
      */
     mapOr<U>(defaultValue: U, fn: (value: T) => U): U;
     /**
@@ -146,6 +350,15 @@ interface Option<T> {
      * @typeParam U - The type of the value returned by the map function or the default function.
      * @param defaultFn - A function that returns the default value.
      * @param fn - A function that takes the contained value and returns a new value.
+     * @see mapOr
+     * @example
+     * ```ts
+     * const x = Some(5);
+     * console.log(x.mapOrElse(() => 0, v => v * 2)); // 10
+     *
+     * const y = None;
+     * console.log(y.mapOrElse(() => 0, v => v * 2)); // 0
+     * ```
      */
     mapOrElse<U>(defaultFn: () => U, fn: (value: T) => U): U;
     /**
@@ -158,6 +371,17 @@ interface Option<T> {
      * @typeParam U - The type of the value in the other `Option`.
      * @param other - The other `Option` to zip with.
      * @returns An `Option` containing a tuple of the values if both are `Some`, otherwise `None`.
+     * @see zipWith
+     * @see unzip
+     * @example
+     * ```ts
+     * const x = Some(1);
+     * const y = Some('hello');
+     * console.log(x.zip(y).unwrap()); // [1, 'hello']
+     *
+     * const z = None;
+     * console.log(x.zip(z).isNone()); // true
+     * ```
      */
     zip<U>(other: Option<U>): Option<[T, U]>;
     /**
@@ -169,17 +393,32 @@ interface Option<T> {
      * @param other - The other `Option` to zip with.
      * @param fn - The function to combine the values from both `Options`.
      * @returns An `Option` containing the result of `fn` if both `Options` are `Some`, otherwise `None`.
+     * @see zip
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * const y = Some(3);
+     * console.log(x.zipWith(y, (a, b) => a * b).unwrap()); // 6
+     * ```
      */
     zipWith<U, R>(other: Option<U>, fn: (value: T, otherValue: U) => R): Option<R>;
     /**
-     * Converts from `Option<[T, U]>` to `[Option<T>, Option<U>]`.
+     * Converts from `Option<[U, R]>` to `[Option<U>, Option<R>]`.
      * If `this` is `Some([a, b])`, returns `[Some(a), Some(b)]`.
      * If `this` is `None`, returns `[None, None]`.
-     * @typeParam T - The type of the first value in the tuple.
-     * @typeParam U - The type of the second value in the tuple.
+     * @typeParam U - The type of the first value in the tuple.
+     * @typeParam R - The type of the second value in the tuple.
      * @returns A tuple of `Options`, one for each element in the original `Option` of a tuple.
+     * @see zip
+     * @example
+     * ```ts
+     * const x = Some([1, 'hello'] as [number, string]);
+     * const [a, b] = x.unzip();
+     * console.log(a.unwrap()); // 1
+     * console.log(b.unwrap()); // 'hello'
+     * ```
      */
-    unzip<T, U>(this: Option<[T, U]>): [Option<T>, Option<U>];
+    unzip<U, R>(this: Option<[U, R]>): [Option<U>, Option<R>];
     /**
      * These methods treat the `Option` as a boolean value, where `Some` acts like `true` and `None` acts like `false`.
      */
@@ -189,6 +428,17 @@ interface Option<T> {
      * @typeParam U - The type of the value in the other `Option`.
      * @param other - The `Option` to return if `this` is `Some`.
      * @returns `None` if `this` is `None`, otherwise returns `other`.
+     * @see or
+     * @see xor
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * const y = Some('hello');
+     * console.log(x.and(y).unwrap()); // 'hello'
+     *
+     * const z = None;
+     * console.log(z.and(y).isNone()); // true
+     * ```
      */
     and<U>(other: Option<U>): Option<U>;
     /**
@@ -197,10 +447,32 @@ interface Option<T> {
      * @typeParam U - The type of the value returned by the function.
      * @param fn - A function that takes the contained value and returns an `Option`.
      * @returns The result of `fn` if `this` is `Some`, otherwise `None`.
+     * @see map
+     * @see orElse
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * const result = x.andThen(v => v > 0 ? Some(v * 2) : None);
+     * console.log(result.unwrap()); // 4
+     *
+     * const y = None;
+     * console.log(y.andThen(v => Some(v * 2)).isNone()); // true
+     * ```
      */
     andThen<U>(fn: (value: T) => Option<U>): Option<U>;
     /**
      * Asynchronous version of `andThen`.
+     * @typeParam U - The type of the value returned by the async function.
+     * @param fn - An async function that takes the contained value and returns a `Promise<Option<U>>`.
+     * @returns A promise that resolves to `None` if `this` is `None`, otherwise the result of `fn`.
+     * @see andThen
+     * @see orElseAsync
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * const result = await x.andThenAsync(async v => Some(v * 2));
+     * console.log(result.unwrap()); // 4
+     * ```
      */
     andThenAsync<U>(fn: (value: T) => AsyncOption<U>): AsyncOption<U>;
     /**
@@ -208,6 +480,17 @@ interface Option<T> {
      * This can be used for providing a fallback `Option`.
      * @param other - The fallback `Option` to use if `this` is `None`.
      * @returns `this` if it is `Some`, otherwise `other`.
+     * @see and
+     * @see xor
+     * @example
+     * ```ts
+     * const x = None;
+     * const y = Some(5);
+     * console.log(x.or(y).unwrap()); // 5
+     *
+     * const z = Some(2);
+     * console.log(z.or(y).unwrap()); // 2
+     * ```
      */
     or(other: Option<T>): Option<T>;
     /**
@@ -215,10 +498,30 @@ interface Option<T> {
      * This method can be used for lazy fallbacks, as `fn` is only evaluated if `this` is `None`.
      * @param fn - A function that produces an `Option`.
      * @returns `this` if it is `Some`, otherwise the result of `fn`.
+     * @see andThen
+     * @example
+     * ```ts
+     * const x = None;
+     * const result = x.orElse(() => Some(10));
+     * console.log(result.unwrap()); // 10
+     *
+     * const y = Some(5);
+     * console.log(y.orElse(() => Some(10)).unwrap()); // 5
+     * ```
      */
     orElse(fn: () => Option<T>): Option<T>;
     /**
      * Asynchronous version of `orElse`.
+     * @param fn - An async function that produces a `Promise<Option<T>>`.
+     * @returns A promise that resolves to `this` if it is `Some`, otherwise the result of `fn`.
+     * @see orElse
+     * @see andThenAsync
+     * @example
+     * ```ts
+     * const x = None;
+     * const result = await x.orElseAsync(async () => Some(10));
+     * console.log(result.unwrap()); // 10
+     * ```
      */
     orElseAsync(fn: () => AsyncOption<T>): AsyncOption<T>;
     /**
@@ -226,6 +529,18 @@ interface Option<T> {
      * This can be thought of as an exclusive or operation on `Option` values.
      * @param other - The other `Option` to compare with.
      * @returns `Some` if exactly one of `this` and `other` is `Some`, otherwise `None`.
+     * @see and
+     * @see or
+     * @example
+     * ```ts
+     * const x = Some(2);
+     * const y = None;
+     * console.log(x.xor(y).unwrap()); // 2
+     *
+     * const a = Some(2);
+     * const b = Some(3);
+     * console.log(a.xor(b).isNone()); // true
+     * ```
      */
     xor(other: Option<T>): Option<T>;
     /**
@@ -233,6 +548,16 @@ interface Option<T> {
      * This is primarily for side effects and does not transform the `Option`.
      * @param fn - A function to call with the contained value.
      * @returns `this`, unmodified, for chaining additional methods.
+     * @example
+     * ```ts
+     * const x = Some(5);
+     * // Prints "value: 5" and returns Some(10)
+     * const doubled = x.inspect(v => console.log('value:', v)).map(v => v * 2);
+     *
+     * const y = None;
+     * // Does nothing and returns None
+     * y.inspect(v => console.log('value:', v));
+     * ```
      */
     inspect(fn: (value: T) => void): this;
     /**
@@ -240,10 +565,25 @@ interface Option<T> {
      * This method can be used for comparing `Option` instances in a value-sensitive manner.
      * @param other - The other `Option` to compare with.
      * @returns `true` if `this` and `other` are both `Some` with equal values, or both are `None`, otherwise `false`.
+     * @example
+     * ```ts
+     * const a = Some(5);
+     * const b = Some(5);
+     * const c = Some(10);
+     * console.log(a.eq(b)); // true
+     * console.log(a.eq(c)); // false
+     * console.log(None.eq(None)); // true
+     * console.log(a.eq(None)); // false
+     * ```
      */
     eq(other: Option<T>): boolean;
     /**
      * Custom `toString` implementation that uses the `Option`'s contained value.
+     * @example
+     * ```ts
+     * console.log(Some(5).toString()); // 'Some(5)'
+     * console.log(None.toString()); // 'None'
+     * ```
      */
     toString(): string;
 }
@@ -264,15 +604,31 @@ pub enum Result<T, E> {
  */
 interface Result<T, E> {
     /**
-     * [object Result].
+     * The well-known symbol `Symbol.toStringTag` used by `Object.prototype.toString()`.
+     * Returns `'Result'` so that `Object.prototype.toString.call(result)` produces `'[object Result]'`.
+     *
+     * This enables reliable type identification even across different execution contexts (e.g., iframes, different module instances).
      *
-     * @private
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(Object.prototype.toString.call(x)); // '[object Result]'
+     * ```
+     *
+     * @internal
      */
     readonly [Symbol.toStringTag]: 'Result';
     /**
-     * Identify `Ok` or `Err`.
+     * A unique symbol property used to identify the variant of this `Result`.
+     * Returns `'Ok'` if the Result represents success, or `'Err'` if it represents failure.
+     *
+     * This is used internally by the `isResult` utility function to verify that an object is a valid `Result` instance,
+     * and to distinguish between `Ok` and `Err` variants without calling methods.
      *
-     * @private
+     * Note: The symbol itself is not exported as part of the public API.
+     * Use the `isResult` utility function or the `isOk()`/`isErr()` methods for type checking.
+     *
+     * @internal
      */
     readonly [ResultKindSymbol]: 'Ok' | 'Err';
     /**
@@ -280,28 +636,75 @@ interface Result<T, E> {
      */
     /**
      * Returns `true` if the result is `Ok`.
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(x.isOk()); // true
+     *
+     * const y = Err('error');
+     * console.log(y.isOk()); // false
+     * ```
      */
     isOk(): boolean;
     /**
      * Returns `true` if the result is `Err`.
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(x.isErr()); // false
+     *
+     * const y = Err('error');
+     * console.log(y.isErr()); // true
+     * ```
      */
     isErr(): boolean;
     /**
      * Returns `true` if the result is `Ok` and the provided predicate returns `true` for the contained value.
      * @param predicate - A function that takes the `Ok` value and returns a boolean.
+     * @see isErrAnd
+     * @example
+     * ```ts
+     * const x = Ok(2);
+     * console.log(x.isOkAnd(v => v > 1)); // true
+     * console.log(x.isOkAnd(v => v > 5)); // false
+     * ```
      */
     isOkAnd(predicate: (value: T) => boolean): boolean;
     /**
      * Asynchronous version of `isOkAnd`.
+     * @param predicate - An async function that takes the `Ok` value and returns a `Promise<boolean>`.
+     * @returns A promise that resolves to `true` if the Result is `Ok` and the predicate resolves to `true`.
+     * @see isOkAnd
+     * @see isErrAndAsync
+     * @example
+     * ```ts
+     * const x = Ok(2);
+     * await x.isOkAndAsync(async v => v > 1); // true
+     * ```
      */
     isOkAndAsync(predicate: (value: T) => Promise<boolean>): Promise<boolean>;
     /**
      * Returns `true` if the result is `Err` and the provided predicate returns `true` for the contained error.
      * @param predicate - A function that takes the `Err` value and returns a boolean.
+     * @see isOkAnd
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * console.log(x.isErrAnd(e => e === 'error')); // true
+     * ```
      */
     isErrAnd(predicate: (error: E) => boolean): boolean;
     /**
      * Asynchronous version of `isErrAnd`.
+     * @param predicate - An async function that takes the `Err` value and returns a `Promise<boolean>`.
+     * @returns A promise that resolves to `true` if the Result is `Err` and the predicate resolves to `true`.
+     * @see isErrAnd
+     * @see isOkAndAsync
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * await x.isErrAndAsync(async e => e.length > 0); // true
+     * ```
      */
     isErrAndAsync(predicate: (error: E) => Promise<boolean>): Promise<boolean>;
     /**
@@ -311,25 +714,69 @@ interface Result<T, E> {
      * Returns the contained `Ok` value, with a provided error message if the result is `Err`.
      * @param msg - The error message to provide if the result is an `Err`.
      * @throws {TypeError} Throws an error with the provided message if the result is an `Err`.
+     * @see unwrap
+     * @see expectErr
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(x.expect('should have value')); // 5
+     *
+     * const y = Err('error');
+     * y.expect('should have value'); // throws TypeError: should have value: error
+     * ```
      */
     expect(msg: string): T;
     /**
      * Returns the contained `Ok` value.
      * @throws {TypeError} Throws an error if the result is an `Err`.
+     * @see expect
+     * @see unwrapOr
+     * @see unwrapErr
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(x.unwrap()); // 5
+     *
+     * const y = Err('error');
+     * y.unwrap(); // throws TypeError
+     * ```
      */
     unwrap(): T;
     /**
      * Returns the contained `Ok` value or a provided default.
      * @param defaultValue - The value to return if the result is an `Err`.
+     * @see unwrapOrElse
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(x.unwrapOr(10)); // 5
+     *
+     * const y = Err('error');
+     * console.log(y.unwrapOr(10)); // 10
+     * ```
      */
     unwrapOr(defaultValue: T): T;
     /**
      * Returns the contained `Ok` value or computes it from a closure if the result is `Err`.
      * @param fn - A function that takes the `Err` value and returns an `Ok` value.
+     * @see unwrapOr
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * console.log(x.unwrapOrElse(e => e.length)); // 5
+     * ```
      */
     unwrapOrElse(fn: (error: E) => T): T;
     /**
      * Asynchronous version of `unwrapOrElse`.
+     * @param fn - An async function that takes the `Err` value and returns a `Promise<T>`.
+     * @returns A promise that resolves to the contained `Ok` value or the result of the async function.
+     * @see unwrapOrElse
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * await x.unwrapOrElseAsync(async e => e.length); // 5
+     * ```
      */
     unwrapOrElseAsync(fn: (error: E) => Promise<T>): Promise<T>;
     /**
@@ -339,11 +786,31 @@ interface Result<T, E> {
      * Returns the contained `Err` value, with a provided error message if the result is `Ok`.
      * @param msg - The error message to provide if the result is an `Ok`.
      * @throws {TypeError} Throws an error with the provided message if the result is an `Ok`.
+     * @see unwrapErr
+     * @see expect
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * console.log(x.expectErr('should have error')); // 'error'
+     *
+     * const y = Ok(5);
+     * y.expectErr('should have error'); // throws TypeError: should have error: 5
+     * ```
      */
     expectErr(msg: string): E;
     /**
      * Returns the contained `Err` value.
      * @throws {TypeError} Throws an error if the result is an `Ok`.
+     * @see expectErr
+     * @see unwrap
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * console.log(x.unwrapErr()); // 'error'
+     *
+     * const y = Ok(5);
+     * y.unwrapErr(); // throws TypeError
+     * ```
      */
     unwrapErr(): E;
     /**
@@ -353,22 +820,51 @@ interface Result<T, E> {
      * Converts from `Result<T, E>` to `Option<T>`.
      * If the result is `Ok`, returns `Some(T)`.
      * If the result is `Err`, returns `None`.
+     * @see err
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(x.ok().unwrap()); // 5
+     *
+     * const y = Err('error');
+     * console.log(y.ok().isNone()); // true
+     * ```
      */
     ok(): Option<T>;
     /**
      * Converts from `Result<T, E>` to `Option<E>`.
      * If the result is `Err`, returns `Some(E)`.
      * If the result is `Ok`, returns `None`.
+     * @see ok
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * console.log(x.err().unwrap()); // 'error'
+     *
+     * const y = Ok(5);
+     * console.log(y.err().isNone()); // true
+     * ```
      */
     err(): Option<E>;
     /**
      * Transposes a `Result` of an `Option` into an `Option` of a `Result`.
-     * @typeParam T - The type of the success value in the `Ok` variant of the `Option`.
+     * @typeParam U - The type of the success value in the `Ok` variant of the `Option`.
      * @returns `Some` containing `Ok` if the result is `Ok` containing `Some`,
      *          `Some` containing `Err` if the result is `Err`,
      *          `None` if the result is `Ok` containing `None`.
+     * @example
+     * ```ts
+     * const x = Ok(Some(5));
+     * console.log(x.transpose().unwrap().unwrap()); // 5
+     *
+     * const y: Result<Option<number>, string> = Err('error');
+     * console.log(y.transpose().unwrap().unwrapErr()); // 'error'
+     *
+     * const z = Ok(None);
+     * console.log(z.transpose().isNone()); // true
+     * ```
      */
-    transpose<T>(this: Result<Option<T>, E>): Option<Result<T, E>>;
+    transpose<U>(this: Result<Option<U>, E>): Option<Result<U, E>>;
     /**
      * This method transforms the contained value of the `Ok` variant:
      */
@@ -377,6 +873,16 @@ interface Result<T, E> {
      * leaving an `Err` value untouched.
      * @typeParam U - The type of the value returned by the map function.
      * @param fn - A function that takes the `Ok` value and returns a new value.
+     * @see mapErr
+     * @see andThen
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(x.map(v => v * 2).unwrap()); // 10
+     *
+     * const y = Err('error');
+     * console.log(y.map(v => v * 2).unwrapErr()); // 'error'
+     * ```
      */
     map<U>(fn: (value: T) => U): Result<U, E>;
     /**
@@ -387,6 +893,12 @@ interface Result<T, E> {
      * leaving an `Ok` value untouched.
      * @typeParam F - The type of the error returned by the map function.
      * @param fn - A function that takes the `Err` value and returns a new error value.
+     * @see map
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * console.log(x.mapErr(e => e.toUpperCase()).unwrapErr()); // 'ERROR'
+     * ```
      */
     mapErr<F>(fn: (error: E) => F): Result<T, F>;
     /**
@@ -397,6 +909,15 @@ interface Result<T, E> {
      * @typeParam U - The type of the value returned by the map function or the default value.
      * @param defaultValue - The value to return if the result is `Err`.
      * @param fn - A function that takes the `Ok` value and returns a new value.
+     * @see mapOrElse
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(x.mapOr(0, v => v * 2)); // 10
+     *
+     * const y = Err('error');
+     * console.log(y.mapOr(0, v => v * 2)); // 0
+     * ```
      */
     mapOr<U>(defaultValue: U, fn: (value: T) => U): U;
     /**
@@ -404,14 +925,32 @@ interface Result<T, E> {
      * @typeParam U - The type of the value returned by the map function or the default function.
      * @param defaultFn - A function that returns the default value.
      * @param fn - A function that takes the `Ok` value and returns a new value.
+     * @see mapOr
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * console.log(x.mapOrElse(e => 0, v => v * 2)); // 10
+     *
+     * const y = Err('error');
+     * console.log(y.mapOrElse(e => e.length, v => v * 2)); // 5
+     * ```
      */
     mapOrElse<U>(defaultFn: (error: E) => U, fn: (value: T) => U): U;
     /**
-     * Converts from `Result<Result<T, E>, E>` to `Result<T, E>`.
-     * If the result is `Ok(Ok(T))`, returns `Ok(T)`.
+     * Converts from `Result<Result<U, E>, E>` to `Result<U, E>`.
+     * If the result is `Ok(Ok(U))`, returns `Ok(U)`.
      * If the result is `Ok(Err(E))` or `Err(E)`, returns `Err(E)`.
+     * @typeParam U - The type of the success value in the inner `Result`.
+     * @example
+     * ```ts
+     * const x = Ok(Ok(5));
+     * console.log(x.flatten().unwrap()); // 5
+     *
+     * const y = Ok(Err('error'));
+     * console.log(y.flatten().unwrapErr()); // 'error'
+     * ```
      */
-    flatten<T>(this: Result<Result<T, E>, E>): Result<T, E>;
+    flatten<U>(this: Result<Result<U, E>, E>): Result<U, E>;
     /**
      * These methods treat the `Result` as a boolean value, where `Ok` acts like `true` and `Err` acts like `false`.
      */
@@ -420,6 +959,17 @@ interface Result<T, E> {
      * @typeParam U - The type of the value in the other `Result`.
      * @param other - The `Result` to return if `this` is `Ok`.
      * @returns The passed `Result` if `this` is `Ok`, otherwise returns `this` (which is `Err`).
+     * @see or
+     * @example
+     * ```ts
+     * const x = Ok(2);
+     * const y = Err('late error');
+     * console.log(x.and(y).unwrapErr()); // 'late error'
+     *
+     * const a = Err('early error');
+     * const b = Ok(5);
+     * console.log(a.and(b).unwrapErr()); // 'early error'
+     * ```
      */
     and<U>(other: Result<U, E>): Result<U, E>;
     /**
@@ -427,6 +977,17 @@ interface Result<T, E> {
      * @typeParam F - The type of the error in the other `Result`.
      * @param other - The `Result` to return if `this` is `Err`.
      * @returns `this` if it is `Ok`, otherwise returns `other`.
+     * @see and
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * const y = Ok(5);
+     * console.log(x.or(y).unwrap()); // 5
+     *
+     * const a = Ok(2);
+     * const b = Ok(100);
+     * console.log(a.or(b).unwrap()); // 2
+     * ```
      */
     or<F>(other: Result<T, F>): Result<T, F>;
     /**
@@ -434,10 +995,32 @@ interface Result<T, E> {
      * @typeParam U - The type of the value returned by the function.
      * @param fn - A function that takes the `Ok` value and returns a `Result`.
      * @returns The result of `fn` if `this` is `Ok`, otherwise `this` as `Err`.
+     * @see map
+     * @see orElse
+     * @example
+     * ```ts
+     * const x = Ok(2);
+     * const result = x.andThen(v => v > 0 ? Ok(v * 2) : Err('negative'));
+     * console.log(result.unwrap()); // 4
+     *
+     * const y = Err('error');
+     * console.log(y.andThen(v => Ok(v * 2)).unwrapErr()); // 'error'
+     * ```
      */
     andThen<U>(fn: (value: T) => Result<U, E>): Result<U, E>;
     /**
      * Asynchronous version of `andThen`.
+     * @typeParam U - The type of the value returned by the async function.
+     * @param fn - An async function that takes the `Ok` value and returns a `Promise<Result<U, E>>`.
+     * @returns A promise that resolves to `this` as `Err` if `this` is `Err`, otherwise the result of `fn`.
+     * @see andThen
+     * @see orElseAsync
+     * @example
+     * ```ts
+     * const x = Ok(2);
+     * const result = await x.andThenAsync(async v => Ok(v * 2));
+     * console.log(result.unwrap()); // 4
+     * ```
      */
     andThenAsync<U>(fn: (value: T) => AsyncResult<U, E>): AsyncResult<U, E>;
     /**
@@ -445,10 +1028,31 @@ interface Result<T, E> {
      * @typeParam F - The type of the error returned by the function.
      * @param fn - A function that takes the `Err` value and returns a `Result`.
      * @returns The result of `fn` if `this` is `Err`, otherwise `this` as `Ok`.
+     * @see andThen
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * const result = x.orElse(e => Ok(e.length));
+     * console.log(result.unwrap()); // 5
+     *
+     * const y = Ok(2);
+     * console.log(y.orElse(e => Ok(0)).unwrap()); // 2
+     * ```
      */
     orElse<F>(fn: (error: E) => Result<T, F>): Result<T, F>;
     /**
      * Asynchronous version of `orElse`.
+     * @typeParam F - The type of the error returned by the async function.
+     * @param fn - An async function that takes the `Err` value and returns a `Promise<Result<T, F>>`.
+     * @returns A promise that resolves to `this` as `Ok` if `this` is `Ok`, otherwise the result of `fn`.
+     * @see orElse
+     * @see andThenAsync
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * const result = await x.orElseAsync(async e => Ok(e.length));
+     * console.log(result.unwrap()); // 5
+     * ```
      */
     orElseAsync<F>(fn: (error: E) => AsyncResult<T, F>): AsyncResult<T, F>;
     /**
@@ -456,6 +1060,12 @@ interface Result<T, E> {
      * Does not modify the `Result`.
      * @param fn - A function to call with the `Ok` value.
      * @returns `this`, unmodified.
+     * @see inspectErr
+     * @example
+     * ```ts
+     * const x = Ok(5);
+     * x.inspect(v => console.log(v)); // prints 5
+     * ```
      */
     inspect(fn: (value: T) => void): this;
     /**
@@ -463,35 +1073,73 @@ interface Result<T, E> {
      * Does not modify the `Result`.
      * @param fn - A function to call with the `Err` value.
      * @returns `this`, unmodified.
+     * @see inspect
+     * @example
+     * ```ts
+     * const x = Err('error');
+     * x.inspectErr(e => console.log(e)); // prints 'error'
+     * ```
      */
     inspectErr(fn: (error: E) => void): this;
     /**
      * Tests whether `this` and `other` are both `Ok` containing equal values, or both are `Err` containing equal errors.
      * @param other - The other `Result` to compare with.
      * @returns `true` if `this` and `other` are both `Ok` with equal values, or both are `Err` with equal errors, otherwise `false`.
+     * @example
+     * ```ts
+     * const a = Ok(5);
+     * const b = Ok(5);
+     * const c = Ok(10);
+     * console.log(a.eq(b)); // true
+     * console.log(a.eq(c)); // false
+     *
+     * const d = Err('error');
+     * const e = Err('error');
+     * console.log(d.eq(e)); // true
+     * console.log(a.eq(d)); // false
+     * ```
      */
     eq(other: Result<T, E>): boolean;
     /**
-     * Transforms the current Result into a new Result where the type of the error result is replaced with a new type `F`.
-     * The type of the success result remains unchanged.
-     * Just same as `result as unknown as Result<T, F>`.
+     * Transforms the current Result into a new Result where the type of the error is replaced with a new type `F`.
+     * The type of the success value remains unchanged.
+     * This is a type-level only operation, equivalent to `result as unknown as Result<T, F>`.
      *
-     * @typeParam F - The new type for the error result.
-     * @returns `this` but the error result type is `F`.
+     * @typeParam F - The new type for the error.
+     * @returns `this` with the error type cast to `F`.
+     * @see asErr
+     * @example
+     * ```ts
+     * const x: Result<number, string> = Ok(5);
+     * const y: Result<number, Error> = x.asOk<Error>();
+     * console.log(y.unwrap()); // 5
+     * ```
      */
     asOk<F>(): Result<T, F>;
     /**
-     * Transforms the current Result into a new Result where the type of the success result is replaced with a new type `U`.
-     * The type of the error result remains unchanged.
-     * Useful where you need to return an Error chained to another type.
-     * Just same as `result as unknown as Result<U, E>`.
+     * Transforms the current Result into a new Result where the type of the success value is replaced with a new type `U`.
+     * The type of the error remains unchanged.
+     * This is a type-level only operation, equivalent to `result as unknown as Result<U, E>`.
+     * Useful when you need to propagate an error to a different success type context.
      *
-     * @typeParam U - The new type for the success result.
-     * @returns `this` but the success result type is `U`.
+     * @typeParam U - The new type for the success value.
+     * @returns `this` with the success type cast to `U`.
+     * @see asOk
+     * @example
+     * ```ts
+     * const x: Result<number, string> = Err('error');
+     * const y: Result<string, string> = x.asErr<string>();
+     * console.log(y.unwrapErr()); // 'error'
+     * ```
      */
     asErr<U>(): Result<U, E>;
     /**
      * Custom `toString` implementation that uses the `Result`'s contained value.
+     * @example
+     * ```ts
+     * console.log(Ok(5).toString()); // 'Ok(5)'
+     * console.log(Err('error').toString()); // 'Err(error)'
+     * ```
      */
     toString(): string;
 }
@@ -512,30 +1160,66 @@ type AsyncOption<T> = Promise<Option<T>>;
 type AsyncResult<T, E> = Promise<Result<T, E>>;
 
 /**
- * Exports some Result constants.
+ * @fileoverview
+ * Pre-defined Result constants for common return values.
+ *
+ * These immutable constants can be reused throughout the application to avoid
+ * creating new Result instances for common values like `true`, `false`, `0`, and `void`.
  */
+
 /**
  * Result constant for `true`.
  * Can be used anywhere due to immutability.
+ * @example
+ * ```ts
+ * function validate(): Result<boolean, Error> {
+ *     return RESULT_TRUE;
+ * }
+ * ```
  */
 declare const RESULT_TRUE: Result<boolean, any>;
 /**
  * Result constant for `false`.
  * Can be used anywhere due to immutability.
+ * @example
+ * ```ts
+ * function validate(): Result<boolean, Error> {
+ *     return RESULT_FALSE;
+ * }
+ * ```
  */
 declare const RESULT_FALSE: Result<boolean, any>;
 /**
  * Result constant for `0`.
  * Can be used anywhere due to immutability.
+ * @example
+ * ```ts
+ * function count(): Result<number, Error> {
+ *     return RESULT_ZERO;
+ * }
+ * ```
  */
 declare const RESULT_ZERO: Result<number, any>;
 /**
  * Result constant for `void` or `()`.
+ * Can be used anywhere due to immutability.
+ * @example
+ * ```ts
+ * function doSomething(): Result<void, Error> {
+ *     return RESULT_VOID;
+ * }
+ * ```
  */
 declare const RESULT_VOID: Result<void, any>;
 
 /**
- * Exports some commonly used types.
+ * @fileoverview
+ * Type aliases for commonly used `Result` type combinations.
+ *
+ * These types provide convenient shortcuts for common patterns like:
+ * - Operations that return nothing on success (`VoidResult`)
+ * - I/O operations that may fail with an Error (`IOResult`)
+ * - Async versions of the above
  */
 
 /**
@@ -573,10 +1257,20 @@ type VoidIOResult = IOResult<void>;
  */
 type AsyncVoidIOResult = AsyncIOResult<void>;
 
+/**
+ * @fileoverview
+ * Extension functions for bridging Promise-based APIs with the Result type.
+ *
+ * This module provides utilities for integrating async/await patterns with Result-based error handling.
+ */
+
 /**
  * Converts a Promise to a Result type, capturing the resolved value in an `Ok`, or the error in an `Err`.
  * This allows for promise-based asynchronous operations to be handled in a way that is more in line with the Result pattern.
  *
+ * Note: JavaScript promises can reject with any value, not just `Error` objects.
+ * The error is cast to type `E`, so ensure your error handling accounts for this.
+ *
  * @typeParam T - The type of the value that the promise resolves to.
  * @typeParam E - The type of the error that the promise may reject with, defaults to `Error`.
  * @param p - The promise to convert into a `Result` type.
@@ -593,9 +1287,27 @@ type AsyncVoidIOResult = AsyncIOResult<void>;
  *     });
  * }
  * ```
+ *
+ * @example
+ * ```ts
+ * // With custom error type
+ * const result = await promiseToAsyncResult<User, ApiError>(fetchUser(id));
+ * ```
  */
 declare function promiseToAsyncResult<T, E = Error>(p: Promise<T>): Promise<Result<T, E>>;
 
+/**
+ * @fileoverview
+ * Constructors and factory functions for creating `Option` and `Result` types.
+ *
+ * This module exports:
+ * - `Some<T>(value)` - Creates an Option containing a value
+ * - `None` - Constant representing absence of value
+ * - `Ok<T, E>(value)` - Creates a successful Result
+ * - `Err<T, E>(error)` - Creates a failed Result
+ * - `None` interface - Type overrides for better type inference
+ */
+
 /**
  * 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.
@@ -626,6 +1338,8 @@ interface None extends Option<never> {
     isNone(): true;
     isSomeAnd(predicate: (value: never) => boolean): false;
     isSomeAndAsync(predicate: (value: never) => Promise<boolean>): Promise<false>;
+    isNoneOr(predicate: (value: never) => boolean): true;
+    isNoneOrAsync(predicate: (value: never) => Promise<boolean>): Promise<true>;
     expect(msg: string): never;
     unwrap(): never;
     unwrapOr<T>(defaultValue: T): T;
@@ -633,18 +1347,18 @@ interface None extends Option<never> {
     unwrapOrElseAsync<T>(fn: () => Promise<T>): Promise<T>;
     okOr<E>(error: E): Result<never, E>;
     okOrElse<E>(err: () => E): Result<never, E>;
-    transpose(): Result<None, never>;
-    filter(predicate: (value: never) => boolean): None;
-    flatten(): None;
-    map<U>(fn: (value: never) => U): None;
+    transpose(): Result<this, never>;
+    filter(predicate: (value: never) => boolean): this;
+    flatten(): this;
+    map<U>(fn: (value: never) => U): this;
     mapOr<U>(defaultValue: U, fn: (value: never) => U): U;
     mapOrElse<U>(defaultFn: () => U, fn: (value: never) => U): U;
-    zip<U>(other: Option<U>): None;
-    zipWith<U, R>(other: Option<U>, fn: (value: never, otherValue: U) => R): None;
-    unzip(): [None, None];
-    and<U>(other: Option<U>): None;
-    andThen<U>(fn: (value: never) => Option<U>): None;
-    andThenAsync<U>(fn: (value: never) => AsyncOption<U>): Promise<None>;
+    zip<U>(other: Option<U>): this;
+    zipWith<U, R>(other: Option<U>, fn: (value: never, otherValue: U) => R): this;
+    unzip(): [this, this];
+    and<U>(other: Option<U>): this;
+    andThen<U>(fn: (value: never) => Option<U>): this;
+    andThenAsync<U>(fn: (value: never) => AsyncOption<U>): Promise<this>;
     or<T>(other: Option<T>): Option<T>;
     orElse<T>(fn: () => Option<T>): Option<T>;
     orElseAsync<T>(fn: () => AsyncOption<T>): AsyncOption<T>;
@@ -655,6 +1369,24 @@ interface None extends Option<never> {
 /**
  * A constant representing the `None` case of an `Option`, indicating the absence of a value.
  * This constant is frozen to ensure it is immutable and cannot be altered, preserving the integrity of `None` throughout the application.
+ *
+ * @example
+ * ```ts
+ * // Use None to represent absence of a value
+ * function findUser(id: number): Option<User> {
+ *     const user = users.find(u => u.id === id);
+ *     return user ? Some(user) : None;
+ * }
+ *
+ * // None is a singleton, so you can compare by reference
+ * const result = findUser(999);
+ * if (result === None) {
+ *     console.log('User not found');
+ * }
+ *
+ * // Use with Option methods
+ * const name = None.unwrapOr('Anonymous'); // 'Anonymous'
+ * ```
  */
 declare const None: None;
 /**
@@ -674,11 +1406,35 @@ declare const None: None;
  * }
  * ```
  */
-declare function Ok<T, E>(value: T): Result<T, E>;
+declare function Ok<T, E = never>(value: T): Result<T, E>;
 /**
- * Because javascript does not have a `()` type, use `void` instead.
+ * Creates a `Result<void, E>` representing a successful outcome with no value.
+ * This overload is used when the operation succeeds but doesn't produce a meaningful value.
+ *
+ * In Rust, this would be `Ok(())` using the unit type `()`.
+ * Since JavaScript doesn't have a unit type, we use `void` instead.
+ *
+ * @typeParam E - The type of the error that the result could potentially contain.
+ * @returns A `Result<void, E>` representing a successful operation with no value.
+ *
+ * @example
+ * ```ts
+ * function saveToFile(path: string): Result<void, Error> {
+ *     try {
+ *         fs.writeFileSync(path, data);
+ *         return Ok(); // Success with no return value
+ *     } catch (e) {
+ *         return Err(e as Error);
+ *     }
+ * }
+ *
+ * const result = saveToFile('/tmp/data.txt');
+ * if (result.isOk()) {
+ *     console.log('File saved successfully');
+ * }
+ * ```
  */
-declare function Ok<E>(): Result<void, E>;
+declare function Ok<E = never>(): Result<void, E>;
 /**
  * Creates a `Result<T, E>` representing a failed outcome containing an error.
  * This function is used to construct a `Result` that signifies the operation failed by containing the error `E`.
@@ -696,7 +1452,14 @@ declare function Ok<E>(): Result<void, E>;
  * }
  * ```
  */
-declare function Err<T, E>(error: E): Result<T, E>;
+declare function Err<T = never, E = unknown>(error: E): Result<T, E>;
+
+/**
+ * @fileoverview
+ * Type guard utilities for checking if values are `Option` or `Result` types.
+ *
+ * These functions provide runtime type checking capabilities for the Option and Result types.
+ */
 
 /**
  * Checks if a value is an `Option`.
@@ -704,6 +1467,13 @@ declare function Err<T, E>(error: E): Result<T, E>;
  * @typeParam T - The expected type of the value contained within the `Option`.
  * @param o - The value to be checked as an `Option`.
  * @returns `true` if the value is an `Option`, otherwise `false`.
+ * @example
+ * ```ts
+ * const x = Some(5);
+ * console.log(isOption(x)); // true
+ * console.log(isOption(null)); // false
+ * console.log(isOption({ value: 5 })); // false
+ * ```
  */
 declare function isOption<T>(o: unknown): o is Option<T>;
 /**
@@ -713,8 +1483,1188 @@ declare function isOption<T>(o: unknown): o is Option<T>;
  * @typeParam E - The expected type of the error value contained within the `Result`.
  * @param r - The value to be checked as a `Result`.
  * @returns `true` if the value is a `Result`, otherwise `false`.
+ * @example
+ * ```ts
+ * const x = Ok(5);
+ * console.log(isResult(x)); // true
+ * console.log(isResult(null)); // false
+ * console.log(isResult({ value: 5 })); // false
+ * ```
  */
 declare function isResult<T, E>(r: unknown): r is Result<T, E>;
 
-export { type AsyncIOResult, type AsyncOption, type AsyncResult, type AsyncVoidIOResult, type AsyncVoidResult, Err, type IOResult, None, Ok, type Option, RESULT_FALSE, RESULT_TRUE, RESULT_VOID, RESULT_ZERO, type Result, Some, type VoidIOResult, type VoidResult, isOption, isResult, promiseToAsyncResult };
-//# sourceMappingURL=types.d.ts.map
+/**
+ * @fileoverview
+ * Internal symbols used to identify `ControlFlow` type variants.
+ *
+ * These symbols are used as property keys to distinguish between `Break` and `Continue` variants.
+ * They provide a reliable way to identify the variant of a `ControlFlow` instance without
+ * relying on method calls or duck typing.
+ *
+ * Note: These symbols are internal implementation details and are not exported as part of the public API.
+ * Use the `isControlFlow` utility function for type checking instead.
+ */
+/**
+ * A unique symbol used as a property key to identify the variant of a `ControlFlow` instance.
+ *
+ * When accessed on a `ControlFlow`, returns `'Break'` if the ControlFlow signals early exit,
+ * or `'Continue'` if it signals to proceed as normal.
+ *
+ * This symbol is used internally by the `isControlFlow` utility function to verify
+ * that an object is a valid `ControlFlow` instance.
+ *
+ * @internal
+ */
+declare const ControlFlowKindSymbol: unique symbol;
+
+/**
+ * @fileoverview
+ * Rust-inspired [ControlFlow](https://doc.rust-lang.org/std/ops/enum.ControlFlow.html) for control flow handling.
+ *
+ * `ControlFlow` is used to tell an operation whether it should exit early or go on as usual.
+ * This is useful for:
+ * - Short-circuiting iterators
+ * - Signaling early termination in fold-like operations
+ * - Implementing custom control flow patterns
+ */
+
+/**
+ * Used to tell an operation whether it should exit early or go on as usual.
+ *
+ * This is the return type of `try_fold` and similar iterator methods that support
+ * short-circuiting. It can also be used in custom control flow scenarios.
+ *
+ * @typeParam B - The type of the value returned on `Break` (early exit).
+ * @typeParam C - The type of the value returned on `Continue` (default: `void`).
+ *
+ * @example
+ * ```ts
+ * // Using ControlFlow to short-circuit a search
+ * function findFirstNegative(numbers: number[]): Option<number> {
+ *     let result: Option<number> = None;
+ *
+ *     for (const n of numbers) {
+ *         const flow = n < 0 ? Break(n) : Continue();
+ *         if (flow.isBreak()) {
+ *             result = Some(flow.breakValue().unwrap());
+ *             break;
+ *         }
+ *     }
+ *
+ *     return result;
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Using ControlFlow in a custom fold operation
+ * function tryFold<T, Acc>(
+ *     arr: T[],
+ *     init: Acc,
+ *     f: (acc: Acc, item: T) => ControlFlow<Acc, Acc>
+ * ): ControlFlow<Acc, Acc> {
+ *     let acc = init;
+ *     for (const item of arr) {
+ *         const flow = f(acc, item);
+ *         if (flow.isBreak()) {
+ *             return flow;
+ *         }
+ *         acc = flow.continueValue().unwrap();
+ *     }
+ *     return Continue(acc);
+ * }
+ * ```
+ */
+interface ControlFlow<B, C = void> {
+    /**
+     * The well-known symbol `Symbol.toStringTag` used by `Object.prototype.toString()`.
+     * Returns `'ControlFlow'` so that `Object.prototype.toString.call(flow)` produces `'[object ControlFlow]'`.
+     *
+     * This enables reliable type identification even across different execution contexts (e.g., iframes, different module instances).
+     *
+     * @example
+     * ```ts
+     * const x = Break(5);
+     * console.log(Object.prototype.toString.call(x)); // '[object ControlFlow]'
+     * ```
+     *
+     * @internal
+     */
+    readonly [Symbol.toStringTag]: 'ControlFlow';
+    /**
+     * A unique symbol property used to identify the variant of this `ControlFlow`.
+     * Returns `'Break'` if the ControlFlow signals early exit, or `'Continue'` if it signals to proceed as normal.
+     *
+     * This is used internally by the `isControlFlow` utility function to verify that an object is a valid `ControlFlow` instance,
+     * and to distinguish between `Break` and `Continue` variants without calling methods.
+     *
+     * Note: The symbol itself is not exported as part of the public API.
+     * Use the `isControlFlow` utility function or the `isBreak()`/`isContinue()` methods for type checking.
+     *
+     * @internal
+     */
+    readonly [ControlFlowKindSymbol]: 'Break' | 'Continue';
+    /**
+     * Returns `true` if this is a `Break` variant.
+     *
+     * @example
+     * ```ts
+     * console.log(Break(3).isBreak()); // true
+     * console.log(Continue().isBreak()); // false
+     * ```
+     */
+    isBreak(): boolean;
+    /**
+     * Returns `true` if this is a `Continue` variant.
+     *
+     * @example
+     * ```ts
+     * console.log(Continue().isContinue()); // true
+     * console.log(Break(3).isContinue()); // false
+     * ```
+     */
+    isContinue(): boolean;
+    /**
+     * Converts the `ControlFlow` into an `Option` which is `Some` if the
+     * `ControlFlow` was `Break` and `None` otherwise.
+     *
+     * @returns `Some(value)` if `Break`, `None` if `Continue`.
+     *
+     * @example
+     * ```ts
+     * console.log(Break(3).breakValue()); // Some(3)
+     * console.log(Continue().breakValue()); // None
+     * ```
+     */
+    breakValue(): Option<B>;
+    /**
+     * Converts the `ControlFlow` into an `Option` which is `Some` if the
+     * `ControlFlow` was `Continue` and `None` otherwise.
+     *
+     * @returns `Some(value)` if `Continue`, `None` if `Break`.
+     *
+     * @example
+     * ```ts
+     * console.log(Continue(5).continueValue()); // Some(5)
+     * console.log(Break(3).continueValue()); // None
+     * ```
+     */
+    continueValue(): Option<C>;
+    /**
+     * Maps `ControlFlow<B, C>` to `ControlFlow<T, C>` by applying a function
+     * to the break value in case it exists.
+     *
+     * @typeParam T - The type of the new break value.
+     * @param fn - A function to apply to the break value.
+     * @returns A new `ControlFlow` with the mapped break value.
+     *
+     * @example
+     * ```ts
+     * const flow = Break(3);
+     * console.log(flow.mapBreak(v => v * 2).breakValue()); // Some(6)
+     * ```
+     */
+    mapBreak<T>(fn: (value: B) => T): ControlFlow<T, C>;
+    /**
+     * Maps `ControlFlow<B, C>` to `ControlFlow<B, T>` by applying a function
+     * to the continue value in case it exists.
+     *
+     * @typeParam T - The type of the new continue value.
+     * @param fn - A function to apply to the continue value.
+     * @returns A new `ControlFlow` with the mapped continue value.
+     *
+     * @example
+     * ```ts
+     * const flow = Continue(5);
+     * console.log(flow.mapContinue(v => v * 2).continueValue()); // Some(10)
+     * ```
+     */
+    mapContinue<T>(fn: (value: C) => T): ControlFlow<B, T>;
+    /**
+     * Converts the `ControlFlow` into a `Result` which is `Ok` if the
+     * `ControlFlow` was `Break` and `Err` otherwise.
+     *
+     * @returns `Ok(breakValue)` if `Break`, `Err(continueValue)` if `Continue`.
+     *
+     * @example
+     * ```ts
+     * console.log(Break(3).breakOk()); // Ok(3)
+     * console.log(Continue('still going').breakOk()); // Err('still going')
+     * ```
+     */
+    breakOk(): Result<B, C>;
+    /**
+     * Converts the `ControlFlow` into a `Result` which is `Ok` if the
+     * `ControlFlow` was `Continue` and `Err` otherwise.
+     *
+     * @returns `Ok(continueValue)` if `Continue`, `Err(breakValue)` if `Break`.
+     *
+     * @example
+     * ```ts
+     * console.log(Continue(5).continueOk()); // Ok(5)
+     * console.log(Break('stopped').continueOk()); // Err('stopped')
+     * ```
+     */
+    continueOk(): Result<C, B>;
+    /**
+     * Custom `toString` implementation that uses the `ControlFlow`'s contained value.
+     * @example
+     * ```ts
+     * console.log(Break(5).toString()); // 'Break(5)'
+     * console.log(Continue('ok').toString()); // 'Continue(ok)'
+     * ```
+     */
+    toString(): string;
+}
+/**
+ * Creates a `Break` variant of `ControlFlow`.
+ *
+ * Use this to signal that an operation should exit early with the given value.
+ *
+ * @typeParam B - The type of the break value.
+ * @typeParam C - The type of the continue value (defaults to `void` when a value is provided).
+ * @param value - The value to return on break.
+ * @returns A `ControlFlow` in the `Break` state.
+ *
+ * @example
+ * ```ts
+ * const flow = Break('found it');
+ * console.log(flow.isBreak()); // true
+ * console.log(flow.breakValue().unwrap()); // 'found it'
+ *
+ * const voidFlow = Break();
+ * console.log(voidFlow.isBreak()); // true
+ * ```
+ */
+declare function Break<B, C = never>(value: B): ControlFlow<B, C>;
+/**
+ * Creates a `Break` variant of `ControlFlow` with no value.
+ * This overload is used when the operation exits early but doesn't produce a meaningful value.
+ *
+ * @typeParam C - The type of the continue value (allows type specification when chaining with Continue).
+ * @returns A `ControlFlow<void, C>` in the `Break` state.
+ *
+ * @example
+ * ```ts
+ * const voidFlow = Break();
+ * console.log(voidFlow.isBreak()); // true
+ * console.log(voidFlow.breakValue()); // Some(undefined)
+ *
+ * // With explicit type parameter
+ * const typedFlow = Break<number>();  // ControlFlow<void, number>
+ * ```
+ */
+declare function Break<C = never>(): ControlFlow<void, C>;
+/**
+ * Creates a `Continue` variant of `ControlFlow`.
+ *
+ * Use this to signal that an operation should continue as normal.
+ *
+ * @typeParam B - The type of the break value (defaults to `void` when a value is provided).
+ * @typeParam C - The type of the continue value.
+ * @param value - The value to carry forward (optional, defaults to `undefined`).
+ * @returns A `ControlFlow` in the `Continue` state.
+ *
+ * @example
+ * ```ts
+ * const flow = Continue();
+ * console.log(flow.isContinue()); // true
+ *
+ * const flowWithValue = Continue(42);
+ * console.log(flowWithValue.continueValue().unwrap()); // 42
+ * ```
+ */
+declare function Continue<B = never, C = void>(value: C): ControlFlow<B, C>;
+/**
+ * Creates a `Continue` variant of `ControlFlow` with no value.
+ * This overload is used when the operation continues but doesn't carry a meaningful value.
+ *
+ * @typeParam B - The type of the break value (allows type specification when chaining with Break).
+ * @returns A `ControlFlow<B, void>` in the `Continue` state.
+ *
+ * @example
+ * ```ts
+ * const voidFlow = Continue();
+ * console.log(voidFlow.isContinue()); // true
+ * console.log(voidFlow.continueValue()); // Some(undefined)
+ *
+ * // With explicit type parameter
+ * const typedFlow = Continue<string>();  // ControlFlow<string, void>
+ * ```
+ */
+declare function Continue<B = never>(): ControlFlow<B, void>;
+
+/**
+ * @fileoverview
+ * Type guard utilities for checking if values are `ControlFlow` types.
+ *
+ * These functions provide runtime type checking capabilities for the ControlFlow type.
+ */
+
+/**
+ * Checks if a value is a `ControlFlow`.
+ *
+ * @typeParam B - The expected type of the break value contained within the `ControlFlow`.
+ * @typeParam C - The expected type of the continue value contained within the `ControlFlow`.
+ * @param cf - The value to be checked as a `ControlFlow`.
+ * @returns `true` if the value is a `ControlFlow`, otherwise `false`.
+ * @example
+ * ```ts
+ * const x = Break(5);
+ * console.log(isControlFlow(x)); // true
+ * console.log(isControlFlow(null)); // false
+ * console.log(isControlFlow({ isBreak: () => true })); // false
+ * ```
+ */
+declare function isControlFlow<B, C>(cf: unknown): cf is ControlFlow<B, C>;
+
+/**
+ * @fileoverview
+ * Rust-inspired [LazyLock](https://doc.rust-lang.org/std/sync/struct.LazyLock.html) for lazy initialization.
+ *
+ * `Lazy<T>` is a value which is initialized on the first access. Unlike `Once<T>`,
+ * the initialization function is provided at construction time.
+ */
+
+/**
+ * A value which is initialized on the first access.
+ *
+ * This is a lazily evaluated value. The initialization function is provided
+ * at construction time and executed on first access. Subsequent accesses
+ * return the cached value.
+ *
+ * Unlike `Once<T>`, which allows setting values manually or with different
+ * initializers, `Lazy<T>` binds the initializer at creation time.
+ *
+ * @typeParam T - The type of the value stored.
+ *
+ * @example
+ * ```ts
+ * const expensive = Lazy(() => {
+ *     console.log('Computing...');
+ *     return heavyComputation();
+ * });
+ *
+ * // Nothing computed yet
+ * console.log(expensive.isInitialized()); // false
+ *
+ * // First access triggers computation
+ * const value = expensive.force(); // logs "Computing..."
+ *
+ * // Subsequent access returns cached value
+ * const same = expensive.force(); // no log, returns cached value
+ * ```
+ */
+interface Lazy<T> {
+    /**
+     * The well-known symbol `Symbol.toStringTag` used by `Object.prototype.toString()`.
+     * Returns `'Lazy'` so that `Object.prototype.toString.call(lazy)` produces `'[object Lazy]'`.
+     *
+     * @internal
+     */
+    readonly [Symbol.toStringTag]: 'Lazy';
+    /**
+     * Forces the evaluation of this lazy value and returns the result.
+     *
+     * If the value has already been initialized, returns the cached value.
+     * Otherwise, executes the initialization function, caches the result,
+     * and returns it.
+     *
+     * @returns The initialized value.
+     *
+     * @example
+     * ```ts
+     * const lazy = Lazy(() => 42);
+     * console.log(lazy.force()); // 42
+     * console.log(lazy.force()); // 42 (cached)
+     * ```
+     */
+    force(): T;
+    /**
+     * Gets the value if it has been initialized.
+     *
+     * Unlike `force()`, this does not trigger initialization.
+     *
+     * @returns `Some(value)` if initialized, `None` otherwise.
+     *
+     * @example
+     * ```ts
+     * const lazy = Lazy(() => 42);
+     * console.log(lazy.get()); // None
+     *
+     * lazy.force();
+     * console.log(lazy.get()); // Some(42)
+     * ```
+     */
+    get(): Option<T>;
+    /**
+     * Returns `true` if the value has been initialized.
+     *
+     * @example
+     * ```ts
+     * const lazy = Lazy(() => 42);
+     * console.log(lazy.isInitialized()); // false
+     *
+     * lazy.force();
+     * console.log(lazy.isInitialized()); // true
+     * ```
+     */
+    isInitialized(): boolean;
+    /**
+     * Custom `toString` implementation.
+     * @example
+     * ```ts
+     * const lazy = Lazy(() => 42);
+     * console.log(lazy.toString()); // 'Lazy(<uninitialized>)'
+     *
+     * lazy.force();
+     * console.log(lazy.toString()); // 'Lazy(42)'
+     * ```
+     */
+    toString(): string;
+}
+/**
+ * Creates a new `Lazy<T>` with the given synchronous initialization function.
+ *
+ * The function is called at most once, on first access via `force()`.
+ *
+ * @typeParam T - The type of value to store.
+ * @param fn - The initialization function that produces the value.
+ * @returns A new `Lazy<T>` instance.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const lazy = Lazy(() => {
+ *     console.log('Initializing');
+ *     return 42;
+ * });
+ *
+ * console.log(lazy.isInitialized()); // false
+ * console.log(lazy.force()); // logs "Initializing", returns 42
+ * console.log(lazy.isInitialized()); // true
+ * console.log(lazy.force()); // returns 42 (no log)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Lazy singleton pattern
+ * const logger = Lazy(() => new Logger('app'));
+ *
+ * function getLogger(): Logger {
+ *     return logger.force();
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Expensive computation
+ * const fibonacci = Lazy(() => {
+ *     function fib(n: number): number {
+ *         if (n <= 1) return n;
+ *         return fib(n - 1) + fib(n - 2);
+ *     }
+ *     return fib(40); // Only computed once
+ * });
+ * ```
+ */
+declare function Lazy<T>(fn: () => T): Lazy<T>;
+/**
+ * A value which is initialized asynchronously on the first access.
+ *
+ * Similar to `Lazy<T>`, but the initialization function is async.
+ * If multiple calls to `force()` occur concurrently before initialization
+ * completes, only one initialization will run.
+ *
+ * @typeParam T - The type of the value stored.
+ *
+ * @example
+ * ```ts
+ * const db = LazyAsync(async () => {
+ *     console.log('Connecting...');
+ *     return await Database.connect(url);
+ * });
+ *
+ * // Multiple concurrent accesses - only one connection
+ * const [db1, db2] = await Promise.all([
+ *     db.force(),
+ *     db.force(),
+ * ]);
+ * // db1 === db2
+ * ```
+ */
+interface LazyAsync<T> {
+    /**
+     * The well-known symbol `Symbol.toStringTag` used by `Object.prototype.toString()`.
+     * Returns `'LazyAsync'` so that `Object.prototype.toString.call(lazy)` produces `'[object LazyAsync]'`.
+     *
+     * @internal
+     */
+    readonly [Symbol.toStringTag]: 'LazyAsync';
+    /**
+     * Forces the evaluation of this lazy value and returns a promise to the result.
+     *
+     * If the value has already been initialized, returns the cached value.
+     * If initialization is in progress, waits for it to complete.
+     * Otherwise, starts initialization.
+     *
+     * @returns A promise that resolves to the initialized value.
+     *
+     * @example
+     * ```ts
+     * const lazy = LazyAsync(async () => {
+     *     await delay(100);
+     *     return 42;
+     * });
+     * console.log(await lazy.force()); // 42
+     * ```
+     */
+    force(): Promise<T>;
+    /**
+     * Gets the value if it has been initialized.
+     *
+     * Unlike `force()`, this does not trigger initialization.
+     *
+     * @returns `Some(value)` if initialized, `None` otherwise.
+     *
+     * @example
+     * ```ts
+     * const lazy = LazyAsync(async () => 42);
+     * console.log(lazy.get()); // None
+     *
+     * await lazy.force();
+     * console.log(lazy.get()); // Some(42)
+     * ```
+     */
+    get(): Option<T>;
+    /**
+     * Returns `true` if the value has been initialized.
+     *
+     * Note: Returns `false` while initialization is in progress.
+     *
+     * @example
+     * ```ts
+     * const lazy = LazyAsync(async () => 42);
+     * console.log(lazy.isInitialized()); // false
+     *
+     * await lazy.force();
+     * console.log(lazy.isInitialized()); // true
+     * ```
+     */
+    isInitialized(): boolean;
+    /**
+     * Custom `toString` implementation.
+     * @example
+     * ```ts
+     * const lazy = LazyAsync(async () => 42);
+     * console.log(lazy.toString()); // 'LazyAsync(<uninitialized>)'
+     *
+     * await lazy.force();
+     * console.log(lazy.toString()); // 'LazyAsync(42)'
+     * ```
+     */
+    toString(): string;
+}
+/**
+ * Creates a new `LazyAsync<T>` with the given async initialization function.
+ *
+ * The function is called at most once, on first access via `force()`.
+ * Concurrent calls to `force()` before initialization completes will
+ * wait for the single initialization to finish.
+ *
+ * @typeParam T - The type of value to store.
+ * @param fn - The async initialization function that produces the value.
+ * @returns A new `LazyAsync<T>` instance.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const lazy = LazyAsync(async () => {
+ *     const response = await fetch('/api/data');
+ *     return await response.json();
+ * });
+ *
+ * const data = await lazy.force();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Database connection singleton
+ * const db = LazyAsync(async () => {
+ *     console.log('Connecting to database...');
+ *     return await Database.connect(connectionString);
+ * });
+ *
+ * async function getDb(): Promise<Database> {
+ *     return await db.force();
+ * }
+ *
+ * // Multiple calls - connection happens only once
+ * const [db1, db2] = await Promise.all([getDb(), getDb()]);
+ * console.log(db1 === db2); // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Configuration loader
+ * const config = LazyAsync(async () => {
+ *     const response = await fetch('/api/config');
+ *     if (!response.ok) {
+ *         throw new Error(`Failed to load config: ${response.status}`);
+ *     }
+ *     return await response.json() as Config;
+ * });
+ *
+ * // Used throughout the app
+ * async function getApiEndpoint(): Promise<string> {
+ *     const cfg = await config.force();
+ *     return cfg.apiEndpoint;
+ * }
+ * ```
+ */
+declare function LazyAsync<T>(fn: () => Promise<T>): LazyAsync<T>;
+
+/**
+ * @fileoverview
+ * Rust-inspired [Mutex](https://doc.rust-lang.org/std/sync/struct.Mutex.html) for async mutual exclusion.
+ *
+ * In JavaScript's single-threaded environment, `Mutex<T>` is used to serialize
+ * async operations, ensuring only one async task accesses the protected resource at a time.
+ */
+
+/**
+ * A guard that provides access to the mutex-protected value.
+ *
+ * The guard must be released after use by calling `unlock()`.
+ * Failure to unlock will cause deadlock for subsequent lock attempts.
+ *
+ * @typeParam T - The type of the protected value.
+ */
+interface MutexGuard<T> {
+    /**
+     * The well-known symbol `Symbol.toStringTag` used by `Object.prototype.toString()`.
+     * Returns `'MutexGuard'` so that `Object.prototype.toString.call(guard)` produces `'[object MutexGuard]'`.
+     *
+     * @internal
+     */
+    readonly [Symbol.toStringTag]: 'MutexGuard';
+    /**
+     * The protected value. Can be read or modified while the guard is held.
+     */
+    value: T;
+    /**
+     * Releases the lock, allowing other waiters to acquire it.
+     *
+     * Must be called when done with the protected value.
+     * After calling `unlock()`, the guard should not be used.
+     *
+     * @example
+     * ```ts
+     * const guard = await mutex.lock();
+     * try {
+     *     guard.value.push('item');
+     * } finally {
+     *     guard.unlock();
+     * }
+     * ```
+     */
+    unlock(): void;
+    /**
+     * Custom `toString` implementation.
+     * @example
+     * ```ts
+     * const guard = await mutex.lock();
+     * console.log(guard.toString()); // 'MutexGuard(42)'
+     * ```
+     */
+    toString(): string;
+}
+/**
+ * An async mutual exclusion primitive for protecting shared data.
+ *
+ * This mutex provides exclusive access to the contained value, ensuring
+ * that only one async operation can access it at a time. This is useful
+ * for preventing race conditions in async code.
+ *
+ * Unlike Rust's Mutex which is for multi-threading, this JavaScript version
+ * serializes async operations in the single-threaded event loop.
+ *
+ * @typeParam T - The type of the protected value.
+ *
+ * @example
+ * ```ts
+ * const mutex = Mutex({ balance: 100 });
+ *
+ * // Safe concurrent updates
+ * await Promise.all([
+ *     mutex.withLock(async (account) => {
+ *         account.balance -= 50;
+ *     }),
+ *     mutex.withLock(async (account) => {
+ *         account.balance += 30;
+ *     }),
+ * ]);
+ * ```
+ */
+interface Mutex<T> {
+    /**
+     * The well-known symbol `Symbol.toStringTag` used by `Object.prototype.toString()`.
+     * Returns `'Mutex'` so that `Object.prototype.toString.call(mutex)` produces `'[object Mutex]'`.
+     *
+     * @internal
+     */
+    readonly [Symbol.toStringTag]: 'Mutex';
+    /**
+     * Acquires the lock and executes the callback with the protected value.
+     *
+     * This is the recommended way to use the mutex as it automatically
+     * releases the lock when the callback completes (or throws).
+     *
+     * @typeParam U - The return type of the callback.
+     * @param fn - The callback that receives the protected value.
+     * @returns A promise that resolves to the callback's return value.
+     *
+     * @example
+     * ```ts
+     * const mutex = Mutex<number[]>([]);
+     *
+     * await mutex.withLock(async (arr) => {
+     *     arr.push(await fetchItem());
+     * });
+     * ```
+     */
+    withLock<U>(fn: (value: T) => Promise<U> | U): Promise<U>;
+    /**
+     * Acquires the lock and returns a guard for manual control.
+     *
+     * Use this when you need more control over when to release the lock.
+     * **Important:** Always release the lock in a `finally` block to prevent deadlocks.
+     *
+     * @returns A promise that resolves to a guard providing access to the value.
+     *
+     * @example
+     * ```ts
+     * const guard = await mutex.lock();
+     * try {
+     *     // Long-running operation with the protected value
+     *     await processData(guard.value);
+     *     guard.value = transformedData;
+     * } finally {
+     *     guard.unlock();
+     * }
+     * ```
+     */
+    lock(): Promise<MutexGuard<T>>;
+    /**
+     * Attempts to acquire the lock without waiting.
+     *
+     * Returns immediately with `Some(guard)` if the lock is available,
+     * or `None` if it's currently held by another operation.
+     *
+     * @returns `Some(guard)` if acquired, `None` if locked.
+     *
+     * @example
+     * ```ts
+     * const maybeGuard = mutex.tryLock();
+     * if (maybeGuard.isSome()) {
+     *     const guard = maybeGuard.unwrap();
+     *     try {
+     *         // Use the value
+     *     } finally {
+     *         guard.unlock();
+     *     }
+     * } else {
+     *     console.log('Mutex is busy');
+     * }
+     * ```
+     */
+    tryLock(): Option<MutexGuard<T>>;
+    /**
+     * Returns `true` if the mutex is currently locked.
+     *
+     * Note: This is a snapshot and may change immediately after the call.
+     *
+     * @example
+     * ```ts
+     * console.log(mutex.isLocked()); // false
+     * const guard = await mutex.lock();
+     * console.log(mutex.isLocked()); // true
+     * guard.unlock();
+     * console.log(mutex.isLocked()); // false
+     * ```
+     */
+    isLocked(): boolean;
+    /**
+     * Custom `toString` implementation.
+     * @example
+     * ```ts
+     * const mutex = Mutex(42);
+     * console.log(mutex.toString()); // 'Mutex(<unlocked>)'
+     *
+     * const guard = await mutex.lock();
+     * console.log(mutex.toString()); // 'Mutex(<locked>)'
+     * ```
+     */
+    toString(): string;
+}
+/**
+ * Creates a new `Mutex<T>` protecting the given value.
+ *
+ * @typeParam T - The type of the protected value.
+ * @param value - The initial value to protect.
+ * @returns A new `Mutex<T>` instance.
+ *
+ * @example
+ * ```ts
+ * // Protect a simple value
+ * const counter = Mutex(0);
+ *
+ * // Protect an object
+ * const state = Mutex({ users: [], lastUpdate: Date.now() });
+ *
+ * // Protect a resource
+ * const db = Mutex(await createConnection());
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Database transaction safety
+ * const connection = Mutex(db);
+ *
+ * async function transfer(from: string, to: string, amount: number) {
+ *     await connection.withLock(async (conn) => {
+ *         await conn.beginTransaction();
+ *         try {
+ *             const balance = await conn.query('SELECT balance FROM accounts WHERE id = ?', [from]);
+ *             if (balance < amount) {
+ *                 throw new Error('Insufficient funds');
+ *             }
+ *             await conn.query('UPDATE accounts SET balance = balance - ? WHERE id = ?', [amount, from]);
+ *             await conn.query('UPDATE accounts SET balance = balance + ? WHERE id = ?', [amount, to]);
+ *             await conn.commit();
+ *         } catch (e) {
+ *             await conn.rollback();
+ *             throw e;
+ *         }
+ *     });
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Token refresh with mutex
+ * const authState = Mutex({ token: '', expiresAt: 0 });
+ *
+ * async function getToken(): Promise<string> {
+ *     return await authState.withLock(async (state) => {
+ *         if (Date.now() > state.expiresAt) {
+ *             const response = await fetch('/api/refresh');
+ *             const data = await response.json();
+ *             state.token = data.token;
+ *             state.expiresAt = Date.now() + data.expiresIn * 1000;
+ *         }
+ *         return state.token;
+ *     });
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // File write serialization
+ * const fileLock = Mutex('/path/to/file.json');
+ *
+ * async function appendToFile(data: string) {
+ *     await fileLock.withLock(async (path) => {
+ *         const content = await fs.readFile(path, 'utf-8');
+ *         const json = JSON.parse(content);
+ *         json.entries.push(data);
+ *         await fs.writeFile(path, JSON.stringify(json, null, 2));
+ *     });
+ * }
+ * ```
+ */
+declare function Mutex<T>(value: T): Mutex<T>;
+
+/**
+ * @fileoverview
+ * Rust-inspired [OnceLock](https://doc.rust-lang.org/std/sync/struct.OnceLock.html) for one-time initialization.
+ *
+ * `Once<T>` is a container which can be written to only once. It provides safe access
+ * to lazily initialized data, supporting both sync and async initialization.
+ */
+
+/**
+ * A container which can be written to only once.
+ *
+ * This is useful for lazy initialization of global data or expensive computations
+ * that should only happen once. Supports both synchronous and asynchronous
+ * initialization functions via separate methods.
+ *
+ * @typeParam T - The type of the value stored.
+ *
+ * @example
+ * ```ts
+ * const once = Once<number>();
+ *
+ * // Set value (only works once)
+ * once.set(42); // Ok(undefined)
+ * once.set(100); // Err(100) - already set
+ *
+ * // Get value
+ * console.log(once.get()); // Some(42)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Sync lazy initialization
+ * const config = Once<Config>();
+ * const cfg = config.getOrInit(() => loadConfigFromFile());
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Async lazy initialization
+ * const db = Once<Database>();
+ * const conn = await db.getOrInitAsync(async () => Database.connect(url));
+ * ```
+ */
+interface Once<T> {
+    /**
+     * The well-known symbol `Symbol.toStringTag` used by `Object.prototype.toString()`.
+     * Returns `'Once'` so that `Object.prototype.toString.call(once)` produces `'[object Once]'`.
+     *
+     * @internal
+     */
+    readonly [Symbol.toStringTag]: 'Once';
+    /**
+     * Gets the reference to the underlying value.
+     *
+     * @returns `Some(value)` if initialized, `None` otherwise.
+     *
+     * @example
+     * ```ts
+     * const once = Once<number>();
+     * console.log(once.get()); // None
+     *
+     * once.set(42);
+     * console.log(once.get()); // Some(42)
+     * ```
+     */
+    get(): Option<T>;
+    /**
+     * Sets the contents to `value`.
+     *
+     * @param value - The value to store.
+     * @returns `Ok(undefined)` if empty, `Err(value)` if already initialized.
+     *
+     * @example
+     * ```ts
+     * const once = Once<number>();
+     *
+     * console.log(once.set(42)); // Ok(undefined)
+     * console.log(once.set(100)); // Err(100) - value returned back
+     * console.log(once.get()); // Some(42)
+     * ```
+     */
+    set(value: T): Result<void, T>;
+    /**
+     * Gets the contents, initializing it with `fn` if empty.
+     *
+     * @param fn - The synchronous initialization function, called only if empty.
+     * @returns The stored value.
+     *
+     * @example
+     * ```ts
+     * const once = Once<number>();
+     *
+     * const value = once.getOrInit(() => {
+     *     console.log('Initializing...');
+     *     return 42;
+     * });
+     * console.log(value); // 42
+     *
+     * // Second call - fn is not called
+     * const value2 = once.getOrInit(() => 100);
+     * console.log(value2); // 42
+     * ```
+     */
+    getOrInit(fn: () => T): T;
+    /**
+     * Gets the contents, initializing it with async `fn` if empty.
+     *
+     * If multiple calls occur concurrently, only the first one will run the
+     * initialization function. Other calls will wait for it to complete.
+     *
+     * @param fn - The async initialization function.
+     * @returns A promise that resolves to the stored value.
+     *
+     * @example
+     * ```ts
+     * const db = Once<Database>();
+     *
+     * // Multiple concurrent calls - only one connection happens
+     * const [db1, db2, db3] = await Promise.all([
+     *     db.getOrInitAsync(() => Database.connect(url)),
+     *     db.getOrInitAsync(() => Database.connect(url)),
+     *     db.getOrInitAsync(() => Database.connect(url)),
+     * ]);
+     * // db1 === db2 === db3
+     * ```
+     */
+    getOrInitAsync(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Gets the contents, initializing it with `fn` if empty.
+     * If `fn` returns `Err`, remains uninitialized.
+     *
+     * @typeParam E - The error type.
+     * @param fn - The initialization function that may fail.
+     * @returns `Ok(value)` if initialized, `Err(error)` if initialization failed.
+     *
+     * @example
+     * ```ts
+     * const once = Once<Config>();
+     *
+     * const result = once.getOrTryInit(() => {
+     *     const config = parseConfig(rawData);
+     *     return config ? Ok(config) : Err(new Error('Invalid config'));
+     * });
+     *
+     * if (result.isOk()) {
+     *     console.log('Config loaded:', result.unwrap());
+     * }
+     * ```
+     */
+    getOrTryInit<E>(fn: () => Result<T, E>): Result<T, E>;
+    /**
+     * Gets the contents, initializing it with async `fn` if empty.
+     * If `fn` returns `Err`, remains uninitialized.
+     *
+     * If multiple calls occur concurrently, only the first one will run the
+     * initialization function. Other calls will wait for it to complete.
+     *
+     * @typeParam E - The error type.
+     * @param fn - The async initialization function that may fail.
+     * @returns A promise that resolves to `Ok(value)` or `Err(error)`.
+     *
+     * @example
+     * ```ts
+     * const config = Once<Config>();
+     *
+     * const result = await config.getOrTryInitAsync(async () => {
+     *     try {
+     *         const response = await fetch('/api/config');
+     *         return Ok(await response.json());
+     *     } catch (e) {
+     *         return Err(e as Error);
+     *     }
+     * });
+     * ```
+     */
+    getOrTryInitAsync<E>(fn: () => Promise<Result<T, E>>): Promise<Result<T, E>>;
+    /**
+     * Takes the value out, leaving it uninitialized.
+     *
+     * @returns `Some(value)` if initialized, `None` otherwise.
+     *
+     * @example
+     * ```ts
+     * const once = Once<number>();
+     * once.set(42);
+     *
+     * console.log(once.take()); // Some(42)
+     * console.log(once.get()); // None - now empty
+     * console.log(once.take()); // None
+     * ```
+     */
+    take(): Option<T>;
+    /**
+     * Returns `true` if initialized.
+     *
+     * @example
+     * ```ts
+     * const once = Once<number>();
+     * console.log(once.isInitialized()); // false
+     *
+     * once.set(42);
+     * console.log(once.isInitialized()); // true
+     * ```
+     */
+    isInitialized(): boolean;
+    /**
+     * Custom `toString` implementation.
+     * @example
+     * ```ts
+     * const once = Once<number>();
+     * console.log(once.toString()); // 'Once(<uninitialized>)'
+     *
+     * once.set(42);
+     * console.log(once.toString()); // 'Once(42)'
+     * ```
+     */
+    toString(): string;
+}
+/**
+ * Creates a new empty `Once<T>`.
+ *
+ * @typeParam T - The type of value to store.
+ * @returns A new uninitialized `Once`.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const once = Once<string>();
+ * once.set('hello');
+ * console.log(once.get().unwrap()); // 'hello'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Sync lazy singleton pattern
+ * const logger = Once<Logger>();
+ *
+ * function getLogger(): Logger {
+ *     return logger.getOrInit(() => new Logger('app'));
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Async lazy initialization
+ * const db = Once<Database>();
+ *
+ * async function getDb(): Promise<Database> {
+ *     return await db.getOrInitAsync(async () => {
+ *         console.log('Connecting to database...');
+ *         return await Database.connect(connectionString);
+ *     });
+ * }
+ *
+ * // Multiple calls - connection happens only once
+ * const [db1, db2] = await Promise.all([getDb(), getDb()]);
+ * console.log(db1 === db2); // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Fallible async initialization
+ * const config = Once<Config>();
+ *
+ * async function loadConfig(): Promise<Result<Config, Error>> {
+ *     return await config.getOrTryInitAsync(async () => {
+ *         try {
+ *             const response = await fetch('/api/config');
+ *             if (!response.ok) {
+ *                 return Err(new Error(`HTTP ${response.status}`));
+ *             }
+ *             return Ok(await response.json());
+ *         } catch (e) {
+ *             return Err(e as Error);
+ *         }
+ *     });
+ * }
+ * ```
+ */
+declare function Once<T>(): Once<T>;
+
+export { Break, Continue, Err, Lazy, LazyAsync, Mutex, None, Ok, Once, RESULT_FALSE, RESULT_TRUE, RESULT_VOID, RESULT_ZERO, Some, isControlFlow, isOption, isResult, promiseToAsyncResult };
+export type { AsyncIOResult, AsyncOption, AsyncResult, AsyncVoidIOResult, AsyncVoidResult, ControlFlow, IOResult, MutexGuard, Option, Result, VoidIOResult, VoidResult };