effect 4.0.0-beta.7 → 4.0.0-beta.8

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.
@@ -1,15 +1,91 @@
1
1
  /**
2
+ * A module for combining two values of the same type into one.
3
+ *
4
+ * A `Combiner<A>` wraps a single binary function `(self: A, that: A) => A`.
5
+ * It describes *how* two values merge but carries no initial/empty value
6
+ * (for that, see {@link Reducer} which extends `Combiner` with an
7
+ * `initialValue`).
8
+ *
9
+ * ## Mental model
10
+ *
11
+ * - **Combiner** – an object with a `combine(self, that)` method that returns
12
+ * a value of the same type.
13
+ * - **Argument order** – `self` is the "left" / accumulator side, `that` is
14
+ * the "right" / incoming side.
15
+ * - **No identity element** – unlike a monoid, a `Combiner` does not require
16
+ * a neutral element. Use {@link Reducer} when you need one.
17
+ * - **Purity** – all combiners produced by this module are pure; they never
18
+ * mutate their arguments.
19
+ * - **Composability** – combiners can be lifted into `Option`, `Struct`,
20
+ * `Tuple`, and other container types via helpers in those modules.
21
+ *
22
+ * ## Common tasks
23
+ *
24
+ * - Create a combiner from any binary function → {@link make}
25
+ * - Swap argument order → {@link flip}
26
+ * - Pick the smaller / larger of two values → {@link min} / {@link max}
27
+ * - Always keep the first or last value → {@link first} / {@link last}
28
+ * - Ignore both values and return a fixed result → {@link constant}
29
+ * - Insert a separator between combined values → {@link intercalate}
30
+ *
31
+ * ## Gotchas
32
+ *
33
+ * - `min` and `max` require an `Order<A>`, not a raw comparator. Import from
34
+ * e.g. `Number.Order` or `String.Order`.
35
+ * - `intercalate` is curried: call it with the separator first, then pass the
36
+ * base combiner.
37
+ * - A `Reducer` (which adds `initialValue`) is also a valid `Combiner` — you
38
+ * can pass a `Reducer` anywhere a `Combiner` is expected.
39
+ *
40
+ * ## Quickstart
41
+ *
42
+ * **Example** (combining strings with a separator)
43
+ *
44
+ * ```ts
45
+ * import { Combiner, String } from "effect"
46
+ *
47
+ * const csv = Combiner.intercalate(",")(String.ReducerConcat)
48
+ *
49
+ * console.log(csv.combine("a", "b"))
50
+ * // Output: "a,b"
51
+ *
52
+ * console.log(csv.combine(csv.combine("a", "b"), "c"))
53
+ * // Output: "a,b,c"
54
+ * ```
55
+ *
56
+ * ## See also
57
+ *
58
+ * - {@link make} – the primary constructor
59
+ * - {@link Combiner} – the core interface
60
+ *
2
61
  * @since 4.0.0
3
62
  */
4
63
  import type * as Order from "./Order.ts";
5
64
  /**
6
- * A `Combiner` represents any type of value that can be combined
7
- * with another value of the same type to produce a new value.
65
+ * Represents a strategy for combining two values of the same type `A`.
66
+ *
67
+ * A `Combiner` contains a single `combine` method that takes two values and
68
+ * returns a merged result. It does not include an identity/empty value; use
69
+ * `Reducer` when you need one.
70
+ *
71
+ * When to use:
72
+ * - You need to describe how two values of the same type merge.
73
+ * - You want to pass a reusable combining strategy to library functions like
74
+ * `Struct.makeCombiner` or `Option.makeCombinerFailFast`.
75
+ * - You are building a `Reducer` and need to define the combining step first.
76
+ *
77
+ * **Example** (number addition combiner)
78
+ *
79
+ * ```ts
80
+ * import { Combiner } from "effect"
81
+ *
82
+ * const Sum = Combiner.make<number>((self, that) => self + that)
8
83
  *
9
- * Examples:
10
- * - numbers with addition
11
- * - strings with concatenation
12
- * - arrays with merging
84
+ * console.log(Sum.combine(3, 4))
85
+ * // Output: 7
86
+ * ```
87
+ *
88
+ * @see {@link make} – create a `Combiner` from a function
13
89
  *
14
90
  * @category model
15
91
  * @since 4.0.0
@@ -21,47 +97,238 @@ export interface Combiner<A> {
21
97
  readonly combine: (self: A, that: A) => A;
22
98
  }
23
99
  /**
24
- * Creates a `Combiner` from a `combine` function.
100
+ * Creates a `Combiner` from a binary function.
101
+ *
102
+ * When to use:
103
+ * - You have a custom combining operation that is not covered by the built-in
104
+ * constructors (`min`, `max`, `first`, `last`, `constant`).
105
+ *
106
+ * Behavior:
107
+ * - Returns a new `Combiner` whose `combine` method delegates to the provided
108
+ * function.
109
+ * - Pure – the returned combiner does not mutate its arguments.
110
+ *
111
+ * **Example** (multiplying numbers)
112
+ *
113
+ * ```ts
114
+ * import { Combiner } from "effect"
115
+ *
116
+ * const Product = Combiner.make<number>((self, that) => self * that)
117
+ *
118
+ * console.log(Product.combine(3, 5))
119
+ * // Output: 15
120
+ * ```
121
+ *
122
+ * @see {@link Combiner} – the interface this creates
25
123
  *
26
124
  * @since 4.0.0
27
125
  */
28
126
  export declare function make<A>(combine: (self: A, that: A) => A): Combiner<A>;
29
127
  /**
128
+ * Reverses the argument order of a combiner's `combine` method.
129
+ *
130
+ * When to use:
131
+ * - You need the "right" value to act as the accumulator side.
132
+ * - You want to reverse the natural direction of a non-commutative combiner
133
+ * (e.g. string concatenation).
134
+ *
135
+ * Behavior:
136
+ * - Returns a new `Combiner` where `combine(self, that)` calls the original
137
+ * combiner as `combine(that, self)`.
138
+ * - Does not mutate the input combiner.
139
+ *
140
+ * **Example** (reversing string concatenation)
141
+ *
142
+ * ```ts
143
+ * import { Combiner, String } from "effect"
144
+ *
145
+ * const Prepend = Combiner.flip(String.ReducerConcat)
146
+ *
147
+ * console.log(Prepend.combine("a", "b"))
148
+ * // Output: "ba"
149
+ * ```
150
+ *
151
+ * @see {@link make}
152
+ *
30
153
  * @since 4.0.0
31
154
  */
32
155
  export declare function flip<A>(combiner: Combiner<A>): Combiner<A>;
33
156
  /**
34
- * Creates a `Combiner` that returns the smaller of two values.
157
+ * Creates a `Combiner` that returns the smaller of two values according to
158
+ * the provided `Order`.
159
+ *
160
+ * When to use:
161
+ * - You want to accumulate the minimum value across a collection.
162
+ * - You are building a `Reducer` that tracks the running minimum.
163
+ *
164
+ * Behavior:
165
+ * - Compares using the given `Order`. When values are equal, returns `that`
166
+ * (the second argument).
167
+ * - Pure – does not mutate either argument.
168
+ *
169
+ * **Example** (minimum of two numbers)
170
+ *
171
+ * ```ts
172
+ * import { Combiner, Number } from "effect"
173
+ *
174
+ * const Min = Combiner.min(Number.Order)
175
+ *
176
+ * console.log(Min.combine(3, 1))
177
+ * // Output: 1
178
+ *
179
+ * console.log(Min.combine(1, 3))
180
+ * // Output: 1
181
+ * ```
182
+ *
183
+ * @see {@link max}
35
184
  *
36
185
  * @since 4.0.0
37
186
  */
38
187
  export declare function min<A>(order: Order.Order<A>): Combiner<A>;
39
188
  /**
40
- * Creates a `Combiner` that returns the larger of two values.
189
+ * Creates a `Combiner` that returns the larger of two values according to
190
+ * the provided `Order`.
191
+ *
192
+ * When to use:
193
+ * - You want to accumulate the maximum value across a collection.
194
+ * - You are building a `Reducer` that tracks the running maximum.
195
+ *
196
+ * Behavior:
197
+ * - Compares using the given `Order`. When values are equal, returns `that`
198
+ * (the second argument).
199
+ * - Pure – does not mutate either argument.
200
+ *
201
+ * **Example** (maximum of two numbers)
202
+ *
203
+ * ```ts
204
+ * import { Combiner, Number } from "effect"
205
+ *
206
+ * const Max = Combiner.max(Number.Order)
207
+ *
208
+ * console.log(Max.combine(3, 1))
209
+ * // Output: 3
210
+ *
211
+ * console.log(Max.combine(1, 3))
212
+ * // Output: 3
213
+ * ```
214
+ *
215
+ * @see {@link min}
41
216
  *
42
217
  * @since 4.0.0
43
218
  */
44
219
  export declare function max<A>(order: Order.Order<A>): Combiner<A>;
45
220
  /**
46
- * Creates a `Combiner` that returns the first value.
221
+ * Creates a `Combiner` that always returns the first (left) argument.
222
+ *
223
+ * When to use:
224
+ * - You want "first write wins" semantics when merging values.
225
+ * - You need a combiner but the combining logic should be a no-op that keeps
226
+ * the existing value.
227
+ *
228
+ * Behavior:
229
+ * - `combine(self, that)` returns `self`, ignoring `that`.
230
+ * - Pure – the second argument is discarded, not mutated.
231
+ *
232
+ * **Example** (keeping the first value)
233
+ *
234
+ * ```ts
235
+ * import { Combiner } from "effect"
236
+ *
237
+ * const First = Combiner.first<number>()
238
+ *
239
+ * console.log(First.combine(1, 2))
240
+ * // Output: 1
241
+ * ```
242
+ *
243
+ * @see {@link last}
47
244
  *
48
245
  * @since 4.0.0
49
246
  */
50
247
  export declare function first<A>(): Combiner<A>;
51
248
  /**
52
- * Creates a `Combiner` that returns the last value.
249
+ * Creates a `Combiner` that always returns the last (right) argument.
250
+ *
251
+ * When to use:
252
+ * - You want "last write wins" semantics when merging values.
253
+ * - You need a combiner that replaces the accumulator with each new value.
254
+ *
255
+ * Behavior:
256
+ * - `combine(self, that)` returns `that`, ignoring `self`.
257
+ * - Pure – the first argument is discarded, not mutated.
258
+ *
259
+ * **Example** (keeping the last value)
260
+ *
261
+ * ```ts
262
+ * import { Combiner } from "effect"
263
+ *
264
+ * const Last = Combiner.last<number>()
265
+ *
266
+ * console.log(Last.combine(1, 2))
267
+ * // Output: 2
268
+ * ```
269
+ *
270
+ * @see {@link first}
53
271
  *
54
272
  * @since 4.0.0
55
273
  */
56
274
  export declare function last<A>(): Combiner<A>;
57
275
  /**
58
- * Creates a `Combiner` that returns a constant value.
276
+ * Creates a `Combiner` that ignores both arguments and always returns the
277
+ * given constant value.
278
+ *
279
+ * When to use:
280
+ * - You need a combiner that produces a fixed result regardless of input.
281
+ * - You are providing a combiner to a generic API but the combined value is
282
+ * predetermined.
283
+ *
284
+ * Behavior:
285
+ * - `combine(self, that)` returns the constant `a`, ignoring both arguments.
286
+ * - Pure – no mutation occurs.
287
+ *
288
+ * **Example** (always returning zero)
289
+ *
290
+ * ```ts
291
+ * import { Combiner } from "effect"
292
+ *
293
+ * const Zero = Combiner.constant(0)
294
+ *
295
+ * console.log(Zero.combine(42, 99))
296
+ * // Output: 0
297
+ * ```
298
+ *
299
+ * @see {@link first}
300
+ * @see {@link last}
59
301
  *
60
302
  * @since 4.0.0
61
303
  */
62
304
  export declare function constant<A>(a: A): Combiner<A>;
63
305
  /**
64
- * Between each pair of elements insert `middle`.
306
+ * Wraps a `Combiner` so that a separator value is inserted between every
307
+ * pair of combined elements.
308
+ *
309
+ * When to use:
310
+ * - You are building delimited strings (CSV, paths, etc.) by repeated
311
+ * combination.
312
+ * - You need to inject a fixed separator between accumulated values.
313
+ *
314
+ * Behavior:
315
+ * - `intercalate(middle)(combiner).combine(self, that)` is equivalent to
316
+ * `combiner.combine(self, combiner.combine(middle, that))`.
317
+ * - Curried: first provide the separator, then the base combiner.
318
+ * - Does not mutate the input combiner; returns a new one.
319
+ *
320
+ * **Example** (joining strings with a separator)
321
+ *
322
+ * ```ts
323
+ * import { Combiner, String } from "effect"
324
+ *
325
+ * const commaSep = Combiner.intercalate(",")(String.ReducerConcat)
326
+ *
327
+ * console.log(commaSep.combine("a", "b"))
328
+ * // Output: "a,b"
329
+ * ```
330
+ *
331
+ * @see {@link make}
65
332
  *
66
333
  * @since 4.0.0
67
334
  */
@@ -1 +1 @@
1
- {"version":3,"file":"Combiner.d.ts","sourceRoot":"","sources":["../src/Combiner.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAA;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAErE;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAErC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,IAC9B,UAAU,QAAQ,CAAC,CAAC,CAAC,KAAG,QAAQ,CAAC,CAAC,CAAC,CAE5C"}
1
+ {"version":3,"file":"Combiner.d.ts","sourceRoot":"","sources":["../src/Combiner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAErE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAE1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,KAAK,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAEtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,IAAI,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAErC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAE7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,IAC9B,UAAU,QAAQ,CAAC,CAAC,CAAC,KAAG,QAAQ,CAAC,CAAC,CAAC,CAE5C"}
package/dist/Combiner.js CHANGED
@@ -1,5 +1,27 @@
1
1
  /**
2
- * Creates a `Combiner` from a `combine` function.
2
+ * Creates a `Combiner` from a binary function.
3
+ *
4
+ * When to use:
5
+ * - You have a custom combining operation that is not covered by the built-in
6
+ * constructors (`min`, `max`, `first`, `last`, `constant`).
7
+ *
8
+ * Behavior:
9
+ * - Returns a new `Combiner` whose `combine` method delegates to the provided
10
+ * function.
11
+ * - Pure – the returned combiner does not mutate its arguments.
12
+ *
13
+ * **Example** (multiplying numbers)
14
+ *
15
+ * ```ts
16
+ * import { Combiner } from "effect"
17
+ *
18
+ * const Product = Combiner.make<number>((self, that) => self * that)
19
+ *
20
+ * console.log(Product.combine(3, 5))
21
+ * // Output: 15
22
+ * ```
23
+ *
24
+ * @see {@link Combiner} – the interface this creates
3
25
  *
4
26
  * @since 4.0.0
5
27
  */
@@ -9,13 +31,64 @@ export function make(combine) {
9
31
  };
10
32
  }
11
33
  /**
34
+ * Reverses the argument order of a combiner's `combine` method.
35
+ *
36
+ * When to use:
37
+ * - You need the "right" value to act as the accumulator side.
38
+ * - You want to reverse the natural direction of a non-commutative combiner
39
+ * (e.g. string concatenation).
40
+ *
41
+ * Behavior:
42
+ * - Returns a new `Combiner` where `combine(self, that)` calls the original
43
+ * combiner as `combine(that, self)`.
44
+ * - Does not mutate the input combiner.
45
+ *
46
+ * **Example** (reversing string concatenation)
47
+ *
48
+ * ```ts
49
+ * import { Combiner, String } from "effect"
50
+ *
51
+ * const Prepend = Combiner.flip(String.ReducerConcat)
52
+ *
53
+ * console.log(Prepend.combine("a", "b"))
54
+ * // Output: "ba"
55
+ * ```
56
+ *
57
+ * @see {@link make}
58
+ *
12
59
  * @since 4.0.0
13
60
  */
14
61
  export function flip(combiner) {
15
62
  return make((self, that) => combiner.combine(that, self));
16
63
  }
17
64
  /**
18
- * Creates a `Combiner` that returns the smaller of two values.
65
+ * Creates a `Combiner` that returns the smaller of two values according to
66
+ * the provided `Order`.
67
+ *
68
+ * When to use:
69
+ * - You want to accumulate the minimum value across a collection.
70
+ * - You are building a `Reducer` that tracks the running minimum.
71
+ *
72
+ * Behavior:
73
+ * - Compares using the given `Order`. When values are equal, returns `that`
74
+ * (the second argument).
75
+ * - Pure – does not mutate either argument.
76
+ *
77
+ * **Example** (minimum of two numbers)
78
+ *
79
+ * ```ts
80
+ * import { Combiner, Number } from "effect"
81
+ *
82
+ * const Min = Combiner.min(Number.Order)
83
+ *
84
+ * console.log(Min.combine(3, 1))
85
+ * // Output: 1
86
+ *
87
+ * console.log(Min.combine(1, 3))
88
+ * // Output: 1
89
+ * ```
90
+ *
91
+ * @see {@link max}
19
92
  *
20
93
  * @since 4.0.0
21
94
  */
@@ -23,7 +96,33 @@ export function min(order) {
23
96
  return make((self, that) => order(self, that) === -1 ? self : that);
24
97
  }
25
98
  /**
26
- * Creates a `Combiner` that returns the larger of two values.
99
+ * Creates a `Combiner` that returns the larger of two values according to
100
+ * the provided `Order`.
101
+ *
102
+ * When to use:
103
+ * - You want to accumulate the maximum value across a collection.
104
+ * - You are building a `Reducer` that tracks the running maximum.
105
+ *
106
+ * Behavior:
107
+ * - Compares using the given `Order`. When values are equal, returns `that`
108
+ * (the second argument).
109
+ * - Pure – does not mutate either argument.
110
+ *
111
+ * **Example** (maximum of two numbers)
112
+ *
113
+ * ```ts
114
+ * import { Combiner, Number } from "effect"
115
+ *
116
+ * const Max = Combiner.max(Number.Order)
117
+ *
118
+ * console.log(Max.combine(3, 1))
119
+ * // Output: 3
120
+ *
121
+ * console.log(Max.combine(1, 3))
122
+ * // Output: 3
123
+ * ```
124
+ *
125
+ * @see {@link min}
27
126
  *
28
127
  * @since 4.0.0
29
128
  */
@@ -31,7 +130,29 @@ export function max(order) {
31
130
  return make((self, that) => order(self, that) === 1 ? self : that);
32
131
  }
33
132
  /**
34
- * Creates a `Combiner` that returns the first value.
133
+ * Creates a `Combiner` that always returns the first (left) argument.
134
+ *
135
+ * When to use:
136
+ * - You want "first write wins" semantics when merging values.
137
+ * - You need a combiner but the combining logic should be a no-op that keeps
138
+ * the existing value.
139
+ *
140
+ * Behavior:
141
+ * - `combine(self, that)` returns `self`, ignoring `that`.
142
+ * - Pure – the second argument is discarded, not mutated.
143
+ *
144
+ * **Example** (keeping the first value)
145
+ *
146
+ * ```ts
147
+ * import { Combiner } from "effect"
148
+ *
149
+ * const First = Combiner.first<number>()
150
+ *
151
+ * console.log(First.combine(1, 2))
152
+ * // Output: 1
153
+ * ```
154
+ *
155
+ * @see {@link last}
35
156
  *
36
157
  * @since 4.0.0
37
158
  */
@@ -39,7 +160,28 @@ export function first() {
39
160
  return make((self, _) => self);
40
161
  }
41
162
  /**
42
- * Creates a `Combiner` that returns the last value.
163
+ * Creates a `Combiner` that always returns the last (right) argument.
164
+ *
165
+ * When to use:
166
+ * - You want "last write wins" semantics when merging values.
167
+ * - You need a combiner that replaces the accumulator with each new value.
168
+ *
169
+ * Behavior:
170
+ * - `combine(self, that)` returns `that`, ignoring `self`.
171
+ * - Pure – the first argument is discarded, not mutated.
172
+ *
173
+ * **Example** (keeping the last value)
174
+ *
175
+ * ```ts
176
+ * import { Combiner } from "effect"
177
+ *
178
+ * const Last = Combiner.last<number>()
179
+ *
180
+ * console.log(Last.combine(1, 2))
181
+ * // Output: 2
182
+ * ```
183
+ *
184
+ * @see {@link first}
43
185
  *
44
186
  * @since 4.0.0
45
187
  */
@@ -47,7 +189,31 @@ export function last() {
47
189
  return make((_, that) => that);
48
190
  }
49
191
  /**
50
- * Creates a `Combiner` that returns a constant value.
192
+ * Creates a `Combiner` that ignores both arguments and always returns the
193
+ * given constant value.
194
+ *
195
+ * When to use:
196
+ * - You need a combiner that produces a fixed result regardless of input.
197
+ * - You are providing a combiner to a generic API but the combined value is
198
+ * predetermined.
199
+ *
200
+ * Behavior:
201
+ * - `combine(self, that)` returns the constant `a`, ignoring both arguments.
202
+ * - Pure – no mutation occurs.
203
+ *
204
+ * **Example** (always returning zero)
205
+ *
206
+ * ```ts
207
+ * import { Combiner } from "effect"
208
+ *
209
+ * const Zero = Combiner.constant(0)
210
+ *
211
+ * console.log(Zero.combine(42, 99))
212
+ * // Output: 0
213
+ * ```
214
+ *
215
+ * @see {@link first}
216
+ * @see {@link last}
51
217
  *
52
218
  * @since 4.0.0
53
219
  */
@@ -55,7 +221,32 @@ export function constant(a) {
55
221
  return make(() => a);
56
222
  }
57
223
  /**
58
- * Between each pair of elements insert `middle`.
224
+ * Wraps a `Combiner` so that a separator value is inserted between every
225
+ * pair of combined elements.
226
+ *
227
+ * When to use:
228
+ * - You are building delimited strings (CSV, paths, etc.) by repeated
229
+ * combination.
230
+ * - You need to inject a fixed separator between accumulated values.
231
+ *
232
+ * Behavior:
233
+ * - `intercalate(middle)(combiner).combine(self, that)` is equivalent to
234
+ * `combiner.combine(self, combiner.combine(middle, that))`.
235
+ * - Curried: first provide the separator, then the base combiner.
236
+ * - Does not mutate the input combiner; returns a new one.
237
+ *
238
+ * **Example** (joining strings with a separator)
239
+ *
240
+ * ```ts
241
+ * import { Combiner, String } from "effect"
242
+ *
243
+ * const commaSep = Combiner.intercalate(",")(String.ReducerConcat)
244
+ *
245
+ * console.log(commaSep.combine("a", "b"))
246
+ * // Output: "a,b"
247
+ * ```
248
+ *
249
+ * @see {@link make}
59
250
  *
60
251
  * @since 4.0.0
61
252
  */
@@ -1 +1 @@
1
- {"version":3,"file":"Combiner.js","names":["make","combine","flip","combiner","self","that","min","order","max","first","_","last","constant","a","intercalate","middle"],"sources":["../src/Combiner.ts"],"sourcesContent":[null],"mappings":"AAwBA;;;;;AAKA,OAAM,SAAUA,IAAIA,CAAIC,OAAgC;EACtD,OAAO;IAAEA;EAAO,CAAE;AACpB;AAEA;;;AAGA,OAAM,SAAUC,IAAIA,CAAIC,QAAqB;EAC3C,OAAOH,IAAI,CAAC,CAACI,IAAI,EAAEC,IAAI,KAAKF,QAAQ,CAACF,OAAO,CAACI,IAAI,EAAED,IAAI,CAAC,CAAC;AAC3D;AAEA;;;;;AAKA,OAAM,SAAUE,GAAGA,CAAIC,KAAqB;EAC1C,OAAOP,IAAI,CAAC,CAACI,IAAI,EAAEC,IAAI,KAAKE,KAAK,CAACH,IAAI,EAAEC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAGD,IAAI,GAAGC,IAAI,CAAC;AACrE;AAEA;;;;;AAKA,OAAM,SAAUG,GAAGA,CAAID,KAAqB;EAC1C,OAAOP,IAAI,CAAC,CAACI,IAAI,EAAEC,IAAI,KAAKE,KAAK,CAACH,IAAI,EAAEC,IAAI,CAAC,KAAK,CAAC,GAAGD,IAAI,GAAGC,IAAI,CAAC;AACpE;AAEA;;;;;AAKA,OAAM,SAAUI,KAAKA,CAAA;EACnB,OAAOT,IAAI,CAAC,CAACI,IAAI,EAAEM,CAAC,KAAKN,IAAI,CAAC;AAChC;AAEA;;;;;AAKA,OAAM,SAAUO,IAAIA,CAAA;EAClB,OAAOX,IAAI,CAAC,CAACU,CAAC,EAAEL,IAAI,KAAKA,IAAI,CAAC;AAChC;AAEA;;;;;AAKA,OAAM,SAAUO,QAAQA,CAAIC,CAAI;EAC9B,OAAOb,IAAI,CAAC,MAAMa,CAAC,CAAC;AACtB;AAEA;;;;;AAKA,OAAM,SAAUC,WAAWA,CAAIC,MAAS;EACtC,OAAQZ,QAAqB,IAC3BH,IAAI,CAAC,CAACI,IAAI,EAAEC,IAAI,KAAKF,QAAQ,CAACF,OAAO,CAACG,IAAI,EAAED,QAAQ,CAACF,OAAO,CAACc,MAAM,EAAEV,IAAI,CAAC,CAAC,CAAC;AAChF","ignoreList":[]}
1
+ {"version":3,"file":"Combiner.js","names":["make","combine","flip","combiner","self","that","min","order","max","first","_","last","constant","a","intercalate","middle"],"sources":["../src/Combiner.ts"],"sourcesContent":[null],"mappings":"AAoGA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAM,SAAUA,IAAIA,CAAIC,OAAgC;EACtD,OAAO;IAAEA;EAAO,CAAE;AACpB;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,OAAM,SAAUC,IAAIA,CAAIC,QAAqB;EAC3C,OAAOH,IAAI,CAAC,CAACI,IAAI,EAAEC,IAAI,KAAKF,QAAQ,CAACF,OAAO,CAACI,IAAI,EAAED,IAAI,CAAC,CAAC;AAC3D;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,OAAM,SAAUE,GAAGA,CAAIC,KAAqB;EAC1C,OAAOP,IAAI,CAAC,CAACI,IAAI,EAAEC,IAAI,KAAKE,KAAK,CAACH,IAAI,EAAEC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAGD,IAAI,GAAGC,IAAI,CAAC;AACrE;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,OAAM,SAAUG,GAAGA,CAAID,KAAqB;EAC1C,OAAOP,IAAI,CAAC,CAACI,IAAI,EAAEC,IAAI,KAAKE,KAAK,CAACH,IAAI,EAAEC,IAAI,CAAC,KAAK,CAAC,GAAGD,IAAI,GAAGC,IAAI,CAAC;AACpE;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,OAAM,SAAUI,KAAKA,CAAA;EACnB,OAAOT,IAAI,CAAC,CAACI,IAAI,EAAEM,CAAC,KAAKN,IAAI,CAAC;AAChC;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,OAAM,SAAUO,IAAIA,CAAA;EAClB,OAAOX,IAAI,CAAC,CAACU,CAAC,EAAEL,IAAI,KAAKA,IAAI,CAAC;AAChC;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAM,SAAUO,QAAQA,CAAIC,CAAI;EAC9B,OAAOb,IAAI,CAAC,MAAMa,CAAC,CAAC;AACtB;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAM,SAAUC,WAAWA,CAAIC,MAAS;EACtC,OAAQZ,QAAqB,IAC3BH,IAAI,CAAC,CAACI,IAAI,EAAEC,IAAI,KAAKF,QAAQ,CAACF,OAAO,CAACG,IAAI,EAAED,QAAQ,CAACF,OAAO,CAACc,MAAM,EAAEV,IAAI,CAAC,CAAC,CAAC;AAChF","ignoreList":[]}