@nunofyobiz/effect-extras 2.0.0 → 3.0.0

package/dist/WarnResult.js

@@ -0,0 +1,991 @@
+/**
+ * The `WarnResult` data type — a result that may carry a success value and/or
+ * warnings, where both sides are optional but never both absent.
+ *
+ * @since 0.0.0
+ */
+import { Data, Effect, Option, pipe } from "effect";
+import { dual } from "effect/Function";
+import * as InclusiveOr from "./InclusiveOr.js";
+const taggedEnum = /*#__PURE__*/Data.taggedEnum();
+/**
+ * Constructs a `WarningsOnly` — a `WarnResult` that carries only `warnings`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const value = WarnResult.WarningsOnly({ warnings: "skipped 2 rows" })
+ *
+ * assert.deepStrictEqual(value._tag, "WarningsOnly")
+ * assert.deepStrictEqual(value.warnings, "skipped 2 rows")
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const WarningsOnly = taggedEnum.WarningsOnly;
+/**
+ * Constructs a `SuccessOnly` — a `WarnResult` that carries only a `success` value.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const value = WarnResult.SuccessOnly({ success: 1 })
+ *
+ * assert.deepStrictEqual(value._tag, "SuccessOnly")
+ * assert.deepStrictEqual(value.success, 1)
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const SuccessOnly = taggedEnum.SuccessOnly;
+/**
+ * Constructs a `SuccessWithWarnings` — a `WarnResult` that carries both a
+ * `success` value and `warnings`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const value = WarnResult.SuccessWithWarnings({
+ *   warnings: "rounded down",
+ *   success: 1
+ * })
+ *
+ * assert.deepStrictEqual(value._tag, "SuccessWithWarnings")
+ * assert.deepStrictEqual(value.warnings, "rounded down")
+ * assert.deepStrictEqual(value.success, 1)
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const SuccessWithWarnings = taggedEnum.SuccessWithWarnings;
+/**
+ * Builds per-tag refinements for `WarnResult`. `is("WarningsOnly")` is a type
+ * guard that narrows a `WarnResult` to its `WarningsOnly` member, and likewise for
+ * `"SuccessOnly"` and `"SuccessWithWarnings"`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.is("WarningsOnly")(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   true
+ * )
+ * assert.deepStrictEqual(
+ *   WarnResult.is("WarningsOnly")(WarnResult.SuccessOnly({ success: 1 })),
+ *   false
+ * )
+ * ```
+ *
+ * @category guards
+ * @since 0.0.0
+ */
+export const is = taggedEnum.$is;
+/**
+ * Folds a `WarnResult` over its three tags. Provide a handler for `WarningsOnly`,
+ * `SuccessOnly`, and `SuccessWithWarnings` and `match` returns a function from a
+ * `WarnResult` to the handlers' common result type.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const describe = WarnResult.match({
+ *   WarningsOnly: ({ warnings }) => `warnings ${warnings}`,
+ *   SuccessOnly: ({ success }) => `success ${success}`,
+ *   SuccessWithWarnings: ({ warnings, success }) => `both ${warnings}/${success}`
+ * })
+ *
+ * assert.deepStrictEqual(
+ *   describe(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })),
+ *   "both w/1"
+ * )
+ * ```
+ *
+ * @category pattern matching
+ * @since 0.0.0
+ */
+export const match = taggedEnum.$match;
+/**
+ * Relabels a `WarnResult` as the equivalent terminology-free `InclusiveOr`,
+ * mapping `warnings` to `left` and `success` to `right`. The inverse of
+ * `fromInclusiveOr`.
+ *
+ * `WarnResult` is the use-case-driven (`warnings`/`success`) face of the generic
+ * `InclusiveOr` (`left`/`right`); every derived `WarnResult` operation is just this
+ * relabeling around the corresponding `InclusiveOr` operation, so all the logic
+ * lives in `InclusiveOr` and is never duplicated here.
+ */
+const toInclusiveOr = warnResult => match(warnResult, {
+  WarningsOnly: ({
+    warnings
+  }) => InclusiveOr.LeftOnly({
+    left: warnings
+  }),
+  SuccessOnly: ({
+    success
+  }) => InclusiveOr.RightOnly({
+    right: success
+  }),
+  SuccessWithWarnings: ({
+    warnings,
+    success
+  }) => InclusiveOr.LeftAndRight({
+    left: warnings,
+    right: success
+  })
+});
+function fromInclusiveOr(io) {
+  return InclusiveOr.match(io, {
+    LeftOnly: ({
+      left
+    }) => WarningsOnly({
+      warnings: left
+    }),
+    RightOnly: ({
+      right
+    }) => SuccessOnly({
+      success: right
+    }),
+    LeftAndRight: ({
+      left,
+      right
+    }) => SuccessWithWarnings({
+      warnings: left,
+      success: right
+    })
+  });
+}
+/**
+ * Builds a `WarnResult` known to carry `warnings`, choosing `SuccessWithWarnings`
+ * when a `success` value is present and `WarningsOnly` otherwise.
+ *
+ * Use it when the `warnings` are mandatory and the `success` value is an optional
+ * companion: pass an absent (`null`/`undefined`) `success` to get a
+ * `WarningsOnly`, or a present one to get a `SuccessWithWarnings`. The return type
+ * `WithWarnings<A, W>` reflects that `warnings` are always present.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.WithWarnings({ warnings: "w", success: 1 }),
+ *   WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.WithWarnings({ warnings: "w" }),
+ *   WarnResult.WarningsOnly({ warnings: "w" })
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const WithWarnings = ({
+  warnings,
+  success
+}) => fromInclusiveOr(InclusiveOr.WithLeft({
+  left: warnings,
+  right: success
+}));
+/**
+ * Builds a `WarnResult` known to carry a `success` value, choosing
+ * `SuccessWithWarnings` when `warnings` are present and `SuccessOnly` otherwise.
+ *
+ * The mirror of `WithWarnings`: the `success` value is mandatory and the
+ * `warnings` are an optional companion. Pass absent (`null`/`undefined`)
+ * `warnings` to get a `SuccessOnly`, or present ones to get a
+ * `SuccessWithWarnings`. The return type `WithSuccess<A, W>` reflects that a
+ * `success` value is always present.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.WithSuccess({ warnings: "w", success: 1 }),
+ *   WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.WithSuccess({ success: 1 }),
+ *   WarnResult.SuccessOnly({ success: 1 })
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const WithSuccess = ({
+  warnings,
+  success
+}) => fromInclusiveOr(InclusiveOr.WithRight({
+  left: warnings,
+  right: success
+}));
+/**
+ * Builds a `WarnResult` from a pair of possibly-nullish inputs, wrapping the
+ * result in an `Option` so the all-absent case is expressible.
+ *
+ * Returns `Option.some(SuccessWithWarnings)` when both are present,
+ * `Option.some(WarningsOnly)` or `Option.some(SuccessOnly)` when exactly one is
+ * present, and `Option.none()` when both are nullish. Use it as the total entry
+ * point for turning an optional success value and optional warnings into a
+ * `WarnResult`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ * import { Option } from "effect"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.optionFromNullables({ warnings: "w", success: 1 }),
+ *   Option.some(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 }))
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.optionFromNullables({ warnings: "w", success: null }),
+ *   Option.some(WarnResult.WarningsOnly({ warnings: "w" }))
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.optionFromNullables({ warnings: null, success: undefined }),
+ *   Option.none()
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const optionFromNullables = ({
+  warnings,
+  success
+}) => Option.map(InclusiveOr.optionFromNullables({
+  left: warnings,
+  right: success
+}), io => fromInclusiveOr(io));
+/**
+ * Builds a `WarnResult` from a pair of possibly-nullish inputs, falling back to
+ * the `orElse` thunk when both are absent.
+ *
+ * The non-optional companion to `optionFromNullables`: it unwraps the same logic
+ * but resolves the all-absent case with `orElse` instead of an `Option`. The
+ * default `orElse` throws, so omit it only when at least one side is guaranteed
+ * present.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.fromNullables({ warnings: "w", success: 1 }),
+ *   WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })
+ * )
+ *
+ * // Both absent — fall back via orElse instead of throwing
+ * assert.deepStrictEqual(
+ *   WarnResult.fromNullables({
+ *     warnings: null,
+ *     success: null,
+ *     orElse: () => WarnResult.WarningsOnly({ warnings: "none" })
+ *   }),
+ *   WarnResult.WarningsOnly({ warnings: "none" })
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export const fromNullables = ({
+  warnings,
+  success,
+  orElse = () => {
+    throw new Error("Both warnings and success are nullish");
+  }
+}) => pipe(optionFromNullables({
+  warnings,
+  success
+}), Option.getOrElse(orElse));
+/**
+ * Folds a `WarnResult` from the warnings' perspective, collapsing the three tags
+ * into two handlers.
+ *
+ * Both `WarningsOnly` and `SuccessWithWarnings` carry `warnings`, so they route to
+ * the `Warnings` handler; only `SuccessOnly` lacks `warnings` and routes to
+ * `SuccessOnly`. Use it when you care about the `warnings` and treat the
+ * success-only case as the exception.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const onWarnings = WarnResult.matchWarnings({
+ *   Warnings: (warnings: string) => `warnings ${warnings}`,
+ *   SuccessOnly: (success: number) => `success ${success}`
+ * })
+ *
+ * assert.deepStrictEqual(
+ *   onWarnings(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   "warnings w"
+ * )
+ * assert.deepStrictEqual(
+ *   onWarnings(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })),
+ *   "warnings w"
+ * )
+ * assert.deepStrictEqual(
+ *   onWarnings(WarnResult.SuccessOnly({ success: 1 })),
+ *   "success 1"
+ * )
+ * ```
+ *
+ * @category pattern matching
+ * @since 0.0.0
+ */
+export const matchWarnings = ({
+  Warnings,
+  SuccessOnly
+}) => warnResult => InclusiveOr.matchLeft({
+  Left: Warnings,
+  RightOnly: SuccessOnly
+})(toInclusiveOr(warnResult));
+/**
+ * Folds a `WarnResult` from the success value's perspective, collapsing the three
+ * tags into two handlers.
+ *
+ * The mirror of `matchWarnings`: both `SuccessOnly` and `SuccessWithWarnings`
+ * carry a `success` value, so they route to the `Success` handler; only
+ * `WarningsOnly` lacks a `success` value and routes to `WarningsOnly`. Use it when
+ * you care about the `success` value and treat the warnings-only case as the
+ * exception.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const onSuccess = WarnResult.matchSuccess({
+ *   WarningsOnly: (warnings: string) => `warnings ${warnings}`,
+ *   Success: (success: number) => `success ${success}`
+ * })
+ *
+ * assert.deepStrictEqual(
+ *   onSuccess(WarnResult.SuccessOnly({ success: 1 })),
+ *   "success 1"
+ * )
+ * assert.deepStrictEqual(
+ *   onSuccess(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })),
+ *   "success 1"
+ * )
+ * assert.deepStrictEqual(
+ *   onSuccess(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   "warnings w"
+ * )
+ * ```
+ *
+ * @category pattern matching
+ * @since 0.0.0
+ */
+export const matchSuccess = ({
+  WarningsOnly,
+  Success
+}) => warnResult => InclusiveOr.matchRight({
+  LeftOnly: WarningsOnly,
+  Right: Success
+})(toInclusiveOr(warnResult));
+/**
+ * Completes a `WarnResult` into a guaranteed `SuccessWithWarnings` by filling
+ * whichever side is missing from the matching `orElse` thunk.
+ *
+ * A `SuccessWithWarnings` passes through unchanged; a `WarningsOnly` gains a
+ * `success` value from `orElseSuccess`; a `SuccessOnly` gains `warnings` from
+ * `orElseWarnings`. Use it to normalise a partial `WarnResult` into the
+ * both-present shape before reading both sides.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const fill = WarnResult.orElse({
+ *   orElseWarnings: () => "no warnings",
+ *   orElseSuccess: () => 0
+ * })
+ *
+ * assert.deepStrictEqual(
+ *   fill(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   WarnResult.SuccessWithWarnings({ warnings: "w", success: 0 })
+ * )
+ * assert.deepStrictEqual(
+ *   fill(WarnResult.SuccessOnly({ success: 1 })),
+ *   WarnResult.SuccessWithWarnings({ warnings: "no warnings", success: 1 })
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const orElse = ({
+  orElseWarnings,
+  orElseSuccess
+}) => warnResult => fromInclusiveOr(InclusiveOr.orElse({
+  orElseLeft: orElseWarnings,
+  orElseRight: orElseSuccess
+})(toInclusiveOr(warnResult)));
+/**
+ * Completes a `WarnResult` into a `SuccessWithWarnings` whose missing side is
+ * filled with `undefined`.
+ *
+ * A specialisation of `orElse` that supplies `undefined` for whichever side is
+ * absent, so the result always exposes both `warnings` and `success` keys (each
+ * possibly `undefined`). Use it when you want to destructure both sides without
+ * branching on the tag.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.orUndefined(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   WarnResult.SuccessWithWarnings({ warnings: "w", success: undefined })
+ * )
+ * assert.deepStrictEqual(
+ *   WarnResult.orUndefined(WarnResult.SuccessOnly({ success: 1 })),
+ *   WarnResult.SuccessWithWarnings({ warnings: undefined, success: 1 })
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const orUndefined = /*#__PURE__*/orElse({
+  orElseWarnings: () => undefined,
+  orElseSuccess: () => undefined
+});
+/**
+ * Extracts the `warnings` of a `WarnResult`, falling back to `orElseReturn` when
+ * no `warnings` are present.
+ *
+ * `WarningsOnly` and `SuccessWithWarnings` return their `warnings`; `SuccessOnly`
+ * returns the result of `orElseReturn`. Use it to read the warnings with a default
+ * in one step.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const warningsOrNone = WarnResult.warningsOrElse(() => "no warnings")
+ *
+ * assert.deepStrictEqual(
+ *   warningsOrNone(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   "w"
+ * )
+ * assert.deepStrictEqual(
+ *   warningsOrNone(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })),
+ *   "w"
+ * )
+ * assert.deepStrictEqual(
+ *   warningsOrNone(WarnResult.SuccessOnly({ success: 1 })),
+ *   "no warnings"
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const warningsOrElse = orElseReturn => warnResult => InclusiveOr.leftOrElse(orElseReturn)(toInclusiveOr(warnResult));
+/**
+ * Extracts the `warnings` of a `WarnResult`, returning `undefined` when no
+ * `warnings` are present.
+ *
+ * A specialisation of `warningsOrElse` whose fallback is `undefined`:
+ * `WarningsOnly` and `SuccessWithWarnings` yield their `warnings`, while
+ * `SuccessOnly` yields `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.warningsOrUndefined(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   "w"
+ * )
+ * assert.deepStrictEqual(
+ *   WarnResult.warningsOrUndefined(WarnResult.SuccessOnly({ success: 1 })),
+ *   undefined
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const warningsOrUndefined = /*#__PURE__*/warningsOrElse(() => undefined);
+/**
+ * Extracts the `success` value of a `WarnResult`, falling back to `orElseReturn`
+ * when no `success` value is present.
+ *
+ * The mirror of `warningsOrElse`: `SuccessOnly` and `SuccessWithWarnings` return
+ * their `success` value; `WarningsOnly` returns the result of `orElseReturn`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const successOrZero = WarnResult.successOrElse(() => 0)
+ *
+ * assert.deepStrictEqual(
+ *   successOrZero(WarnResult.SuccessOnly({ success: 1 })),
+ *   1
+ * )
+ * assert.deepStrictEqual(
+ *   successOrZero(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   0
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const successOrElse = orElseReturn => warnResult => InclusiveOr.rightOrElse(orElseReturn)(toInclusiveOr(warnResult));
+/**
+ * Extracts the `success` value of a `WarnResult`, returning `undefined` when no
+ * `success` value is present.
+ *
+ * A specialisation of `successOrElse` whose fallback is `undefined`: `SuccessOnly`
+ * and `SuccessWithWarnings` yield their `success` value, while `WarningsOnly`
+ * yields `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.successOrUndefined(WarnResult.SuccessOnly({ success: 1 })),
+ *   1
+ * )
+ * assert.deepStrictEqual(
+ *   WarnResult.successOrUndefined(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   undefined
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const successOrUndefined = /*#__PURE__*/successOrElse(() => undefined);
+/**
+ * Extracts the `success` value of a `WarnResult` as an `Option`.
+ *
+ * `SuccessOnly` and `SuccessWithWarnings` yield `Option.some(success)`;
+ * `WarningsOnly` yields `Option.none()`. Use it when you want to chain the success
+ * value through `Option` combinators rather than fall back to a default eagerly.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ * import { Option } from "effect"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.successOption(WarnResult.SuccessOnly({ success: 1 })),
+ *   Option.some(1)
+ * )
+ * assert.deepStrictEqual(
+ *   WarnResult.successOption(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   Option.none()
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const successOption = warnResult => InclusiveOr.rightOption(toInclusiveOr(warnResult));
+/**
+ * Extracts the `warnings` of a `WarnResult` as an `Option`.
+ *
+ * The mirror of `successOption`: `WarningsOnly` and `SuccessWithWarnings` yield
+ * `Option.some(warnings)`, while `SuccessOnly` yields `Option.none()`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ * import { Option } from "effect"
+ *
+ * assert.deepStrictEqual(
+ *   WarnResult.warningsOption(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   Option.some("w")
+ * )
+ * assert.deepStrictEqual(
+ *   WarnResult.warningsOption(WarnResult.SuccessOnly({ success: 1 })),
+ *   Option.none()
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const warningsOption = warnResult => InclusiveOr.leftOption(toInclusiveOr(warnResult));
+/**
+ * Transforms both sides of a `WarnResult`, applying `mapWarnings` to any
+ * `warnings` and `mapSuccess` to any `success` value.
+ *
+ * Each constructor is rebuilt with its mapped contents, so `WarningsOnly` maps
+ * only the warnings, `SuccessOnly` only the success value, and
+ * `SuccessWithWarnings` both. The tag is preserved. Use it as the bifunctor map
+ * over `WarnResult`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const both = WarnResult.mapBoth({
+ *   mapWarnings: (warnings: string) => warnings.toUpperCase(),
+ *   mapSuccess: (success: number) => success + 1
+ * })
+ *
+ * assert.deepStrictEqual(
+ *   both(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })),
+ *   WarnResult.SuccessWithWarnings({ warnings: "W", success: 2 })
+ * )
+ * assert.deepStrictEqual(
+ *   both(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   WarnResult.WarningsOnly({ warnings: "W" })
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export const mapBoth = ({
+  mapWarnings,
+  mapSuccess
+}) => warnResult => fromInclusiveOr(InclusiveOr.mapBoth({
+  mapLeft: mapWarnings,
+  mapRight: mapSuccess
+})(toInclusiveOr(warnResult)));
+/**
+ * Effectful `mapBoth`: transforms each present side through an `Effect`,
+ * reassembling the results into a `WarnResult` inside an `Effect`.
+ *
+ * For `SuccessWithWarnings` both effects run via `Effect.all` and their results
+ * are combined; `WarningsOnly`/`SuccessOnly` run only the relevant effect. Errors
+ * and requirements from both mappers are unioned into the result type. Use it when
+ * mapping a `WarnResult`'s sides requires effects (validation, IO).
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ * import { Effect } from "effect"
+ *
+ * const both = WarnResult.mapBothEffect({
+ *   mapWarnings: (warnings: string) => Effect.succeed(warnings.toUpperCase()),
+ *   mapSuccess: (success: number) => Effect.succeed(success + 1)
+ * })
+ *
+ * assert.deepStrictEqual(
+ *   Effect.runSync(
+ *     both(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 }))
+ *   ),
+ *   WarnResult.SuccessWithWarnings({ warnings: "W", success: 2 })
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export const mapBothEffect = ({
+  mapWarnings,
+  mapSuccess
+}) => warnResult => pipe(toInclusiveOr(warnResult), InclusiveOr.mapBothEffect({
+  mapLeft: mapWarnings,
+  mapRight: mapSuccess
+}), Effect.map(io => fromInclusiveOr(io)));
+/**
+ * Transforms the `warnings` of a `WarnResult`, leaving any `success` value
+ * untouched.
+ *
+ * A specialisation of `mapBoth` with the success mapper set to `identity`:
+ * `WarningsOnly` and `SuccessWithWarnings` have their `warnings` mapped, while
+ * `SuccessOnly` passes through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const shout = WarnResult.mapWarnings((warnings: string) =>
+ *   warnings.toUpperCase()
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   shout(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })),
+ *   WarnResult.SuccessWithWarnings({ warnings: "W", success: 1 })
+ * )
+ * assert.deepStrictEqual(
+ *   shout(WarnResult.SuccessOnly({ success: 1 })),
+ *   WarnResult.SuccessOnly({ success: 1 })
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export const mapWarnings = mapWarnings => warnResult => fromInclusiveOr(InclusiveOr.mapLeft(mapWarnings)(toInclusiveOr(warnResult)));
+/**
+ * Chains the `warnings` of a `WarnResult` into a new `WarnResult`, flattening the
+ * result.
+ *
+ * Whenever `warnings` are present (`WarningsOnly` or `SuccessWithWarnings`) they
+ * are passed to `mapWarnings`, whose returned `WarnResult` replaces the original;
+ * `SuccessOnly` passes through unchanged. Use it to sequence warnings-driven
+ * computations that themselves produce a `WarnResult`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const chain = WarnResult.flatMapWarnings((warnings: string) =>
+ *   warnings.length > 0
+ *     ? WarnResult.WarningsOnly({ warnings: warnings.toUpperCase() })
+ *     : WarnResult.SuccessOnly({ success: 0 })
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   chain(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   WarnResult.WarningsOnly({ warnings: "W" })
+ * )
+ * assert.deepStrictEqual(
+ *   chain(WarnResult.SuccessOnly({ success: 1 })),
+ *   WarnResult.SuccessOnly({ success: 1 })
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export const flatMapWarnings = mapWarnings => warnResult => fromInclusiveOr(InclusiveOr.flatMapLeft(warnings => toInclusiveOr(mapWarnings(warnings)))(toInclusiveOr(warnResult)));
+/**
+ * Effectful `mapWarnings`: transforms the `warnings` of a `WarnResult` through an
+ * `Effect`, leaving any `success` value untouched.
+ *
+ * A specialisation of `mapBothEffect` with the success mapper set to
+ * `Effect.succeed`: the `warnings` (when present) are mapped effectfully and the
+ * `success` value is carried through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ * import { Effect } from "effect"
+ *
+ * const shout = WarnResult.mapWarningsEffect((warnings: string) =>
+ *   Effect.succeed(warnings.toUpperCase())
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   Effect.runSync(
+ *     shout(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 }))
+ *   ),
+ *   WarnResult.SuccessWithWarnings({ warnings: "W", success: 1 })
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export const mapWarningsEffect = mapWarnings => warnResult => pipe(toInclusiveOr(warnResult), InclusiveOr.mapLeftEffect(mapWarnings), Effect.map(io => fromInclusiveOr(io)));
+/**
+ * Effectful `flatMapWarnings`: chains the `warnings` of a `WarnResult` into an
+ * `Effect` that yields a new `WarnResult`, flattening the result.
+ *
+ * When `warnings` are present they are passed to `mapWarnings`, whose effectful
+ * `WarnResult` replaces the original; `SuccessOnly` is lifted unchanged via
+ * `Effect.succeed`. Use it to sequence warnings-driven effectful computations that
+ * produce a `WarnResult`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ * import { Effect } from "effect"
+ *
+ * const chain = WarnResult.flatMapWarningsEffect((warnings: string) =>
+ *   Effect.succeed(WarnResult.WarningsOnly({ warnings: warnings.toUpperCase() }))
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   Effect.runSync(chain(WarnResult.WarningsOnly({ warnings: "w" }))),
+ *   WarnResult.WarningsOnly({ warnings: "W" })
+ * )
+ * assert.deepStrictEqual(
+ *   Effect.runSync(chain(WarnResult.SuccessOnly({ success: 1 }))),
+ *   WarnResult.SuccessOnly({ success: 1 })
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export const flatMapWarningsEffect = mapWarnings => warnResult => pipe(toInclusiveOr(warnResult), InclusiveOr.flatMapLeftEffect(warnings => Effect.map(mapWarnings(warnings), toInclusiveOr)), Effect.map(io => fromInclusiveOr(io)));
+/**
+ * Transforms the `success` value of a `WarnResult`, leaving any `warnings`
+ * untouched.
+ *
+ * The mirror of `mapWarnings`: `SuccessOnly` and `SuccessWithWarnings` have their
+ * `success` value mapped, while `WarningsOnly` passes through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const inc = WarnResult.mapSuccess((success: number) => success + 1)
+ *
+ * assert.deepStrictEqual(
+ *   inc(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 })),
+ *   WarnResult.SuccessWithWarnings({ warnings: "w", success: 2 })
+ * )
+ * assert.deepStrictEqual(
+ *   inc(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   WarnResult.WarningsOnly({ warnings: "w" })
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export const mapSuccess = mapSuccess => warnResult => fromInclusiveOr(InclusiveOr.mapRight(mapSuccess)(toInclusiveOr(warnResult)));
+/**
+ * Chains the `success` value of a `WarnResult` into a new `WarnResult`, flattening
+ * the result.
+ *
+ * The mirror of `flatMapWarnings`: whenever a `success` value is present
+ * (`SuccessOnly` or `SuccessWithWarnings`) it is passed to `mapSuccess`, whose
+ * returned `WarnResult` replaces the original; `WarningsOnly` passes through
+ * unchanged.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ *
+ * const chain = WarnResult.flatMapSuccess((success: number) =>
+ *   WarnResult.SuccessOnly({ success: success + 1 })
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   chain(WarnResult.SuccessOnly({ success: 1 })),
+ *   WarnResult.SuccessOnly({ success: 2 })
+ * )
+ * assert.deepStrictEqual(
+ *   chain(WarnResult.WarningsOnly({ warnings: "w" })),
+ *   WarnResult.WarningsOnly({ warnings: "w" })
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export const flatMapSuccess = mapSuccess => warnResult => fromInclusiveOr(InclusiveOr.flatMapRight(success => toInclusiveOr(mapSuccess(success)))(toInclusiveOr(warnResult)));
+/**
+ * Effectful `mapSuccess`: transforms the `success` value of a `WarnResult` through
+ * an `Effect`, leaving any `warnings` untouched.
+ *
+ * The mirror of `mapWarningsEffect`: the `success` value (when present) is mapped
+ * effectfully and the `warnings` are carried through unchanged via
+ * `Effect.succeed`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ * import { Effect } from "effect"
+ *
+ * const inc = WarnResult.mapSuccessEffect((success: number) =>
+ *   Effect.succeed(success + 1)
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   Effect.runSync(
+ *     inc(WarnResult.SuccessWithWarnings({ warnings: "w", success: 1 }))
+ *   ),
+ *   WarnResult.SuccessWithWarnings({ warnings: "w", success: 2 })
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export const mapSuccessEffect = mapSuccess => warnResult => pipe(toInclusiveOr(warnResult), InclusiveOr.mapRightEffect(mapSuccess), Effect.map(io => fromInclusiveOr(io)));
+/**
+ * Effectful `flatMapSuccess`: chains the `success` value of a `WarnResult` into an
+ * `Effect` that yields a new `WarnResult`, flattening the result.
+ *
+ * The mirror of `flatMapWarningsEffect`: when a `success` value is present it is
+ * passed to `mapSuccess`, whose effectful `WarnResult` replaces the original;
+ * `WarningsOnly` is lifted unchanged via `Effect.succeed`.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ * import { Effect } from "effect"
+ *
+ * const chain = WarnResult.flatMapSuccessEffect((success: number) =>
+ *   Effect.succeed(WarnResult.SuccessOnly({ success: success + 1 }))
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   Effect.runSync(chain(WarnResult.SuccessOnly({ success: 1 }))),
+ *   WarnResult.SuccessOnly({ success: 2 })
+ * )
+ * assert.deepStrictEqual(
+ *   Effect.runSync(chain(WarnResult.WarningsOnly({ warnings: "w" }))),
+ *   WarnResult.WarningsOnly({ warnings: "w" })
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export const flatMapSuccessEffect = mapSuccess => warnResult => pipe(toInclusiveOr(warnResult), InclusiveOr.flatMapRightEffect(success => Effect.map(mapSuccess(success), toInclusiveOr)), Effect.map(io => fromInclusiveOr(io)));
+/**
+ * Zips two arrays into one, calling `f` with a `WarnResult` for each index so
+ * that length mismatches are handled explicitly rather than truncated.
+ *
+ * Unlike `Array.zipWith` (which stops at the shorter array), this walks to the
+ * length of the *longer* array. The first array's element fills the `warnings`
+ * side and the second array's element fills the `success` side, so at each index
+ * `f` receives a `WarnResult.WarnResult<B, A>`: `SuccessWithWarnings` when both
+ * arrays have an element, `WarningsOnly` when only the first does, and
+ * `SuccessOnly` when only the second does. Use it when the "extra" tail of either
+ * array still carries meaning.
+ *
+ * @example
+ * ```ts
+ * import { WarnResult } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * const describe = WarnResult.match({
+ *   WarningsOnly: ({ warnings }) => `warnings ${warnings}`,
+ *   SuccessOnly: ({ success }) => `success ${success}`,
+ *   SuccessWithWarnings: ({ warnings, success }) => `both ${warnings}/${success}`
+ * })
+ *
+ * // data-first
+ * assert.deepStrictEqual(WarnResult.zip([1, 2, 3], [10, 20], describe), [
+ *   "both 1/10",
+ *   "both 2/20",
+ *   "warnings 3"
+ * ])
+ *
+ * // data-last (pipeable)
+ * assert.deepStrictEqual(pipe([1, 2, 3], WarnResult.zip([10, 20], describe)), [
+ *   "both 1/10",
+ *   "both 2/20",
+ *   "warnings 3"
+ * ])
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const zip = /*#__PURE__*/dual(3, (array1, array2, f) => InclusiveOr.zip(array1, array2, io => f(fromInclusiveOr(io))));
+//# sourceMappingURL=WarnResult.js.map