@nunofyobiz/effect-extras 2.0.0 → 3.0.0

package/dist/ArrayX.js

@@ -0,0 +1,493 @@
+/**
+ * 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 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));
+/**
+ * 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);
+  // Unreachable via the public API: the only caller (`insertUniq`) appends the
+  // item before delegating here, so `sourceId` is always present. Kept as a
+  // defensive no-op for direct (internal) callers.
+  /* v8 ignore next 3 */
+  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","ResultX","slice","array","start","end","moveUniqWith","inputArray","identify","sourceId","moveToBeLeftOfId","sourceIndex","findIndex","item","sourceItem","arrayWithoutSource","filter","destinationIndex","length","insertUniq","insertToBeLeftOf","arrayWithNewItem","existingItem","append","mapRightAccum","initialAccumulator","f","accumulator","result","reverse","mapAccum","maxOption","order","liftPredicate","isArrayNonEmpty","map","max","takeFirstOrLastWhere","predicate","takeOne","takeFirstWhere","min","takeLastWhere","categorize","items","reduce","empty","categorizedItems","upsert","match","onNone","of","onSome","compactNullable","isNotNullish","filterHead","firstMatchingIndex","findFirstIndex","index","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":[]}