@nunofyobiz/effect-extras 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/README.md +38 -3
  2. package/dist/ArrayX.d.ts +381 -0
  3. package/dist/ArrayX.d.ts.map +1 -0
  4. package/dist/ArrayX.js +493 -0
  5. package/dist/ArrayX.js.map +1 -0
  6. package/dist/BigIntX.d.ts +24 -0
  7. package/dist/BigIntX.d.ts.map +1 -0
  8. package/dist/BigIntX.js +30 -0
  9. package/dist/BigIntX.js.map +1 -0
  10. package/dist/BooleanX.d.ts +25 -0
  11. package/dist/BooleanX.d.ts.map +1 -0
  12. package/dist/BooleanX.js +25 -0
  13. package/dist/BooleanX.js.map +1 -0
  14. package/dist/DurationX.d.ts +73 -0
  15. package/dist/DurationX.d.ts.map +1 -0
  16. package/dist/DurationX.js +91 -0
  17. package/dist/DurationX.js.map +1 -0
  18. package/dist/EffectX.d.ts +120 -0
  19. package/dist/EffectX.d.ts.map +1 -0
  20. package/dist/EffectX.js +140 -0
  21. package/dist/EffectX.js.map +1 -0
  22. package/dist/FormDataX.d.ts +49 -0
  23. package/dist/FormDataX.d.ts.map +1 -0
  24. package/dist/FormDataX.js +42 -0
  25. package/dist/FormDataX.js.map +1 -0
  26. package/dist/InclusiveOr.d.ts +1123 -0
  27. package/dist/InclusiveOr.d.ts.map +1 -0
  28. package/dist/InclusiveOr.js +1074 -0
  29. package/dist/InclusiveOr.js.map +1 -0
  30. package/dist/MapX.d.ts +32 -0
  31. package/dist/MapX.d.ts.map +1 -0
  32. package/dist/MapX.js +49 -0
  33. package/dist/MapX.js.map +1 -0
  34. package/dist/NonNullableX.d.ts +174 -0
  35. package/dist/NonNullableX.d.ts.map +1 -0
  36. package/dist/NonNullableX.js +217 -0
  37. package/dist/NonNullableX.js.map +1 -0
  38. package/dist/NumberX.d.ts +178 -0
  39. package/dist/NumberX.d.ts.map +1 -0
  40. package/dist/NumberX.js +214 -0
  41. package/dist/NumberX.js.map +1 -0
  42. package/dist/OptionX.d.ts +187 -0
  43. package/dist/OptionX.d.ts.map +1 -0
  44. package/dist/OptionX.js +201 -0
  45. package/dist/OptionX.js.map +1 -0
  46. package/dist/OrderX.d.ts +32 -0
  47. package/dist/OrderX.d.ts.map +1 -0
  48. package/dist/OrderX.js +32 -0
  49. package/dist/OrderX.js.map +1 -0
  50. package/dist/PredicateX.d.ts +108 -0
  51. package/dist/PredicateX.d.ts.map +1 -0
  52. package/dist/PredicateX.js +111 -0
  53. package/dist/PredicateX.js.map +1 -0
  54. package/dist/PromiseX.d.ts +32 -0
  55. package/dist/PromiseX.d.ts.map +1 -0
  56. package/dist/PromiseX.js +32 -0
  57. package/dist/PromiseX.js.map +1 -0
  58. package/dist/RecordX.d.ts +450 -0
  59. package/dist/RecordX.d.ts.map +1 -0
  60. package/dist/RecordX.js +487 -0
  61. package/dist/RecordX.js.map +1 -0
  62. package/dist/ResultX.d.ts +50 -0
  63. package/dist/ResultX.d.ts.map +1 -0
  64. package/dist/ResultX.js +50 -0
  65. package/dist/ResultX.js.map +1 -0
  66. package/dist/SchemaX.d.ts +249 -0
  67. package/dist/SchemaX.d.ts.map +1 -0
  68. package/dist/SchemaX.js +243 -0
  69. package/dist/SchemaX.js.map +1 -0
  70. package/dist/SetX.d.ts +121 -0
  71. package/dist/SetX.d.ts.map +1 -0
  72. package/dist/SetX.js +137 -0
  73. package/dist/SetX.js.map +1 -0
  74. package/dist/StringX.d.ts +131 -0
  75. package/dist/StringX.d.ts.map +1 -0
  76. package/dist/StringX.js +149 -0
  77. package/dist/StringX.js.map +1 -0
  78. package/dist/StructX.d.ts +219 -0
  79. package/dist/StructX.d.ts.map +1 -0
  80. package/dist/StructX.js +173 -0
  81. package/dist/StructX.js.map +1 -0
  82. package/dist/WarnResult.d.ts +1191 -0
  83. package/dist/WarnResult.d.ts.map +1 -0
  84. package/dist/WarnResult.js +991 -0
  85. package/dist/WarnResult.js.map +1 -0
  86. package/dist/index.d.ts +23 -3772
  87. package/dist/index.d.ts.map +1 -0
  88. package/dist/index.js +22 -1011
  89. package/dist/index.js.map +1 -1
  90. package/package.json +18 -5
  91. package/src/{ArrayX/ArrayX.ts → ArrayX.ts} +6 -88
  92. package/src/{DurationX/DurationX.ts → DurationX.ts} +1 -1
  93. package/src/InclusiveOr.ts +1255 -0
  94. package/src/{NonNullableX/NonNullableX.ts → NonNullableX.ts} +5 -0
  95. package/src/{OptionX/OptionX.ts → OptionX.ts} +8 -2
  96. package/src/{PredicateX/PredicateX.ts → PredicateX.ts} +41 -0
  97. package/src/{RecordX/RecordX.ts → RecordX.ts} +184 -2
  98. package/src/StringX.ts +210 -0
  99. package/src/{WarnResult/WarnResult.ts → WarnResult.ts} +297 -227
  100. package/src/index.ts +22 -20
  101. package/src/ArrayX/index.ts +0 -1
  102. package/src/BigIntX/index.ts +0 -1
  103. package/src/BooleanX/index.ts +0 -1
  104. package/src/DurationX/index.ts +0 -1
  105. package/src/EffectX/index.ts +0 -1
  106. package/src/FormDataX/index.ts +0 -1
  107. package/src/MapX/index.ts +0 -1
  108. package/src/NonNullableX/index.ts +0 -2
  109. package/src/NumberX/index.ts +0 -1
  110. package/src/OptionX/index.ts +0 -1
  111. package/src/OrderX/index.ts +0 -1
  112. package/src/PredicateX/index.ts +0 -1
  113. package/src/PromiseX/index.ts +0 -1
  114. package/src/RecordX/index.ts +0 -1
  115. package/src/ResultX/index.ts +0 -1
  116. package/src/SchemaX/index.ts +0 -1
  117. package/src/SetX/index.ts +0 -1
  118. package/src/StringX/StringX.ts +0 -97
  119. package/src/StringX/index.ts +0 -1
  120. package/src/StructX/index.ts +0 -1
  121. package/src/WarnResult/index.ts +0 -1
  122. /package/src/{BigIntX/BigIntX.ts → BigIntX.ts} +0 -0
  123. /package/src/{BooleanX/BooleanX.ts → BooleanX.ts} +0 -0
  124. /package/src/{EffectX/EffectX.ts → EffectX.ts} +0 -0
  125. /package/src/{FormDataX/FormDataX.ts → FormDataX.ts} +0 -0
  126. /package/src/{MapX/MapX.ts → MapX.ts} +0 -0
  127. /package/src/{NumberX/NumberX.ts → NumberX.ts} +0 -0
  128. /package/src/{OrderX/OrderX.ts → OrderX.ts} +0 -0
  129. /package/src/{PromiseX/PromiseX.ts → PromiseX.ts} +0 -0
  130. /package/src/{ResultX/ResultX.ts → ResultX.ts} +0 -0
  131. /package/src/{SchemaX/SchemaX.ts → SchemaX.ts} +0 -0
  132. /package/src/{SetX/SetX.ts → SetX.ts} +0 -0
  133. /package/src/{StructX/StructX.ts → StructX.ts} +0 -0
@@ -0,0 +1,450 @@
1
+ /**
2
+ * Generic, framework-agnostic extensions to Effect's `Record` module.
3
+ *
4
+ * @since 0.0.0
5
+ */
6
+ import { Option, Order, Predicate, Reducer } from "effect";
7
+ /**
8
+ * Returns `true` when `record` has at least one entry, narrowing it to a
9
+ * known-non-empty `Record`.
10
+ *
11
+ * The negation of `Record.isEmptyRecord`, packaged as a type guard so it reads
12
+ * naturally at call sites that want to branch on "this record has something in
13
+ * it" without a manual `!Record.isEmptyRecord(...)`.
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * import { RecordX } from "@nunofyobiz/effect-extras"
18
+ *
19
+ * assert.deepStrictEqual(RecordX.isNonEmptyRecord({ a: 1 }), true)
20
+ * assert.deepStrictEqual(RecordX.isNonEmptyRecord({}), false)
21
+ * ```
22
+ *
23
+ * @category guards
24
+ * @since 0.0.0
25
+ */
26
+ export declare const isNonEmptyRecord: <K extends PropertyKey, V>(record: Record<K, V>) => record is Record<K, V>;
27
+ /**
28
+ * Modifies the value at `key` in `self` with `f`, leaving the record unchanged
29
+ * if the key doesn't exist.
30
+ *
31
+ * v4's `Record.modify` returns `Option<Record>` — `None` when the key is
32
+ * absent. This helper picks the "do nothing if absent" semantics that v3's
33
+ * `Record.modify` had implicitly, and that most call sites assume. The modifier
34
+ * is never invoked when the key is missing.
35
+ *
36
+ * @example
37
+ * ```ts
38
+ * import { pipe } from "effect"
39
+ * import { RecordX } from "@nunofyobiz/effect-extras"
40
+ *
41
+ * // data-first
42
+ * assert.deepStrictEqual(
43
+ * RecordX.modifyIfExists({ a: 1, b: 2 }, "b", (n) => n * 10),
44
+ * { a: 1, b: 20 },
45
+ * )
46
+ *
47
+ * // a missing key leaves the record untouched
48
+ * const counts: Record<string, number> = { a: 1, b: 2 }
49
+ * assert.deepStrictEqual(
50
+ * RecordX.modifyIfExists(counts, "missing", (n) => n + 1),
51
+ * { a: 1, b: 2 },
52
+ * )
53
+ *
54
+ * // data-last (pipeable)
55
+ * assert.deepStrictEqual(
56
+ * pipe({ a: 1, b: 2 }, RecordX.modifyIfExists("a", (n) => n * 10)),
57
+ * { a: 10, b: 2 },
58
+ * )
59
+ * ```
60
+ *
61
+ * @category mapping
62
+ * @since 0.0.0
63
+ */
64
+ export declare const modifyIfExists: {
65
+ <K extends string, A>(key: NoInfer<K>, f: (a: A) => A): (self: Record<K, A>) => Record<K, A>;
66
+ <K extends string, A>(self: Record<K, A>, key: NoInfer<K>, f: (a: A) => A): Record<K, A>;
67
+ };
68
+ /**
69
+ * Returns the smallest value of `record` (per `order`) that matches
70
+ * `predicate`, narrowed to the refined type `B`, or `Option.none()` if none
71
+ * match.
72
+ *
73
+ * The `Record` counterpart of `ArrayX.takeFirstWhere`: it considers only the
74
+ * record's values, keeps those satisfying `predicate`, and returns the minimum
75
+ * of them by `order`. Keys are ignored entirely.
76
+ *
77
+ * @example
78
+ * ```ts
79
+ * import { Option, Order, pipe } from "effect"
80
+ * import { RecordX } from "@nunofyobiz/effect-extras"
81
+ *
82
+ * const isEven = (n: number): n is number => n % 2 === 0
83
+ *
84
+ * // data-first
85
+ * assert.deepStrictEqual(
86
+ * RecordX.takeFirstWhere({ a: 3, b: 4, c: 2 }, isEven, Order.Number),
87
+ * Option.some(2),
88
+ * )
89
+ *
90
+ * // data-last (pipeable); no even values yields None
91
+ * assert.deepStrictEqual(
92
+ * pipe({ a: 1, b: 3 }, RecordX.takeFirstWhere(isEven, Order.Number)),
93
+ * Option.none(),
94
+ * )
95
+ * ```
96
+ *
97
+ * @category getters
98
+ * @since 0.0.0
99
+ */
100
+ export declare const takeFirstWhere: (<K extends PropertyKey, A, B extends A>(predicate: Predicate.Refinement<A, B>, order: Order.Order<B>) => (record: Record<K, A>) => Option.Option<B>) & (<K extends PropertyKey, A, B extends A>(record: Record<K, A>, predicate: Predicate.Refinement<A, B>, order: Order.Order<B>) => Option.Option<B>);
101
+ /**
102
+ * Returns the largest value of `record` (per `order`) that matches `predicate`,
103
+ * narrowed to the refined type `B`, or `Option.none()` if none match.
104
+ *
105
+ * The mirror of {@link takeFirstWhere}: it considers only the record's values,
106
+ * keeps those satisfying `predicate`, and returns the maximum of them by
107
+ * `order`. Keys are ignored entirely.
108
+ *
109
+ * @example
110
+ * ```ts
111
+ * import { Option, Order, pipe } from "effect"
112
+ * import { RecordX } from "@nunofyobiz/effect-extras"
113
+ *
114
+ * const isEven = (n: number): n is number => n % 2 === 0
115
+ *
116
+ * // data-first
117
+ * assert.deepStrictEqual(
118
+ * RecordX.takeLastWhere({ a: 3, b: 4, c: 2 }, isEven, Order.Number),
119
+ * Option.some(4),
120
+ * )
121
+ *
122
+ * // data-last (pipeable); no even values yields None
123
+ * assert.deepStrictEqual(
124
+ * pipe({ a: 1, b: 3 }, RecordX.takeLastWhere(isEven, Order.Number)),
125
+ * Option.none(),
126
+ * )
127
+ * ```
128
+ *
129
+ * @category getters
130
+ * @since 0.0.0
131
+ */
132
+ export declare const takeLastWhere: (<K extends PropertyKey, A, B extends A>(predicate: Predicate.Refinement<A, B>, order: Order.Order<B>) => (record: Record<K, A>) => Option.Option<B>) & (<K extends PropertyKey, A, B extends A>(record: Record<K, A>, predicate: Predicate.Refinement<A, B>, order: Order.Order<B>) => Option.Option<B>);
133
+ /**
134
+ * Returns the largest value of `record` according to `order`, wrapped in an
135
+ * `Option` so empty records are handled safely.
136
+ *
137
+ * Sorts the record's values by `order` and takes the last one, yielding
138
+ * `Option.none()` when the record is empty and `Option.some(max)` otherwise.
139
+ * Keys are ignored — only values participate in the ordering.
140
+ *
141
+ * @example
142
+ * ```ts
143
+ * import { Option, Order, pipe } from "effect"
144
+ * import { RecordX } from "@nunofyobiz/effect-extras"
145
+ *
146
+ * // data-first
147
+ * assert.deepStrictEqual(
148
+ * RecordX.takeLast({ a: 3, b: 5, c: 1 }, Order.Number),
149
+ * Option.some(5),
150
+ * )
151
+ *
152
+ * // data-last (pipeable); empty record yields None
153
+ * assert.deepStrictEqual(
154
+ * pipe({}, RecordX.takeLast(Order.Number)),
155
+ * Option.none(),
156
+ * )
157
+ * ```
158
+ *
159
+ * @category getters
160
+ * @since 0.0.0
161
+ */
162
+ export declare const takeLast: (<K extends PropertyKey, A>(order: Order.Order<A>) => (record: Record<K, A>) => Option.Option<A>) & (<K extends PropertyKey, A>(record: Record<K, A>, order: Order.Order<A>) => Option.Option<A>);
163
+ /**
164
+ * Re-types the keys of a `Record` to a different key type `K2` without touching
165
+ * the runtime value.
166
+ *
167
+ * A purely type-level reinterpretation: the record is returned as-is, but the
168
+ * compiler now treats its keys as `K2` instead of the inferred `K1`. Use it at a
169
+ * boundary where you know the keys conform to a narrower branded or literal key
170
+ * type that TypeScript can't infer from the value alone. It performs no
171
+ * validation — the caller is responsible for the keys actually matching `K2`.
172
+ *
173
+ * @example
174
+ * ```ts
175
+ * import { RecordX } from "@nunofyobiz/effect-extras"
176
+ *
177
+ * type UserId = string & { readonly _brand: "UserId" }
178
+ *
179
+ * const byId: Record<string, number> = { u1: 10, u2: 20 }
180
+ * const branded = RecordX.keysAs<UserId>()(byId)
181
+ *
182
+ * // Same runtime value, keys now seen as `UserId`
183
+ * assert.deepStrictEqual(branded, { u1: 10, u2: 20 })
184
+ * ```
185
+ *
186
+ * @category conversions
187
+ * @since 0.0.0
188
+ */
189
+ export declare const keysAs: <K2 extends PropertyKey>() => <K1 extends PropertyKey, V>(record: Record<K1, V>) => Record<K2, V>;
190
+ /**
191
+ * Returns the value at `key` in `record`, throwing an `Error` if the key is
192
+ * absent.
193
+ *
194
+ * The unsafe, get-or-explode counterpart to `Record.get` (which returns an
195
+ * `Option`). The thrown error names the missing key and lists the record's
196
+ * existing keys to aid debugging. Reach for {@link getOrThrowWith} when you need
197
+ * a custom error; prefer `Record.get` whenever absence is a real possibility.
198
+ *
199
+ * @example
200
+ * ```ts
201
+ * import { pipe } from "effect"
202
+ * import { RecordX } from "@nunofyobiz/effect-extras"
203
+ *
204
+ * const record: Record<string, number> = { a: 1, b: 2 }
205
+ *
206
+ * // data-first
207
+ * assert.deepStrictEqual(RecordX.getOrThrow(record, "a"), 1)
208
+ *
209
+ * // data-last (pipeable)
210
+ * assert.deepStrictEqual(pipe(record, RecordX.getOrThrow("b")), 2)
211
+ *
212
+ * // missing key throws
213
+ * assert.throws(() => RecordX.getOrThrow(record, "missing"))
214
+ * ```
215
+ *
216
+ * @category unsafe
217
+ * @since 0.0.0
218
+ */
219
+ export declare const getOrThrow: (<K extends string | symbol>(key: K) => <V>(record: Record<K, V>) => V) & (<K extends string | symbol, V>(record: Record<K, V>, key: K) => V);
220
+ /**
221
+ * Returns the value at `key` in `record`, throwing the result of `onNone(key)`
222
+ * if the key is absent.
223
+ *
224
+ * Like {@link getOrThrow}, but lets the caller supply the thrown value (an
225
+ * `Error`, a string, or any custom failure) computed from the missing key. Use
226
+ * it when the default "key not found" message isn't descriptive enough for the
227
+ * call site.
228
+ *
229
+ * @example
230
+ * ```ts
231
+ * import { pipe } from "effect"
232
+ * import { RecordX } from "@nunofyobiz/effect-extras"
233
+ *
234
+ * const record: Record<string, number> = { a: 1 }
235
+ * const onNone = (key: string) => new Error(`no ${key}`)
236
+ *
237
+ * // data-first
238
+ * assert.deepStrictEqual(RecordX.getOrThrowWith(record, "a", onNone), 1)
239
+ *
240
+ * // data-last (pipeable)
241
+ * assert.deepStrictEqual(pipe(record, RecordX.getOrThrowWith("a", onNone)), 1)
242
+ *
243
+ * // missing key throws the custom error
244
+ * assert.throws(() => RecordX.getOrThrowWith(record, "missing", onNone))
245
+ * ```
246
+ *
247
+ * @category unsafe
248
+ * @since 0.0.0
249
+ */
250
+ export declare const getOrThrowWith: (<K extends string | symbol>(key: K, onNone: (key: K) => unknown) => <V>(record: Record<K, V>) => V) & (<K extends string | symbol, V>(record: Record<K, V>, key: K, onNone: (key: K) => unknown) => V);
251
+ /**
252
+ * Inserts or updates the value at `key`, deriving the new value from the current
253
+ * one via `upsert`.
254
+ *
255
+ * The `upsert` function receives an `Option` of the existing value —
256
+ * `Option.some(value)` when the key is present, `Option.none()` when it's
257
+ * absent — and returns the value to store. This unifies "insert if missing" and
258
+ * "update if present" into a single pass, with `Option.match` as the natural way
259
+ * to handle both cases.
260
+ *
261
+ * @example
262
+ * ```ts
263
+ * import { Option, pipe } from "effect"
264
+ * import { RecordX } from "@nunofyobiz/effect-extras"
265
+ *
266
+ * const bump = Option.match({
267
+ * onNone: () => 1,
268
+ * onSome: (n: number) => n + 1,
269
+ * })
270
+ *
271
+ * // data-first: updates an existing entry
272
+ * assert.deepStrictEqual(RecordX.upsert({ a: 1 }, "a", bump), { a: 2 })
273
+ *
274
+ * // data-last (pipeable): inserts a missing entry
275
+ * const counts: Record<string, number> = { a: 1 }
276
+ * assert.deepStrictEqual(pipe(counts, RecordX.upsert("b", bump)), {
277
+ * a: 1,
278
+ * b: 1,
279
+ * })
280
+ * ```
281
+ *
282
+ * @category mapping
283
+ * @since 0.0.0
284
+ */
285
+ export declare const upsert: (<K extends string | symbol, V>(key: K, upsert: (existingValue: Option.Option<V>) => V) => (record: Record<K, V>) => Record<K, V>) & (<K extends string | symbol, V>(record: Record<K, V>, key: K, upsert: (existingValue: Option.Option<V>) => V) => Record<K, V>);
286
+ /**
287
+ * Indexes an iterable of values into a `Record`, keying each value by the result
288
+ * of `identify`.
289
+ *
290
+ * Builds a lookup table from a collection: every value is stored under the key
291
+ * `identify(value)`. When two values produce the same key the later one wins, so
292
+ * the result holds the last value seen per key. Useful for turning a list of
293
+ * records into a by-id map.
294
+ *
295
+ * @example
296
+ * ```ts
297
+ * import { pipe } from "effect"
298
+ * import { RecordX } from "@nunofyobiz/effect-extras"
299
+ *
300
+ * const items = [
301
+ * { id: "a", n: 1 },
302
+ * { id: "b", n: 2 },
303
+ * { id: "a", n: 3 }, // wins over the earlier "a"
304
+ * ]
305
+ *
306
+ * // data-first
307
+ * assert.deepStrictEqual(
308
+ * RecordX.collectBy(items, (item) => item.id),
309
+ * { a: { id: "a", n: 3 }, b: { id: "b", n: 2 } },
310
+ * )
311
+ *
312
+ * // data-last (pipeable)
313
+ * assert.deepStrictEqual(
314
+ * pipe(items, RecordX.collectBy((item) => item.id)),
315
+ * { a: { id: "a", n: 3 }, b: { id: "b", n: 2 } },
316
+ * )
317
+ * ```
318
+ *
319
+ * @category constructors
320
+ * @since 0.0.0
321
+ */
322
+ export declare const collectBy: (<K extends string | symbol, V>(identify: (v: V) => K) => (values: Iterable<V>) => Record<K, V>) & (<K extends string | symbol, V>(values: Iterable<V>, identify: (v: V) => K) => Record<K, V>);
323
+ /**
324
+ * Deep-merges two JSON values, with `b` winning on conflicts.
325
+ *
326
+ * Plain objects (per `PredicateX.unsafeIsRecord`) are merged recursively,
327
+ * key-by-key; every other shape — primitives, arrays, and impostors like
328
+ * `Map`/`Date`/class instances — is replaced wholesale by `b`. If either side
329
+ * isn't a plain object, `b` is returned as-is. Neither input is mutated. Reach
330
+ * for it to layer partial JSON overrides on top of a base.
331
+ *
332
+ * @example
333
+ * ```ts
334
+ * import { RecordX } from "@nunofyobiz/effect-extras"
335
+ * import { pipe } from "effect"
336
+ *
337
+ * // data-first — nested objects merge, b wins on leaf conflicts
338
+ * assert.deepStrictEqual(
339
+ * RecordX.deepMerge({ a: { x: 1 }, b: 2 }, { a: { y: 3 }, c: 4 }),
340
+ * { a: { x: 1, y: 3 }, b: 2, c: 4 },
341
+ * )
342
+ *
343
+ * // arrays are replaced wholesale, not concatenated
344
+ * assert.deepStrictEqual(RecordX.deepMerge({ a: [1, 2] }, { a: [3] }), { a: [3] })
345
+ *
346
+ * // data-last (pipeable) — merges the override onto the piped base
347
+ * assert.deepStrictEqual(pipe({ a: 1 }, RecordX.deepMerge({ b: 2 })), {
348
+ * a: 1,
349
+ * b: 2,
350
+ * })
351
+ * ```
352
+ *
353
+ * @category combining
354
+ * @since 0.0.0
355
+ */
356
+ export declare const deepMerge: ((b: unknown) => (a: unknown) => unknown) & ((a: unknown, b: unknown) => unknown);
357
+ /**
358
+ * {@link deepMerge} as a `Reducer` (monoid) with identity `{}`.
359
+ *
360
+ * `deepMergeReducer.combineAll(layers)` folds an iterable of object layers
361
+ * left-to-right via {@link deepMerge} — the universal "merge N JSON objects into
362
+ * one" fold, replacing a hand-rolled `Array.reduce(layers, {}, deepMerge)`. The
363
+ * `{}` identity is exact for the object-valued layers these folds carry: an empty
364
+ * list yields `{}`, and a single layer is returned unchanged.
365
+ *
366
+ * @example
367
+ * ```ts
368
+ * import { RecordX } from "@nunofyobiz/effect-extras"
369
+ *
370
+ * assert.deepStrictEqual(
371
+ * RecordX.deepMergeReducer.combineAll([
372
+ * { a: { x: 1 } },
373
+ * { a: { y: 2 }, b: 3 },
374
+ * { b: 4 },
375
+ * ]),
376
+ * { a: { x: 1, y: 2 }, b: 4 },
377
+ * )
378
+ *
379
+ * assert.deepStrictEqual(RecordX.deepMergeReducer.combineAll([]), {})
380
+ * ```
381
+ *
382
+ * @category instances
383
+ * @since 0.0.0
384
+ */
385
+ export declare const deepMergeReducer: Reducer.Reducer<unknown>;
386
+ /**
387
+ * Canonicalizes a JSON value by recursively sorting object keys; arrays keep
388
+ * their order.
389
+ *
390
+ * Two structurally-equal values that differ only in key order canonicalize to
391
+ * the same shape, so `JSON.stringify(canonicalize(x))` is a stable structural
392
+ * key for comparison, deduping, or hashing. Plain objects (per
393
+ * `PredicateX.unsafeIsRecord`) have their keys sorted ascending and their values
394
+ * canonicalized recursively; arrays are canonicalized element-wise in place;
395
+ * everything else passes through unchanged.
396
+ *
397
+ * @example
398
+ * ```ts
399
+ * import { RecordX } from "@nunofyobiz/effect-extras"
400
+ *
401
+ * assert.deepStrictEqual(
402
+ * JSON.stringify(RecordX.canonicalize({ b: 1, a: { d: 1, c: 2 } })),
403
+ * JSON.stringify({ a: { c: 2, d: 1 }, b: 1 }),
404
+ * )
405
+ *
406
+ * // arrays keep their order; primitives pass through
407
+ * assert.deepStrictEqual(RecordX.canonicalize([3, 1, 2]), [3, 1, 2])
408
+ * assert.deepStrictEqual(RecordX.canonicalize("x"), "x")
409
+ * ```
410
+ *
411
+ * @category transformations
412
+ * @since 0.0.0
413
+ */
414
+ export declare const canonicalize: (value: unknown) => unknown;
415
+ /**
416
+ * Immutably deletes the value at a `path` from a JSON object, pruning any parent
417
+ * objects left empty by the deletion.
418
+ *
419
+ * Walks `path` from the root; when it resolves to an existing key, that key is
420
+ * removed and every ancestor that becomes empty as a result is removed too.
421
+ * Returns `Some(newObject)` when the path existed (so callers can tell something
422
+ * changed), or `None` when it was absent or `object` isn't a plain object. The
423
+ * input is never mutated.
424
+ *
425
+ * @example
426
+ * ```ts
427
+ * import { RecordX } from "@nunofyobiz/effect-extras"
428
+ * import { Option, pipe } from "effect"
429
+ *
430
+ * // deletes the leaf and prunes the now-empty parent
431
+ * assert.deepStrictEqual(
432
+ * RecordX.deleteByPath({ a: { b: 1 } }, ["a", "b"]),
433
+ * Option.some({}),
434
+ * )
435
+ *
436
+ * // a sibling key keeps the parent alive
437
+ * assert.deepStrictEqual(
438
+ * RecordX.deleteByPath({ a: { b: 1, c: 2 } }, ["a", "b"]),
439
+ * Option.some({ a: { c: 2 } }),
440
+ * )
441
+ *
442
+ * // absent path → None; data-last (pipeable) form
443
+ * assert.deepStrictEqual(pipe({ a: 1 }, RecordX.deleteByPath(["b"])), Option.none())
444
+ * ```
445
+ *
446
+ * @category combining
447
+ * @since 0.0.0
448
+ */
449
+ export declare const deleteByPath: ((path: readonly string[]) => (object: unknown) => Option.Option<unknown>) & ((object: unknown, path: readonly string[]) => Option.Option<unknown>);
450
+ //# sourceMappingURL=RecordX.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"RecordX.d.ts","sourceRoot":"","sources":["../src/RecordX.ts"],"names":[],"mappings":"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"}