@nunofyobiz/effect-extras 0.0.1

package/src/ArrayX/index.ts

@@ -0,0 +1 @@
+export * as ArrayX from "./ArrayX";

package/src/BigIntX/BigIntX.ts

@@ -0,0 +1,35 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `BigInt` module.
+ *
+ * @since 0.0.0
+ */
+import { BigInt, Option } from "effect";
+
+/**
+ * Converts a `bigint` to a `number`, throwing when the value cannot be
+ * represented exactly.
+ *
+ * Delegates to Effect's `BigInt.toNumber`, which returns `None` once the
+ * `bigint` falls outside the safe integer range (`Number.MAX_SAFE_INTEGER`).
+ * This unwraps that `Option`, throwing instead of silently losing precision —
+ * use it only when the value is known to fit.
+ *
+ * @example
+ * ```ts
+ * import { BigIntX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(BigIntX.toNumberOrThrow(42n), 42)
+ *
+ * // throws when outside the safe integer range
+ * assert.throws(() => BigIntX.toNumberOrThrow(9007199254740993n))
+ * ```
+ *
+ * @category unsafe
+ * @since 0.0.0
+ */
+export const toNumberOrThrow = (value: bigint): number =>
+  BigInt.toNumber(value).pipe(
+    Option.getOrThrowWith(
+      () => new Error(`Value ${value} is outside safe integer range`),
+    ),
+  );

package/src/BigIntX/index.ts

@@ -0,0 +1 @@
+export * as BigIntX from "./BigIntX";

package/src/BooleanX/BooleanX.ts

@@ -0,0 +1,24 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Boolean` module.
+ *
+ * @since 0.0.0
+ */
+/**
+ * Converts a `boolean` to its binary digit: `1` for `true`, `0` for `false`.
+ *
+ * Useful when a numeric flag is required — summing booleans to count how many
+ * predicates hold, or feeding a bit into bitwise math or an external API that
+ * expects `0`/`1` rather than `false`/`true`.
+ *
+ * @example
+ * ```ts
+ * import { BooleanX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(BooleanX.toBinary(true), 1)
+ * assert.deepStrictEqual(BooleanX.toBinary(false), 0)
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export const toBinary = (value: boolean): 0 | 1 => (value ? 1 : 0);

package/src/BooleanX/index.ts

@@ -0,0 +1 @@
+export * as BooleanX from "./BooleanX";

package/src/DurationX/DurationX.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 { BigIntX } from "../BigIntX";
+
+// 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 = dual<
+  // Data-last typing
+  (that: DateTime.DateTime) => (self: DateTime.DateTime) => Duration.Duration,
+  // Data-first typing
+  (self: DateTime.DateTime, that: DateTime.DateTime) => Duration.Duration
+>(
+  2,
+  (self: DateTime.DateTime, that: DateTime.DateTime): Duration.Duration =>
+    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 = dual<
+  // Data-last typing
+  (unit: Duration.Unit) => (duration: Duration.Duration) => number,
+  // Data-first typing
+  (duration: Duration.Duration, unit: Duration.Unit) => number
+>(2, (duration: Duration.Duration, unit: Duration.Unit): number =>
+  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 = dual<
+  // Data-last typing
+  (unit: Duration.Unit) => (value: number) => Duration.Duration,
+  // Data-first typing
+  (value: number, unit: Duration.Unit) => Duration.Duration
+>(
+  2,
+  (value: number, unit: Duration.Unit): Duration.Duration =>
+    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 = dual<
+  // Data-last typing
+  (
+    unit: Duration.Unit,
+    map: (numberOfUnits: number) => number,
+  ) => (duration: Duration.Duration) => Duration.Duration,
+  // Data-first typing
+  (
+    duration: Duration.Duration,
+    unit: Duration.Unit,
+    map: (numberOfUnits: number) => number,
+  ) => Duration.Duration
+>(
+  3,
+  (
+    duration: Duration.Duration,
+    unit: Duration.Unit,
+    map: (numberOfUnits: number) => number,
+  ): Duration.Duration =>
+    pipe(
+      duration,
+
+      // Convert to that unit
+      toUnit(unit),
+
+      // Truncate to the requested number of digits
+      map,
+
+      // Convert back to a duration
+      fromUnit(unit),
+    ),
+);

package/src/DurationX/index.ts

@@ -0,0 +1 @@
+export * as DurationX from "./DurationX";

package/src/EffectX/EffectX.ts

@@ -0,0 +1,183 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Effect` module.
+ *
+ * @since 0.0.0
+ */
+import { Cause, Duration, Effect, Option, Predicate, 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 = 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 = dual<
+  <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>
+>(
+  2,
+  <A, E1, E2, R>(
+    effect: Effect.Effect<Option.Option<A>, E1, R>,
+    onNone: () => E2,
+  ): Effect.Effect<A, E1 | E2, R> =>
+    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: {
+  <E>(onNone: () => E): <A>(option: Option.Option<A>) => Effect.Effect<A, E>;
+  <A, E>(option: Option.Option<A>, onNone: () => E): Effect.Effect<A, E>;
+} = dual(
+  2,
+  <A, E>(option: Option.Option<A>, onNone: () => E): Effect.Effect<A, E> =>
+    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 = <A, B extends A>({
+  try: doTry,
+  until: isDone,
+  sleepDuration = USER_INSTANT_DURATION,
+  maxDuration,
+}: {
+  try: () => A;
+  until: Predicate.Refinement<A, B>;
+  sleepDuration?: Duration.Duration;
+  maxDuration: Duration.Duration;
+}): Effect.Effect<B, Cause.TimeoutError, never> => {
+  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`,
+        ),
+      ),
+    ),
+  );
+};

package/src/EffectX/index.ts

@@ -0,0 +1 @@
+export * as EffectX from "./EffectX";

package/src/FormDataX/FormDataX.ts

@@ -0,0 +1,57 @@
+/**
+ * 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: {
+  <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"];
+} = Function.dual(
+  2,
+  <S extends Schema.Top & { readonly DecodingServices: never }>(
+    formData: FormData,
+    schema: S,
+  ): S["Type"] =>
+    Schema.decodeUnknownSync(Schema.fromFormData(schema))(formData),
+);

package/src/FormDataX/index.ts

@@ -0,0 +1 @@
+export * as FormDataX from "./FormDataX";

package/src/MapX/MapX.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 = dual<
+  <K, V>(key: K, fallbackIfNotFound: () => V) => (map: Map<K, V>) => V,
+  <K, V>(map: Map<K, V>, key: K, fallbackIfNotFound: () => V) => V
+>(3, <K, V>(map: Map<K, V>, key: K, fallbackIfNotFound: () => V): V => {
+  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;
+});

package/src/MapX/index.ts

@@ -0,0 +1 @@
+export * as MapX from "./MapX";