ts-data-forge 3.3.0 → 4.0.0

package/dist/functional/result/impl/result-unwrap-ok-or.d.mts

@@ -0,0 +1,29 @@
+import { type UnwrapOk } from './types.mjs';
+/**
+ * Unwraps a `Result`, returning the success value or a default value if it is
+ * `Result.Err`.
+ *
+ * @example
+ *
+ * ```ts
+ * const okValue = Result.ok(10);
+ * const errValue = Result.err('fail');
+ *
+ * assert(Result.unwrapOkOr(okValue, 0) === 10);
+ * assert(Result.unwrapOkOr(errValue, 0) === 0);
+ *
+ * const unwrapWithDefault = Result.unwrapOkOr(5);
+ *
+ * assert(unwrapWithDefault(Result.ok(3)) === 3);
+ * assert(unwrapWithDefault(Result.err('no data')) === 5);
+ * ```
+ *
+ * @template R The `UnknownResult` type to unwrap.
+ * @template D The type of the default value.
+ * @param result The `Result` to unwrap.
+ * @param defaultValue The value to return if `result` is `Result.Err`.
+ * @returns The success value if `Result.Ok`, otherwise `defaultValue`.
+ */
+export declare function unwrapOkOr<R extends UnknownResult, D>(result: R, defaultValue: D): D | UnwrapOk<R>;
+export declare function unwrapOkOr<S, D>(defaultValue: D): <E>(result: Result<S, E>) => D | S;
+//# sourceMappingURL=result-unwrap-ok-or.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result-unwrap-ok-or.d.mts","sourceRoot":"","sources":["../../../../src/functional/result/impl/result-unwrap-ok-or.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,EACnD,MAAM,EAAE,CAAC,EACT,YAAY,EAAE,CAAC,GACd,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAGnB,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAC7B,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC"}

package/dist/functional/result/impl/result-unwrap-ok-or.mjs

@@ -0,0 +1,20 @@
+import { unwrapOk } from './result-unwrap-ok.mjs';
+
+function unwrapOkOr(...args) {
+    switch (args.length) {
+        case 2: {
+            // Direct version: first argument is result
+            const [result, defaultValue] = args;
+            return unwrapOkOrImpl(result, defaultValue);
+        }
+        case 1: {
+            // Curried version
+            const [defaultValue] = args;
+            return (result) => unwrapOkOrImpl(result, defaultValue);
+        }
+    }
+}
+const unwrapOkOrImpl = (result, defaultValue) => unwrapOk(result) ?? defaultValue;
+
+export { unwrapOkOr };
+//# sourceMappingURL=result-unwrap-ok-or.mjs.map

package/dist/functional/result/impl/result-unwrap-ok-or.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-unwrap-ok-or.mjs","sources":["../../../../src/functional/result/impl/result-unwrap-ok-or.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAsCM,SAAU,UAAU,CACxB,GAAG,IAAwE,EAAA;AAE3E,IAAA,QAAQ,IAAI,CAAC,MAAM;QACjB,KAAK,CAAC,EAAE;;AAEN,YAAA,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,IAAI;AACnC,YAAA,OAAO,cAAc,CAAC,MAAM,EAAE,YAAY,CAAC;QAC7C;QAEA,KAAK,CAAC,EAAE;;AAEN,YAAA,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI;YAC3B,OAAO,CAAC,MAAS,KAAK,cAAc,CAAC,MAAM,EAAE,YAAY,CAAC;QAC5D;;AAEJ;AAEA,MAAM,cAAc,GAAG,CACrB,MAAS,EACT,YAAe,KACK,QAAQ,CAAC,MAAM,CAAC,IAAI,YAAY;;;;"}

package/dist/functional/result/impl/result-unwrap-ok.d.mts

@@ -0,0 +1,23 @@
+import { type UnwrapOk } from './types.mjs';
+/**
+ * Safely unwraps the success value, returning `undefined` for failures.
+ *
+ * @example
+ *
+ * ```ts
+ * const okResult = Result.ok(42);
+ * const errResult = Result.err('oops');
+ *
+ * // Result.unwrapOk returns the value for Ok results
+ *
+ * assert(Result.unwrapOk(okResult) === 42);
+ *
+ * // Result.unwrapOk returns undefined for Err results
+ *
+ * // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+ * assert(Result.unwrapOk(errResult) === undefined);
+ * ```
+ */
+export declare function unwrapOk<R extends Ok<unknown>>(result: R): UnwrapOk<R>;
+export declare function unwrapOk<R extends UnknownResult>(result: R): UnwrapOk<R> | undefined;
+//# sourceMappingURL=result-unwrap-ok.d.mts.map

package/dist/functional/result/impl/result-unwrap-ok.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-unwrap-ok.d.mts","sourceRoot":"","sources":["../../../../src/functional/result/impl/result-unwrap-ok.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AACxE,wBAAgB,QAAQ,CAAC,CAAC,SAAS,aAAa,EAC9C,MAAM,EAAE,CAAC,GACR,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC"}

package/dist/functional/result/impl/result-unwrap-ok.mjs

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

package/dist/functional/result/impl/result-unwrap-ok.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-unwrap-ok.mjs","sources":["../../../../src/functional/result/impl/result-unwrap-ok.mts"],"sourcesContent":[null],"names":[],"mappings":";;AA2BM,SAAU,QAAQ,CACtB,MAAS,EAAA;IAET,OAAO,IAAI,CAAC,MAAM;AAChB;AACG,YAAA,MAAM,CAAC;UACR,SAAS;AACf;;;;"}

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

@@ -0,0 +1,30 @@
+import { type UnwrapErr, type UnwrapOk } from './types.mjs';
+/**
+ * Unwraps a `Result`, returning the success value. Throws an error if the
+ * `Result` is `Result.Err`.
+ *
+ * This is useful when you're confident that a Result should contain a success
+ * value and want to treat errors as exceptional conditions. The error message
+ * will be constructed from the error value using the provided string
+ * conversion function.
+ *
+ * @example
+ *
+ * ```ts
+ * const okResult = Result.ok('data');
+ * const errResult = Result.err(new Error('fail'));
+ *
+ * assert(Result.unwrapThrow(okResult) === 'data');
+ * assert.throws(() => Result.unwrapThrow(errResult), /fail/u);
+ * ```
+ *
+ * @template R The `UnknownResult` type to unwrap.
+ * @param result The `Result` to unwrap.
+ * @param toStr An optional function to convert the error value to a string
+ *   for the error message. Defaults to `String`.
+ * @returns The success value if `Result.Ok`.
+ * @throws {Error} Error with the stringified error value if the `Result` is
+ *   `Result.Err`.
+ */
+export declare const unwrapThrow: <R extends UnknownResult>(result: R, toStr?: (e: UnwrapErr<R>) => string) => UnwrapOk<R>;
+//# sourceMappingURL=result-unwrap-throw.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result-unwrap-throw.d.mts","sourceRoot":"","sources":["../../../../src/functional/result/impl/result-unwrap-throw.mts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,aAAa,EACjD,QAAQ,CAAC,EACT,QAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,MAAwB,KACnD,QAAQ,CAAC,CAAC,CAQZ,CAAC"}

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

@@ -0,0 +1,41 @@
+import { unknownToString } from '../../../others/unknown-to-string.mjs';
+import { isErr } from './result-is-err.mjs';
+
+/**
+ * Unwraps a `Result`, returning the success value. Throws an error if the
+ * `Result` is `Result.Err`.
+ *
+ * This is useful when you're confident that a Result should contain a success
+ * value and want to treat errors as exceptional conditions. The error message
+ * will be constructed from the error value using the provided string
+ * conversion function.
+ *
+ * @example
+ *
+ * ```ts
+ * const okResult = Result.ok('data');
+ * const errResult = Result.err(new Error('fail'));
+ *
+ * assert(Result.unwrapThrow(okResult) === 'data');
+ * assert.throws(() => Result.unwrapThrow(errResult), /fail/u);
+ * ```
+ *
+ * @template R The `UnknownResult` type to unwrap.
+ * @param result The `Result` to unwrap.
+ * @param toStr An optional function to convert the error value to a string
+ *   for the error message. Defaults to `String`.
+ * @returns The success value if `Result.Ok`.
+ * @throws {Error} Error with the stringified error value if the `Result` is
+ *   `Result.Err`.
+ */
+const unwrapThrow = (result, toStr = unknownToString) => {
+    if (isErr(result)) {
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        throw new Error(toStr(result.value));
+    }
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return result.value;
+};
+
+export { unwrapThrow };
+//# sourceMappingURL=result-unwrap-throw.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result-unwrap-throw.mjs","sources":["../../../../src/functional/result/impl/result-unwrap-throw.mts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BG;AACI,MAAM,WAAW,GAAG,CACzB,MAAS,EACT,KAAA,GAAqC,eAAe,KACrC;AACf,IAAA,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE;;QAEjB,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,KAAqB,CAAC,CAAC;IACtD;;IAGA,OAAO,MAAM,CAAC,KAAoB;AACpC;;;;"}

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

@@ -0,0 +1,29 @@
+/**
+ * Combines two `Result` values into a single `Result` containing a tuple. If
+ * either `Result` is `Err`, returns the first `Err` encountered.
+ *
+ * @example
+ *
+ * ```ts
+ * const first = Result.ok('left');
+ * const second = Result.ok(1);
+ *
+ * const expected: readonly [string, number] = ['left', 1];
+ *
+ * assert.deepStrictEqual(Result.zip(first, second), Result.ok(expected));
+ * assert.deepStrictEqual(
+ *   Result.zip(first, Result.err('error')),
+ *   Result.err('error'),
+ * );
+ * ```
+ *
+ * @template S1 The success type of the first `Result`.
+ * @template E1 The error type of the first `Result`.
+ * @template S2 The success type of the second `Result`.
+ * @template E2 The error type of the second `Result`.
+ * @param resultA The first `Result`.
+ * @param resultB The second `Result`.
+ * @returns A `Result` containing a tuple of both values, or the first `Err`.
+ */
+export declare const zip: <S1, E1, S2, E2>(resultA: Result<S1, E1>, resultB: Result<S2, E2>) => Result<readonly [S1, S2], E1 | E2>;
+//# sourceMappingURL=result-zip.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result-zip.d.mts","sourceRoot":"","sources":["../../../../src/functional/result/impl/result-zip.mts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,GAAG,GAAI,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAChC,SAAS,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,EACvB,SAAS,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,KACtB,MAAM,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAKvB,CAAC"}

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

@@ -0,0 +1,38 @@
+import { isOk } from './result-is-ok.mjs';
+import { ok } from './result-ok.mjs';
+
+/**
+ * Combines two `Result` values into a single `Result` containing a tuple. If
+ * either `Result` is `Err`, returns the first `Err` encountered.
+ *
+ * @example
+ *
+ * ```ts
+ * const first = Result.ok('left');
+ * const second = Result.ok(1);
+ *
+ * const expected: readonly [string, number] = ['left', 1];
+ *
+ * assert.deepStrictEqual(Result.zip(first, second), Result.ok(expected));
+ * assert.deepStrictEqual(
+ *   Result.zip(first, Result.err('error')),
+ *   Result.err('error'),
+ * );
+ * ```
+ *
+ * @template S1 The success type of the first `Result`.
+ * @template E1 The error type of the first `Result`.
+ * @template S2 The success type of the second `Result`.
+ * @template E2 The error type of the second `Result`.
+ * @param resultA The first `Result`.
+ * @param resultB The second `Result`.
+ * @returns A `Result` containing a tuple of both values, or the first `Err`.
+ */
+const zip = (resultA, resultB) => isOk(resultA)
+    ? isOk(resultB)
+        ? ok([resultA.value, resultB.value])
+        : resultB
+    : resultA;
+
+export { zip };
+//# sourceMappingURL=result-zip.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result-zip.mjs","sources":["../../../../src/functional/result/impl/result-zip.mts"],"sourcesContent":[null],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BG;AACI,MAAM,GAAG,GAAG,CACjB,OAAuB,EACvB,OAAuB,KAEvB,IAAI,CAAC,OAAO;AACV,MAAE,IAAI,CAAC,OAAO;AACZ,UAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAU;AAC5C,UAAE;MACF;;;;"}

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

@@ -0,0 +1,5 @@
+/** @internal Tag identifying the Ok variant. */
+export declare const OkTypeTagName: Ok<unknown>['$$tag'];
+/** @internal Tag identifying the Err variant. */
+export declare const ErrTypeTagName: Err<unknown>['$$tag'];
+//# sourceMappingURL=tag.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tag.d.mts","sourceRoot":"","sources":["../../../../src/functional/result/impl/tag.mts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,eAAO,MAAM,aAAa,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,OAAO,CAA8B,CAAC;AAE9E,iDAAiD;AACjD,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,CACpB,CAAC"}

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

@@ -0,0 +1,7 @@
+/** @internal Tag identifying the Ok variant. */
+const OkTypeTagName = 'ts-data-forge::Result.ok';
+/** @internal Tag identifying the Err variant. */
+const ErrTypeTagName = 'ts-data-forge::Result.err';
+
+export { ErrTypeTagName, OkTypeTagName };
+//# sourceMappingURL=tag.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tag.mjs","sources":["../../../../src/functional/result/impl/tag.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;AACO,MAAM,aAAa,GAAyB;AAEnD;AACO,MAAM,cAAc,GACzB;;;;"}

package/dist/functional/result/impl/types.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Extracts the success value type `S` from a `Result.Ok<S>`. If the `Result`
+ * is `Result.Err<E>`, resolves to `never`.
+ *
+ * @template R The `UnknownResult` type to unwrap.
+ */
+export type UnwrapOk<R extends UnknownResult> = R extends Ok<infer S> ? S : never;
+/**
+ * Extracts the error value type `E` from a `Result.Err<E>`. If the `Result`
+ * is `Result.Ok<S>`, resolves to `never`.
+ *
+ * @template R The `UnknownResult` type to unwrap.
+ */
+export type UnwrapErr<R extends UnknownResult> = R extends Err<infer E> ? E : never;
+/**
+ * Narrows a `UnknownResult` type to `Result.Ok<S>` if it is an `Ok`. If the
+ * `Result` is `Result.Err<E>`, resolves to `never`.
+ *
+ * @template R The `UnknownResult` type to narrow.
+ */
+export type NarrowToOk<R extends UnknownResult> = R extends Ok<unknown> ? R : never;
+/**
+ * Narrows a `UnknownResult` type to `Result.Err<E>` if it is an `Err`. If the
+ * `Result` is `Result.Ok<S>`, resolves to `never`.
+ *
+ * @template R The `UnknownResult` type to narrow.
+ */
+export type NarrowToErr<R extends UnknownResult> = R extends Err<unknown> ? R : never;
+//# sourceMappingURL=types.d.mts.map

package/dist/functional/result/impl/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../../../src/functional/result/impl/types.mts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,aAAa,IAC1C,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,aAAa,IAC3C,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAErC;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,aAAa,IAC5C,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,aAAa,IAC7C,CAAC,SAAS,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC"}

package/dist/functional/result/impl/types.mjs

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=types.mjs.map

package/dist/functional/result/impl/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/functional/result/index.d.mts

@@ -0,0 +1,2 @@
+export * as Result from './impl/index.mjs';
+//# sourceMappingURL=index.d.mts.map

package/dist/functional/result/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../src/functional/result/index.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC"}

package/dist/functional/result/index.mjs

@@ -0,0 +1,3 @@
+import * as index from './impl/index.mjs';
+export { index as Result };
+//# sourceMappingURL=index.mjs.map

package/dist/functional/result/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/globals.d.mts

@@ -1,14 +1,21 @@
-/* eslint-disable import/unambiguous */
-
 /// <reference types="ts-type-forge" />
 
 type SmallPositiveInt = WithSmallInt<PositiveInt>;
 
-/**
- * Represents the type of keys that can be used in a standard JavaScript Map.
- */
+/** Represents the type of keys that can be used in a standard JavaScript Map. */
 type MapSetKeyType = Primitive;
 
+type ArrayIndex<Ar extends readonly unknown[]> =
+  IsFixedLengthList<Ar> extends true ? IndexOfTuple<Ar> : SizeType.Arr;
+
+type ArgArrayIndex<Ar extends readonly unknown[]> =
+  IsFixedLengthList<Ar> extends true ? IndexOfTuple<Ar> : SizeType.ArgArr;
+
+type ArgArrayIndexWithNegative<Ar extends readonly unknown[]> =
+  IsFixedLengthList<Ar> extends true
+    ? IndexOfTuple<[...Ar, 0]> | NegativeIndexOfTuple<Ar>
+    : SizeType.ArgArrWithNegative;
+
 // https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/length
 // https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/String/length
 // Max array length : 2^32 - 1
@@ -39,3 +46,86 @@ declare namespace SizeType {
   >;
   type ArgStrPositive = WithSmallInt<IntersectBrand<PositiveNumber, Str>>;
 }
+
+// #region Optional
+/**
+ * Represents the 'Some' variant of an {@link Optional}, containing a value.
+ *
+ * @template S The type of the contained value.
+ */
+type Some<S> = Readonly<{
+  /** @internal Discriminant property for the 'Some' type. */
+  $$tag: 'ts-data-forge::Optional.some';
+
+  /** The contained value. */
+  value: S;
+}>;
+
+/**
+ * Represents the 'None' variant of an {@link Optional}, indicating the absence
+ * of a value.
+ */
+type None = Readonly<{
+  /** @internal Discriminant property for the 'None' type. */
+  $$tag: 'ts-data-forge::Optional.none';
+}>;
+
+/**
+ * Represents an optional value that can either be `Some` (containing a value)
+ * or `None` (empty).
+ *
+ * @template S The type of the value that might be present.
+ */
+type Optional<S> = None | Some<S>;
+
+/**
+ * Base type for any {@link Optional}, used for generic constraints. Represents
+ * an {@link Optional} with an unknown value type.
+ */
+type UnknownOptional = Optional<unknown>;
+
+// #endregion
+
+// #region Result
+
+/**
+ * Represents a `Result` that is a success, containing a value.
+ *
+ * @template S The type of the success value.
+ */
+type Ok<S> = Readonly<{
+  /** @internal Discriminant property for the 'Ok' type. */
+  $$tag: 'ts-data-forge::Result.ok';
+
+  /** The success value. */
+  value: S;
+}>;
+
+/**
+ * Represents a `Result` that is an error, containing an error value.
+ *
+ * @template E The type of the error value.
+ */
+type Err<E> = Readonly<{
+  /** @internal Discriminant property for the 'Err' type. */
+  $$tag: 'ts-data-forge::Result.err';
+
+  /** The error value. */
+  value: E;
+}>;
+
+/**
+ * Represents a value that can either be a success (`Ok`) or an error (`Err`).
+ *
+ * @template S The type of the success value.
+ * @template E The type of the error value.
+ */
+type Result<S, E> = Ok<S> | Err<E>;
+
+/**
+ * Base type for any `Result`, used for generic constraints. Represents a
+ * `Result` with unknown success and error types.
+ */
+type UnknownResult = Result<unknown, unknown>;
+
+// #endregion

package/dist/guard/has-key.d.mts

@@ -1,91 +1,40 @@
 /**
- * Type guard function that checks if an object has a specific key as its own property.
+ * Type guard function that checks if an object has a specific key as its own
+ * property.
  *
- * This function uses `Object.hasOwn()` to check if the given object has the specified key
- * as its own property (not inherited). It acts as a type guard that narrows the type of the
- * object to guarantee the key exists, enabling type-safe property access.
+ * This function uses `Object.hasOwn()` to check if the given object has the
+ * specified key as its own property (not inherited). It acts as a type guard
+ * that narrows the type of the object to guarantee the key exists, enabling
+ * type-safe property access.
  *
  * **Type Narrowing Behavior:**
- * - When the guard returns `true`, TypeScript narrows the object type to include the checked key
+ *
+ * - When the guard returns `true`, TypeScript narrows the object type to include
+ *   the checked key
  * - For union types, only union members that contain the key are preserved
  * - The key's value type is preserved from the original object type when possible
  *
- * @template R - The type of the input object, must extend UnknownRecord
- * @template K - The type of the key to check for, must extend PropertyKey (string | number | symbol)
- * @param obj - The object to check for the presence of the key
- * @param key - The key to check for in the object
- * @returns `true` if the object has the specified key as its own property, `false` otherwise.
- *          When `true`, TypeScript narrows the object type to guarantee the key exists.
- *
  * @example
- * Basic usage with known object structure:
- * ```typescript
- * const obj = { a: 1, b: 'hello' };
- *
- * if (hasKey(obj, 'a')) {
- *   // obj is narrowed to guarantee 'a' exists
- *   console.log(obj.a); // TypeScript knows 'a' exists and is type number
- *   // No need for optional chaining or undefined checks
- * }
  *
- * if (hasKey(obj, 'c')) {
- *   // This block won't execute at runtime
- *   console.log(obj.c); // But TypeScript would know 'c' exists if it did
- * }
- * ```
- *
- * @example
- * Working with dynamic objects and unknown keys:
- * ```typescript
- * const dynamicObj: Record<string, unknown> = { x: 10, y: 20 };
- * const userInput: string = getUserInput();
+ * ```ts
+ * const maybeUser: { id?: number; name?: string } = { id: 42 };
  *
- * if (hasKey(dynamicObj, userInput)) {
- *   // Safe to access the dynamic key
- *   const value = dynamicObj[userInput]; // Type: unknown
- *   console.log(`Value for ${userInput}:`, value);
+ * if (hasKey(maybeUser, 'id')) {
+ *   // `maybeUser` is now known to have an `id` property.
+ *   assert(maybeUser.id === 42);
  * } else {
- *   console.log(`Key '${userInput}' not found`);
- * }
- * ```
- *
- * @example
- * Type narrowing with union types:
- * ```typescript
- * type UserPreferences =
- *   | { theme: 'dark'; notifications: boolean }
- *   | { theme: 'light' }
- *   | { autoSave: true; interval: number };
- *
- * const preferences: UserPreferences = getPreferences();
- *
- * if (hasKey(preferences, 'theme')) {
- *   // preferences is narrowed to the first two union members
- *   console.log(preferences.theme); // 'dark' | 'light'
- * }
- *
- * if (hasKey(preferences, 'autoSave')) {
- *   // preferences is narrowed to the third union member
- *   console.log(preferences.interval); // number (we know this exists)
- * }
- * ```
- *
- * @example
- * Basic usage with isRecord for progressive narrowing:
- * ```typescript
- * const data: unknown = parseApiResponse();
- *
- * if (isRecord(data) && hasKey(data, 'user')) {
- *   // data is now Record<string, unknown> with guaranteed 'user' key
- *   const user = data.user;
- *
- *   if (isRecord(user) && hasKey(user, 'name')) {
- *     // Safely access nested properties
- *     console.log('User name:', user.name);
- *   }
+ *   assert.fail('Expected the object to contain the id key.');
  * }
  * ```
  *
+ * @template R - The type of the input object, must extend UnknownRecord
+ * @template K - The type of the key to check for, must extend PropertyKey
+ *   (string | number | symbol)
+ * @param obj - The object to check for the presence of the key
+ * @param key - The key to check for in the object
+ * @returns `true` if the object has the specified key as its own property,
+ *   `false` otherwise. When `true`, TypeScript narrows the object type to
+ *   guarantee the key exists.
  * @see {@link keyIsIn} - Similar function that narrows the key type instead of the object type
  */
 export declare const hasKey: <const R extends UnknownRecord, const K extends PropertyKey>(obj: R, key: K) => obj is HasKeyReturnType<R, K>;

package/dist/guard/has-key.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"has-key.d.mts","sourceRoot":"","sources":["../../src/guard/has-key.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AACH,eAAO,MAAM,MAAM,GACjB,KAAK,CAAC,CAAC,SAAS,aAAa,EAC7B,KAAK,CAAC,CAAC,SAAS,WAAW,EAE3B,KAAK,CAAC,EACN,KAAK,CAAC,KACL,GAAG,IAAI,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAA4B,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,WAAW,IACnB,CAAC,SAAS,CAAC,GACX,CAAC,SAAS,MAAM,CAAC,GACf,MAAM,SAAS,MAAM,CAAC,GACpB,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GACjC,MAAM,SAAS,MAAM,CAAC,GACpB,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GACjC,MAAM,SAAS,MAAM,CAAC,GACpB,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GACjC,CAAC,GACP,KAAK,GACP,KAAK,CAAC"}
+{"version":3,"file":"has-key.d.mts","sourceRoot":"","sources":["../../src/guard/has-key.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,MAAM,GACjB,KAAK,CAAC,CAAC,SAAS,aAAa,EAC7B,KAAK,CAAC,CAAC,SAAS,WAAW,EAE3B,KAAK,CAAC,EACN,KAAK,CAAC,KACL,GAAG,IAAI,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAA4B,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,aAAa,EACvB,CAAC,SAAS,WAAW,IACnB,CAAC,SAAS,CAAC,GACX,CAAC,SAAS,MAAM,CAAC,GACf,MAAM,SAAS,MAAM,CAAC,GACpB,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GACjC,MAAM,SAAS,MAAM,CAAC,GACpB,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GACjC,MAAM,SAAS,MAAM,CAAC,GACpB,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GACjC,CAAC,GACP,KAAK,GACP,KAAK,CAAC"}