@nunofyobiz/effect-extras 2.0.0 → 2.1.0

package/dist/NonNullableX.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Helpers for working with non-nullable values.
+ *
+ * @since 0.0.0
+ */
+import { Order } from "effect";
+/**
+ * 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 declare const fromNullableOrThrow: <A>(value: A, variableName?: string) => NonNullable<A>;
+/**
+ * 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 declare const match: (<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);
+/**
+ * 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 declare const map: (<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));
+/**
+ * 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 declare const lift: <A, B>(map: (a: A) => B) => (a: A | null | undefined) => B | null | undefined;
+/**
+ * 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 declare const nullableOrder: ((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>);
+//# sourceMappingURL=NonNullableX.d.ts.map

package/dist/NonNullableX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NonNullableX.d.ts","sourceRoot":"","sources":["../src/NonNullableX.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAGL,KAAK,EAGN,MAAM,QAAQ,CAAC;AAGhB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,EACnC,OAAO,CAAC,EACR,eAAe,MAAM,KACpB,WAAW,CAAC,CAAC,CAOf,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,KAAK,IACf,CAAC,EAAE,CAAC,YAAY;IACf,YAAY,EAAE,MAAM,CAAC,CAAC;IACtB,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;CAC/C,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,MACpB,CAAC,EAAE,CAAC,SACI,CAAC,YACE;IACR,YAAY,EAAE,MAAM,CAAC,CAAC;IACtB,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;CAC/C,KACE,CAAC,CAWP,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,GAAG,IACb,CAAC,EAAE,CAAC,OACE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,KAC1B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,MAC9C,CAAC,EAAE,CAAC,KACA,CAAC,OACC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,KAC1B,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,CAiBtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,IAAI,GACd,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MACtB,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,KAAG,CAAC,GAAG,IAAI,GAAG,SAMrC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,aAAa,cAEZ,YAAY,GAAG,YAAY,KAClC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,MACvD,CAAC,SACO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,YACX,YAAY,GAAG,YAAY,KAClC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAwC3B,CAAC"}

package/dist/NonNullableX.js

@@ -0,0 +1,212 @@
+/**
+ * Helpers for working with non-nullable values.
+ *
+ * @since 0.0.0
+ */
+import { Number as EffectNumber, Match, 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 = (value, variableName) => {
+  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 = /*#__PURE__*/dual(2, (value, {
+  whenNullable,
+  whenNotNullable
+}) => 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 = /*#__PURE__*/dual(2, (a, map) => {
+  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 = map => a => {
+  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 = /*#__PURE__*/dual(2, (order, behavior) => {
+  // 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, b) => {
+    // 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);
+  };
+});
+//# sourceMappingURL=NonNullableX.js.map

package/dist/NonNullableX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NonNullableX.js","names":["Number","EffectNumber","Match","Predicate","dual","fromNullableOrThrow","value","variableName","isNotNullish","Error","String","match","whenNullable","whenNotNullable","map","a","isNullish","lift","nullableOrder","order","behavior","nullableSortCategory","valueSortCategory","pipe","when","exhaustive","b","aCategory","bCategory","sign"],"sources":["../src/NonNullableX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,SACEA,MAAM,IAAIC,YAAY,EACtBC,KAAK,EAGLC,SAAS,QACJ,QAAQ;AACf,SAASC,IAAI,QAAQ,iBAAiB;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMC,mBAAmB,GAAGA,CACjCC,KAAQ,EACRC,YAAqB,KACH;EAClB,IAAIJ,SAAS,CAACK,YAAY,CAACF,KAAK,CAAC,EAAE;IACjC,OAAOA,KAAK;EACd;EACA,MAAM,IAAIG,KAAK,CACb,sBAAsBC,MAAM,CAACJ,KAAK,CAAC,GAAGH,SAAS,CAACK,YAAY,CAACD,YAAY,CAAC,GAAG,oBAAoBA,YAAY,GAAG,GAAG,EAAE,EAAE,CACxH;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,OAAO,MAAMI,KAAK,gBAAGP,IAAI,CAavB,CAAC,EACD,CACEE,KAAQ,EACR;EACEM,YAAY;EACZC;AAAe,CAC0D,KAE3EV,SAAS,CAACK,YAAY,CAACF,KAAK,CAAC,GAAGO,eAAe,CAACP,KAAK,CAAC,GAAGM,YAAY,EAAE,CAC1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,OAAO,MAAME,GAAG,gBAAGV,IAAI,CASrB,CAAC,EACD,CACEW,CAAI,EACJD,GAA6B,KACO;EACpC,IAAIX,SAAS,CAACK,YAAY,CAACO,CAAC,CAAC,EAAE;IAC7B,OAAOD,GAAG,CAACC,CAAC,CAAC;EACf;EAEA,IAAIZ,SAAS,CAACa,SAAS,CAACD,CAAC,CAAC,EAAE;IAC1B,OAAOA,CAAC;EACV;EAEA,MAAM,IAAIN,KAAK,CAAC,+CAA+CC,MAAM,CAACK,CAAC,CAAC,EAAE,CAAC;AAC7E,CAAC,CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,MAAME,IAAI,GACRH,GAAgB,IACtBC,CAAuB,IAA0B;EAChD,IAAIZ,SAAS,CAACa,SAAS,CAACD,CAAC,CAAC,EAAE;IAC1B,OAAOA,CAAC;EACV;EAEA,OAAOD,GAAG,CAACC,CAAC,CAAC;AACf,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,OAAO,MAAMG,aAAa,gBAAGd,IAAI,CAS/B,CAAC,EACD,CACEe,KAAqB,EACrBC,QAAqC,KACZ;EACzB;EACA,MAAM;IAAEC,oBAAoB;IAAEC;EAAiB,CAAE,GAAGpB,KAAK,CAACI,KAAK,CAC7Dc,QAAQ,CACT,CAACG,IAAI,CACJrB,KAAK,CAACsB,IAAI,CAAC,YAAY,EAAE,OAAO;IAC9BH,oBAAoB,EAAE,CAAC;IACvBC,iBAAiB,EAAE;GACpB,CAAC,CAAC,EACHpB,KAAK,CAACsB,IAAI,CAAC,YAAY,EAAE,OAAO;IAC9BH,oBAAoB,EAAE,CAAC;IACvBC,iBAAiB,EAAE;GACpB,CAAC,CAAC,EACHpB,KAAK,CAACuB,UAAU,CACjB;EAED,OAAO,CAACV,CAAW,EAAEW,CAAW,KAAuB;IACrD;IACA,IAAIvB,SAAS,CAACK,YAAY,CAACO,CAAC,CAAC,IAAIZ,SAAS,CAACK,YAAY,CAACkB,CAAC,CAAC,EAAE;MAC1D,OAAOP,KAAK,CAACJ,CAAC,EAAEW,CAAC,CAAC;IACpB;IAEA;IACA,MAAMC,SAAS,GAAGxB,SAAS,CAACK,YAAY,CAACO,CAAC,CAAC,GACvCO,iBAAiB,GACjBD,oBAAoB;IAExB,MAAMO,SAAS,GAAGzB,SAAS,CAACK,YAAY,CAACkB,CAAC,CAAC,GACvCJ,iBAAiB,GACjBD,oBAAoB;IAExB,OAAOpB,YAAY,CAAC4B,IAAI,CAACF,SAAS,GAAGC,SAAS,CAAC;EACjD,CAAC;AACH,CAAC,CACF","ignoreList":[]}

package/dist/NumberX.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Number` module.
+ *
+ * @since 0.0.0
+ */
+import { Option } from "effect";
+/**
+ * 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 declare const unsafeLogBase: ((base: number) => (number: number) => number) & ((number: number, base: number) => number);
+/**
+ * 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 declare const unsafeToPercentOf: ((total: number) => (numerator: number) => number) & ((numerator: number, total: number) => number);
+/**
+ * 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 declare const toFixed: ((numberDigits: number) => (number: number) => string) & ((number: number, numberDigits: number) => string);
+/**
+ * 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 declare const roundToDigits: ((numberDigits: number) => (number: number) => number) & ((number: number, numberDigits: number) => number);
+/**
+ * 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 declare const padLeftZeroes: ((numberDigits: number) => (number: number) => string) & ((number: number, numberDigits: number) => string);
+/**
+ * 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 declare const indexToRank: (index: number) => number;
+/**
+ * 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 declare const indexToExcel: (index: number) => Option.Option<string>;
+//# sourceMappingURL=NumberX.d.ts.map

package/dist/NumberX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NumberX.d.ts","sourceRoot":"","sources":["../src/NumberX.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAA0B,MAAM,EAAQ,MAAM,QAAQ,CAAC;AA6B9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,aAAa,UACjB,MAAM,KAAK,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,cACnC,MAAM,QAAQ,MAAM,KAAK,MAAM,CAMzC,CAAC;AAqBF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,iBAAiB,WAEpB,MAAM,KAAK,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,iBAEpC,MAAM,SAAS,MAAM,KAAK,MAAM,CAM7C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,OAAO,kBACH,MAAM,KAAK,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,cAC3C,MAAM,gBAAgB,MAAM,KAAK,MAAM,CAGjD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,aAAa,kBAET,MAAM,KAAK,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,cAE3C,MAAM,gBAAgB,MAAM,KAAK,MAAM,CAGjD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,kBACT,MAAM,KAAK,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,cAC3C,MAAM,gBAAgB,MAAM,KAAK,MAAM,CAGjD,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,MAAmB,CAAC;AAIhE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAehE,CAAC"}