effect 4.0.0-beta.70 → 4.0.0-beta.71

package/dist/UndefinedOr.d.ts

@@ -1,29 +1,59 @@
 /**
- * This module provides small, allocation-free utilities for working with values of type
- * `A | undefined`, where `undefined` means "no value".
- *
- * Why not `Option<A>`?
- * In TypeScript, `Option<A>` is often unnecessary. If `undefined` already models absence
- * in your domain, using `A | undefined` keeps types simple, avoids extra wrappers, and
- * reduces overhead. The key is that `A` itself must not include `undefined`; in this
- * module `undefined` is reserved to mean "no value".
- *
- * When to use `A | undefined`:
- * - Absence can be represented by `undefined` in your domain model.
- * - You do not need to distinguish between "no value" and "value is undefined".
- * - You want straightforward ergonomics and zero extra allocations.
- *
- * When to prefer `Option<A>`:
- * - You must distinguish `None` from `Some(undefined)` (that is, `undefined` is a valid
- *   payload and carries meaning on its own).
- * - You need a tagged representation for serialization or pattern matching across
- *   boundaries where `undefined` would be ambiguous.
- * - You want the richer `Option` API and are comfortable with the extra wrapper.
- *
- * Lawfulness note:
- * All helpers treat `undefined` as absence. Do not use these utilities with payloads
- * where `A` can itself be `undefined`, or you will lose information. If you need to
- * carry `undefined` as a valid payload, use `Option<A>` instead.
+ * The `UndefinedOr` module works with plain TypeScript values of type
+ * `A | undefined` where `undefined` is the only absence marker. It is a small
+ * alternative to wrapping values in `Option` when your domain already uses
+ * `undefined` to mean "no value".
+ *
+ * **Mental model**
+ *
+ * - A defined value is the present branch.
+ * - `undefined` is reserved for absence; the payload type `A` should not itself
+ *   include `undefined`.
+ * - Helpers such as {@link map} and {@link match} keep values unwrapped and use
+ *   `undefined` directly instead of allocating tagged values.
+ * - The fail-fast combiner and reducer helpers propagate `undefined` when a
+ *   required value is missing.
+ *
+ * **Common tasks**
+ *
+ * - Transform a present value: {@link map}
+ * - Branch on present versus absent: {@link match}
+ * - Unwrap at a boundary: {@link getOrThrow}, {@link getOrThrowWith}
+ * - Adapt throwing code to an optional result: {@link liftThrowable}
+ * - Lift combination and reduction logic: {@link makeReducer},
+ *   {@link makeCombinerFailFast}, {@link makeReducerFailFast}
+ *
+ * **Gotchas**
+ *
+ * - `A | undefined` cannot distinguish "missing" from "present and
+ *   undefined". Use `Option` when that distinction matters.
+ * - {@link liftThrowable} discards the thrown value and also returns
+ *   `undefined` when the wrapped function throws.
+ *
+ * **Example** (Parsing optional input)
+ *
+ * ```ts
+ * import { UndefinedOr } from "effect"
+ *
+ * const parseInteger = UndefinedOr.liftThrowable((input: string) => {
+ *   const value = Number.parseInt(input, 10)
+ *   if (Number.isNaN(value)) {
+ *     throw new Error("not an integer")
+ *   }
+ *   return value
+ * })
+ *
+ * console.log(UndefinedOr.map(parseInteger("42"), (n) => n + 1))
+ * // 43
+ *
+ * console.log(
+ *   UndefinedOr.match(parseInteger("abc"), {
+ *     onUndefined: () => "missing",
+ *     onDefined: (n) => `parsed ${n}`
+ *   })
+ * )
+ * // "missing"
+ * ```
  *
  * @since 4.0.0
  */
@@ -33,6 +63,13 @@ import * as Reducer from "./Reducer.ts";
 /**
  * Maps a defined value with `f`, or returns `undefined` unchanged.
  *
+ * **When to use**
+ *
+ * Use to apply a pure transformation to an `A | undefined` value while
+ * preserving `undefined` as absence.
+ *
+ * @see {@link match} when you need to handle the `undefined` case explicitly
+ *
  * @category mapping
  * @since 4.0.0
  */
@@ -40,6 +77,13 @@ export declare const map: {
     /**
      * Maps a defined value with `f`, or returns `undefined` unchanged.
      *
+     * **When to use**
+     *
+     * Use to apply a pure transformation to an `A | undefined` value while
+     * preserving `undefined` as absence.
+     *
+     * @see {@link match} when you need to handle the `undefined` case explicitly
+     *
      * @category mapping
      * @since 4.0.0
      */
@@ -47,6 +91,13 @@ export declare const map: {
     /**
      * Maps a defined value with `f`, or returns `undefined` unchanged.
      *
+     * **When to use**
+     *
+     * Use to apply a pure transformation to an `A | undefined` value while
+     * preserving `undefined` as absence.
+     *
+     * @see {@link match} when you need to handle the `undefined` case explicitly
+     *
      * @category mapping
      * @since 4.0.0
      */
@@ -56,6 +107,14 @@ export declare const map: {
  * Pattern matches on an `A | undefined` value, running `onDefined` when the
  * value is present or evaluating `onUndefined` when the value is `undefined`.
  *
+ * **When to use**
+ *
+ * Use when you need to turn an `A | undefined` into a non-optional result by
+ * handling both the defined and undefined branches in one expression.
+ *
+ * @see {@link map} for transforming defined values while preserving `undefined`
+ * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
+ *
  * @category pattern matching
  * @since 4.0.0
  */
@@ -64,6 +123,14 @@ export declare const match: {
      * Pattern matches on an `A | undefined` value, running `onDefined` when the
      * value is present or evaluating `onUndefined` when the value is `undefined`.
      *
+     * **When to use**
+     *
+     * Use when you need to turn an `A | undefined` into a non-optional result by
+     * handling both the defined and undefined branches in one expression.
+     *
+     * @see {@link map} for transforming defined values while preserving `undefined`
+     * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
+     *
      * @category pattern matching
      * @since 4.0.0
      */
@@ -75,6 +142,14 @@ export declare const match: {
      * Pattern matches on an `A | undefined` value, running `onDefined` when the
      * value is present or evaluating `onUndefined` when the value is `undefined`.
      *
+     * **When to use**
+     *
+     * Use when you need to turn an `A | undefined` into a non-optional result by
+     * handling both the defined and undefined branches in one expression.
+     *
+     * @see {@link map} for transforming defined values while preserving `undefined`
+     * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
+     *
      * @category pattern matching
      * @since 4.0.0
      */
@@ -87,6 +162,19 @@ export declare const match: {
  * Returns the defined value, or throws the value produced by `onUndefined`
  * when the input is `undefined`.
  *
+ * **When to use**
+ *
+ * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
+ * callers need to provide the thrown error for the undefined case.
+ *
+ * **Details**
+ *
+ * Defined values are returned unchanged. When the input is `undefined`,
+ * `onUndefined` is called and its result is thrown.
+ *
+ * @see {@link getOrThrow} for the default-error sibling
+ * @see {@link match} for handling defined and undefined cases without throwing
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -95,6 +183,19 @@ export declare const getOrThrowWith: {
      * Returns the defined value, or throws the value produced by `onUndefined`
      * when the input is `undefined`.
      *
+     * **When to use**
+     *
+     * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
+     * callers need to provide the thrown error for the undefined case.
+     *
+     * **Details**
+     *
+     * Defined values are returned unchanged. When the input is `undefined`,
+     * `onUndefined` is called and its result is thrown.
+     *
+     * @see {@link getOrThrow} for the default-error sibling
+     * @see {@link match} for handling defined and undefined cases without throwing
+     *
      * @category getters
      * @since 4.0.0
      */
@@ -103,6 +204,19 @@ export declare const getOrThrowWith: {
      * Returns the defined value, or throws the value produced by `onUndefined`
      * when the input is `undefined`.
      *
+     * **When to use**
+     *
+     * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
+     * callers need to provide the thrown error for the undefined case.
+     *
+     * **Details**
+     *
+     * Defined values are returned unchanged. When the input is `undefined`,
+     * `onUndefined` is called and its result is thrown.
+     *
+     * @see {@link getOrThrow} for the default-error sibling
+     * @see {@link match} for handling defined and undefined cases without throwing
+     *
      * @category getters
      * @since 4.0.0
      */
@@ -112,6 +226,19 @@ export declare const getOrThrowWith: {
  * Returns the defined value, or throws a default `Error` when the input is
  * `undefined`.
  *
+ * **When to use**
+ *
+ * Use when a value should already be defined at this point and throwing a
+ * generic missing-value `Error` is acceptable.
+ *
+ * **Details**
+ *
+ * Defined inputs are returned unchanged. `undefined` throws
+ * `new Error("getOrThrow called on a undefined")`.
+ *
+ * @see {@link getOrThrowWith} for the sibling that lets callers choose the thrown value
+ * @see {@link match} for handling defined and undefined cases without throwing
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -120,6 +247,16 @@ export declare const getOrThrow: <A>(self: A | undefined) => A;
  * Converts a throwing function into one that returns successful results
  * unchanged and returns `undefined` when the function throws.
  *
+ * **When to use**
+ *
+ * Use to adapt exception-throwing functions when `undefined` is the absence
+ * value you want to return for failures.
+ *
+ * **Gotchas**
+ *
+ * Thrown values are discarded. If the wrapped function can successfully return
+ * `undefined`, that success is indistinguishable from a thrown failure.
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -130,9 +267,8 @@ export declare const liftThrowable: <A extends ReadonlyArray<unknown>, B>(f: (..
  *
  * **When to use**
  *
- * - Take the first available value (like a fallback chain)
- * - Combine values when both are present
- * - Maintain a `undefined` state only when all values are `undefined`
+ * Use to take the first available value like a fallback chain, combining values
+ * only when both operands are present.
  *
  * **Details**
  *
@@ -150,6 +286,11 @@ export declare function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.
  * Creates a `Combiner` for `A | undefined` that combines values only when both
  * operands are defined.
  *
+ * **When to use**
+ *
+ * Use to lift a `Combiner` so any `undefined` operand makes the combined result
+ * `undefined`.
+ *
  * **Details**
  *
  * - `undefined` combined with any value returns `undefined`
@@ -169,8 +310,8 @@ export declare function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>):
  *
  * **When to use**
  *
- * - Wrapping an existing `Reducer` to work with `A | undefined` values
- * - Reductions where any `undefined` value should abort the entire result
+ * Use to wrap an existing `Reducer` so any `undefined` value aborts the entire
+ * reduction result.
  *
  * **Details**
  *

package/dist/UndefinedOr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UndefinedOr.d.ts","sourceRoot":"","sources":["../src/UndefinedOr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE5C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,GAAG,EAAE;IAChB;;;;;OAKG;IACH,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,SAAS,CAAA;IAC9D;;;;;OAKG;IACH,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAA;CACQ,CAAA;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE;IAClB;;;;;;OAMG;IACH,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EACV,OAAO,EAAE;QACP,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;QAChC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;KAChC,GACA,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,CAAC,CAAA;IACjC;;;;;;OAMG;IACH,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EACV,IAAI,EAAE,CAAC,GAAG,SAAS,EACnB,OAAO,EAAE;QACP,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;QAChC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;KAChC,GACA,CAAC,GAAG,CAAC,CAAA;CAOT,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE;IAC3B;;;;;;OAMG;IACH,CAAC,WAAW,EAAE,MAAM,OAAO,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,CAAA;IAC3D;;;;;;OAMG;IACH,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,GAAG,CAAC,CAAA;CAMvD,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,KAAK,CAEpD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,EAC/D,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,KAChB,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,SAOnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAM7F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,GAAG,SAAS,CAAC,CAKxG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAWlG"}
+{"version":3,"file":"UndefinedOr.d.ts","sourceRoot":"","sources":["../src/UndefinedOr.ts"],"names":[],"mappings":"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"}

package/dist/UndefinedOr.js

@@ -1,29 +1,59 @@
 /**
- * This module provides small, allocation-free utilities for working with values of type
- * `A | undefined`, where `undefined` means "no value".
- *
- * Why not `Option<A>`?
- * In TypeScript, `Option<A>` is often unnecessary. If `undefined` already models absence
- * in your domain, using `A | undefined` keeps types simple, avoids extra wrappers, and
- * reduces overhead. The key is that `A` itself must not include `undefined`; in this
- * module `undefined` is reserved to mean "no value".
- *
- * When to use `A | undefined`:
- * - Absence can be represented by `undefined` in your domain model.
- * - You do not need to distinguish between "no value" and "value is undefined".
- * - You want straightforward ergonomics and zero extra allocations.
- *
- * When to prefer `Option<A>`:
- * - You must distinguish `None` from `Some(undefined)` (that is, `undefined` is a valid
- *   payload and carries meaning on its own).
- * - You need a tagged representation for serialization or pattern matching across
- *   boundaries where `undefined` would be ambiguous.
- * - You want the richer `Option` API and are comfortable with the extra wrapper.
- *
- * Lawfulness note:
- * All helpers treat `undefined` as absence. Do not use these utilities with payloads
- * where `A` can itself be `undefined`, or you will lose information. If you need to
- * carry `undefined` as a valid payload, use `Option<A>` instead.
+ * The `UndefinedOr` module works with plain TypeScript values of type
+ * `A | undefined` where `undefined` is the only absence marker. It is a small
+ * alternative to wrapping values in `Option` when your domain already uses
+ * `undefined` to mean "no value".
+ *
+ * **Mental model**
+ *
+ * - A defined value is the present branch.
+ * - `undefined` is reserved for absence; the payload type `A` should not itself
+ *   include `undefined`.
+ * - Helpers such as {@link map} and {@link match} keep values unwrapped and use
+ *   `undefined` directly instead of allocating tagged values.
+ * - The fail-fast combiner and reducer helpers propagate `undefined` when a
+ *   required value is missing.
+ *
+ * **Common tasks**
+ *
+ * - Transform a present value: {@link map}
+ * - Branch on present versus absent: {@link match}
+ * - Unwrap at a boundary: {@link getOrThrow}, {@link getOrThrowWith}
+ * - Adapt throwing code to an optional result: {@link liftThrowable}
+ * - Lift combination and reduction logic: {@link makeReducer},
+ *   {@link makeCombinerFailFast}, {@link makeReducerFailFast}
+ *
+ * **Gotchas**
+ *
+ * - `A | undefined` cannot distinguish "missing" from "present and
+ *   undefined". Use `Option` when that distinction matters.
+ * - {@link liftThrowable} discards the thrown value and also returns
+ *   `undefined` when the wrapped function throws.
+ *
+ * **Example** (Parsing optional input)
+ *
+ * ```ts
+ * import { UndefinedOr } from "effect"
+ *
+ * const parseInteger = UndefinedOr.liftThrowable((input: string) => {
+ *   const value = Number.parseInt(input, 10)
+ *   if (Number.isNaN(value)) {
+ *     throw new Error("not an integer")
+ *   }
+ *   return value
+ * })
+ *
+ * console.log(UndefinedOr.map(parseInteger("42"), (n) => n + 1))
+ * // 43
+ *
+ * console.log(
+ *   UndefinedOr.match(parseInteger("abc"), {
+ *     onUndefined: () => "missing",
+ *     onDefined: (n) => `parsed ${n}`
+ *   })
+ * )
+ * // "missing"
+ * ```
  *
  * @since 4.0.0
  */
@@ -33,6 +63,13 @@ import * as Reducer from "./Reducer.js";
 /**
  * Maps a defined value with `f`, or returns `undefined` unchanged.
  *
+ * **When to use**
+ *
+ * Use to apply a pure transformation to an `A | undefined` value while
+ * preserving `undefined` as absence.
+ *
+ * @see {@link match} when you need to handle the `undefined` case explicitly
+ *
  * @category mapping
  * @since 4.0.0
  */
@@ -41,6 +78,14 @@ export const map = /*#__PURE__*/dual(2, (self, f) => self === undefined ? undefi
  * Pattern matches on an `A | undefined` value, running `onDefined` when the
  * value is present or evaluating `onUndefined` when the value is `undefined`.
  *
+ * **When to use**
+ *
+ * Use when you need to turn an `A | undefined` into a non-optional result by
+ * handling both the defined and undefined branches in one expression.
+ *
+ * @see {@link map} for transforming defined values while preserving `undefined`
+ * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
+ *
  * @category pattern matching
  * @since 4.0.0
  */
@@ -52,6 +97,19 @@ export const match = /*#__PURE__*/dual(2, (self, {
  * Returns the defined value, or throws the value produced by `onUndefined`
  * when the input is `undefined`.
  *
+ * **When to use**
+ *
+ * Use when fail-fast unwrapping of an `A | undefined` value is appropriate and
+ * callers need to provide the thrown error for the undefined case.
+ *
+ * **Details**
+ *
+ * Defined values are returned unchanged. When the input is `undefined`,
+ * `onUndefined` is called and its result is thrown.
+ *
+ * @see {@link getOrThrow} for the default-error sibling
+ * @see {@link match} for handling defined and undefined cases without throwing
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -65,6 +123,19 @@ export const getOrThrowWith = /*#__PURE__*/dual(2, (self, onUndefined) => {
  * Returns the defined value, or throws a default `Error` when the input is
  * `undefined`.
  *
+ * **When to use**
+ *
+ * Use when a value should already be defined at this point and throwing a
+ * generic missing-value `Error` is acceptable.
+ *
+ * **Details**
+ *
+ * Defined inputs are returned unchanged. `undefined` throws
+ * `new Error("getOrThrow called on a undefined")`.
+ *
+ * @see {@link getOrThrowWith} for the sibling that lets callers choose the thrown value
+ * @see {@link match} for handling defined and undefined cases without throwing
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -73,6 +144,16 @@ export const getOrThrow = /*#__PURE__*/getOrThrowWith(() => new Error("getOrThro
  * Converts a throwing function into one that returns successful results
  * unchanged and returns `undefined` when the function throws.
  *
+ * **When to use**
+ *
+ * Use to adapt exception-throwing functions when `undefined` is the absence
+ * value you want to return for failures.
+ *
+ * **Gotchas**
+ *
+ * Thrown values are discarded. If the wrapped function can successfully return
+ * `undefined`, that success is indistinguishable from a thrown failure.
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -89,9 +170,8 @@ export const liftThrowable = f => (...a) => {
  *
  * **When to use**
  *
- * - Take the first available value (like a fallback chain)
- * - Combine values when both are present
- * - Maintain a `undefined` state only when all values are `undefined`
+ * Use to take the first available value like a fallback chain, combining values
+ * only when both operands are present.
  *
  * **Details**
  *
@@ -115,6 +195,11 @@ export function makeReducer(combiner) {
  * Creates a `Combiner` for `A | undefined` that combines values only when both
  * operands are defined.
  *
+ * **When to use**
+ *
+ * Use to lift a `Combiner` so any `undefined` operand makes the combined result
+ * `undefined`.
+ *
  * **Details**
  *
  * - `undefined` combined with any value returns `undefined`
@@ -139,8 +224,8 @@ export function makeCombinerFailFast(combiner) {
  *
  * **When to use**
  *
- * - Wrapping an existing `Reducer` to work with `A | undefined` values
- * - Reductions where any `undefined` value should abort the entire result
+ * Use to wrap an existing `Reducer` so any `undefined` value aborts the entire
+ * reduction result.
  *
  * **Details**
  *

package/dist/UndefinedOr.js.map

@@ -1 +1 @@
-{"version":3,"file":"UndefinedOr.js","names":["Combiner","dual","Reducer","map","self","f","undefined","match","onDefined","onUndefined","getOrThrowWith","getOrThrow","Error","liftThrowable","a","makeReducer","combiner","make","that","combine","makeCombinerFailFast","makeReducerFailFast","reducer","initialValue","collection","out","value"],"sources":["../src/UndefinedOr.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,KAAKA,QAAQ,MAAM,eAAe;AAEzC,SAASC,IAAI,QAAQ,eAAe;AACpC,OAAO,KAAKC,OAAO,MAAM,cAAc;AAEvC;;;;;;AAMA,OAAO,MAAMC,GAAG,gBAeZF,IAAI,CAAC,CAAC,EAAE,CAACG,IAAI,EAAEC,CAAC,KAAMD,IAAI,KAAKE,SAAS,GAAGA,SAAS,GAAGD,CAAC,CAACD,IAAI,CAAE,CAAC;AAEpE;;;;;;;AAOA,OAAO,MAAMG,KAAK,gBA4BdN,IAAI,CACN,CAAC,EACD,CAAcG,IAAmB,EAAE;EAAEI,SAAS;EAAEC;AAAW,CAG1D,KAAYL,IAAI,KAAKE,SAAS,GAAGG,WAAW,EAAE,GAAGD,SAAS,CAACJ,IAAI,CAAC,CAClE;AAED;;;;;;;AAOA,OAAO,MAAMM,cAAc,gBAiBvBT,IAAI,CAAC,CAAC,EAAE,CAAIG,IAAmB,EAAEK,WAA0B,KAAO;EACpE,IAAIL,IAAI,KAAKE,SAAS,EAAE;IACtB,OAAOF,IAAI;EACb;EACA,MAAMK,WAAW,EAAE;AACrB,CAAC,CAAC;AAEF;;;;;;;AAOA,OAAO,MAAME,UAAU,gBAAkCD,cAAc,CAAC,MACtE,IAAIE,KAAK,CAAC,kCAAkC,CAAC,CAC9C;AAED;;;;;;;AAOA,OAAO,MAAMC,aAAa,GACxBR,CAAiB,IAEnB,CAAC,GAAGS,CAAC,KAAI;EACP,IAAI;IACF,OAAOT,CAAC,CAAC,GAAGS,CAAC,CAAC;EAChB,CAAC,CAAC,MAAM;IACN,OAAOR,SAAS;EAClB;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAM,SAAUS,WAAWA,CAAIC,QAA8B;EAC3D,OAAOd,OAAO,CAACe,IAAI,CAAC,CAACb,IAAI,EAAEc,IAAI,KAAI;IACjC,IAAId,IAAI,KAAKE,SAAS,EAAE,OAAOY,IAAI;IACnC,IAAIA,IAAI,KAAKZ,SAAS,EAAE,OAAOF,IAAI;IACnC,OAAOY,QAAQ,CAACG,OAAO,CAACf,IAAI,EAAEc,IAAI,CAAC;EACrC,CAAC,EAAEZ,SAA0B,CAAC;AAChC;AAEA;;;;;;;;;;;;;;;;AAgBA,OAAM,SAAUc,oBAAoBA,CAAIJ,QAA8B;EACpE,OAAOhB,QAAQ,CAACiB,IAAI,CAAC,CAACb,IAAI,EAAEc,IAAI,KAAI;IAClC,IAAId,IAAI,KAAKE,SAAS,IAAIY,IAAI,KAAKZ,SAAS,EAAE,OAAOA,SAAS;IAC9D,OAAOU,QAAQ,CAACG,OAAO,CAACf,IAAI,EAAEc,IAAI,CAAC;EACrC,CAAC,CAAC;AACJ;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAM,SAAUG,mBAAmBA,CAAIC,OAA2B;EAChE,MAAMH,OAAO,GAAGC,oBAAoB,CAACE,OAAO,CAAC,CAACH,OAAO;EACrD,MAAMI,YAAY,GAAGD,OAAO,CAACC,YAA6B;EAC1D,OAAOrB,OAAO,CAACe,IAAI,CAACE,OAAO,EAAEI,YAAY,EAAGC,UAAU,IAAI;IACxD,IAAIC,GAAG,GAAGF,YAAY;IACtB,KAAK,MAAMG,KAAK,IAAIF,UAAU,EAAE;MAC9BC,GAAG,GAAGN,OAAO,CAACM,GAAG,EAAEC,KAAK,CAAC;MACzB,IAAID,GAAG,KAAKnB,SAAS,EAAE,OAAOmB,GAAG;IACnC;IACA,OAAOA,GAAG;EACZ,CAAC,CAAC;AACJ","ignoreList":[]}
+{"version":3,"file":"UndefinedOr.js","names":["Combiner","dual","Reducer","map","self","f","undefined","match","onDefined","onUndefined","getOrThrowWith","getOrThrow","Error","liftThrowable","a","makeReducer","combiner","make","that","combine","makeCombinerFailFast","makeReducerFailFast","reducer","initialValue","collection","out","value"],"sources":["../src/UndefinedOr.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,OAAO,KAAKA,QAAQ,MAAM,eAAe;AAEzC,SAASC,IAAI,QAAQ,eAAe;AACpC,OAAO,KAAKC,OAAO,MAAM,cAAc;AAEvC;;;;;;;;;;;;;AAaA,OAAO,MAAMC,GAAG,gBA6BZF,IAAI,CAAC,CAAC,EAAE,CAACG,IAAI,EAAEC,CAAC,KAAMD,IAAI,KAAKE,SAAS,GAAGA,SAAS,GAAGD,CAAC,CAACD,IAAI,CAAE,CAAC;AAEpE;;;;;;;;;;;;;;;AAeA,OAAO,MAAMG,KAAK,gBA4CdN,IAAI,CACN,CAAC,EACD,CAAcG,IAAmB,EAAE;EAAEI,SAAS;EAAEC;AAAW,CAG1D,KAAYL,IAAI,KAAKE,SAAS,GAAGG,WAAW,EAAE,GAAGD,SAAS,CAACJ,IAAI,CAAC,CAClE;AAED;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMM,cAAc,gBA2CvBT,IAAI,CAAC,CAAC,EAAE,CAAIG,IAAmB,EAAEK,WAA0B,KAAO;EACpE,IAAIL,IAAI,KAAKE,SAAS,EAAE;IACtB,OAAOF,IAAI;EACb;EACA,MAAMK,WAAW,EAAE;AACrB,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAME,UAAU,gBAAkCD,cAAc,CAAC,MACtE,IAAIE,KAAK,CAAC,kCAAkC,CAAC,CAC9C;AAED;;;;;;;;;;;;;;;;;AAiBA,OAAO,MAAMC,aAAa,GACxBR,CAAiB,IAEnB,CAAC,GAAGS,CAAC,KAAI;EACP,IAAI;IACF,OAAOT,CAAC,CAAC,GAAGS,CAAC,CAAC;EAChB,CAAC,CAAC,MAAM;IACN,OAAOR,SAAS;EAClB;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;AAoBA,OAAM,SAAUS,WAAWA,CAAIC,QAA8B;EAC3D,OAAOd,OAAO,CAACe,IAAI,CAAC,CAACb,IAAI,EAAEc,IAAI,KAAI;IACjC,IAAId,IAAI,KAAKE,SAAS,EAAE,OAAOY,IAAI;IACnC,IAAIA,IAAI,KAAKZ,SAAS,EAAE,OAAOF,IAAI;IACnC,OAAOY,QAAQ,CAACG,OAAO,CAACf,IAAI,EAAEc,IAAI,CAAC;EACrC,CAAC,EAAEZ,SAA0B,CAAC;AAChC;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAM,SAAUc,oBAAoBA,CAAIJ,QAA8B;EACpE,OAAOhB,QAAQ,CAACiB,IAAI,CAAC,CAACb,IAAI,EAAEc,IAAI,KAAI;IAClC,IAAId,IAAI,KAAKE,SAAS,IAAIY,IAAI,KAAKZ,SAAS,EAAE,OAAOA,SAAS;IAC9D,OAAOU,QAAQ,CAACG,OAAO,CAACf,IAAI,EAAEc,IAAI,CAAC;EACrC,CAAC,CAAC;AACJ;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAM,SAAUG,mBAAmBA,CAAIC,OAA2B;EAChE,MAAMH,OAAO,GAAGC,oBAAoB,CAACE,OAAO,CAAC,CAACH,OAAO;EACrD,MAAMI,YAAY,GAAGD,OAAO,CAACC,YAA6B;EAC1D,OAAOrB,OAAO,CAACe,IAAI,CAACE,OAAO,EAAEI,YAAY,EAAGC,UAAU,IAAI;IACxD,IAAIC,GAAG,GAAGF,YAAY;IACtB,KAAK,MAAMG,KAAK,IAAIF,UAAU,EAAE;MAC9BC,GAAG,GAAGN,OAAO,CAACM,GAAG,EAAEC,KAAK,CAAC;MACzB,IAAID,GAAG,KAAKnB,SAAS,EAAE,OAAOmB,GAAG;IACnC;IACA,OAAOA,GAAG;EACZ,CAAC,CAAC;AACJ","ignoreList":[]}