ts-data-forge 3.3.1 → 4.1.0

package/dist/functional/optional.mjs

@@ -1,328 +0,0 @@
-import { isRecord } from '../guard/is-record.mjs';
-
-/** @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';
-/**
- * Namespace for the {@link Optional} type and related functions. Provides
- * utilities to handle values that might be absent, similar to Option types in
- * other languages.
- */
-var Optional;
-(function (Optional) {
-    /**
-     * Checks if the given value is an {@link Optional}.
-     *
-     * @example
-     *
-     * ```ts
-     * const maybeOptional = Optional.some('value');
-     * const notOptional = { $$tag: 'ts-data-forge::Optional.some' };
-     *
-     * assert.ok(Optional.isOptional(maybeOptional));
-     * assert.notOk(Optional.isOptional(notOptional));
-     * ```
-     *
-     * @param maybeOptional The value to check.
-     * @returns `true` if the value is an {@link Optional}, otherwise `false`.
-     */
-    Optional.isOptional = (maybeOptional) => isRecord(maybeOptional) &&
-        Object.hasOwn(maybeOptional, '$$tag') &&
-        ((maybeOptional['$$tag'] === SomeTypeTagName &&
-            Object.hasOwn(maybeOptional, 'value')) ||
-            maybeOptional['$$tag'] === NoneTypeTagName);
-    /**
-     * Creates an {@link Optional.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 Optional.Some}.
-     * @returns An {@link Optional.Some}<S> containing the value.
-     */
-    Optional.some = (value) => ({
-        $$tag: SomeTypeTagName,
-        value,
-    });
-    /**
-     * The singleton instance representing {@link Optional.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));
-     * ```
-     */
-    Optional.none = { $$tag: NoneTypeTagName };
-    /**
-     * Checks if an {@link Optional} is {@link Optional.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 Optional.Base} type to check.
-     * @param optional The {@link Optional} to check.
-     * @returns `true` if the {@link Optional} is {@link Optional.Some}, `false`
-     *   otherwise.
-     */
-    Optional.isSome = (optional) => optional.$$tag === SomeTypeTagName;
-    /**
-     * Checks if an {@link Optional} is {@link Optional.None}. Acts as a type guard.
-     *
-     * @example
-     *
-     * ```ts
-     * const optionalValue = Optional.none as Optional<number>;
-     *
-     * if (Optional.isNone(optionalValue)) {
-     *   // Type narrowed to None
-     *   assert.ok(true); // optionalValue is None
-     * }
-     * ```
-     *
-     * @template O The {@link Optional.Base} type to check.
-     * @param optional The {@link Optional} to check.
-     * @returns `true` if the {@link Optional} is {@link Optional.None}, `false`
-     *   otherwise.
-     */
-    Optional.isNone = (optional) => optional.$$tag === NoneTypeTagName;
-    /**
-     * Unwraps an `Optional`, returning the contained value. Throws an error if
-     * the `Optional` is `Optional.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 `Optional.Base` type to unwrap.
-     * @param optional The `Optional` to unwrap.
-     * @returns The contained value if `Optional.Some`.
-     * @throws {Error} Error with message "`unwrapThrow()` has failed because it
-     *   is `None`" if the `Optional` is `Optional.None`.
-     */
-    Optional.unwrapThrow = (optional) => {
-        if (Optional.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`');
-    };
-    function unwrap(optional) {
-        return Optional.isSome(optional)
-            ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-                optional.value
-            : undefined;
-    }
-    Optional.unwrap = unwrap;
-    function unwrapOr(...args) {
-        switch (args.length) {
-            case 2: {
-                const [optional, defaultValue] = args;
-                return Optional.isSome(optional)
-                    ? // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-                        optional.value
-                    : defaultValue;
-            }
-            case 1: {
-                // Curried version: first argument is default value
-                const [defaultValue] = args;
-                return (optional) => unwrapOr(optional, defaultValue);
-            }
-        }
-    }
-    Optional.unwrapOr = unwrapOr;
-    function orElse(...args) {
-        switch (args.length) {
-            case 2: {
-                const [optional, alternative] = args;
-                return Optional.isNone(optional) ? alternative : optional;
-            }
-            case 1: {
-                const [alternative] = args;
-                return (optional) => orElse(optional, alternative);
-            }
-        }
-    }
-    Optional.orElse = orElse;
-    function map(...args) {
-        switch (args.length) {
-            case 2: {
-                const [optional, mapFn] = args;
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                return Optional.isSome(optional) ? Optional.some(mapFn(unwrap(optional))) : Optional.none;
-            }
-            case 1: {
-                // Curried version: first argument is mapping function
-                const [mapFn] = args;
-                return (optional) => map(optional, mapFn);
-            }
-        }
-    }
-    Optional.map = map;
-    function flatMap(...args) {
-        switch (args.length) {
-            case 2: {
-                const [optional, flatMapFn] = args;
-                return Optional.isSome(optional) ? flatMapFn(unwrap(optional)) : Optional.none;
-            }
-            case 1: {
-                const [flatMapFn] = args;
-                return (optional) => flatMap(optional, flatMapFn);
-            }
-        }
-    }
-    Optional.flatMap = flatMap;
-    function filter(...args) {
-        switch (args.length) {
-            case 2: {
-                const [optional, predicate] = args;
-                if (Optional.isSome(optional)) {
-                    const value = unwrap(optional);
-                    return predicate(value) ? Optional.some(value) : Optional.none;
-                }
-                // If the optional is None, return None
-                return Optional.none;
-            }
-            case 1: {
-                // Curried version: first argument is predicate function
-                const [predicate] = args;
-                return (optional) => filter(optional, predicate);
-            }
-        }
-    }
-    Optional.filter = filter;
-    function expectToBe(...args) {
-        switch (args.length) {
-            case 2: {
-                const [optional, message] = args;
-                if (Optional.isSome(optional)) {
-                    return unwrap(optional);
-                }
-                throw new Error(message);
-            }
-            case 1: {
-                // Curried version: first argument is message
-                const [message] = args;
-                return (optional) => expectToBe(optional, message);
-            }
-        }
-    }
-    Optional.expectToBe = expectToBe;
-    /**
-     * 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`.
-     */
-    Optional.zip = (optionalA, optionalB) => Optional.isSome(optionalA) && Optional.isSome(optionalB)
-        ? Optional.some([optionalA.value, optionalB.value])
-        : Optional.none;
-    /**
-     * Converts a nullable value to an `Optional`.
-     *
-     * This is the primary way to lift nullable values (null or undefined) into
-     * the Optional type system. The function treats both `null` and `undefined`
-     * as empty values, converting them to `Optional.None`.
-     *
-     * @example
-     *
-     * ```ts
-     * const present = Optional.fromNullable('hello');
-     * const absent = Optional.fromNullable<string | null>(null);
-     *
-     * assert.deepStrictEqual(present, Optional.some('hello'));
-     * assert.deepStrictEqual(absent, Optional.none);
-     * ```
-     *
-     * @template T The type of the nullable value.
-     * @param value The nullable value to convert.
-     * @returns `Optional.Some<NonNullable<T>>` if the value is not null or
-     *   undefined, otherwise `Optional.None`.
-     */
-    Optional.fromNullable = (value) => (value == null ? Optional.none : Optional.some(value));
-    /**
-     * 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 `Optional.Base` type to convert.
-     * @param optional The `Optional` to convert.
-     * @returns The contained value if `Some`, otherwise `undefined`.
-     */
-    Optional.toNullable = (optional) => (Optional.isSome(optional) ? unwrap(optional) : undefined);
-})(Optional || (Optional = {}));
-
-export { Optional };
-//# sourceMappingURL=optional.mjs.map

package/dist/functional/optional.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"optional.mjs","sources":["../../src/functional/optional.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}