@nunofyobiz/effect-extras 2.0.0 → 3.0.0

package/dist/SetX.js

@@ -0,0 +1,137 @@
+/**
+ * Generic, framework-agnostic extensions for working with `Set`.
+ *
+ * @since 0.0.0
+ */
+import { dual } from "effect/Function";
+/**
+ * Runs a mutating function against a copy of `set`, leaving the original
+ * untouched, and returns the mutated copy.
+ *
+ * Use it to reuse imperative `Set` mutation code (`.add`, `.delete`) without
+ * sacrificing immutability: the callback may freely mutate the set it receives
+ * because it operates on a fresh clone. Supports both data-first and data-last
+ * (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { SetX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * const original = new Set(["a", "b"])
+ *
+ * const result = pipe(
+ *   original,
+ *   SetX.safelyMutate((set) => {
+ *     set.delete("a")
+ *     return set.add("c")
+ *   })
+ * )
+ *
+ * assert.deepStrictEqual(result, new Set(["b", "c"]))
+ * // The original is left intact
+ * assert.deepStrictEqual(original, new Set(["a", "b"]))
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const safelyMutate = /*#__PURE__*/dual(2, (set, mutate) => {
+  const copy = new Set(set);
+  return mutate(copy);
+});
+/**
+ * Returns a new `Set` with `value` added, leaving the input set unchanged.
+ *
+ * When `value` is already present the input set is returned as-is (no copy),
+ * making repeated adds of existing members allocation-free. Supports both
+ * data-first and data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { SetX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Data-first — adds a new element into a fresh set
+ * assert.deepStrictEqual(
+ *   SetX.add(new Set(["a", "b"]), "c"),
+ *   new Set(["a", "b", "c"])
+ * )
+ *
+ * // Data-last — existing element leaves the set unchanged
+ * assert.deepStrictEqual(
+ *   pipe(new Set(["a", "b"]), SetX.add("b")),
+ *   new Set(["a", "b"])
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const add = /*#__PURE__*/dual(2, (set, value) => set.has(value) ? set : new Set(set).add(value));
+/**
+ * Returns a new `Set` with `value` removed, leaving the input set unchanged.
+ *
+ * When `value` is absent the input set is returned as-is (no copy). Supports both
+ * data-first and data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { SetX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Data-first — removes an existing element into a fresh set
+ * assert.deepStrictEqual(
+ *   SetX.remove(new Set(["a", "b", "c"]), "c"),
+ *   new Set(["a", "b"])
+ * )
+ *
+ * // Data-last — absent element leaves the set unchanged
+ * assert.deepStrictEqual(
+ *   pipe(new Set(["a", "b"]), SetX.remove("z")),
+ *   new Set(["a", "b"])
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const remove = /*#__PURE__*/dual(2, (set, value) => {
+  if (set.has(value)) {
+    const newSet = new Set(set);
+    newSet.delete(value);
+    return newSet;
+  }
+  return set;
+});
+/**
+ * Returns a new `Set` with `value` added if it was absent or removed if it was
+ * present, leaving the input set unchanged.
+ *
+ * Use it for membership toggles (selection state, feature flags by key) where a
+ * value's presence should flip on each call. Supports both data-first and
+ * data-last (pipeable) call styles.
+ *
+ * @example
+ * ```ts
+ * import { SetX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // Data-first — absent value gets added
+ * assert.deepStrictEqual(
+ *   SetX.toggle(new Set(["a", "b"]), "c"),
+ *   new Set(["a", "b", "c"])
+ * )
+ *
+ * // Data-last — present value gets removed
+ * assert.deepStrictEqual(
+ *   pipe(new Set(["a", "b", "c"]), SetX.toggle("b")),
+ *   new Set(["a", "c"])
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const toggle = /*#__PURE__*/dual(2, (set, value) => set.has(value) ? remove(set, value) : add(set, value));
+//# sourceMappingURL=SetX.js.map

package/dist/SetX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SetX.js","names":["dual","safelyMutate","set","mutate","copy","Set","add","value","has","remove","newSet","delete","toggle"],"sources":["../src/SetX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,SAASA,IAAI,QAAQ,iBAAiB;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,OAAO,MAAMC,YAAY,gBAAGD,IAAI,CAG9B,CAAC,EAAE,CAAIE,GAAW,EAAEC,MAA+B,KAAY;EAC/D,MAAMC,IAAI,GAAG,IAAIC,GAAG,CAACH,GAAG,CAAC;EACzB,OAAOC,MAAM,CAACC,IAAI,CAAC;AACrB,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,OAAO,MAAME,GAAG,gBAAGN,IAAI,CAIrB,CAAC,EACD,CAAIE,GAAW,EAAEK,KAAQ,KACvBL,GAAG,CAACM,GAAG,CAACD,KAAK,CAAC,GAAGL,GAAG,GAAG,IAAIG,GAAG,CAACH,GAAG,CAAC,CAACI,GAAG,CAACC,KAAK,CAAC,CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAO,MAAME,MAAM,gBAAGT,IAAI,CAGxB,CAAC,EAAE,CAAIE,GAAW,EAAEK,KAAQ,KAAY;EACxC,IAAIL,GAAG,CAACM,GAAG,CAACD,KAAK,CAAC,EAAE;IAClB,MAAMG,MAAM,GAAG,IAAIL,GAAG,CAACH,GAAG,CAAC;IAC3BQ,MAAM,CAACC,MAAM,CAACJ,KAAK,CAAC;IACpB,OAAOG,MAAM;EACf;EACA,OAAOR,GAAG;AACZ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,MAAMU,MAAM,gBAAGZ,IAAI,CAIxB,CAAC,EACD,CAAIE,GAAW,EAAEK,KAAQ,KACvBL,GAAG,CAACM,GAAG,CAACD,KAAK,CAAC,GAAGE,MAAM,CAACP,GAAG,EAAEK,KAAK,CAAC,GAAGD,GAAG,CAACJ,GAAG,EAAEK,KAAK,CAAC,CACxD","ignoreList":[]}

package/dist/StringX.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Prepends `start` to `string_`.
+ *
+ * v4's `String` module has no native `prepend` (only `concat`), so this fills
+ * the gap as a pipeable helper.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(StringX.prepend("world", "hello "), "hello world")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("world", StringX.prepend("hello ")), "hello world")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export declare const prepend: ((start: string) => (string_: string) => string) & ((string_: string, start: string) => string);
+/**
+ * Wraps `string_` between `start` and `end`.
+ *
+ * No v4 native equivalent — handy for quoting, bracketing, or fencing a value.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(StringX.surround("value", "[", "]"), "[value]")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("value", StringX.surround("(", ")")), "(value)")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export declare const surround: ((start: string, end: string) => (string_: string) => string) & ((string_: string, start: string, end: string) => string);
+/**
+ * Prepends `start` to `string_` unless `string_` already starts with it.
+ *
+ * Idempotent: applying it to an already-prefixed string is a no-op, so
+ * `ensurePrepend("foofoo", "foo")` stays `"foofoo"` rather than gaining a
+ * second `"foo"`.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first — adds the prefix when missing
+ * assert.deepStrictEqual(StringX.ensurePrepend("bar", "foo"), "foobar")
+ *
+ * // idempotent — already prefixed, returned unchanged
+ * assert.deepStrictEqual(StringX.ensurePrepend("foobar", "foo"), "foobar")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("bar", StringX.ensurePrepend("foo")), "foobar")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export declare const ensurePrepend: ((start: string) => (string_: string) => string) & ((string_: string, start: string) => string);
+/**
+ * Replaces the inclusive line range `[startLine, endLine]` of `content` with
+ * `replacement` lines, returning the rejoined string.
+ *
+ * `content` is split on `\n`; the zero-based lines `startLine` through `endLine`
+ * (both inclusive) are dropped and `replacement` is spliced into their place.
+ * Pass an empty `replacement` to delete the range. Indices clamp naturally via
+ * `Array.take`/`Array.drop`, so out-of-range values don't throw.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first — replace lines 1..2 with a single line
+ * assert.deepStrictEqual(
+ *   StringX.replaceLineRange("a\nb\nc\nd", 1, 2, ["X"]),
+ *   "a\nX\nd",
+ * )
+ *
+ * // an empty replacement deletes the range
+ * assert.deepStrictEqual(StringX.replaceLineRange("a\nb\nc\nd", 1, 2, []), "a\nd")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(
+ *   pipe("a\nb\nc", StringX.replaceLineRange(1, 1, ["X", "Y"])),
+ *   "a\nX\nY\nc",
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export declare const replaceLineRange: ((startLine: number, endLine: number, replacement: readonly string[]) => (content: string) => string) & ((content: string, startLine: number, endLine: number, replacement: readonly string[]) => string);
+/**
+ * Inserts `lines` immediately before the line at `anchorIndex`, preserving the
+ * anchor line and everything after it; returns the rejoined string.
+ *
+ * `content` is split on `\n` and `lines` are spliced in just before the
+ * zero-based `anchorIndex`. An `anchorIndex` of `0` prepends, and one at or past
+ * the end appends.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first — insert before line 1, keeping the anchor and the rest
+ * assert.deepStrictEqual(StringX.insertBeforeLine("a\nb\nc", 1, ["X"]), "a\nX\nb\nc")
+ *
+ * // an anchor at the end appends
+ * assert.deepStrictEqual(StringX.insertBeforeLine("a\nb", 2, ["X"]), "a\nb\nX")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("a\nb", StringX.insertBeforeLine(0, ["X"])), "X\na\nb")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export declare const insertBeforeLine: ((anchorIndex: number, lines: readonly string[]) => (content: string) => string) & ((content: string, anchorIndex: number, lines: readonly string[]) => string);
+//# sourceMappingURL=StringX.d.ts.map

package/dist/StringX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StringX.d.ts","sourceRoot":"","sources":["../src/StringX.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,OAAO,WACV,MAAM,KAAK,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,eACpC,MAAM,SAAS,MAAM,KAAK,MAAM,CAC0B,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,WACX,MAAM,OAAO,MAAM,KAAK,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,eACjD,MAAM,SAAS,MAAM,OAAO,MAAM,KAAK,MAAM,CAKxD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,WAChB,MAAM,KAAK,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,eACpC,MAAM,SAAS,MAAM,KAAK,MAAM,CAO1C,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB,eAEd,MAAM,WACR,MAAM,eACF,SAAS,MAAM,EAAE,KAC3B,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,eAErB,MAAM,aACJ,MAAM,WACR,MAAM,eACF,SAAS,MAAM,EAAE,KAC3B,MAAM,CAmBZ,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,gBAAgB,iBAEZ,MAAM,SACZ,SAAS,MAAM,EAAE,KACrB,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,eACtB,MAAM,eAAe,MAAM,SAAS,SAAS,MAAM,EAAE,KAAK,MAAM,CAc3E,CAAC"}

package/dist/StringX.js

@@ -0,0 +1,149 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `String` module.
+ *
+ * @since 0.0.0
+ */
+import { Array } from "effect";
+import { dual } from "effect/Function";
+/**
+ * Prepends `start` to `string_`.
+ *
+ * v4's `String` module has no native `prepend` (only `concat`), so this fills
+ * the gap as a pipeable helper.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(StringX.prepend("world", "hello "), "hello world")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("world", StringX.prepend("hello ")), "hello world")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const prepend = /*#__PURE__*/dual(2, (string_, start) => `${start}${string_}`);
+/**
+ * Wraps `string_` between `start` and `end`.
+ *
+ * No v4 native equivalent — handy for quoting, bracketing, or fencing a value.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(StringX.surround("value", "[", "]"), "[value]")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("value", StringX.surround("(", ")")), "(value)")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const surround = /*#__PURE__*/dual(3, (string_, start, end) => `${start}${string_}${end}`);
+/**
+ * Prepends `start` to `string_` unless `string_` already starts with it.
+ *
+ * Idempotent: applying it to an already-prefixed string is a no-op, so
+ * `ensurePrepend("foofoo", "foo")` stays `"foofoo"` rather than gaining a
+ * second `"foo"`.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first — adds the prefix when missing
+ * assert.deepStrictEqual(StringX.ensurePrepend("bar", "foo"), "foobar")
+ *
+ * // idempotent — already prefixed, returned unchanged
+ * assert.deepStrictEqual(StringX.ensurePrepend("foobar", "foo"), "foobar")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("bar", StringX.ensurePrepend("foo")), "foobar")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const ensurePrepend = /*#__PURE__*/dual(2, (string_, start) => {
+  if (string_.startsWith(start)) {
+    return string_;
+  }
+  return `${start}${string_}`;
+});
+/**
+ * Replaces the inclusive line range `[startLine, endLine]` of `content` with
+ * `replacement` lines, returning the rejoined string.
+ *
+ * `content` is split on `\n`; the zero-based lines `startLine` through `endLine`
+ * (both inclusive) are dropped and `replacement` is spliced into their place.
+ * Pass an empty `replacement` to delete the range. Indices clamp naturally via
+ * `Array.take`/`Array.drop`, so out-of-range values don't throw.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first — replace lines 1..2 with a single line
+ * assert.deepStrictEqual(
+ *   StringX.replaceLineRange("a\nb\nc\nd", 1, 2, ["X"]),
+ *   "a\nX\nd",
+ * )
+ *
+ * // an empty replacement deletes the range
+ * assert.deepStrictEqual(StringX.replaceLineRange("a\nb\nc\nd", 1, 2, []), "a\nd")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(
+ *   pipe("a\nb\nc", StringX.replaceLineRange(1, 1, ["X", "Y"])),
+ *   "a\nX\nY\nc",
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const replaceLineRange = /*#__PURE__*/dual(4, (content, startLine, endLine, replacement) => {
+  const lines = content.split("\n");
+  return Array.join([...Array.take(lines, startLine), ...replacement, ...Array.drop(lines, endLine + 1)], "\n");
+});
+/**
+ * Inserts `lines` immediately before the line at `anchorIndex`, preserving the
+ * anchor line and everything after it; returns the rejoined string.
+ *
+ * `content` is split on `\n` and `lines` are spliced in just before the
+ * zero-based `anchorIndex`. An `anchorIndex` of `0` prepends, and one at or past
+ * the end appends.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StringX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first — insert before line 1, keeping the anchor and the rest
+ * assert.deepStrictEqual(StringX.insertBeforeLine("a\nb\nc", 1, ["X"]), "a\nX\nb\nc")
+ *
+ * // an anchor at the end appends
+ * assert.deepStrictEqual(StringX.insertBeforeLine("a\nb", 2, ["X"]), "a\nb\nX")
+ *
+ * // data-last (piped)
+ * assert.deepStrictEqual(pipe("a\nb", StringX.insertBeforeLine(0, ["X"])), "X\na\nb")
+ * ```
+ *
+ * @category combinators
+ * @since 0.0.0
+ */
+export const insertBeforeLine = /*#__PURE__*/dual(3, (content, anchorIndex, lines) => {
+  const split = content.split("\n");
+  return Array.join([...Array.take(split, anchorIndex), ...lines, ...Array.drop(split, anchorIndex)], "\n");
+});
+//# sourceMappingURL=StringX.js.map

package/dist/StringX.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StringX.js","names":["Array","dual","prepend","string_","start","surround","end","ensurePrepend","startsWith","replaceLineRange","content","startLine","endLine","replacement","lines","split","join","take","drop","insertBeforeLine","anchorIndex"],"sources":["../src/StringX.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,SAASA,KAAK,QAAQ,QAAQ;AAC9B,SAASC,IAAI,QAAQ,iBAAiB;AAEtC;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMC,OAAO,gBAAGD,IAAI,CAGzB,CAAC,EAAE,CAACE,OAAe,EAAEC,KAAa,KAAa,GAAGA,KAAK,GAAGD,OAAO,EAAE,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAME,QAAQ,gBAAGJ,IAAI,CAI1B,CAAC,EACD,CAACE,OAAe,EAAEC,KAAa,EAAEE,GAAW,KAC1C,GAAGF,KAAK,GAAGD,OAAO,GAAGG,GAAG,EAAE,CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMC,aAAa,gBAAGN,IAAI,CAG/B,CAAC,EAAE,CAACE,OAAe,EAAEC,KAAa,KAAY;EAC9C,IAAID,OAAO,CAACK,UAAU,CAACJ,KAAK,CAAC,EAAE;IAC7B,OAAOD,OAAO;EAChB;EAEA,OAAO,GAAGC,KAAK,GAAGD,OAAO,EAAE;AAC7B,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,OAAO,MAAMM,gBAAgB,gBAAGR,IAAI,CAalC,CAAC,EACD,CACES,OAAe,EACfC,SAAiB,EACjBC,OAAe,EACfC,WAA8B,KACpB;EACV,MAAMC,KAAK,GAAGJ,OAAO,CAACK,KAAK,CAAC,IAAI,CAAC;EACjC,OAAOf,KAAK,CAACgB,IAAI,CACf,CACE,GAAGhB,KAAK,CAACiB,IAAI,CAACH,KAAK,EAAEH,SAAS,CAAC,EAC/B,GAAGE,WAAW,EACd,GAAGb,KAAK,CAACkB,IAAI,CAACJ,KAAK,EAAEF,OAAO,GAAG,CAAC,CAAC,CAClC,EACD,IAAI,CACL;AACH,CAAC,CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,OAAO,MAAMO,gBAAgB,gBAAGlB,IAAI,CAOlC,CAAC,EACD,CAACS,OAAe,EAAEU,WAAmB,EAAEN,KAAwB,KAAY;EACzE,MAAMC,KAAK,GAAGL,OAAO,CAACK,KAAK,CAAC,IAAI,CAAC;EACjC,OAAOf,KAAK,CAACgB,IAAI,CACf,CACE,GAAGhB,KAAK,CAACiB,IAAI,CAACF,KAAK,EAAEK,WAAW,CAAC,EACjC,GAAGN,KAAK,EACR,GAAGd,KAAK,CAACkB,IAAI,CAACH,KAAK,EAAEK,WAAW,CAAC,CAClC,EACD,IAAI,CACL;AACH,CAAC,CACF","ignoreList":[]}

package/dist/StructX.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Generic, framework-agnostic extensions to Effect's `Struct` module.
+ *
+ * @since 0.0.0
+ */
+import { Option } from "effect";
+/**
+ * Describes the shape of a per-field transformation over an object `O`: a record
+ * `T` whose values are functions taking the corresponding field of `O`.
+ *
+ * Used to type the "evolve" pattern, where each provided key maps to a function
+ * that receives that field's current value. Copied from Effect's internal
+ * `Struct.evolve()` type, which is not exported — it would be better to use
+ * theirs directly if it ever becomes public.
+ *
+ * @example
+ * ```ts
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * type Transform = StructX.PartialTransform<
+ *   { a: number; b: string },
+ *   { a: (n: number) => boolean }
+ * >
+ *
+ * const evolve: Transform = { a: (n) => n > 0 }
+ *
+ * assert.deepStrictEqual(evolve.a(1), true)
+ * ```
+ *
+ * @category models
+ * @since 0.0.0
+ */
+export type PartialTransform<O, T> = {
+    [K in keyof T]: T[K] extends (a: O[K & keyof O]) => unknown ? T[K] : (a: O[K & keyof O]) => unknown;
+};
+/**
+ * Builds a singleton record `{ [name]: value }` when `value` is defined, or an
+ * empty object `{}` when it is `undefined` — meant to be spread into an object
+ * literal.
+ *
+ * This is the canonical fix for `exactOptionalPropertyTypes: true` (which this
+ * repo enables for Effect Schema). Under that flag, spreading
+ * `{ key: maybeUndefined }` into an object whose key is `key?: T` is a type
+ * error: the property must be *absent*, not present-but-`undefined`. Spreading
+ * `...defined("key", maybeUndefined)` instead conditionally omits the property
+ * altogether. Note that `null` and other falsy-but-defined values (`0`, `""`,
+ * `false`) are kept — only `undefined` is dropped.
+ *
+ * @example
+ * ```ts
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // Defined value → singleton record
+ * assert.deepStrictEqual(StructX.defined("name", "Ada"), { name: "Ada" })
+ *
+ * // undefined → property omitted entirely
+ * assert.deepStrictEqual(StructX.defined("name", undefined), {})
+ *
+ * // Falsy-but-defined values are kept
+ * assert.deepStrictEqual(StructX.defined("name", 0), { name: 0 })
+ *
+ * // Typical use: spread to conditionally include an optional field
+ * const maybeAge: number | undefined = undefined
+ * assert.deepStrictEqual({ id: 1, ...StructX.defined("age", maybeAge) }, {
+ *   id: 1,
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export declare const defined: <const K extends string, V>(name: K, value: V | undefined) => Partial<Record<K, Exclude<V, undefined>>>;
+/**
+ * Removes every property whose value is `undefined` from `record`, narrowing
+ * each remaining property type to exclude `undefined`.
+ *
+ * The bulk counterpart of {@link defined}: instead of building one optional
+ * field, it filters a whole object. Very useful for update/patch actions where
+ * `undefined` means "leave this field unchanged" while every other value —
+ * including `null`, `0`, `""`, `false`, and `Option.none()` — means "set the
+ * field to exactly this".
+ *
+ * @example
+ * ```ts
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // Drops `b` (undefined) but keeps every other value, including null/0/false
+ * assert.deepStrictEqual(
+ *   StructX.filterDefined({ a: "x", b: undefined, c: 0, d: null, e: false }),
+ *   { a: "x", c: 0, d: null, e: false },
+ * )
+ * ```
+ *
+ * @category filtering
+ * @since 0.0.0
+ */
+export declare const filterDefined: <R extends Record<string, unknown>>(record: R) => Partial<{ [P in keyof R]: Exclude<R[P], undefined>; }>;
+/**
+ * Builds a singleton record `{ [name]: value }` when `value` is `Some`, or an
+ * empty object `{}` when it is `None` — meant to be spread into an object
+ * literal.
+ *
+ * The `Option`-valued sibling of {@link defined}: where `defined` keys off
+ * `undefined`, this keys off `Option` presence. Spread `...some("key", opt)` to
+ * conditionally include a field only when the `Option` carries a value, which
+ * stays correct under `exactOptionalPropertyTypes: true`.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // Some → singleton record
+ * assert.deepStrictEqual(StructX.some("name", Option.some("Ada")), {
+ *   name: "Ada",
+ * })
+ *
+ * // None → property omitted entirely
+ * assert.deepStrictEqual(StructX.some("name", Option.none()), {})
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export declare const some: <const K extends string, V>(name: K, value: Option.Option<V>) => Partial<Record<K, V>>;
+/**
+ * Looks up `key` in a record of `Option` values and returns a singleton record
+ * when the value is `Some`, or `{}` when the key is absent or its value is
+ * `None`.
+ *
+ * Combines `Record.get` + `Option.flatten` + a singleton builder in one call —
+ * ideal for spreading an optional field out of a lookup table into an object
+ * literal under `exactOptionalPropertyTypes: true`. By default the output key
+ * matches the lookup key; pass `renameKeyTo` to emit the value under a different
+ * name.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect"
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * const lookup = {
+ *   a: Option.some(100),
+ *   b: Option.none<number>(),
+ * }
+ *
+ * // Some → singleton record under the same key
+ * assert.deepStrictEqual(StructX.pickSome(lookup, "a"), { a: 100 })
+ *
+ * // None → property omitted entirely
+ * assert.deepStrictEqual(StructX.pickSome(lookup, "b"), {})
+ *
+ * // Rename the output key
+ * assert.deepStrictEqual(StructX.pickSome(lookup, "a", "count"), { count: 100 })
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export declare function pickSome<const K extends string, V>(record: Record<K, Option.Option<V>>, key: K): Partial<Record<K, V>>;
+export declare function pickSome<const K1 extends string, V, const K2 extends string>(record: Record<K1, Option.Option<V>>, key: K1, renameKeyTo: K2): Partial<Record<K2, V>>;
+/**
+ * Builds a singleton record `{ [name]: value }` when `value` is truthy, or an
+ * empty object `{}` otherwise — meant to be spread into an object literal.
+ *
+ * Stricter than {@link defined}: it drops not just `undefined` but every falsy
+ * value (`null`, `false`, `0`, `""`, `NaN`), and narrows the value type
+ * accordingly. Use it to spread a field only when it carries a meaningful,
+ * non-falsy value.
+ *
+ * @example
+ * ```ts
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // Truthy value → singleton record
+ * assert.deepStrictEqual(StructX.truthy("name", "Ada"), { name: "Ada" })
+ *
+ * // Falsy values → property omitted entirely
+ * assert.deepStrictEqual(StructX.truthy("name", ""), {})
+ * assert.deepStrictEqual(StructX.truthy("name", 0), {})
+ * assert.deepStrictEqual(StructX.truthy("name", false), {})
+ * ```
+ *
+ * @category constructors
+ * @since 0.0.0
+ */
+export declare const truthy: <const K extends string, V>(name: K, value: V) => Partial<Record<K, Exclude<NonNullable<V>, false | 0 | "">>>;
+/**
+ * Returns `true` when `object` has `key` set to a non-nullish value, narrowing
+ * that property to `NonNullable` on the type level.
+ *
+ * A type guard combining `hasProperty` with a nullish check: after a successful
+ * test, TypeScript treats `object[key]` as present and free of `null` /
+ * `undefined`. Handy as a predicate passed to `Array.filter` to keep only the
+ * elements whose `key` is populated.
+ *
+ * @example
+ * ```ts
+ * import { pipe } from "effect"
+ * import { StructX } from "@nunofyobiz/effect-extras"
+ *
+ * // data-first
+ * assert.deepStrictEqual(
+ *   StructX.hasNotNullableProperty({ id: "1" }, "id"),
+ *   true,
+ * )
+ *
+ * // data-last (pipeable); a null value fails the guard
+ * assert.deepStrictEqual(
+ *   pipe({ id: null }, StructX.hasNotNullableProperty("id")),
+ *   false,
+ * )
+ * ```
+ *
+ * @category refinements
+ * @since 0.0.0
+ */
+export declare const hasNotNullableProperty: (<T, K extends keyof T>(key: K) => (object: T) => object is T & Record<K, NonNullable<T[K]>>) & (<T, K extends keyof T>(object: T, key: K) => object is T & Record<K, NonNullable<T[K]>>);
+//# sourceMappingURL=StructX.d.ts.map

package/dist/StructX.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StructX.d.ts","sourceRoot":"","sources":["../src/StructX.ts"],"names":[],"mappings":"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"}