@nunofyobiz/effect-extras 2.0.0 → 3.0.0

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"}

package/dist/NumberX.js

@@ -0,0 +1,214 @@
+/**
+ * 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 = /*#__PURE__*/dual(2, (number, base) => {
+  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 = /*#__PURE__*/dual(2, (number, base) => 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 = /*#__PURE__*/dual(2, (numerator, total) => 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 = /*#__PURE__*/dual(2, (numerator, total) => 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 = /*#__PURE__*/dual(2, (number, numberDigits) => 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 = /*#__PURE__*/dual(2, (number, numberDigits) => 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 = /*#__PURE__*/dual(2, (number, numberDigits) => 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 => 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 => {
+  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);
+};
+//# sourceMappingURL=NumberX.js.map

package/dist/NumberX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NumberX.js","names":["Number","EffectNumber","Option","pipe","dual","logBase","number","base","none","some","Math","log","unsafeLogBase","getOrThrowWith","Error","toPercentOf","numerator","total","divide","map","ratio","unsafeToPercentOf","toFixed","numberDigits","roundToDigits","padLeftZeroes","toString","padStart","indexToRank","index","EXCEL_COLUMNS_BASE_CHARS","indexToExcel","baseChars","excel","length","floor"],"sources":["../src/NumberX.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/OptionX.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Option` module.
+ *
+ * @since 0.0.0
+ */
+import { Option } from "effect";
+/**
+ * Combines two `Option`s into an `Option` of a tuple, succeeding only when both
+ * are `Some`.
+ *
+ * Returns `Some([a, b])` when both inputs are `Some`, and `None` if either is
+ * `None`. Useful when an operation needs two optional values present at once.
+ *
+ * @example
+ * ```ts
+ * import { Option, pipe } from "effect"
+ * import { OptionX } from "@nunofyobiz/effect-extras"
+ *
+ * // Both Some — succeeds with the pair
+ * assert.deepStrictEqual(
+ *   OptionX.tupleOf(Option.some(1), Option.some("a")),
+ *   Option.some([1, "a"]),
+ * )
+ *
+ * // Either None collapses to None
+ * assert.deepStrictEqual(
+ *   OptionX.tupleOf(Option.some(1), Option.none()),
+ *   Option.none(),
+ * )
+ *
+ * // Data-last (piped): the piped Option fills the first tuple slot
+ * assert.deepStrictEqual(
+ *   pipe(Option.some(1), OptionX.tupleOf(Option.some("a"))),
+ *   Option.some([1, "a"]),
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export declare const tupleOf: (<B>(b: Option.Option<B>) => <A>(a: Option.Option<A>) => Option.Option<[A, B]>) & (<A, B>(a: Option.Option<A>, b: Option.Option<B>) => Option.Option<[A, B]>);
+/**
+ * Runs a side effect with the value of an `Option` when it is `Some`, doing
+ * nothing when it is `None`.
+ *
+ * A shorthand for the "if Some, do something" branch of `Option.match` where the
+ * `None` case is a no-op. The callback's return value is ignored — `ifSome`
+ * always returns `void`.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { OptionX } from "@nunofyobiz/effect-extras"
+ *
+ * const log: Array<number> = []
+ * OptionX.ifSome(Option.some(1), (value) => log.push(value))
+ * OptionX.ifSome(Option.none<number>(), (value) => log.push(value))
+ *
+ * assert.deepStrictEqual(log, [1])
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export declare const ifSome: (<A>(ifSome: (value: A) => void) => (self: Option.Option<A>) => void) & (<A>(self: Option.Option<A>, ifSome: (value: A) => void) => void);
+/**
+ * Runs a side effect with the value of an `Option` when it is `Some`, then
+ * returns the `Option` unchanged.
+ *
+ * The pass-through counterpart of {@link ifSome}: it taps into a `Some` value
+ * (for logging, metrics, debugging) without breaking a `pipe` chain, since it
+ * returns the original `Option`. For `None` it is a no-op.
+ *
+ * @example
+ * ```ts
+ * import { Option, pipe } from "effect"
+ * import { OptionX } from "@nunofyobiz/effect-extras"
+ *
+ * const log: Array<number> = []
+ * const result = pipe(
+ *   Option.some(1),
+ *   OptionX.inspectSome((value) => log.push(value)),
+ *   Option.map((value) => value + 1),
+ * )
+ *
+ * assert.deepStrictEqual(result, Option.some(2))
+ * assert.deepStrictEqual(log, [1])
+ * ```
+ *
+ * @category sequencing
+ * @since 0.0.0
+ */
+export declare const inspectSome: (<A>(function_: (value: A) => void) => (self: Option.Option<A>) => Option.Option<A>) & (<A>(self: Option.Option<A>, function_: (value: A) => void) => Option.Option<A>);
+/**
+ * Normalizes a possibly-nullish `Option` into a plain `Option`, mapping `null`
+ * and `undefined` to `None`.
+ *
+ * Handy at boundaries where an `Option` value might itself arrive as `null` or
+ * `undefined` (for example an optional field that holds an `Option`): the result
+ * is always a well-formed `Option`, never `null`/`undefined`.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { OptionX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(OptionX.fromNullableOption(Option.some(1)), Option.some(1))
+ * assert.deepStrictEqual(OptionX.fromNullableOption(null), Option.none())
+ * assert.deepStrictEqual(OptionX.fromNullableOption(undefined), Option.none())
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export declare const fromNullableOption: <A>(nullableOption: Option.Option<A> | null | undefined) => Option.Option<A>;
+/**
+ * Maps the value of an `Option` when it is `Some`, returning `null` when it is
+ * `None`.
+ *
+ * A shorthand for `pipe(self, Option.map(map), Option.getOrNull)`. The `null`
+ * fallback makes it especially convenient in JSX/React, where rendering `null`
+ * skips output — `mapSomeOrNull(value, (v) => render(v))` replaces a more verbose
+ * `Option.match` with `onNone: () => null`.
+ *
+ * @example
+ * ```ts
+ * import { Option, pipe } from "effect"
+ * import { OptionX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(OptionX.mapSomeOrNull(Option.some(1), (v) => v + 1), 2)
+ *
+ * // None maps to null
+ * assert.deepStrictEqual(
+ *   OptionX.mapSomeOrNull(Option.none<number>(), (v) => v + 1),
+ *   null,
+ * )
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(
+ *   pipe(Option.some(1), OptionX.mapSomeOrNull((v) => v + 1)),
+ *   2,
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export declare const mapSomeOrNull: (<A, B>(map: (a: A) => B) => (self: Option.Option<A>) => B | null) & (<A, B>(self: Option.Option<A>, map: (a: A) => B) => B | null);
+/**
+ * Maps the value of an `Option` when it is `Some`, returning `undefined` when it
+ * is `None`.
+ *
+ * The `undefined`-returning counterpart of {@link mapSomeOrNull}: a shorthand for
+ * `pipe(self, Option.map(map), Option.getOrUndefined)`. Reach for it when the
+ * consuming API expects `undefined` rather than `null` for "absent" (for example
+ * an optional prop or a value spread into an object).
+ *
+ * @example
+ * ```ts
+ * import { Option, pipe } from "effect"
+ * import { OptionX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(
+ *   OptionX.mapSomeOrUndefined(Option.some(1), (v) => v + 1),
+ *   2,
+ * )
+ *
+ * // None maps to undefined
+ * assert.deepStrictEqual(
+ *   OptionX.mapSomeOrUndefined(Option.none<number>(), (v) => v + 1),
+ *   undefined,
+ * )
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(
+ *   pipe(Option.some(1), OptionX.mapSomeOrUndefined((v) => v + 1)),
+ *   2,
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 0.0.0
+ */
+export declare const mapSomeOrUndefined: (<A, B>(map: (a: A) => B) => (self: Option.Option<A>) => B | undefined) & (<A, B>(self: Option.Option<A>, map: (a: A) => B) => B | undefined);
+//# sourceMappingURL=OptionX.d.ts.map

package/dist/OptionX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OptionX.d.ts","sourceRoot":"","sources":["../src/OptionX.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,MAAM,EAAmB,MAAM,QAAQ,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,OAAO,IACjB,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAC5E,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAK1E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,MAAM,IAChB,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,MAClE,CAAC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,CAW/D,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,WAAW,IACrB,CAAC,aACW,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAC1B,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAChD,CAAC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAU/E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAClC,gBAAgB,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,KAClD,MAAM,CAAC,MAAM,CAAC,CAAC,CACuD,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,aAAa,IACvB,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI,MAC/D,CAAC,EAAE,CAAC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,IAAI,CAG7D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,kBAAkB,IAC5B,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,SAAS,MACpE,CAAC,EAAE,CAAC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,SAAS,CAGlE,CAAC"}