@nunofyobiz/effect-extras 2.0.0 → 2.1.0

package/dist/ArrayX.js

@@ -0,0 +1,547 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Array` module.
+ *
+ * @since 0.0.0
+ */
+import { Array, Option, Predicate, Record, pipe } from "effect";
+import { dual, identity } from "effect/Function";
+import * as RecordX from "./RecordX.js";
+import * as WarnResult from "./WarnResult.js";
+import * as ResultX from "./ResultX.js";
+/**
+ * Returns a shallow copy of `array` between `start` (inclusive) and `end`
+ * (exclusive), as a pipeable, dual-form alias for `Array.prototype.slice`.
+ *
+ * `Array.prototype.slice` is already non-mutating (it returns a shallow copy),
+ * but it isn't pipeable. This helper makes it composable inside `pipe(...)`
+ * chains alongside the rest of the codebase's Effect-style utilities.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(ArrayX.slice([1, 2, 3, 4], 1, 3), [2, 3])
+ *
+ * // data-last (pipeable)
+ * assert.deepStrictEqual(pipe([1, 2, 3, 4], ArrayX.slice(1, 3)), [2, 3])
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const slice = /*#__PURE__*/dual(3, (array, start, end) => array.slice(start, end));
+/**
+ * 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<A, B>`: `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 { ArrayX, 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(ArrayX.zipWithWarnings([1, 2, 3], [10, 20], describe), [
+ *   "both 1/10",
+ *   "both 2/20",
+ *   "warnings 3",
+ * ])
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const zipWithWarnings = /*#__PURE__*/dual(3, (array1, array2, f) => {
+  const newLength = Math.max(array1.length, array2.length);
+  if (newLength === 0) {
+    return [];
+  }
+  return Array.makeBy(newLength, index => {
+    if (index < array1.length && index < array2.length) {
+      return f(WarnResult.SuccessWithWarnings({
+        warnings: array1[index],
+        success: array2[index]
+      }));
+    }
+    if (index < array1.length) {
+      return f(WarnResult.WarningsOnly({
+        warnings: array1[index]
+      }));
+    }
+    if (index < array2.length) {
+      return f(WarnResult.SuccessOnly({
+        success: array2[index]
+      }));
+    }
+    throw new Error(`Index ${index} is out of bounds for array1 and array2`);
+  });
+});
+/**
+ * Moves a unique item within an array to a new position, using a custom identification function.
+ *
+ * **Assumption**: Items should be unique in the array based on the identification function.
+ *
+ * **Happy case**: If the source item is found exactly once and the destination reference item is found (or null, to move to the end):
+ * The source item is moved from its current position to the new position
+ *
+ * **Source item not found**: The array is returned unchanged, regardless of whether the destination reference item exists.
+ *
+ * **Source item found but duplicated**:
+ * - If destination reference item is found: All copies of the source item are removed, then a single copy is inserted before the destination reference item
+ * - If destination reference item is not found: The array is returned completely unchanged (no items are moved or removed)
+ *
+ * Used internally by {@link insertUniq}; not exported as the codebase has no
+ * direct callers.
+ */
+const moveUniqWith = /*#__PURE__*/dual(2, (inputArray, {
+  identify,
+  sourceId,
+  moveToBeLeftOfId
+}) => {
+  const array = [...inputArray];
+  // Find the source item and its index
+  const sourceIndex = array.findIndex(item => identify(item) === sourceId);
+  if (sourceIndex < 0) {
+    return array;
+  }
+  const sourceItem = array[sourceIndex];
+  // Remove ALL occurrences of the source item from the array
+  const arrayWithoutSource = array.filter(item => identify(item) !== sourceId);
+  // If moveToBeLeftOfId is null, move to end
+  if (moveToBeLeftOfId === null) {
+    return [...arrayWithoutSource, sourceItem];
+  }
+  // Find the destination index in the array without the source item
+  const destinationIndex = arrayWithoutSource.findIndex(item => identify(item) === moveToBeLeftOfId);
+  if (destinationIndex < 0) {
+    // If destination not found, leave array completely unchanged
+    return array;
+  }
+  // Insert the source item before the destination index
+  return [...slice(arrayWithoutSource, 0, destinationIndex), sourceItem, ...slice(arrayWithoutSource, destinationIndex, arrayWithoutSource.length)];
+});
+/**
+ * Inserts or moves a unique item in an array at a specified position.
+ *
+ * **Assumption**: Items should be unique in the array based on standard equality.
+ *
+ * **Happy case**: If the item doesn't exist in the array and the destination reference item is found:
+ * The new item is inserted before the destination reference item
+ *
+ * **Item not found in array**:
+ * - If destination reference item is found: The new item is inserted before the destination reference item
+ * - If destination reference item is not found: The new item is inserted at the end of the array
+ *
+ * **Item found but duplicated**:
+ * - If destination reference item is found: All existing copies are removed, then a single copy is inserted before the destination reference item
+ * - If destination reference item is not found: All existing copies are removed, then a single copy is inserted at the end of the array
+ *
+ * @param array - The input array to modify
+ * @param config - Configuration object containing:
+ *   - `item`: The item to insert or update (must be a string or number)
+ *   - `insertToBeLeftOf`: The item to position the new/updated item before,
+ *                         or null to insert at the end
+ *
+ * @returns A new array with the item inserted or moved to the specified position
+ *
+ * @example
+ * ```ts
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * // Move an existing item to sit just before "c"
+ * assert.deepStrictEqual(
+ *   ArrayX.insertUniq(["a", "b", "c", "d"], { item: "a", insertToBeLeftOf: "c" }),
+ *   ["b", "a", "c", "d"],
+ * )
+ *
+ * // Insert a brand-new item; unknown destination falls through to the end
+ * assert.deepStrictEqual(
+ *   ArrayX.insertUniq(["a", "b"], { item: "new", insertToBeLeftOf: null }),
+ *   ["a", "b", "new"],
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const insertUniq = /*#__PURE__*/dual(2, (array, {
+  item,
+  insertToBeLeftOf
+}) => {
+  // Always deduplicate and append the item to the end for insertUniq
+  // This ensures we always have exactly one copy of the item, regardless of destination
+  const arrayWithNewItem = pipe(array, Array.filter(existingItem => existingItem !== item), Array.append(item));
+  // Now move that new item to the desired position
+  return moveUniqWith(arrayWithNewItem, {
+    identify: identity,
+    sourceId: item,
+    moveToBeLeftOfId: insertToBeLeftOf
+  });
+});
+/**
+ * Maps over `array` while threading an accumulator, iterating from right to
+ * left instead of left to right.
+ *
+ * Identical to `Array.mapAccum`, except the traversal order is reversed: `f` is
+ * called on the last element first, and the resulting array is returned in the
+ * original (left-to-right) order. Use it when each element's mapped value
+ * depends on state accumulated from the elements that follow it.
+ *
+ * @example
+ * ```ts
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * // Running suffix-sum: each slot holds the sum of itself and everything after it
+ * assert.deepStrictEqual(
+ *   ArrayX.mapRightAccum([1, 2, 3], 0, (total, n) => [total + n, total + n]),
+ *   [6, [6, 5, 3]],
+ * )
+ * ```
+ *
+ * @category folding
+ * @since 0.0.0
+ */
+export const mapRightAccum = /*#__PURE__*/dual(3, (array, initialAccumulator, f) => {
+  const [accumulator, result] = pipe(array, Array.reverse, Array.mapAccum(initialAccumulator, f));
+  return [accumulator, Array.reverse(result)];
+});
+/**
+ * Returns the maximum element of `array` according to `order`, wrapped in an
+ * `Option` so that empty arrays are handled safely.
+ *
+ * Effect's `Array.max` throws on an empty array; this returns `Option.none()`
+ * instead, and `Option.some(max)` otherwise. Reach for it whenever the input
+ * array might be empty.
+ *
+ * @example
+ * ```ts
+ * import { Option, Order, pipe } from "effect"
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   pipe([3, 7, 2], ArrayX.maxOption(Order.Number)),
+ *   Option.some(7),
+ * )
+ * assert.deepStrictEqual(
+ *   pipe([], ArrayX.maxOption(Order.Number)),
+ *   Option.none(),
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const maxOption = /*#__PURE__*/dual(2, (array, order) => pipe(
+// If the array is empty, there is no max
+array, Option.liftPredicate(Array.isArrayNonEmpty),
+// If it is non-empty, get the max
+Option.map(Array.max(order))));
+const takeFirstOrLastWhere = /*#__PURE__*/dual(3, (array, predicate, takeOne) => pipe(
+// Keep only the items that match
+array, Array.filter(predicate),
+// If there is anything left, take one
+Option.liftPredicate(Array.isArrayNonEmpty), Option.map(takeOne)));
+/**
+ * Returns the smallest element of `array` (per `order`) that matches
+ * `predicate`, narrowed to the refined type `B`, or `Option.none()` if none
+ * match.
+ *
+ * Combines a refinement filter with `Array.min`: only elements satisfying
+ * `predicate` are considered, and the minimum of those (by `order`) is
+ * returned. The refinement narrows the element type, so the resulting `Option`
+ * carries the more specific `B`.
+ *
+ * @example
+ * ```ts
+ * import { Option, Order, pipe } from "effect"
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * const isEven = (n: number): n is number => n % 2 === 0
+ *
+ * assert.deepStrictEqual(
+ *   pipe([3, 4, 1, 2, 5], ArrayX.takeFirstWhere(isEven, Order.Number)),
+ *   Option.some(2),
+ * )
+ * assert.deepStrictEqual(
+ *   pipe([1, 3, 5], ArrayX.takeFirstWhere(isEven, Order.Number)),
+ *   Option.none(),
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const takeFirstWhere = /*#__PURE__*/dual(3, (array, predicate, order) => takeFirstOrLastWhere(array, predicate, Array.min(order)));
+/**
+ * Returns the largest element of `array` (per `order`) that matches
+ * `predicate`, narrowed to the refined type `B`, or `Option.none()` if none
+ * match.
+ *
+ * The mirror of {@link takeFirstWhere}: only elements satisfying `predicate`
+ * are considered, and the maximum of those (by `order`) is returned. The
+ * refinement narrows the element type, so the resulting `Option` carries the
+ * more specific `B`.
+ *
+ * @example
+ * ```ts
+ * import { Option, Order, pipe } from "effect"
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * const isEven = (n: number): n is number => n % 2 === 0
+ *
+ * assert.deepStrictEqual(
+ *   pipe([3, 4, 1, 2, 5], ArrayX.takeLastWhere(isEven, Order.Number)),
+ *   Option.some(4),
+ * )
+ * assert.deepStrictEqual(
+ *   pipe([1, 3, 5], ArrayX.takeLastWhere(isEven, Order.Number)),
+ *   Option.none(),
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const takeLastWhere = /*#__PURE__*/dual(3, (array, predicate, order) => takeFirstOrLastWhere(array, predicate, Array.max(order)));
+/**
+ * Groups `items` into a partial record keyed by the category each item maps to
+ * via `categorize`.
+ *
+ * Each item is appended to the array under its category, preserving input
+ * order. The result is `Partial<Record<C, A[]>>` because not every possible
+ * category `C` is guaranteed to appear — only categories that received at least
+ * one item are present.
+ *
+ * @example
+ * ```ts
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * const parity = (n: number) => (n % 2 === 0 ? "even" : "odd")
+ *
+ * assert.deepStrictEqual(ArrayX.categorize([1, 2, 3, 4], parity), {
+ *   odd: [1, 3],
+ *   even: [2, 4],
+ * })
+ * ```
+ *
+ * @category folding
+ * @since 0.0.0
+ */
+export const categorize = (items, categorize) => Array.reduce(items,
+// Start with an empty record of categorized items. `Record.empty()`
+// returns a `NonLiteralKey<C>`-keyed record, which is structurally
+// equivalent to `Partial<Record<C, A[]>>`; the cast tells TypeScript
+// we'll be writing typed keys back via the reducer below.
+Record.empty(),
+// For each item, add it to the appropriate category
+(categorizedItems, item) => RecordX.upsert(categorizedItems, categorize(item),
+// This is the next item's category
+Option.match({
+  // This is the first item in this category, so create a new array
+  onNone: () => Array.of(item),
+  // Append the item to the existing array
+  onSome: Array.append(item)
+})));
+/**
+ * Removes all `null` and `undefined` elements from `array`, narrowing the
+ * element type to `NonNullable<A>`.
+ *
+ * Falsy-but-present values such as `0` and `""` are kept — only nullish values
+ * are dropped. Use it to clean up an array of optionals into a dense array of
+ * known-present values.
+ *
+ * @example
+ * ```ts
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   ArrayX.compactNullable([1, null, 2, undefined, 0, ""]),
+ *   [1, 2, 0, ""],
+ * )
+ * ```
+ *
+ * @category filtering
+ * @since 0.0.0
+ */
+export const compactNullable = array => Array.filter(array, Predicate.isNotNullish);
+/**
+ * Drops the leading elements of `array` until `predicate` first holds, keeping
+ * everything from the first match onward.
+ *
+ * The first matching element and all subsequent elements are retained
+ * regardless of whether they match — only the prefix *before* the first match
+ * is trimmed. If nothing matches, returns an empty array.
+ *
+ * @example
+ * ```ts
+ * import { Predicate } from "effect"
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * // Trims the leading strings, then keeps everything (including the trailing "b")
+ * assert.deepStrictEqual(
+ *   ArrayX.filterHead(["a", 1, 2, "b"], Predicate.isNumber),
+ *   [1, 2, "b"],
+ * )
+ * ```
+ *
+ * @category filtering
+ * @since 0.0.0
+ */
+export const filterHead = /*#__PURE__*/dual(2, (array, predicate) => {
+  const firstMatchingIndex = Array.findFirstIndex(array, predicate);
+  return Option.match(firstMatchingIndex, {
+    onSome: index => slice(array, index, array.length),
+    onNone: () => []
+  });
+});
+/**
+ * Drops the trailing elements of `array` after `predicate` last holds, keeping
+ * everything up to and including the last match.
+ *
+ * The mirror of {@link filterHead}: the last matching element and all preceding
+ * elements are retained regardless of whether they match — only the suffix
+ * *after* the last match is trimmed. If nothing matches, returns an empty
+ * array.
+ *
+ * @example
+ * ```ts
+ * import { Predicate } from "effect"
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * // Keeps the leading "a" and trims the trailing strings after the last number
+ * assert.deepStrictEqual(
+ *   ArrayX.filterTail(["a", 1, 2, "b"], Predicate.isNumber),
+ *   ["a", 1, 2],
+ * )
+ * ```
+ *
+ * @category filtering
+ * @since 0.0.0
+ */
+export const filterTail = /*#__PURE__*/dual(2, (array, predicate) => {
+  const lastMatchingIndex = Array.findLastIndex(array, predicate);
+  return Option.match(lastMatchingIndex, {
+    onSome: index => slice(array, 0, index + 1),
+    onNone: () => []
+  });
+});
+/**
+ * Maps `f` over `array` and drops every result that is `null` or `undefined`,
+ * narrowing the element type to `NonNullable<B>`.
+ *
+ * A nullable-friendly `Array.filterMap`: where `filterMap` expects `f` to
+ * return an `Option`, this accepts a function returning `B | null` (or
+ * `undefined`) and treats nullish results as "skip this element". Falsy-but-
+ * present values such as `0` and `""` are kept.
+ *
+ * @example
+ * ```ts
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * // Keep only the even numbers, mapped to their halves
+ * assert.deepStrictEqual(
+ *   ArrayX.filterMapNullable([1, 2, 3, 4], (n) => (n % 2 === 0 ? n / 2 : null)),
+ *   [1, 2],
+ * )
+ * ```
+ *
+ * @category filtering
+ * @since 0.0.0
+ */
+export const filterMapNullable = /*#__PURE__*/dual(2, (array, f) => pipe(array, Array.filterMap(value => pipe(f(value), Option.fromNullishOr, ResultX.fromOption))));
+/**
+ * Finds the first element of a 2-dimensional array (row-major order) matching
+ * `predicate`, returning it alongside its row and column indices.
+ *
+ * Scans rows top-to-bottom and, within each row, left-to-right. On a match
+ * returns `Option.some([value, rowIndex, columnIndex])`; if no element matches
+ * (or the grid is empty), returns `Option.none()`.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * const grid = [
+ *   ["A", "B", "C"],
+ *   ["D", "E", "F"],
+ * ]
+ *
+ * assert.deepStrictEqual(
+ *   ArrayX.findFirstWithIndex2d(grid, (cell) => cell === "E"),
+ *   Option.some(["E", 1, 1]),
+ * )
+ * ```
+ *
+ * @category getters
+ * @since 0.0.0
+ */
+export const findFirstWithIndex2d = /*#__PURE__*/dual(2, (array, predicate) => Array.findFirstWithIndex(array, row => Array.findFirstWithIndex(row, predicate)).pipe(Option.map(([[value, secondIndex], firstIndex]) => [value, firstIndex, secondIndex])));
+/**
+ * Splits `array` into runs of consecutive elements that share the same group
+ * value, where the group is derived by `chunk` and compared with the provided
+ * `Equivalence`.
+ *
+ * Only *adjacent* elements are grouped: a new run starts every time the group
+ * value changes from the previous element. Each entry in the result carries the
+ * `group` value and the non-empty array of `values` that produced it, preserving
+ * input order. An empty input yields an empty array. Use it for run-length-style
+ * segmentation; reach for `Array.groupBy` instead when you want all elements
+ * with the same key collapsed regardless of position.
+ *
+ * @example
+ * ```ts
+ * import { Equivalence } from "effect"
+ * import { ArrayX } from "@nunofyobiz/effect-extras"
+ *
+ * // Group adjacent numbers by parity
+ * assert.deepStrictEqual(
+ *   ArrayX.chunkBy([2, 4, 1, 3, 6], (n) => n % 2 === 0, Equivalence.Boolean),
+ *   [
+ *     { group: true, values: [2, 4] },
+ *     { group: false, values: [1, 3] },
+ *     { group: true, values: [6] },
+ *   ],
+ * )
+ * ```
+ *
+ * @category folding
+ * @since 0.0.0
+ */
+export const chunkBy = /*#__PURE__*/dual(3, (array, chunk, chunkEquals) => {
+  if (array.length === 0) {
+    return [];
+  }
+  const result = [];
+  for (const item of array) {
+    const groupValue = chunk(item);
+    if (result.length > 0) {
+      const lastGroup = result.at(-1);
+      if (lastGroup && chunkEquals(lastGroup.group, groupValue)) {
+        // Add to current group
+        lastGroup.values.push(item);
+        continue;
+      }
+    }
+    // Start a new group
+    result.push({
+      group: groupValue,
+      values: Array.of(item)
+    });
+  }
+  return result;
+});
+//# sourceMappingURL=ArrayX.js.map

package/dist/ArrayX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArrayX.js","names":["Array","Option","Predicate","Record","pipe","dual","identity","RecordX","WarnResult","ResultX","slice","array","start","end","zipWithWarnings","array1","array2","f","newLength","Math","max","length","makeBy","index","SuccessWithWarnings","warnings","success","WarningsOnly","SuccessOnly","Error","moveUniqWith","inputArray","identify","sourceId","moveToBeLeftOfId","sourceIndex","findIndex","item","sourceItem","arrayWithoutSource","filter","destinationIndex","insertUniq","insertToBeLeftOf","arrayWithNewItem","existingItem","append","mapRightAccum","initialAccumulator","accumulator","result","reverse","mapAccum","maxOption","order","liftPredicate","isArrayNonEmpty","map","takeFirstOrLastWhere","predicate","takeOne","takeFirstWhere","min","takeLastWhere","categorize","items","reduce","empty","categorizedItems","upsert","match","onNone","of","onSome","compactNullable","isNotNullish","filterHead","firstMatchingIndex","findFirstIndex","filterTail","lastMatchingIndex","findLastIndex","filterMapNullable","filterMap","value","fromNullishOr","fromOption","findFirstWithIndex2d","findFirstWithIndex","row","secondIndex","firstIndex","chunkBy","chunk","chunkEquals","groupValue","lastGroup","at","group","values","push"],"sources":["../src/ArrayX.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/BigIntX.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare const toNumberOrThrow: (value: bigint) => number;
+//# sourceMappingURL=BigIntX.d.ts.map

package/dist/BigIntX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BigIntX.d.ts","sourceRoot":"","sources":["../src/BigIntX.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,MAK7C,CAAC"}

package/dist/BigIntX.js

@@ -0,0 +1,30 @@
+/**
+ * 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.toNumber(value).pipe(Option.getOrThrowWith(() => new Error(`Value ${value} is outside safe integer range`)));
+//# sourceMappingURL=BigIntX.js.map

package/dist/BigIntX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BigIntX.js","names":["BigInt","Option","toNumberOrThrow","value","toNumber","pipe","getOrThrowWith","Error"],"sources":["../src/BigIntX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,SAASA,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AAEvC;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMC,eAAe,GAAIC,KAAa,IAC3CH,MAAM,CAACI,QAAQ,CAACD,KAAK,CAAC,CAACE,IAAI,CACzBJ,MAAM,CAACK,cAAc,CACnB,MAAM,IAAIC,KAAK,CAAC,SAASJ,KAAK,gCAAgC,CAAC,CAChE,CACF","ignoreList":[]}

package/dist/BooleanX.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare const toBinary: (value: boolean) => 0 | 1;
+//# sourceMappingURL=BooleanX.d.ts.map

package/dist/BooleanX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BooleanX.d.ts","sourceRoot":"","sources":["../src/BooleanX.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,CAAC,GAAG,CAAoB,CAAC"}

package/dist/BooleanX.js

@@ -0,0 +1,25 @@
+/**
+ * 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 => value ? 1 : 0;
+//# sourceMappingURL=BooleanX.js.map

package/dist/BooleanX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BooleanX.js","names":["toBinary","value"],"sources":["../src/BooleanX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA;;;;;;;;;;;;;;;;;;AAkBA,OAAO,MAAMA,QAAQ,GAAIC,KAAc,IAAaA,KAAK,GAAG,CAAC,GAAG,CAAE","ignoreList":[]}