@nunofyobiz/effect-extras 1.0.0 → 2.1.0

package/dist/DurationX.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Duration` module.
+ *
+ * @since 0.0.0
+ */
+import { DateTime, Duration } from "effect";
+/**
+ * Computes the elapsed `Duration` from `that` to `self`, clamped at zero.
+ *
+ * Represents the time that has passed since the reference instant `that`. When
+ * `that` lies in the future relative to `self`, the elapsed time is `zero`
+ * rather than a negative duration.
+ *
+ * @example
+ * ```ts
+ * import { DateTime, Duration, pipe } from "effect"
+ * import { DurationX } from "@nunofyobiz/effect-extras"
+ *
+ * const earlier = DateTime.makeUnsafe(1000)
+ * const later = DateTime.makeUnsafe(4000)
+ *
+ * // data-first
+ * assert.deepStrictEqual(DurationX.diff(later, earlier), Duration.seconds(3))
+ *
+ * // future reference clamps to zero
+ * assert.deepStrictEqual(DurationX.diff(earlier, later), Duration.zero)
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(
+ *   pipe(later, DurationX.diff(earlier)),
+ *   Duration.seconds(3),
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export declare const diff: ((that: DateTime.DateTime) => (self: DateTime.DateTime) => Duration.Duration) & ((self: DateTime.DateTime, that: DateTime.DateTime) => Duration.Duration);
+/**
+ * Transforms a `Duration` by converting it to a numeric `unit`, applying `map`,
+ * then converting back.
+ *
+ * Lets you operate on a duration in whatever unit is convenient — round it to
+ * whole minutes, halve its seconds, floor its days — without juggling
+ * conversions by hand. The `map` callback receives the duration expressed as a
+ * `number` of `unit`s and returns the new count.
+ *
+ * @example
+ * ```ts
+ * import { Duration, Number, pipe } from "effect"
+ * import { DurationX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first: halve a 4-second duration
+ * assert.deepStrictEqual(
+ *   DurationX.mapAsUnit(Duration.seconds(4), "second", Number.divideUnsafe(2)),
+ *   Duration.seconds(2),
+ * )
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     Duration.minutes(10),
+ *     DurationX.mapAsUnit("minute", (minutes) => minutes + 5),
+ *   ),
+ *   Duration.minutes(15),
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export declare const mapAsUnit: ((unit: Duration.Unit, map: (numberOfUnits: number) => number) => (duration: Duration.Duration) => Duration.Duration) & ((duration: Duration.Duration, unit: Duration.Unit, map: (numberOfUnits: number) => number) => Duration.Duration);
+//# sourceMappingURL=DurationX.d.ts.map

package/dist/DurationX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DurationX.d.ts","sourceRoot":"","sources":["../src/DurationX.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAiB,MAAM,QAAQ,CAAC;AAO3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,IAAI,UAER,QAAQ,CAAC,QAAQ,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,YAEpE,QAAQ,CAAC,QAAQ,QAAQ,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,CAUxE,CAAC;AAwDF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,SAAS,UAGZ,QAAQ,CAAC,IAAI,OACd,CAAC,aAAa,EAAE,MAAM,KAAK,MAAM,KACnC,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,gBAG3C,QAAQ,CAAC,QAAQ,QACrB,QAAQ,CAAC,IAAI,OACd,CAAC,aAAa,EAAE,MAAM,KAAK,MAAM,KACnC,QAAQ,CAAC,QAAQ,CAoBvB,CAAC"}

package/dist/DurationX.js

@@ -0,0 +1,91 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Duration` module.
+ *
+ * @since 0.0.0
+ */
+import { DateTime, Duration, Match, Option } from "effect";
+import { dual, pipe } from "effect/Function";
+import * as BigIntX from "./BigIntX.js";
+// Some private constants for conversion
+const MICROS_PER_MILLI = 1000;
+/**
+ * Computes the elapsed `Duration` from `that` to `self`, clamped at zero.
+ *
+ * Represents the time that has passed since the reference instant `that`. When
+ * `that` lies in the future relative to `self`, the elapsed time is `zero`
+ * rather than a negative duration.
+ *
+ * @example
+ * ```ts
+ * import { DateTime, Duration, pipe } from "effect"
+ * import { DurationX } from "@nunofyobiz/effect-extras"
+ *
+ * const earlier = DateTime.makeUnsafe(1000)
+ * const later = DateTime.makeUnsafe(4000)
+ *
+ * // data-first
+ * assert.deepStrictEqual(DurationX.diff(later, earlier), Duration.seconds(3))
+ *
+ * // future reference clamps to zero
+ * assert.deepStrictEqual(DurationX.diff(earlier, later), Duration.zero)
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(
+ *   pipe(later, DurationX.diff(earlier)),
+ *   Duration.seconds(3),
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const diff = /*#__PURE__*/dual(2, (self, that) => Duration.millis(
+// Clamp at 0 — "diff" represents elapsed time since `that`; if `that`
+// is in the future relative to `self`, the elapsed time is zero
+// (not negative).
+Math.max(0, DateTime.toEpochMillis(self) - DateTime.toEpochMillis(that))));
+// Internal — used by mapAsUnit.
+const toUnit = /*#__PURE__*/dual(2, (duration, unit) => Match.value(unit).pipe(Match.whenOr("week", "weeks", () => Duration.toWeeks(duration)), Match.whenOr("day", "days", () => Duration.toDays(duration)), Match.whenOr("hour", "hours", () => Duration.toHours(duration)), Match.whenOr("minute", "minutes", () => Duration.toMinutes(duration)), Match.whenOr("second", "seconds", () => Duration.toSeconds(duration)), Match.whenOr("milli", "millis", () => Duration.toMillis(duration)), Match.whenOr("micro", "micros", () => Duration.toMillis(duration) * MICROS_PER_MILLI), Match.whenOr("nano", "nanos", () => pipe(Duration.toNanos(duration), Option.getOrThrowWith(() => new Error("Duration.toNanos returned None")), BigIntX.toNumberOrThrow)), Match.exhaustive));
+// Internal — used by mapAsUnit.
+const fromUnit = /*#__PURE__*/dual(2, (value, unit) => Match.value(unit).pipe(Match.whenOr("week", "weeks", () => Duration.weeks(value)), Match.whenOr("day", "days", () => Duration.days(value)), Match.whenOr("hour", "hours", () => Duration.hours(value)), Match.whenOr("minute", "minutes", () => Duration.minutes(value)), Match.whenOr("second", "seconds", () => Duration.seconds(value)), Match.whenOr("milli", "millis", () => Duration.millis(value)), Match.whenOr("micro", "micros", () => Duration.micros(BigInt(value))), Match.whenOr("nano", "nanos", () => Duration.nanos(BigInt(value))), Match.exhaustive));
+/**
+ * Transforms a `Duration` by converting it to a numeric `unit`, applying `map`,
+ * then converting back.
+ *
+ * Lets you operate on a duration in whatever unit is convenient — round it to
+ * whole minutes, halve its seconds, floor its days — without juggling
+ * conversions by hand. The `map` callback receives the duration expressed as a
+ * `number` of `unit`s and returns the new count.
+ *
+ * @example
+ * ```ts
+ * import { Duration, Number, pipe } from "effect"
+ * import { DurationX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first: halve a 4-second duration
+ * assert.deepStrictEqual(
+ *   DurationX.mapAsUnit(Duration.seconds(4), "second", Number.divideUnsafe(2)),
+ *   Duration.seconds(2),
+ * )
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     Duration.minutes(10),
+ *     DurationX.mapAsUnit("minute", (minutes) => minutes + 5),
+ *   ),
+ *   Duration.minutes(15),
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const mapAsUnit = /*#__PURE__*/dual(3, (duration, unit, map) => pipe(duration,
+// Convert to that unit
+toUnit(unit),
+// Truncate to the requested number of digits
+map,
+// Convert back to a duration
+fromUnit(unit)));
+//# sourceMappingURL=DurationX.js.map

package/dist/DurationX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DurationX.js","names":["DateTime","Duration","Match","Option","dual","pipe","BigIntX","MICROS_PER_MILLI","diff","self","that","millis","Math","max","toEpochMillis","toUnit","duration","unit","value","whenOr","toWeeks","toDays","toHours","toMinutes","toSeconds","toMillis","toNanos","getOrThrowWith","Error","toNumberOrThrow","exhaustive","fromUnit","weeks","days","hours","minutes","seconds","micros","BigInt","nanos","mapAsUnit","map"],"sources":["../src/DurationX.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/EffectX.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Effect` module.
+ *
+ * @since 0.0.0
+ */
+import { Cause, Duration, Effect, Option, Predicate } from "effect";
+/**
+ * Flattens an `Effect` that succeeds with an `Option` into an `Effect` that
+ * fails with `onNone()` when the `Option` is `None`.
+ *
+ * When the wrapped `Option` is `Some(value)` the effect succeeds with `value`;
+ * when it is `None` the effect fails with the error produced by the `onNone`
+ * thunk. An existing failure of the source effect is preserved untouched, so the
+ * result's error channel is the union of the original error and the `None`
+ * error.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option, Result } from "effect"
+ * import { EffectX } from "@nunofyobiz/effect-extras"
+ *
+ * const some = EffectX.flattenOption(
+ *   Effect.succeed(Option.some(1)),
+ *   () => "missing",
+ * )
+ * assert.deepStrictEqual(Effect.runSync(Effect.result(some)), Result.succeed(1))
+ *
+ * const none = EffectX.flattenOption(
+ *   Effect.succeed(Option.none<number>()),
+ *   () => "missing",
+ * )
+ * assert.deepStrictEqual(
+ *   Effect.runSync(Effect.result(none)),
+ *   Result.fail("missing"),
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export declare const flattenOption: (<A, E1, E2, R>(onNone: () => E2) => (effect: Effect.Effect<Option.Option<A>, E1, R>) => Effect.Effect<A, E1 | E2, R>) & (<A, E1, E2, R>(effect: Effect.Effect<Option.Option<A>, E1, R>, onNone: () => E2) => Effect.Effect<A, E1 | E2, R>);
+/**
+ * Converts an `Option` to an `Effect`, mapping the `None` case to a caller-chosen
+ * error via the `onNone` thunk.
+ *
+ * Equivalent to `Effect.mapError(Effect.fromOption(option), onNone)`: it bridges
+ * the `NoSuchElementError` that `Effect.fromOption` produces to the caller's own
+ * error type, so callers never have to handle `NoSuchElementError`. This fills
+ * the v4 gap where `Effect.mapError` no longer accepts an `Option` directly —
+ * instead of
+ * `pipe(option, Effect.fromOption, Effect.mapError(() => new MyError()))`, write
+ * `pipe(option, EffectX.fromOptionOrElse(() => new MyError()))`. The `onNone`
+ * thunk runs only when the `Option` is `None`.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option, Result, pipe } from "effect"
+ * import { EffectX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * const some = EffectX.fromOptionOrElse(Option.some(42), () => "missing")
+ * assert.deepStrictEqual(Effect.runSync(Effect.result(some)), Result.succeed(42))
+ *
+ * // data-last (piped) — None maps to the chosen error
+ * const none = pipe(
+ *   Option.none<number>(),
+ *   EffectX.fromOptionOrElse(() => "missing"),
+ * )
+ * assert.deepStrictEqual(
+ *   Effect.runSync(Effect.result(none)),
+ *   Result.fail("missing"),
+ * )
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export declare const fromOptionOrElse: {
+    <E>(onNone: () => E): <A>(option: Option.Option<A>) => Effect.Effect<A, E>;
+    <A, E>(option: Option.Option<A>, onNone: () => E): Effect.Effect<A, E>;
+};
+/**
+ * Repeatedly calls a synchronous `try` thunk until its result satisfies the
+ * `until` refinement, sleeping `sleepDuration` between attempts and failing with
+ * a `TimeoutError` once `maxDuration` elapses.
+ *
+ * The thunk is evaluated immediately; if its first result already passes the
+ * refinement the effect succeeds without any delay. Otherwise it polls on the
+ * `sleepDuration` interval (defaulting to 200ms — the threshold below which a
+ * delay reads as "instant" to a user) until either the predicate holds (the
+ * effect succeeds with the narrowed `B` value) or `maxDuration` is exceeded (the
+ * effect fails with a `Cause.TimeoutError`). Use it to await an external,
+ * non-effectful condition such as a flag flipped by a callback.
+ *
+ * @example
+ * ```ts
+ * import { Duration, Effect } from "effect"
+ * import { EffectX } from "@nunofyobiz/effect-extras"
+ *
+ * // First attempt already matches, so it resolves immediately.
+ * const effect = EffectX.tryUntil({
+ *   try: () => 1,
+ *   until: (value: number): value is number => value === 1,
+ *   sleepDuration: Duration.millis(100),
+ *   maxDuration: Duration.seconds(1),
+ * })
+ *
+ * assert.deepStrictEqual(Effect.runSync(effect), 1)
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export declare const tryUntil: <A, B extends A>({ try: doTry, until: isDone, sleepDuration, maxDuration, }: {
+    try: () => A;
+    until: Predicate.Refinement<A, B>;
+    sleepDuration?: Duration.Duration;
+    maxDuration: Duration.Duration;
+}) => Effect.Effect<B, Cause.TimeoutError, never>;
+//# sourceMappingURL=EffectX.d.ts.map

package/dist/EffectX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EffectX.d.ts","sourceRoot":"","sources":["../src/EffectX.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAQ,MAAM,QAAQ,CAAC;AAU1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,aAAa,IACvB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,UACH,MAAM,EAAE,KACb,CACH,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,KAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,MAChC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,UACH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UACtC,MAAM,EAAE,KACb,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAUlC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,gBAAgB,EAAE;IAC7B,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAKxE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,4DAKtC;IACD,GAAG,EAAE,MAAM,CAAC,CAAC;IACb,KAAK,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,aAAa,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAClC,WAAW,EAAE,QAAQ,CAAC,QAAQ,CAAC;CAChC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,EAAE,KAAK,CAyB7C,CAAC"}

package/dist/EffectX.js

@@ -0,0 +1,140 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Effect` module.
+ *
+ * @since 0.0.0
+ */
+import { Cause, Duration, Effect, pipe } from "effect";
+import { dual } from "effect/Function";
+/**
+ * The duration of time a user registers something as "instant" — used as the
+ * default poll interval for {@link tryUntil}. 200ms is the generally agreed
+ * value. See https://psychology.stackexchange.com/a/1680
+ */
+const USER_INSTANT_DURATION = /*#__PURE__*/Duration.millis(200);
+/**
+ * Flattens an `Effect` that succeeds with an `Option` into an `Effect` that
+ * fails with `onNone()` when the `Option` is `None`.
+ *
+ * When the wrapped `Option` is `Some(value)` the effect succeeds with `value`;
+ * when it is `None` the effect fails with the error produced by the `onNone`
+ * thunk. An existing failure of the source effect is preserved untouched, so the
+ * result's error channel is the union of the original error and the `None`
+ * error.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option, Result } from "effect"
+ * import { EffectX } from "@nunofyobiz/effect-extras"
+ *
+ * const some = EffectX.flattenOption(
+ *   Effect.succeed(Option.some(1)),
+ *   () => "missing",
+ * )
+ * assert.deepStrictEqual(Effect.runSync(Effect.result(some)), Result.succeed(1))
+ *
+ * const none = EffectX.flattenOption(
+ *   Effect.succeed(Option.none<number>()),
+ *   () => "missing",
+ * )
+ * assert.deepStrictEqual(
+ *   Effect.runSync(Effect.result(none)),
+ *   Result.fail("missing"),
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export const flattenOption = /*#__PURE__*/dual(2, (effect, onNone) => Effect.flatMap(effect, option => pipe(Effect.fromOption(option), Effect.mapError(onNone))));
+/**
+ * Converts an `Option` to an `Effect`, mapping the `None` case to a caller-chosen
+ * error via the `onNone` thunk.
+ *
+ * Equivalent to `Effect.mapError(Effect.fromOption(option), onNone)`: it bridges
+ * the `NoSuchElementError` that `Effect.fromOption` produces to the caller's own
+ * error type, so callers never have to handle `NoSuchElementError`. This fills
+ * the v4 gap where `Effect.mapError` no longer accepts an `Option` directly —
+ * instead of
+ * `pipe(option, Effect.fromOption, Effect.mapError(() => new MyError()))`, write
+ * `pipe(option, EffectX.fromOptionOrElse(() => new MyError()))`. The `onNone`
+ * thunk runs only when the `Option` is `None`.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option, Result, pipe } from "effect"
+ * import { EffectX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * const some = EffectX.fromOptionOrElse(Option.some(42), () => "missing")
+ * assert.deepStrictEqual(Effect.runSync(Effect.result(some)), Result.succeed(42))
+ *
+ * // data-last (piped) — None maps to the chosen error
+ * const none = pipe(
+ *   Option.none<number>(),
+ *   EffectX.fromOptionOrElse(() => "missing"),
+ * )
+ * assert.deepStrictEqual(
+ *   Effect.runSync(Effect.result(none)),
+ *   Result.fail("missing"),
+ * )
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export const fromOptionOrElse = /*#__PURE__*/dual(2, (option, onNone) => pipe(Effect.fromOption(option), Effect.mapError(onNone)));
+/**
+ * Repeatedly calls a synchronous `try` thunk until its result satisfies the
+ * `until` refinement, sleeping `sleepDuration` between attempts and failing with
+ * a `TimeoutError` once `maxDuration` elapses.
+ *
+ * The thunk is evaluated immediately; if its first result already passes the
+ * refinement the effect succeeds without any delay. Otherwise it polls on the
+ * `sleepDuration` interval (defaulting to 200ms — the threshold below which a
+ * delay reads as "instant" to a user) until either the predicate holds (the
+ * effect succeeds with the narrowed `B` value) or `maxDuration` is exceeded (the
+ * effect fails with a `Cause.TimeoutError`). Use it to await an external,
+ * non-effectful condition such as a flag flipped by a callback.
+ *
+ * @example
+ * ```ts
+ * import { Duration, Effect } from "effect"
+ * import { EffectX } from "@nunofyobiz/effect-extras"
+ *
+ * // First attempt already matches, so it resolves immediately.
+ * const effect = EffectX.tryUntil({
+ *   try: () => 1,
+ *   until: (value: number): value is number => value === 1,
+ *   sleepDuration: Duration.millis(100),
+ *   maxDuration: Duration.seconds(1),
+ * })
+ *
+ * assert.deepStrictEqual(Effect.runSync(effect), 1)
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export const tryUntil = ({
+  try: doTry,
+  until: isDone,
+  sleepDuration = USER_INSTANT_DURATION,
+  maxDuration
+}) => {
+  const immediateValue = doTry();
+  if (isDone(immediateValue)) {
+    return Effect.succeed(immediateValue);
+  }
+  // Continually call it again on a schedule with a delay
+  return Effect.sync(doTry).pipe(
+  // Sleep in between each attempt
+  Effect.delay(sleepDuration),
+  // Keep doing this until the predicate passes
+  Effect.repeat({
+    until: isDone
+  }),
+  // Until a timeout occurs. In v4, `Effect.timeout` raises `TimeoutError`
+  // on its own — no separate `timeoutFail` overload is needed.
+  Effect.timeout(maxDuration), Effect.catchTag("TimeoutError", () => Effect.fail(new Cause.TimeoutError(`Timed out after ${Duration.format(maxDuration)} waiting for value to pass predicate`))));
+};
+//# sourceMappingURL=EffectX.js.map

package/dist/EffectX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EffectX.js","names":["Cause","Duration","Effect","pipe","dual","USER_INSTANT_DURATION","millis","flattenOption","effect","onNone","flatMap","option","fromOption","mapError","fromOptionOrElse","tryUntil","try","doTry","until","isDone","sleepDuration","maxDuration","immediateValue","succeed","sync","delay","repeat","timeout","catchTag","fail","TimeoutError","format"],"sources":["../src/EffectX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,SAASA,KAAK,EAAEC,QAAQ,EAAEC,MAAM,EAAqBC,IAAI,QAAQ,QAAQ;AACzE,SAASC,IAAI,QAAQ,iBAAiB;AAEtC;;;;;AAKA,MAAMC,qBAAqB,gBAAGJ,QAAQ,CAACK,MAAM,CAAC,GAAG,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,MAAMC,aAAa,gBAAGH,IAAI,CAW/B,CAAC,EACD,CACEI,MAA8C,EAC9CC,MAAgB,KAEhBP,MAAM,CAACQ,OAAO,CAACF,MAAM,EAAGG,MAAM,IAC5BR,IAAI,CAACD,MAAM,CAACU,UAAU,CAACD,MAAM,CAAC,EAAET,MAAM,CAACW,QAAQ,CAACJ,MAAM,CAAC,CAAC,CACzD,CACJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,OAAO,MAAMK,gBAAgB,gBAGzBV,IAAI,CACN,CAAC,EACD,CAAOO,MAAwB,EAAEF,MAAe,KAC9CN,IAAI,CAACD,MAAM,CAACU,UAAU,CAACD,MAAM,CAAC,EAAET,MAAM,CAACW,QAAQ,CAACJ,MAAM,CAAC,CAAC,CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,OAAO,MAAMM,QAAQ,GAAGA,CAAiB;EACvCC,GAAG,EAAEC,KAAK;EACVC,KAAK,EAAEC,MAAM;EACbC,aAAa,GAAGf,qBAAqB;EACrCgB;AAAW,CAMZ,KAAiD;EAChD,MAAMC,cAAc,GAAGL,KAAK,EAAE;EAC9B,IAAIE,MAAM,CAACG,cAAc,CAAC,EAAE;IAC1B,OAAOpB,MAAM,CAACqB,OAAO,CAACD,cAAc,CAAC;EACvC;EAEA;EACA,OAAOpB,MAAM,CAACsB,IAAI,CAACP,KAAK,CAAC,CAACd,IAAI;EAC5B;EACAD,MAAM,CAACuB,KAAK,CAACL,aAAa,CAAC;EAE3B;EACAlB,MAAM,CAACwB,MAAM,CAAC;IAAER,KAAK,EAAEC;EAAM,CAAE,CAAC;EAEhC;EACA;EACAjB,MAAM,CAACyB,OAAO,CAACN,WAAW,CAAC,EAC3BnB,MAAM,CAAC0B,QAAQ,CAAC,cAAc,EAAE,MAC9B1B,MAAM,CAAC2B,IAAI,CACT,IAAI7B,KAAK,CAAC8B,YAAY,CACpB,mBAAmB7B,QAAQ,CAAC8B,MAAM,CAACV,WAAW,CAAC,sCAAsC,CACtF,CACF,CACF,CACF;AACH,CAAC","ignoreList":[]}

package/dist/FormDataX.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Helpers for decoding `FormData` with Effect `Schema`.
+ *
+ * @since 0.0.0
+ */
+import { Schema } from "effect";
+/**
+ * Decodes a `FormData` into a typed value using a `Schema`, throwing on
+ * validation failure.
+ *
+ * Built on v4's native `Schema.fromFormData`, which first parses the `FormData`
+ * entries into a nested tree record (bracket-path notation is supported) and then
+ * decodes that tree with the provided inner schema. For schemas with non-string
+ * fields (for example `Schema.Int`), wrap the inner schema in
+ * `Schema.toCodecStringTree(schema, { keepDeclarations: true })` so the
+ * string → number/boolean coercion happens. Usable only with schemas that have
+ * no decoding services — this is enforced at the type level via
+ * `S["DecodingServices"] = never` — and it throws synchronously when the input
+ * fails validation.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { FormDataX } from "@nunofyobiz/effect-extras"
+ *
+ * const formData = new FormData()
+ * formData.append("name", "John")
+ * formData.append("age", "30")
+ *
+ * const result = FormDataX.decodeSync(
+ *   formData,
+ *   Schema.Struct({ name: Schema.String, age: Schema.NumberFromString }),
+ * )
+ *
+ * assert.deepStrictEqual(result, { name: "John", age: 30 })
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export declare const decodeSync: {
+    <S extends Schema.Top & {
+        readonly DecodingServices: never;
+    }>(formData: FormData, schema: S): S["Type"];
+    <S extends Schema.Top & {
+        readonly DecodingServices: never;
+    }>(schema: S): (formData: FormData) => S["Type"];
+};
+//# sourceMappingURL=FormDataX.d.ts.map

package/dist/FormDataX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormDataX.d.ts","sourceRoot":"","sources":["../src/FormDataX.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAY,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,GAAG;QAAE,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAA;KAAE,EAC1D,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,CAAC,GACR,CAAC,CAAC,MAAM,CAAC,CAAC;IACb,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,GAAG;QAAE,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAA;KAAE,EAC1D,MAAM,EAAE,CAAC,GACR,CAAC,QAAQ,EAAE,QAAQ,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;CAQtC,CAAC"}

package/dist/FormDataX.js

@@ -0,0 +1,42 @@
+/**
+ * Helpers for decoding `FormData` with Effect `Schema`.
+ *
+ * @since 0.0.0
+ */
+import { Function, Schema } from "effect";
+/**
+ * Decodes a `FormData` into a typed value using a `Schema`, throwing on
+ * validation failure.
+ *
+ * Built on v4's native `Schema.fromFormData`, which first parses the `FormData`
+ * entries into a nested tree record (bracket-path notation is supported) and then
+ * decodes that tree with the provided inner schema. For schemas with non-string
+ * fields (for example `Schema.Int`), wrap the inner schema in
+ * `Schema.toCodecStringTree(schema, { keepDeclarations: true })` so the
+ * string → number/boolean coercion happens. Usable only with schemas that have
+ * no decoding services — this is enforced at the type level via
+ * `S["DecodingServices"] = never` — and it throws synchronously when the input
+ * fails validation.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { FormDataX } from "@nunofyobiz/effect-extras"
+ *
+ * const formData = new FormData()
+ * formData.append("name", "John")
+ * formData.append("age", "30")
+ *
+ * const result = FormDataX.decodeSync(
+ *   formData,
+ *   Schema.Struct({ name: Schema.String, age: Schema.NumberFromString }),
+ * )
+ *
+ * assert.deepStrictEqual(result, { name: "John", age: 30 })
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export const decodeSync = /*#__PURE__*/Function.dual(2, (formData, schema) => Schema.decodeUnknownSync(Schema.fromFormData(schema))(formData));
+//# sourceMappingURL=FormDataX.js.map

package/dist/FormDataX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormDataX.js","names":["Function","Schema","decodeSync","dual","formData","schema","decodeUnknownSync","fromFormData"],"sources":["../src/FormDataX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,SAASA,QAAQ,EAAEC,MAAM,QAAQ,QAAQ;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,MAAMC,UAAU,gBAQnBF,QAAQ,CAACG,IAAI,CACf,CAAC,EACD,CACEC,QAAkB,EAClBC,MAAS,KAETJ,MAAM,CAACK,iBAAiB,CAACL,MAAM,CAACM,YAAY,CAACF,MAAM,CAAC,CAAC,CAACD,QAAQ,CAAC,CAClE","ignoreList":[]}

package/dist/MapX.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Like `Map.prototype.get`, but when the key is absent it stores the computed
+ * fallback at that key and returns it. Mutates the input map in place.
+ *
+ * Use it for memoization-style caches where a miss should both populate the map
+ * and yield the value in one step. Throws if the resolved value is nullish (only
+ * possible when `fallbackIfNotFound` returns `null`/`undefined` for a value type
+ * that admits them — treated as a programmer error). Supports both data-first and
+ * data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { MapX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Miss: stores the fallback and returns it (data-first)
+ * const map = new Map<string, number>()
+ * assert.deepStrictEqual(MapX.getOrElseSetGet(map, "a", () => 1), 1)
+ * assert.deepStrictEqual(map.get("a"), 1)
+ *
+ * // Hit: returns the existing value, fallback is ignored (data-last)
+ * assert.deepStrictEqual(
+ *   pipe(map, MapX.getOrElseSetGet("a", () => 99)),
+ *   1
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export declare const getOrElseSetGet: (<K, V>(key: K, fallbackIfNotFound: () => V) => (map: Map<K, V>) => V) & (<K, V>(map: Map<K, V>, key: K, fallbackIfNotFound: () => V) => V);
+//# sourceMappingURL=MapX.d.ts.map

package/dist/MapX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapX.d.ts","sourceRoot":"","sources":["../src/MapX.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,eAAe,IACzB,CAAC,EAAE,CAAC,OAAO,CAAC,sBAAsB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,MACnE,CAAC,EAAE,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,MAAM,CAAC,KAAK,CAAC,CAahE,CAAC"}

package/dist/MapX.js

@@ -0,0 +1,49 @@
+/**
+ * Generic, framework-agnostic extensions for working with `Map`.
+ *
+ * @since 0.0.0
+ */
+import { Predicate } from "effect";
+import { dual } from "effect/Function";
+/**
+ * Like `Map.prototype.get`, but when the key is absent it stores the computed
+ * fallback at that key and returns it. Mutates the input map in place.
+ *
+ * Use it for memoization-style caches where a miss should both populate the map
+ * and yield the value in one step. Throws if the resolved value is nullish (only
+ * possible when `fallbackIfNotFound` returns `null`/`undefined` for a value type
+ * that admits them — treated as a programmer error). Supports both data-first and
+ * data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { MapX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Miss: stores the fallback and returns it (data-first)
+ * const map = new Map<string, number>()
+ * assert.deepStrictEqual(MapX.getOrElseSetGet(map, "a", () => 1), 1)
+ * assert.deepStrictEqual(map.get("a"), 1)
+ *
+ * // Hit: returns the existing value, fallback is ignored (data-last)
+ * assert.deepStrictEqual(
+ *   pipe(map, MapX.getOrElseSetGet("a", () => 99)),
+ *   1
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const getOrElseSetGet = /*#__PURE__*/dual(3, (map, key, fallbackIfNotFound) => {
+  if (!map.has(key)) {
+    map.set(key, fallbackIfNotFound());
+    return fallbackIfNotFound();
+  }
+  const existingValue = map.get(key);
+  if (Predicate.isNullish(existingValue)) {
+    throw new Error(`Value is nullable: ${String(key)}`);
+  }
+  return existingValue;
+});
+//# sourceMappingURL=MapX.js.map

package/dist/MapX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapX.js","names":["Predicate","dual","getOrElseSetGet","map","key","fallbackIfNotFound","has","set","existingValue","get","isNullish","Error","String"],"sources":["../src/MapX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,SAASA,SAAS,QAAQ,QAAQ;AAClC,SAASC,IAAI,QAAQ,iBAAiB;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAO,MAAMC,eAAe,gBAAGD,IAAI,CAGjC,CAAC,EAAE,CAAOE,GAAc,EAAEC,GAAM,EAAEC,kBAA2B,KAAO;EACpE,IAAI,CAACF,GAAG,CAACG,GAAG,CAACF,GAAG,CAAC,EAAE;IACjBD,GAAG,CAACI,GAAG,CAACH,GAAG,EAAEC,kBAAkB,EAAE,CAAC;IAClC,OAAOA,kBAAkB,EAAE;EAC7B;EAEA,MAAMG,aAAa,GAAGL,GAAG,CAACM,GAAG,CAACL,GAAG,CAAC;EAClC,IAAIJ,SAAS,CAACU,SAAS,CAACF,aAAa,CAAC,EAAE;IACtC,MAAM,IAAIG,KAAK,CAAC,sBAAsBC,MAAM,CAACR,GAAG,CAAC,EAAE,CAAC;EACtD;EAEA,OAAOI,aAAa;AACtB,CAAC,CAAC","ignoreList":[]}