@nunofyobiz/effect-extras 2.1.0 → 3.1.0

package/src/NonNullableX.ts

@@ -162,10 +162,15 @@ export const map = dual<
       return map(a);
     }
 
+    // Every value is either nullish or not, so once the check above has failed
+    // `isNullish(a)` is always true — its false branch (and the defensive throw
+    // below) is unreachable.
+    /* v8 ignore next */
     if (Predicate.isNullish(a)) {
       return a;
     }
 
+    /* v8 ignore next */
     throw new Error(`Value is neither nullable nor non-nullable: ${String(a)}`);
   },
 );

package/src/OptionX.ts

@@ -15,7 +15,7 @@ import { dual } from "effect/Function";
  *
  * @example
  * ```ts
- * import { Option } from "effect"
+ * import { Option, pipe } from "effect"
  * import { OptionX } from "@nunofyobiz/effect-extras"
  *
  * // Both Some — succeeds with the pair
@@ -29,13 +29,19 @@ import { dual } from "effect/Function";
  *   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 const tupleOf = dual<
-  <A>(a: Option.Option<A>) => <B>(b: Option.Option<B>) => Option.Option<[A, B]>,
+  <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]>
 >(
   2,

package/src/PredicateX.ts

@@ -96,3 +96,44 @@ export function isNonEmptyString(value: unknown): value is string {
     String.isNonEmpty(value)
   );
 }
+
+/**
+ * Refines an `unknown` value to a plain `Record<string, unknown>` — `true` only
+ * for a non-null, non-array object whose prototype is `Object.prototype` (an
+ * object literal) or `null` (an `Object.create(null)` map).
+ *
+ * Effect ships no `Predicate.isRecord`. `Predicate.isObject` is the closest, but
+ * it also accepts `Map`, `Set`, `Date`, `RegExp`, and class instances. This guard
+ * adds a prototype check to rule those out, narrowing to `Record<string, unknown>`
+ * so the JSON-tree helpers (`RecordX.deepMerge`, `RecordX.canonicalize`,
+ * `RecordX.deleteByPath`) can compose without an `as` cast.
+ *
+ * It is named **`unsafe`** because the narrowing comes purely from the value's
+ * runtime shape — it does *not* validate the key or value types. A symbol-keyed
+ * entry still passes despite the `string` key claim, and values are asserted
+ * `unknown` without any check. Treat it as a structural convenience, not a
+ * `Schema` validation: reach for `Schema` when you need real key/value guarantees.
+ *
+ * @example
+ * ```ts
+ * import { PredicateX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(PredicateX.unsafeIsRecord({ a: 1 }), true)
+ * assert.deepStrictEqual(PredicateX.unsafeIsRecord(Object.create(null)), true)
+ * assert.deepStrictEqual(PredicateX.unsafeIsRecord([1, 2]), false)
+ * assert.deepStrictEqual(PredicateX.unsafeIsRecord(new Map()), false)
+ * assert.deepStrictEqual(PredicateX.unsafeIsRecord(null), false)
+ * ```
+ *
+ * @category refinements
+ * @since 0.0.0
+ */
+export function unsafeIsRecord(
+  value: unknown,
+): value is Record<string, unknown> {
+  if (!Predicate.isObject(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

package/src/RecordX.ts

@@ -3,9 +3,10 @@
  *
  * @since 0.0.0
  */
-import { Array, Option, Order, Predicate, Record, pipe } from "effect";
+import { Array, Option, Order, Predicate, Record, Reducer, pipe } from "effect";
 import { dual } from "effect/Function";
 import * as ArrayX from "./ArrayX.js";
+import * as PredicateX from "./PredicateX.js";
 
 /**
  * Returns `true` when `record` has at least one entry, narrowing it to a
@@ -476,3 +477,184 @@ export const collectBy = dual<
       Record.set<K, V, K, V>(accumulator, identify(value), value),
     ),
 );
+
+/**
+ * Deep-merges two JSON values, with `b` winning on conflicts.
+ *
+ * Plain objects (per `PredicateX.unsafeIsRecord`) are merged recursively,
+ * key-by-key; every other shape — primitives, arrays, and impostors like
+ * `Map`/`Date`/class instances — is replaced wholesale by `b`. If either side
+ * isn't a plain object, `b` is returned as-is. Neither input is mutated. Reach
+ * for it to layer partial JSON overrides on top of a base.
+ *
+ * @example
+ * ```ts
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ * import { pipe } from "effect"
+ *
+ * // data-first — nested objects merge, b wins on leaf conflicts
+ * assert.deepStrictEqual(
+ *   RecordX.deepMerge({ a: { x: 1 }, b: 2 }, { a: { y: 3 }, c: 4 }),
+ *   { a: { x: 1, y: 3 }, b: 2, c: 4 },
+ * )
+ *
+ * // arrays are replaced wholesale, not concatenated
+ * assert.deepStrictEqual(RecordX.deepMerge({ a: [1, 2] }, { a: [3] }), { a: [3] })
+ *
+ * // data-last (pipeable) — merges the override onto the piped base
+ * assert.deepStrictEqual(pipe({ a: 1 }, RecordX.deepMerge({ b: 2 })), {
+ *   a: 1,
+ *   b: 2,
+ * })
+ * ```
+ *
+ * @category combining
+ * @since 0.0.0
+ */
+export const deepMerge = dual<
+  (b: unknown) => (a: unknown) => unknown,
+  (a: unknown, b: unknown) => unknown
+>(2, (a: unknown, b: unknown): unknown => {
+  if (!PredicateX.unsafeIsRecord(a) || !PredicateX.unsafeIsRecord(b)) {
+    return b;
+  }
+  return Record.reduce(b, { ...a }, (accumulator, value, key) => ({
+    ...accumulator,
+    [key]: key in a ? deepMerge(a[key], value) : value,
+  }));
+});
+
+/**
+ * {@link deepMerge} as a `Reducer` (monoid) with identity `{}`.
+ *
+ * `deepMergeReducer.combineAll(layers)` folds an iterable of object layers
+ * left-to-right via {@link deepMerge} — the universal "merge N JSON objects into
+ * one" fold, replacing a hand-rolled `Array.reduce(layers, {}, deepMerge)`. The
+ * `{}` identity is exact for the object-valued layers these folds carry: an empty
+ * list yields `{}`, and a single layer is returned unchanged.
+ *
+ * @example
+ * ```ts
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   RecordX.deepMergeReducer.combineAll([
+ *     { a: { x: 1 } },
+ *     { a: { y: 2 }, b: 3 },
+ *     { b: 4 },
+ *   ]),
+ *   { a: { x: 1, y: 2 }, b: 4 },
+ * )
+ *
+ * assert.deepStrictEqual(RecordX.deepMergeReducer.combineAll([]), {})
+ * ```
+ *
+ * @category instances
+ * @since 0.0.0
+ */
+export const deepMergeReducer: Reducer.Reducer<unknown> = Reducer.make<unknown>(
+  deepMerge,
+  {},
+);
+
+/**
+ * Canonicalizes a JSON value by recursively sorting object keys; arrays keep
+ * their order.
+ *
+ * Two structurally-equal values that differ only in key order canonicalize to
+ * the same shape, so `JSON.stringify(canonicalize(x))` is a stable structural
+ * key for comparison, deduping, or hashing. Plain objects (per
+ * `PredicateX.unsafeIsRecord`) have their keys sorted ascending and their values
+ * canonicalized recursively; arrays are canonicalized element-wise in place;
+ * everything else passes through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ *
+ * assert.deepStrictEqual(
+ *   JSON.stringify(RecordX.canonicalize({ b: 1, a: { d: 1, c: 2 } })),
+ *   JSON.stringify({ a: { c: 2, d: 1 }, b: 1 }),
+ * )
+ *
+ * // arrays keep their order; primitives pass through
+ * assert.deepStrictEqual(RecordX.canonicalize([3, 1, 2]), [3, 1, 2])
+ * assert.deepStrictEqual(RecordX.canonicalize("x"), "x")
+ * ```
+ *
+ * @category transformations
+ * @since 0.0.0
+ */
+export const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return Array.map(value, canonicalize);
+  }
+  if (!PredicateX.unsafeIsRecord(value)) {
+    return value;
+  }
+  return pipe(
+    Record.toEntries(value),
+    Array.map(([key, entry]) => [key, canonicalize(entry)] as const),
+    Array.sort(
+      Order.mapInput(Order.String, ([key]: readonly [string, unknown]) => key),
+    ),
+    Record.fromEntries,
+  );
+};
+
+/**
+ * Immutably deletes the value at a `path` from a JSON object, pruning any parent
+ * objects left empty by the deletion.
+ *
+ * Walks `path` from the root; when it resolves to an existing key, that key is
+ * removed and every ancestor that becomes empty as a result is removed too.
+ * Returns `Some(newObject)` when the path existed (so callers can tell something
+ * changed), or `None` when it was absent or `object` isn't a plain object. The
+ * input is never mutated.
+ *
+ * @example
+ * ```ts
+ * import { RecordX } from "@nunofyobiz/effect-extras"
+ * import { Option, pipe } from "effect"
+ *
+ * // deletes the leaf and prunes the now-empty parent
+ * assert.deepStrictEqual(
+ *   RecordX.deleteByPath({ a: { b: 1 } }, ["a", "b"]),
+ *   Option.some({}),
+ * )
+ *
+ * // a sibling key keeps the parent alive
+ * assert.deepStrictEqual(
+ *   RecordX.deleteByPath({ a: { b: 1, c: 2 } }, ["a", "b"]),
+ *   Option.some({ a: { c: 2 } }),
+ * )
+ *
+ * // absent path → None; data-last (pipeable) form
+ * assert.deepStrictEqual(pipe({ a: 1 }, RecordX.deleteByPath(["b"])), Option.none())
+ * ```
+ *
+ * @category combining
+ * @since 0.0.0
+ */
+export const deleteByPath = dual<
+  (path: readonly string[]) => (object: unknown) => Option.Option<unknown>,
+  (object: unknown, path: readonly string[]) => Option.Option<unknown>
+>(2, (object: unknown, path: readonly string[]): Option.Option<unknown> => {
+  if (!PredicateX.unsafeIsRecord(object)) {
+    return Option.none();
+  }
+  const [head, ...rest] = path;
+  if (head === undefined) {
+    return Option.none();
+  }
+  if (rest.length === 0) {
+    return head in object
+      ? Option.some(Record.remove(object, head))
+      : Option.none();
+  }
+  return Option.map(deleteByPath(object[head], rest), (newChild) =>
+    PredicateX.unsafeIsRecord(newChild) && Record.isEmptyRecord(newChild)
+      ? Record.remove(object, head)
+      : { ...object, [head]: newChild },
+  );
+});

package/src/StringX.ts

@@ -3,6 +3,7 @@
  *
  * @since 0.0.0
  */
+import { Array } from "effect";
 import { dual } from "effect/Function";
 
 /**
@@ -95,3 +96,115 @@ export const ensurePrepend = dual<
 
   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 = dual<
+  (
+    startLine: number,
+    endLine: number,
+    replacement: readonly string[],
+  ) => (content: string) => string,
+  (
+    content: string,
+    startLine: number,
+    endLine: number,
+    replacement: readonly string[],
+  ) => string
+>(
+  4,
+  (
+    content: string,
+    startLine: number,
+    endLine: number,
+    replacement: readonly string[],
+  ): string => {
+    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 = dual<
+  (
+    anchorIndex: number,
+    lines: readonly string[],
+  ) => (content: string) => string,
+  (content: string, anchorIndex: number, lines: readonly string[]) => string
+>(
+  3,
+  (content: string, anchorIndex: number, lines: readonly string[]): string => {
+    const split = content.split("\n");
+    return Array.join(
+      [
+        ...Array.take(split, anchorIndex),
+        ...lines,
+        ...Array.drop(split, anchorIndex),
+      ],
+      "\n",
+    );
+  },
+);