@nunofyobiz/effect-extras 0.0.1

package/src/NonNullableX/NonNullableX.ts

@@ -0,0 +1,290 @@
+/**
+ * Helpers for working with non-nullable values.
+ *
+ * @since 0.0.0
+ */
+import {
+  Number as EffectNumber,
+  Match,
+  Order,
+  Ordering,
+  Predicate,
+} from "effect";
+import { dual } from "effect/Function";
+
+/**
+ * Returns `value` narrowed to `NonNullable<A>`, throwing an `Error` if it is
+ * `null` or `undefined`.
+ *
+ * Use it at trusted boundaries where a value is known to be present but typed as
+ * nullable, turning a silent `undefined` into a loud failure. An optional
+ * `variableName` is woven into the thrown message to aid debugging. This is the
+ * function re-exported as `nn` from the module barrel, a terse shorthand handy
+ * inside string interpolations.
+ *
+ * @example
+ * ```ts
+ * import { NonNullableX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(NonNullableX.fromNullableOrThrow("value"), "value")
+ *
+ * assert.throws(
+ *   () => NonNullableX.fromNullableOrThrow(null, "varName"),
+ *   /Value is nullable: null \(variable name: varName\)/
+ * )
+ * ```
+ *
+ * @category unsafe
+ * @since 0.0.0
+ */
+export const fromNullableOrThrow = <A>(
+  value: A,
+  variableName?: string,
+): NonNullable<A> => {
+  if (Predicate.isNotNullish(value)) {
+    return value;
+  }
+  throw new Error(
+    `Value is nullable: ${String(value)}${Predicate.isNotNullish(variableName) ? ` (variable name: ${variableName})` : ""}`,
+  );
+};
+
+/**
+ * Branches on whether `value` is nullish, passing the value narrowed to
+ * `NonNullable<A>` to the `whenNotNullable` handler.
+ *
+ * A nullable-aware sibling of `Match.value`: it folds a present-or-absent value
+ * into a single `B` without an `if`/`else` or a manual `!= null` check. Note that
+ * falsy-but-present values (`""`, `0`, `false`) take the `whenNotNullable`
+ * branch — only `null` and `undefined` are treated as absent. Supports both
+ * data-first and data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { NonNullableX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Data-first — present value flows through narrowed
+ * assert.deepStrictEqual(
+ *   NonNullableX.match("value", {
+ *     whenNullable: () => "nullable",
+ *     whenNotNullable: (value) => value
+ *   }),
+ *   "value"
+ * )
+ *
+ * // Data-last — null takes the whenNullable branch
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     null,
+ *     NonNullableX.match({
+ *       whenNullable: () => "nullable",
+ *       whenNotNullable: (value) => value
+ *     })
+ *   ),
+ *   "nullable"
+ * )
+ * ```
+ *
+ * @category pattern matching
+ * @since 0.0.0
+ */
+export const match = dual<
+  <A, B>(handlers: {
+    whenNullable: () => B;
+    whenNotNullable: (value: NonNullable<A>) => B;
+  }) => (value: A) => B,
+  <A, B>(
+    value: A,
+    handlers: {
+      whenNullable: () => B;
+      whenNotNullable: (value: NonNullable<A>) => B;
+    },
+  ) => B
+>(
+  2,
+  <A, B>(
+    value: A,
+    {
+      whenNullable,
+      whenNotNullable,
+    }: { whenNullable: () => B; whenNotNullable: (value: NonNullable<A>) => B },
+  ): B =>
+    Predicate.isNotNullish(value) ? whenNotNullable(value) : whenNullable(),
+);
+
+/**
+ * Applies `map` to `a` only when it is non-nullish, passing nullish inputs
+ * through unchanged.
+ *
+ * This is the nullable-preserving map: a present value is transformed to `B`,
+ * while `null` stays `null` and `undefined` stays `undefined`, so nullability is
+ * carried through the transformation. Supports both data-first and data-last
+ * (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { NonNullableX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Data-first — present value is transformed
+ * assert.deepStrictEqual(NonNullableX.map(1, (v: number) => v + 1), 2)
+ *
+ * // Data-last — nullish passes through unchanged
+ * const value: number | null = null
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     value,
+ *     NonNullableX.map<number | null, number>((v) => v + 1)
+ *   ),
+ *   null
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export const map = dual<
+  <A, B>(
+    map: (a: NonNullable<A>) => B,
+  ) => (a: A) => B | (null & A) | (undefined & A),
+  <A, B>(
+    a: A,
+    map: (a: NonNullable<A>) => B,
+  ) => B | (null & A) | (undefined & A)
+>(
+  2,
+  <A, B>(
+    a: A,
+    map: (a: NonNullable<A>) => B,
+  ): B | (null & A) | (undefined & A) => {
+    if (Predicate.isNotNullish(a)) {
+      return map(a);
+    }
+
+    if (Predicate.isNullish(a)) {
+      return a;
+    }
+
+    throw new Error(`Value is neither nullable nor non-nullable: ${String(a)}`);
+  },
+);
+
+/**
+ * Lifts a total function `(a: A) => B` into one that tolerates nullish input,
+ * applying it to present values and passing `null`/`undefined` through unchanged.
+ *
+ * Where `map` operates on a value, `lift` transforms the function itself,
+ * yielding a reusable `(a: A | null | undefined) => B | null | undefined` you can
+ * drop into a `pipe`. Use it to adapt a plain transform to a nullable pipeline
+ * without wrapping each call site.
+ *
+ * @example
+ * ```ts
+ * import { NonNullableX } from "@nunofyobiz/effect-extras"
+ * import { Number, pipe } from "effect"
+ *
+ * const addOne = NonNullableX.lift(Number.sum(1))
+ *
+ * assert.deepStrictEqual(pipe(1, addOne), 2)
+ * assert.deepStrictEqual(pipe(null, addOne), null)
+ * assert.deepStrictEqual(pipe(undefined, addOne), undefined)
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export const lift =
+  <A, B>(map: (a: A) => B) =>
+  (a: A | null | undefined): B | null | undefined => {
+    if (Predicate.isNullish(a)) {
+      return a;
+    }
+
+    return map(a);
+  };
+
+/**
+ * Extends an `Order.Order<A>` to an `Order.Order<A | null>`, deciding where
+ * `null` sorts relative to present values via the `behavior` argument.
+ *
+ * Pass `"value-null"` to push `null`s to the end and `"null-value"` to pull them
+ * to the front; two present values fall back to the wrapped order. Use it to sort
+ * collections that mix real values with gaps without a bespoke comparator.
+ * Supports both data-first and data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { NonNullableX } from "@nunofyobiz/effect-extras"
+ * import { Array, Order, pipe } from "effect"
+ *
+ * // "value-null" — nulls sorted last
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     [null, 1, 3, null, 2],
+ *     Array.sort(NonNullableX.nullableOrder(Order.Number, "value-null"))
+ *   ),
+ *   [1, 2, 3, null, null]
+ * )
+ *
+ * // "null-value" — nulls sorted first (data-last)
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     [null, 1, 3, null, 2],
+ *     Array.sort(pipe(Order.Number, NonNullableX.nullableOrder("null-value")))
+ *   ),
+ *   [null, null, 1, 2, 3]
+ * )
+ * ```
+ *
+ * @category ordering
+ * @since 0.0.0
+ */
+export const nullableOrder = dual<
+  (
+    behavior: "value-null" | "null-value",
+  ) => <A>(order: Order.Order<A>) => Order.Order<A | null>,
+  <A>(
+    order: Order.Order<A>,
+    behavior: "value-null" | "null-value",
+  ) => Order.Order<A | null>
+>(
+  2,
+  <A>(
+    order: Order.Order<A>,
+    behavior: "value-null" | "null-value",
+  ): Order.Order<A | null> => {
+    // Prepare to sort them based on their nullability
+    const { nullableSortCategory, valueSortCategory } = Match.value(
+      behavior,
+    ).pipe(
+      Match.when("value-null", () => ({
+        nullableSortCategory: 1,
+        valueSortCategory: 0,
+      })),
+      Match.when("null-value", () => ({
+        nullableSortCategory: 0,
+        valueSortCategory: 1,
+      })),
+      Match.exhaustive,
+    );
+
+    return (a: A | null, b: A | null): Ordering.Ordering => {
+      // Right off the bat, if they are both defined just return the regular ordering
+      if (Predicate.isNotNullish(a) && Predicate.isNotNullish(b)) {
+        return order(a, b);
+      }
+
+      // Otherwise figure out which category each value is
+      const aCategory = Predicate.isNotNullish(a)
+        ? valueSortCategory
+        : nullableSortCategory;
+
+      const bCategory = Predicate.isNotNullish(b)
+        ? valueSortCategory
+        : nullableSortCategory;
+
+      return EffectNumber.sign(aCategory - bCategory);
+    };
+  },
+);

package/src/NonNullableX/index.ts

@@ -0,0 +1,2 @@
+export * as NonNullableX from "./NonNullableX";
+export { fromNullableOrThrow as nn } from "./NonNullableX";

package/src/NumberX/NumberX.ts

@@ -0,0 +1,282 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Number` module.
+ *
+ * @since 0.0.0
+ */
+import { Number as EffectNumber, Option, pipe } from "effect";
+import { dual } from "effect/Function";
+
+// Internal — used by unsafeLogBase.
+const logBase = dual<
+  // Data-last typing
+  (base: number) => (number: number) => Option.Option<number>,
+  // Data-first typing
+  (number: number, base: number) => Option.Option<number>
+>(2, (number: number, base: number): Option.Option<number> => {
+  if (number <= 0) {
+    return Option.none();
+  }
+
+  if (base <= 0 || base === 1) {
+    return Option.none();
+  }
+
+  if (base < 1 && number >= 1) {
+    return Option.none();
+  }
+
+  if (base >= 1 && number < 1) {
+    return Option.none();
+  }
+
+  return Option.some(Math.log(number) / Math.log(base));
+});
+
+/**
+ * Computes the logarithm of `number` in the given `base`, throwing when the
+ * inputs fall outside the domain of `log`.
+ *
+ * Throws when `number <= 0`, when `base` is `<= 0` or `1`, or when `number` and
+ * `base` sit on opposite sides of `1` (a fractional base with `number >= 1`, or
+ * a base `>= 1` with `number < 1`) — cases where the real logarithm is
+ * undefined or non-finite. Reach for it only when the inputs are already known
+ * to be valid.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { NumberX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(NumberX.unsafeLogBase(8, 2), 3)
+ * assert.deepStrictEqual(NumberX.unsafeLogBase(100, 10), 2)
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe(8, NumberX.unsafeLogBase(2)), 3)
+ *
+ * // throws outside the domain of log
+ * assert.throws(() => NumberX.unsafeLogBase(0, 2))
+ * ```
+ *
+ * @category unsafe
+ * @since 0.0.0
+ */
+export const unsafeLogBase = dual<
+  (base: number) => (number: number) => number,
+  (number: number, base: number) => number
+>(2, (number: number, base: number): number =>
+  Option.getOrThrowWith(
+    logBase(number, base),
+    () => new Error(`Error calculating log base ${base} of ${number}`),
+  ),
+);
+
+/**
+ * Converts a number to a percentage of some total.
+ *
+ * Internal — used by unsafeToPercentOf.
+ */
+const toPercentOf = dual<
+  // Data-last typing
+  (total: number) => (numerator: number) => Option.Option<number>,
+  // Data-first typing
+  (numerator: number, total: number) => Option.Option<number>
+>(
+  2,
+  (numerator: number, total: number): Option.Option<number> =>
+    pipe(
+      EffectNumber.divide(numerator, total),
+      Option.map((ratio) => ratio * 100),
+    ),
+);
+
+/**
+ * Expresses `numerator` as a percentage of `total`, throwing on division by
+ * zero.
+ *
+ * Returns `(numerator / total) * 100`. When `total` is `0` the percentage is
+ * undefined, so this throws rather than returning `Infinity` or `NaN` — use it
+ * only when `total` is known to be non-zero.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { NumberX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(NumberX.unsafeToPercentOf(1, 2), 50)
+ * assert.deepStrictEqual(NumberX.unsafeToPercentOf(2, 1), 200)
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe(1, NumberX.unsafeToPercentOf(2)), 50)
+ *
+ * // throws on division by zero
+ * assert.throws(() => NumberX.unsafeToPercentOf(1, 0))
+ * ```
+ *
+ * @category unsafe
+ * @since 0.0.0
+ */
+export const unsafeToPercentOf = dual<
+  // Data-last typing
+  (total: number) => (numerator: number) => number,
+  // Data-first typing
+  (numerator: number, total: number) => number
+>(2, (numerator: number, total: number): number =>
+  Option.getOrThrowWith(
+    toPercentOf(numerator, total),
+    () => new Error(`Division by zero when dividing ${numerator} by ${total}`),
+  ),
+);
+
+/**
+ * Formats `number` with a fixed number of decimal places, returning a `string`.
+ *
+ * A pipeable wrapper around `Number.prototype.toFixed` — the result is rounded
+ * (not truncated) to `numberDigits` decimals and always carries exactly that
+ * many digits after the point.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { NumberX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(NumberX.toFixed(3.236242, 2), "3.24")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe(3.236242, NumberX.toFixed(0)), "3")
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export const toFixed = dual<
+  (numberDigits: number) => (number: number) => string,
+  (number: number, numberDigits: number) => string
+>(2, (number: number, numberDigits: number): string =>
+  number.toFixed(numberDigits),
+);
+
+/**
+ * Rounds `number` to a fixed number of decimal places, returning a `number`.
+ *
+ * Unlike {@link toFixed}, the result stays a `number` (no trailing zeroes) — it
+ * formats via `toFixed` then parses back, which sidesteps the usual
+ * floating-point rounding artifacts. See
+ * https://stackoverflow.com/a/29494612/22875620.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { NumberX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(NumberX.roundToDigits(3.236242, 2), 3.24)
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe(3.736242, NumberX.roundToDigits(0)), 4)
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export const roundToDigits = dual<
+  // Data-last typing
+  (numberDigits: number) => (number: number) => number,
+  // Data-first typing
+  (number: number, numberDigits: number) => number
+>(2, (number: number, numberDigits: number): number =>
+  Number(number.toFixed(numberDigits)),
+);
+
+/**
+ * Renders `number` as a `string`, left-padded with zeroes to at least
+ * `numberDigits` characters.
+ *
+ * If the number's string representation is already as long as (or longer than)
+ * `numberDigits`, it is returned unchanged.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { NumberX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(NumberX.padLeftZeroes(1, 3), "001")
+ *
+ * // longer than the target width is returned unchanged
+ * assert.deepStrictEqual(NumberX.padLeftZeroes(1000, 3), "1000")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe(10, NumberX.padLeftZeroes(3)), "010")
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export const padLeftZeroes = dual<
+  (numberDigits: number) => (number: number) => string,
+  (number: number, numberDigits: number) => string
+>(2, (number: number, numberDigits: number): string =>
+  number.toString().padStart(numberDigits, "0"),
+);
+
+/**
+ * Converts a `0`-indexed value to its `1`-indexed rank by adding `1`.
+ *
+ * Handy for presentation where humans count from one (e.g. the element at
+ * index `0` is shown as "item 1").
+ *
+ * @example
+ * ```ts
+ * import { NumberX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(NumberX.indexToRank(0), 1)
+ * assert.deepStrictEqual(NumberX.indexToRank(4), 5)
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export const indexToRank = (index: number): number => index + 1;
+
+const EXCEL_COLUMNS_BASE_CHARS = [..."ABCDEFGHIJKLMNOPQRSTUVWXYZ"];
+
+/**
+ * Converts a `0`-indexed column number into its bijective base-26 spreadsheet
+ * label (`A`, `B`, …, `Z`, `AA`, `AB`, …).
+ *
+ * Returns `None` for a negative `index`; every non-negative index maps to a
+ * `Some` label. Indexing is `0`-based here, so `0` is `"A"` and `25` is `"Z"`,
+ * unlike the `1`-based numbering shown in most spreadsheet references.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { NumberX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(NumberX.indexToExcel(0), Option.some("A"))
+ * assert.deepStrictEqual(NumberX.indexToExcel(26), Option.some("AA"))
+ * assert.deepStrictEqual(NumberX.indexToExcel(-1), Option.none())
+ * ```
+ *
+ * @category conversions
+ * @since 0.0.0
+ */
+export const indexToExcel = (index: number): Option.Option<string> => {
+  if (index < 0) {
+    return Option.none();
+  }
+
+  const baseChars = EXCEL_COLUMNS_BASE_CHARS;
+
+  let excel = "";
+  const base = baseChars.length;
+  do {
+    excel = baseChars[index % base] + excel;
+    index = Math.floor(index / base) - 1;
+  } while (index >= 0);
+
+  return Option.some(excel);
+};

package/src/NumberX/index.ts

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