@openstage/monadyssey-core 3.0.0-rc.1 → 3.0.0-rc.2

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.
@@ -172,6 +172,15 @@ export declare interface Err<E> {
172
172
  * @template A The type of the value that this computation produces.
173
173
  */
174
174
  export declare abstract class Eval<A> {
175
+ /**
176
+ * Retrieves the value of the operation.
177
+ * This is an internal method used by the trampoline interpreter. External code should
178
+ * always use `evaluate()` instead — calling `value()` directly on `Map` or `FlatMap`
179
+ * nodes throws an `EvaluationError`.
180
+ *
181
+ * @returns {A} The value produced by the operation.
182
+ */
183
+ protected abstract value(): A;
175
184
  /**
176
185
  * Creates a deferred operation that will be evaluated later.
177
186
  * The provided function is not executed until the value of the operation is needed.
@@ -333,13 +342,19 @@ export declare class EvaluationError<E> extends Error {
333
342
  constructor(error: E);
334
343
  }
335
344
 
345
+ /**
346
+ * The outcome of a run: a value, a typed error, or cancellation. A forked fiber's `join()` resolves to
347
+ * an `Exit`; `unsafeRun()` cannot be cancelled from outside, so it yields `Ok<A> | Err<E>`.
348
+ */
349
+ export declare type Exit<E, A> = Ok<A> | Err<E> | Cancelled;
350
+
336
351
  export declare interface Fiber<E, A> {
337
352
  /**
338
353
  * Wait for the computation to complete. Rejects with the original exception on a defect. A
339
354
  * defect in a fiber that nobody joins is reported as an unhandled rejection instead, once the
340
355
  * run that forked the fiber has ended (until then, that run may still join it).
341
356
  */
342
- readonly join: () => Promise<Ok<A> | Err<E> | Cancelled>;
357
+ readonly join: () => Promise<Exit<E, A>>;
343
358
  /** Request cancellation. Idempotent. Resolves after finalizers run. */
344
359
  readonly cancel: () => Promise<void>;
345
360
  /** The underlying AbortSignal for interop with platform APIs. */
@@ -389,6 +404,8 @@ export declare function identity<A>(a: A): A;
389
404
  * to evaluate the tree, ensuring stack safety for arbitrarily deep chains.
390
405
  */
391
406
  export declare class IO<E, A> {
407
+ /** Build an `IO` through its static constructors: `IO.of`, `IO.fail`, `IO.lift`, `IO.sync`, `IO.promise`. */
408
+ private constructor();
392
409
  /**
393
410
  * Creates an IO from an effectful function that may be synchronous or asynchronous.
394
411
  * The function is not executed until `unsafeRun()` is called on the resulting IO,
@@ -979,7 +996,9 @@ export declare class IO<E, A> {
979
996
  * ```
980
997
  *
981
998
  * @template F The timeout error type.
982
- * @param {number} ms The timeout duration in milliseconds.
999
+ * @param {number} ms The timeout duration in milliseconds. Must be a non-negative number: a negative or `NaN`
1000
+ * deadline throws `RangeError` where it is written. A deadline above 2,147,483,647 ms (the
1001
+ * `setTimeout` limit), including `Infinity`, is lowered to it instead of firing at once.
983
1002
  * @param {() => F} onTimeout A thunk that produces the timeout error value. If it throws, that
984
1003
  * is a defect.
985
1004
  * @returns {IO<E | F, A>} A new IO that fails with `F` if the timeout elapses.
@@ -1041,7 +1060,8 @@ export declare class IO<E, A> {
1041
1060
  *
1042
1061
  * Supports heterogeneous error types — each IO may have a different error type, and the
1043
1062
  * accumulated error is `NonEmptyList<E1 | E2 | …>`. The last argument is the combiner that
1044
- * receives the success values in argument order (the applicative `yield`).
1063
+ * receives the success values in argument order (the applicative `yield`). Accumulated errors are in
1064
+ * argument order too.
1045
1065
  *
1046
1066
  * @example
1047
1067
  * const io = IO.forA(
@@ -1130,7 +1150,8 @@ export declare class IO<E, A> {
1130
1150
  /**
1131
1151
  * Executes a function over each item in parallel, collecting all results or all errors.
1132
1152
  * Unlike `traverse`, all items are processed concurrently. If any fail, all errors
1133
- * are collected into a `NonEmptyList`.
1153
+ * are collected into a `NonEmptyList`. Results, and errors, keep the order of
1154
+ * `items`, not the order of completion.
1134
1155
  *
1135
1156
  * @template E The error type.
1136
1157
  * @template A The input item type.
@@ -1160,7 +1181,7 @@ export declare class IO<E, A> {
1160
1181
  static sequence<E, A>(ios: readonly IO<E, A>[]): IO<E, List<A>>;
1161
1182
  /**
1162
1183
  * Executes an array of IOs in parallel, collecting all results or all errors.
1163
- * Equivalent to `parTraverse(ios, x => x)`.
1184
+ * Equivalent to `parTraverse(ios, x => x)`. Results and errors keep the order of `ios`.
1164
1185
  *
1165
1186
  * @template E The error type.
1166
1187
  * @template A The success type of each IO.
@@ -1226,7 +1247,7 @@ export declare class List<A> {
1226
1247
  * @example
1227
1248
  * List.empty<number>().isEmpty; // true
1228
1249
  */
1229
- static empty<A>(): List<A>;
1250
+ static empty<A = never>(): List<A>;
1230
1251
  /**
1231
1252
  * Creates a `List` from a variadic argument list.
1232
1253
  *
@@ -1238,7 +1259,7 @@ export declare class List<A> {
1238
1259
  * List.of(1, 2, 3).toArray(); // [1, 2, 3]
1239
1260
  * List.of<number>().toArray(); // []
1240
1261
  */
1241
- static of<A>(...values: A[]): List<A>;
1262
+ static of<A = never>(...values: A[]): List<A>;
1242
1263
  /**
1243
1264
  * Creates a `List` from any iterable — an array, `Set`, `Map` (yields `[key, value]`
1244
1265
  * entries), generator, another `List` or `NonEmptyList`, etc. The iterable is consumed once
@@ -1964,6 +1985,8 @@ export declare class List<A> {
1964
1985
  * List.empty<number>().toString(); // "[]"
1965
1986
  */
1966
1987
  toString(): string;
1988
+ /** The elements of a `List` or `NonEmptyList`, including one built by another copy of the library. */
1989
+ private static _elements;
1967
1990
  /**
1968
1991
  * The JSON form of a `List`: a plain array of its elements, so `JSON.stringify(list)` is
1969
1992
  * `JSON.stringify(list.toArray())`.
@@ -2806,7 +2829,7 @@ export declare abstract class Option<A> {
2806
2829
  * const value = Option.of(5).getOrNull(); // Returns 5
2807
2830
  * const empty = Option.empty<number>().getOrNull(); // Returns null
2808
2831
  */
2809
- getOrNull(): A | null;
2832
+ abstract getOrNull(): A | null;
2810
2833
  /**
2811
2834
  * Returns the contained value if `Some`, otherwise returns the provided default value.
2812
2835
  * @example
@@ -2814,7 +2837,7 @@ export declare abstract class Option<A> {
2814
2837
  * const empty = Option.empty<number>().getOrElse(() => 10); // Returns 10
2815
2838
  *
2816
2839
  */
2817
- getOrElse(defaultValue: () => A): A;
2840
+ abstract getOrElse(defaultValue: () => A): A;
2818
2841
  }
2819
2842
 
2820
2843
  /**
@@ -4041,7 +4064,9 @@ export declare class Schedule {
4041
4064
  */
4042
4065
  jittered(factor?: number): Schedule;
4043
4066
  /**
4044
- * Whether another attempt is allowed after `attempts` attempts have run.
4067
+ * Whether another attempt is allowed after `attempts` attempts have run. Together with
4068
+ * {@link delayAfter} this is the schedule protocol that `IO.retry`, `IO.repeat` and the SSE
4069
+ * reconnect in `@openstage/monadyssey-fetch` consume; both are public so other drivers can use it.
4045
4070
  *
4046
4071
  * @param {number} attempts The number of attempts made so far (`>= 1`).
4047
4072
  * @returns {boolean}
@@ -4050,6 +4075,7 @@ export declare class Schedule {
4050
4075
  /**
4051
4076
  * The delay before the next attempt, after `attempts` attempts have run: `initialDelay ×
4052
4077
  * factor^(attempts − 1)`, capped at `maxDelay`, then jittered.
4078
+ * The second half of the schedule protocol (see {@link allowsAttempt}).
4053
4079
  *
4054
4080
  * @param {number} attempts The number of attempts made so far (`>= 1`).
4055
4081
  * @returns {number} The delay in milliseconds.
@@ -4184,7 +4210,7 @@ export declare class Stream<E, A> {
4184
4210
  * @example
4185
4211
  * Stream.of(1, 2, 3); // emits 1, 2, 3
4186
4212
  */
4187
- static of<A>(...values: A[]): Stream<never, A>;
4213
+ static of<A = never>(...values: A[]): Stream<never, A>;
4188
4214
  /**
4189
4215
  * A stream over any iterable (array, `Set`, `List`, generator, …), in iteration order. Lazy:
4190
4216
  * iteration starts when the stream is run, and each run iterates afresh — so a one-shot