ts-data-forge 3.3.1 → 4.0.0

package/dist/functional/optional/impl/optional-is-some.mjs

@@ -0,0 +1,25 @@
+import { SomeTypeTagName } from './tag.mjs';
+
+/**
+ * Checks if an {@link Optional} is {@link Some}. Acts as a type guard.
+ *
+ * @example
+ *
+ * ```ts
+ * const optionalNumber = Optional.some(42);
+ *
+ * if (Optional.isSome(optionalNumber)) {
+ *   const value: number = optionalNumber.value;
+ *   assert(value === 42);
+ * }
+ * ```
+ *
+ * @template O The {@link UnknownOptional} type to check.
+ * @param optional The {@link Optional} to check.
+ * @returns `true` if the {@link Optional} is {@link Some}, `false`
+ *   otherwise.
+ */
+const isSome = (optional) => optional.$$tag === SomeTypeTagName;
+
+export { isSome };
+//# sourceMappingURL=optional-is-some.mjs.map

package/dist/functional/optional/impl/optional-is-some.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-is-some.mjs","sources":["../../../../src/functional/optional/impl/optional-is-some.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;;AAkBG;AACI,MAAM,MAAM,GAAG,CACpB,QAAW,KACqB,QAAQ,CAAC,KAAK,KAAK;;;;"}

package/dist/functional/optional/impl/optional-map.d.mts

@@ -0,0 +1,31 @@
+import { type Unwrap } from './types.mjs';
+/**
+ * Maps an {@link Optional}<S> to {@link Optional}<S2> by applying a function to
+ * a contained value. If the {@link Optional} is {@link None}, it
+ * returns {@link Optional.none}. Otherwise, it applies the `mapFn` to the
+ * value in `Some` and returns a new `Some` with the result.
+ *
+ * @example
+ *
+ * ```ts
+ * const numberOptional = Optional.some(21);
+ * const mapped = Optional.map(numberOptional, (value) => value * 2);
+ *
+ * assert.deepStrictEqual(mapped, Optional.some(42));
+ *
+ * const mapToLength = Optional.map((text: string) => text.length);
+ *
+ * assert.deepStrictEqual(mapToLength(Optional.some('abc')), Optional.some(3));
+ * assert.deepStrictEqual(mapToLength(Optional.none), Optional.none);
+ * ```
+ *
+ * @template O The input `UnknownOptional` type.
+ * @template S2 The type of the value returned by the mapping function.
+ * @param optional The `Optional` to map.
+ * @param mapFn The function to apply to the value if it exists.
+ * @returns A new `Optional<S2>` resulting from the mapping, or
+ *   `None` if the input was `None`.
+ */
+export declare function map<O extends UnknownOptional, S2>(optional: O, mapFn: (value: Unwrap<O>) => S2): Optional<S2>;
+export declare function map<S, S2>(mapFn: (value: S) => S2): (optional: Optional<S>) => Optional<S2>;
+//# sourceMappingURL=optional-map.d.mts.map

package/dist/functional/optional/impl/optional-map.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-map.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/optional-map.mts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,eAAe,EAAE,EAAE,EAC/C,QAAQ,EAAE,CAAC,EACX,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,GAC9B,QAAQ,CAAC,EAAE,CAAC,CAAC;AAGhB,wBAAgB,GAAG,CAAC,CAAC,EAAE,EAAE,EACvB,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,GACtB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAC"}

package/dist/functional/optional/impl/optional-map.mjs

@@ -0,0 +1,25 @@
+import { isSome } from './optional-is-some.mjs';
+import { none } from './optional-none.mjs';
+import { some } from './optional-some.mjs';
+import { unwrap } from './optional-unwrap.mjs';
+
+function map(...args) {
+    switch (args.length) {
+        case 2: {
+            const [optional, mapFn] = args;
+            return mapImpl(optional, mapFn);
+        }
+        case 1: {
+            // Curried version: first argument is mapping function
+            const [mapFn] = args;
+            return (optional) => mapImpl(optional, mapFn);
+        }
+    }
+}
+const mapImpl = (optional, mapFn) => isSome(optional)
+    ? // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        some(mapFn(unwrap(optional)))
+    : none;
+
+export { map };
+//# sourceMappingURL=optional-map.mjs.map

package/dist/functional/optional/impl/optional-map.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-map.mjs","sources":["../../../../src/functional/optional/impl/optional-map.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AA2CM,SAAU,GAAG,CACjB,GAAG,IAE2C,EAAA;AAE9C,IAAA,QAAQ,IAAI,CAAC,MAAM;QACjB,KAAK,CAAC,EAAE;AACN,YAAA,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,IAAI;AAC9B,YAAA,OAAO,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC;QACjC;QACA,KAAK,CAAC,EAAE;;AAEN,YAAA,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI;YACpB,OAAO,CAAC,QAAW,KAAK,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC;QAClD;;AAEJ;AAEA,MAAM,OAAO,GAAG,CACd,QAAW,EACX,KAA+B,KAE/B,MAAM,CAAC,QAAQ;AACb;QACE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAE,CAAC;MAC7B,IAAI;;;;"}

package/dist/functional/optional/impl/optional-none.d.mts

@@ -0,0 +1,16 @@
+/**
+ * The singleton instance representing {@link None} (an empty
+ * Optional).
+ *
+ * @example
+ *
+ * ```ts
+ * const someValue = Optional.some({ id: 1 });
+ * const noneValue = Optional.none;
+ *
+ * assert.ok(Optional.isSome(someValue));
+ * assert.ok(Optional.isNone(noneValue));
+ * ```
+ */
+export declare const none: None;
+//# sourceMappingURL=optional-none.d.mts.map

package/dist/functional/optional/impl/optional-none.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-none.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/optional-none.mts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI,EAAE,IAA0C,CAAC"}

package/dist/functional/optional/impl/optional-none.mjs

@@ -0,0 +1,20 @@
+import { NoneTypeTagName } from './tag.mjs';
+
+/**
+ * The singleton instance representing {@link None} (an empty
+ * Optional).
+ *
+ * @example
+ *
+ * ```ts
+ * const someValue = Optional.some({ id: 1 });
+ * const noneValue = Optional.none;
+ *
+ * assert.ok(Optional.isSome(someValue));
+ * assert.ok(Optional.isNone(noneValue));
+ * ```
+ */
+const none = { $$tag: NoneTypeTagName };
+
+export { none };
+//# sourceMappingURL=optional-none.mjs.map

package/dist/functional/optional/impl/optional-none.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-none.mjs","sources":["../../../../src/functional/optional/impl/optional-none.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;AAaG;MACU,IAAI,GAAS,EAAE,KAAK,EAAE,eAAe;;;;"}

package/dist/functional/optional/impl/optional-or-else.d.mts

@@ -0,0 +1,35 @@
+/**
+ * Returns the `Optional` if it is `Some`, otherwise returns the alternative.
+ *
+ * Provides a way to chain Optional operations with fallback values. This is
+ * particularly useful for implementing default behavior or cascading lookups.
+ * Supports both direct usage and curried form for functional composition.
+ *
+ * @example
+ *
+ * ```ts
+ * const preferred = Optional.some('primary');
+ * const fallback = Optional.some('secondary');
+ * const noneValue = Optional.none as Optional<string>;
+ *
+ * assert.deepStrictEqual(Optional.orElse(preferred, fallback), preferred);
+ * assert.deepStrictEqual(Optional.orElse(noneValue, fallback), fallback);
+ *
+ * const orElseFallback = Optional.orElse(Optional.some('default'));
+ *
+ * assert.deepStrictEqual(orElseFallback(Optional.none), Optional.some('default'));
+ * assert.deepStrictEqual(
+ *   orElseFallback(Optional.some('value')),
+ *   Optional.some('value'),
+ * );
+ * ```
+ *
+ * @template O The input `UnknownOptional` type.
+ * @param optional The `Optional` to check.
+ * @param alternative The alternative `Optional` to return if the first is
+ *   `None`.
+ * @returns The first `Optional` if `Some`, otherwise the alternative.
+ */
+export declare function orElse<O extends UnknownOptional, const O2 extends UnknownOptional>(optional: O, alternative: O2): O | O2;
+export declare function orElse<S, S2>(alternative: Optional<S2>): (optional: Optional<S>) => Optional<S> | Optional<S2>;
+//# sourceMappingURL=optional-or-else.d.mts.map

package/dist/functional/optional/impl/optional-or-else.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-or-else.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/optional-or-else.mts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CACpB,CAAC,SAAS,eAAe,EACzB,KAAK,CAAC,EAAE,SAAS,eAAe,EAChC,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC;AAGxC,wBAAgB,MAAM,CAAC,CAAC,EAAE,EAAE,EAC1B,WAAW,EAAE,QAAQ,CAAC,EAAE,CAAC,GACxB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC"}

package/dist/functional/optional/impl/optional-or-else.mjs

@@ -0,0 +1,19 @@
+import { isNone } from './optional-is-none.mjs';
+
+function orElse(...args) {
+    switch (args.length) {
+        case 2: {
+            const [optional, alternative] = args;
+            return orElseImpl(optional, alternative);
+        }
+        case 1: {
+            // Curried version
+            const [alternative] = args;
+            return (optional) => orElseImpl(optional, alternative);
+        }
+    }
+}
+const orElseImpl = (optional, alternative) => (isNone(optional) ? alternative : optional);
+
+export { orElse };
+//# sourceMappingURL=optional-or-else.mjs.map

package/dist/functional/optional/impl/optional-or-else.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-or-else.mjs","sources":["../../../../src/functional/optional/impl/optional-or-else.mts"],"sourcesContent":[null],"names":[],"mappings":";;AA6CM,SAAU,MAAM,CAIpB,GAAG,IAA0E,EAAA;AAE7E,IAAA,QAAQ,IAAI,CAAC,MAAM;QACjB,KAAK,CAAC,EAAE;AACN,YAAA,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,IAAI;AACpC,YAAA,OAAO,UAAU,CAAC,QAAQ,EAAE,WAAW,CAAC;QAC1C;QAEA,KAAK,CAAC,EAAE;;AAEN,YAAA,MAAM,CAAC,WAAW,CAAC,GAAG,IAAI;YAC1B,OAAO,CAAC,QAA6B,KACnC,UAAU,CAAC,QAAQ,EAAE,WAAW,CAAC;QACrC;;AAEJ;AAEA,MAAM,UAAU,GAAG,CAIjB,QAAW,EACX,WAAe,MACH,MAAM,CAAC,QAAQ,CAAC,GAAG,WAAW,GAAG,QAAQ,CAAC;;;;"}

package/dist/functional/optional/impl/optional-some.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Creates an {@link Some} containing the given value.
+ *
+ * @example
+ *
+ * ```ts
+ * const someValue = Optional.some({ id: 1 });
+ * const noneValue = Optional.none;
+ *
+ * assert.ok(Optional.isSome(someValue));
+ * assert.ok(Optional.isNone(noneValue));
+ * ```
+ *
+ * @template S The type of the value.
+ * @param value The value to wrap in an {@link Some}.
+ * @returns An {@link Some}<S> containing the value.
+ */
+export declare const some: <S>(value: S) => Some<S>;
+//# sourceMappingURL=optional-some.d.mts.map

package/dist/functional/optional/impl/optional-some.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-some.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/optional-some.mts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAG,OAAO,CAAC,KAAG,IAAI,CAAC,CAAC,CAGxC,CAAC"}

package/dist/functional/optional/impl/optional-some.mjs

@@ -0,0 +1,26 @@
+import { SomeTypeTagName } from './tag.mjs';
+
+/**
+ * Creates an {@link Some} containing the given value.
+ *
+ * @example
+ *
+ * ```ts
+ * const someValue = Optional.some({ id: 1 });
+ * const noneValue = Optional.none;
+ *
+ * assert.ok(Optional.isSome(someValue));
+ * assert.ok(Optional.isNone(noneValue));
+ * ```
+ *
+ * @template S The type of the value.
+ * @param value The value to wrap in an {@link Some}.
+ * @returns An {@link Some}<S> containing the value.
+ */
+const some = (value) => ({
+    $$tag: SomeTypeTagName,
+    value,
+});
+
+export { some };
+//# sourceMappingURL=optional-some.mjs.map

package/dist/functional/optional/impl/optional-some.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-some.mjs","sources":["../../../../src/functional/optional/impl/optional-some.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;;AAgBG;MACU,IAAI,GAAG,CAAK,KAAQ,MAAe;AAC9C,IAAA,KAAK,EAAE,eAAe;IACtB,KAAK;AACN,CAAA;;;;"}

package/dist/functional/optional/impl/optional-to-nullable.d.mts

@@ -0,0 +1,27 @@
+import { type Unwrap } from './types.mjs';
+/**
+ * Converts an `Optional` to a nullable value.
+ *
+ * This function extracts the value from an Optional, returning `undefined`
+ * for empty Optionals. This is useful when interfacing with APIs or systems
+ * that expect nullable values rather than Optional types.
+ *
+ * Note: This returns `undefined` (not `null`) for consistency with
+ * JavaScript's undefined semantics and TypeScript's optional properties.
+ *
+ * @example
+ *
+ * ```ts
+ * const someNumber = Optional.some(42);
+ * const noneNumber = Optional.none as Optional<number>;
+ *
+ * assert(Optional.toNullable(someNumber) === 42);
+ * assert(Optional.toNullable(noneNumber) === undefined);
+ * ```
+ *
+ * @template O The `UnknownOptional` type to convert.
+ * @param optional The `Optional` to convert.
+ * @returns The contained value if `Some`, otherwise `undefined`.
+ */
+export declare const toNullable: <O extends UnknownOptional>(optional: O) => Unwrap<O> | undefined;
+//# sourceMappingURL=optional-to-nullable.d.mts.map

package/dist/functional/optional/impl/optional-to-nullable.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-to-nullable.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/optional-to-nullable.mts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,eAAe,EAClD,UAAU,CAAC,KACV,MAAM,CAAC,CAAC,CAAC,GAAG,SAA8D,CAAC"}

package/dist/functional/optional/impl/optional-to-nullable.mjs

@@ -0,0 +1,31 @@
+import { isSome } from './optional-is-some.mjs';
+import { unwrap } from './optional-unwrap.mjs';
+
+/**
+ * Converts an `Optional` to a nullable value.
+ *
+ * This function extracts the value from an Optional, returning `undefined`
+ * for empty Optionals. This is useful when interfacing with APIs or systems
+ * that expect nullable values rather than Optional types.
+ *
+ * Note: This returns `undefined` (not `null`) for consistency with
+ * JavaScript's undefined semantics and TypeScript's optional properties.
+ *
+ * @example
+ *
+ * ```ts
+ * const someNumber = Optional.some(42);
+ * const noneNumber = Optional.none as Optional<number>;
+ *
+ * assert(Optional.toNullable(someNumber) === 42);
+ * assert(Optional.toNullable(noneNumber) === undefined);
+ * ```
+ *
+ * @template O The `UnknownOptional` type to convert.
+ * @param optional The `Optional` to convert.
+ * @returns The contained value if `Some`, otherwise `undefined`.
+ */
+const toNullable = (optional) => (isSome(optional) ? unwrap(optional) : undefined);
+
+export { toNullable };
+//# sourceMappingURL=optional-to-nullable.mjs.map

package/dist/functional/optional/impl/optional-to-nullable.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-to-nullable.mjs","sources":["../../../../src/functional/optional/impl/optional-to-nullable.mts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AACI,MAAM,UAAU,GAAG,CACxB,QAAW,MACgB,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS;;;;"}

package/dist/functional/optional/impl/optional-unwrap-or.d.mts

@@ -0,0 +1,33 @@
+import { type Unwrap } from './types.mjs';
+/**
+ * Unwraps an `Optional`, returning the contained value or a default value if
+ * it's `None`.
+ *
+ * Supports both direct usage and curried form for functional composition.
+ * This is often preferred over `unwrap()` when you have a sensible fallback
+ * value.
+ *
+ * @example
+ *
+ * ```ts
+ * const withValue = Optional.some(5);
+ * const withoutValue = Optional.none as Optional<number>;
+ *
+ * assert(Optional.unwrapOr(withValue, 0) === 5);
+ * assert(Optional.unwrapOr(withoutValue, 0) === 0);
+ *
+ * const unwrapWithDefault = Optional.unwrapOr(10);
+ *
+ * assert(unwrapWithDefault(Optional.some(3)) === 3);
+ * assert(unwrapWithDefault(Optional.none) === 10);
+ * ```
+ *
+ * @template O The `UnknownOptional` type to unwrap.
+ * @template D The type of the default value.
+ * @param optional The `Optional` to unwrap.
+ * @param defaultValue The value to return if `optional` is `None`.
+ * @returns The contained value if `Some`, otherwise `defaultValue`.
+ */
+export declare function unwrapOr<O extends UnknownOptional, D>(optional: O, defaultValue: D): D | Unwrap<O>;
+export declare function unwrapOr<S, D>(defaultValue: D): (optional: Optional<S>) => D | S;
+//# sourceMappingURL=optional-unwrap-or.d.mts.map

package/dist/functional/optional/impl/optional-unwrap-or.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-unwrap-or.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/optional-unwrap-or.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,eAAe,EAAE,CAAC,EACnD,QAAQ,EAAE,CAAC,EACX,YAAY,EAAE,CAAC,GACd,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;AAGjB,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAC3B,YAAY,EAAE,CAAC,GACd,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC"}

package/dist/functional/optional/impl/optional-unwrap-or.mjs

@@ -0,0 +1,19 @@
+import { unwrap } from './optional-unwrap.mjs';
+
+function unwrapOr(...args) {
+    switch (args.length) {
+        case 2: {
+            const [optional, defaultValue] = args;
+            return unwrapOrImpl(optional, defaultValue);
+        }
+        case 1: {
+            // Curried version: first argument is default value
+            const [defaultValue] = args;
+            return (optional) => unwrapOrImpl(optional, defaultValue);
+        }
+    }
+}
+const unwrapOrImpl = (optional, defaultValue) => unwrap(optional) ?? defaultValue;
+
+export { unwrapOr };
+//# sourceMappingURL=optional-unwrap-or.mjs.map

package/dist/functional/optional/impl/optional-unwrap-or.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-unwrap-or.mjs","sources":["../../../../src/functional/optional/impl/optional-unwrap-or.mts"],"sourcesContent":[null],"names":[],"mappings":";;AA0CM,SAAU,QAAQ,CACtB,GAAG,IAA0E,EAAA;AAE7E,IAAA,QAAQ,IAAI,CAAC,MAAM;QACjB,KAAK,CAAC,EAAE;AACN,YAAA,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,GAAG,IAAI;AACrC,YAAA,OAAO,YAAY,CAAC,QAAQ,EAAE,YAAY,CAAC;QAC7C;QAEA,KAAK,CAAC,EAAE;;AAEN,YAAA,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI;YAC3B,OAAO,CAAC,QAA6B,KACnC,YAAY,CAAC,QAAQ,EAAE,YAAY,CAAC;QACxC;;AAEJ;AAEA,MAAM,YAAY,GAAG,CACnB,QAAW,EACX,YAAe,KACG,MAAM,CAAC,QAAQ,CAAC,IAAI,YAAY;;;;"}

package/dist/functional/optional/impl/optional-unwrap-throw.d.mts

@@ -0,0 +1,29 @@
+import { type Unwrap } from './types.mjs';
+/**
+ * Unwraps an `Optional`, returning the contained value. Throws an error if
+ * the `Optional` is `None`.
+ *
+ * This is a safer alternative to direct value access when you know the
+ * Optional should contain a value. Use this method when an empty Optional
+ * represents a programming error or unexpected condition.
+ *
+ * @example
+ *
+ * ```ts
+ * const present = Optional.some('available');
+ *
+ * assert(Optional.unwrapThrow(present) === 'available');
+ * assert.throws(
+ *   () => Optional.unwrapThrow(Optional.none),
+ *   /has failed because it is `None`/u,
+ * );
+ * ```
+ *
+ * @template O The `UnknownOptional` type to unwrap.
+ * @param optional The `Optional` to unwrap.
+ * @returns The contained value if `Some`.
+ * @throws {Error} Error with message "`unwrapThrow()` has failed because it
+ *   is `None`" if the `Optional` is `None`.
+ */
+export declare const unwrapThrow: <O extends UnknownOptional>(optional: O) => Unwrap<O>;
+//# sourceMappingURL=optional-unwrap-throw.d.mts.map

package/dist/functional/optional/impl/optional-unwrap-throw.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-unwrap-throw.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/optional-unwrap-throw.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,eAAe,EACnD,UAAU,CAAC,KACV,MAAM,CAAC,CAAC,CAOV,CAAC"}

package/dist/functional/optional/impl/optional-unwrap-throw.mjs

@@ -0,0 +1,38 @@
+import { isSome } from './optional-is-some.mjs';
+
+/**
+ * Unwraps an `Optional`, returning the contained value. Throws an error if
+ * the `Optional` is `None`.
+ *
+ * This is a safer alternative to direct value access when you know the
+ * Optional should contain a value. Use this method when an empty Optional
+ * represents a programming error or unexpected condition.
+ *
+ * @example
+ *
+ * ```ts
+ * const present = Optional.some('available');
+ *
+ * assert(Optional.unwrapThrow(present) === 'available');
+ * assert.throws(
+ *   () => Optional.unwrapThrow(Optional.none),
+ *   /has failed because it is `None`/u,
+ * );
+ * ```
+ *
+ * @template O The `UnknownOptional` type to unwrap.
+ * @param optional The `Optional` to unwrap.
+ * @returns The contained value if `Some`.
+ * @throws {Error} Error with message "`unwrapThrow()` has failed because it
+ *   is `None`" if the `Optional` is `None`.
+ */
+const unwrapThrow = (optional) => {
+    if (isSome(optional)) {
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        return optional.value;
+    }
+    throw new Error('`unwrapThrow()` has failed because it is `None`');
+};
+
+export { unwrapThrow };
+//# sourceMappingURL=optional-unwrap-throw.mjs.map

package/dist/functional/optional/impl/optional-unwrap-throw.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-unwrap-throw.mjs","sources":["../../../../src/functional/optional/impl/optional-unwrap-throw.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACI,MAAM,WAAW,GAAG,CACzB,QAAW,KACE;AACb,IAAA,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE;;QAEpB,OAAO,QAAQ,CAAC,KAAkB;IACpC;AAEA,IAAA,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC;AACpE;;;;"}

package/dist/functional/optional/impl/optional-unwrap.d.mts

@@ -0,0 +1,28 @@
+import { type Unwrap } from './types.mjs';
+/**
+ * Unwraps an `Optional`, returning the contained value or `undefined` if
+ * empty.
+ *
+ * This function provides a safe way to extract values from Optionals without
+ * throwing exceptions. It has overloaded behavior based on the type:
+ *
+ * - For `Some<T>`: Always returns `T` (guaranteed by type system)
+ * - For general `Optional<T>`: Returns `T | undefined`
+ *
+ * @example
+ *
+ * ```ts
+ * const someString = Optional.some('text');
+ * const noneString = Optional.none as Optional<string>;
+ *
+ * assert(Optional.unwrap(someString) === 'text');
+ * assert(Optional.unwrap(noneString) === undefined);
+ * ```
+ *
+ * @template O The `UnknownOptional` type to unwrap.
+ * @param optional The `Optional` to unwrap.
+ * @returns The contained value if `Some`, otherwise `undefined`.
+ */
+export declare function unwrap<O extends Some<unknown>>(optional: O): Unwrap<O>;
+export declare function unwrap<O extends UnknownOptional>(optional: O): Unwrap<O> | undefined;
+//# sourceMappingURL=optional-unwrap.d.mts.map

package/dist/functional/optional/impl/optional-unwrap.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-unwrap.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/optional-unwrap.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;AAExE,wBAAgB,MAAM,CAAC,CAAC,SAAS,eAAe,EAC9C,QAAQ,EAAE,CAAC,GACV,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC"}

package/dist/functional/optional/impl/optional-unwrap.mjs

@@ -0,0 +1,11 @@
+import { isSome } from './optional-is-some.mjs';
+
+function unwrap(optional) {
+    return isSome(optional)
+        ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            optional.value
+        : undefined;
+}
+
+export { unwrap };
+//# sourceMappingURL=optional-unwrap.mjs.map

package/dist/functional/optional/impl/optional-unwrap.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-unwrap.mjs","sources":["../../../../src/functional/optional/impl/optional-unwrap.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAiCM,SAAU,MAAM,CACpB,QAAW,EAAA;IAEX,OAAO,MAAM,CAAC,QAAQ;AACpB;AACG,YAAA,QAAQ,CAAC;UACV,SAAS;AACf;;;;"}

package/dist/functional/optional/impl/optional-zip.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Combines two `Optional` values into a single `Optional` containing a tuple.
+ * If either `Optional` is `None`, returns `None`.
+ *
+ * @example
+ *
+ * ```ts
+ * const zipped = Optional.zip(Optional.some('left'), Optional.some(1));
+ *
+ * assert.ok(Optional.isSome(zipped));
+ * if (Optional.isSome(zipped)) {
+ *   const expected: readonly [string, number] = ['left', 1];
+ *   assert.deepStrictEqual(zipped.value, expected);
+ * }
+ *
+ * const missing = Optional.zip(
+ *   Optional.some('value'),
+ *   Optional.none as Optional<number>,
+ * );
+ *
+ * assert.deepStrictEqual(missing, Optional.none);
+ * ```
+ *
+ * @template A The value type of the first `Optional`.
+ * @template B The value type of the second `Optional`.
+ * @param optionalA The first `Optional`.
+ * @param optionalB The second `Optional`.
+ * @returns An `Optional` containing a tuple of both values, or `None`.
+ */
+export declare const zip: <A, const B>(optionalA: Optional<A>, optionalB: Optional<B>) => Optional<readonly [A, B]>;
+//# sourceMappingURL=optional-zip.d.mts.map

package/dist/functional/optional/impl/optional-zip.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-zip.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/optional-zip.mts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,KAAK,CAAC,CAAC,EAC5B,WAAW,QAAQ,CAAC,CAAC,CAAC,EACtB,WAAW,QAAQ,CAAC,CAAC,CAAC,KACrB,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAGjB,CAAC"}

package/dist/functional/optional/impl/optional-zip.mjs

@@ -0,0 +1,39 @@
+import { isSome } from './optional-is-some.mjs';
+import { none } from './optional-none.mjs';
+import { some } from './optional-some.mjs';
+
+/**
+ * Combines two `Optional` values into a single `Optional` containing a tuple.
+ * If either `Optional` is `None`, returns `None`.
+ *
+ * @example
+ *
+ * ```ts
+ * const zipped = Optional.zip(Optional.some('left'), Optional.some(1));
+ *
+ * assert.ok(Optional.isSome(zipped));
+ * if (Optional.isSome(zipped)) {
+ *   const expected: readonly [string, number] = ['left', 1];
+ *   assert.deepStrictEqual(zipped.value, expected);
+ * }
+ *
+ * const missing = Optional.zip(
+ *   Optional.some('value'),
+ *   Optional.none as Optional<number>,
+ * );
+ *
+ * assert.deepStrictEqual(missing, Optional.none);
+ * ```
+ *
+ * @template A The value type of the first `Optional`.
+ * @template B The value type of the second `Optional`.
+ * @param optionalA The first `Optional`.
+ * @param optionalB The second `Optional`.
+ * @returns An `Optional` containing a tuple of both values, or `None`.
+ */
+const zip = (optionalA, optionalB) => isSome(optionalA) && isSome(optionalB)
+    ? some([optionalA.value, optionalB.value])
+    : none;
+
+export { zip };
+//# sourceMappingURL=optional-zip.mjs.map

package/dist/functional/optional/impl/optional-zip.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-zip.mjs","sources":["../../../../src/functional/optional/impl/optional-zip.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BG;AACI,MAAM,GAAG,GAAG,CACjB,SAAsB,EACtB,SAAsB,KAEtB,MAAM,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,SAAS;AACnC,MAAE,IAAI,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,CAAU;MAChD;;;;"}

package/dist/functional/optional/impl/tag.d.mts

@@ -0,0 +1,5 @@
+/** @internal String literal tag to identify the 'Some' variant of Optional. */
+export declare const SomeTypeTagName: Some<unknown>['$$tag'];
+/** @internal String literal tag to identify the 'None' variant of Optional. */
+export declare const NoneTypeTagName: None['$$tag'];
+//# sourceMappingURL=tag.d.mts.map

package/dist/functional/optional/impl/tag.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.d.mts","sourceRoot":"","sources":["../../../../src/functional/optional/impl/tag.mts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,eAAO,MAAM,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,CACnB,CAAC;AAEjC,+EAA+E;AAC/E,eAAO,MAAM,eAAe,EAAE,IAAI,CAAC,OAAO,CAAkC,CAAC"}

package/dist/functional/optional/impl/tag.mjs

@@ -0,0 +1,7 @@
+/** @internal String literal tag to identify the 'Some' variant of Optional. */
+const SomeTypeTagName = 'ts-data-forge::Optional.some';
+/** @internal String literal tag to identify the 'None' variant of Optional. */
+const NoneTypeTagName = 'ts-data-forge::Optional.none';
+
+export { NoneTypeTagName, SomeTypeTagName };
+//# sourceMappingURL=tag.mjs.map

package/dist/functional/optional/impl/tag.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.mjs","sources":["../../../../src/functional/optional/impl/tag.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;AACO,MAAM,eAAe,GAC1B;AAEF;AACO,MAAM,eAAe,GAAkB;;;;"}