Sequence

1
import { type Awaitable, type Err, type Result, err } from "./result";
2

3
/**
4
 * Runtime error returned when execution is cancelled through an `AbortSignal`.
5
 *
6
 * Cancellation is cooperative. Flow helpers check the signal before and after async work and pass
7
 * linked signals to child behaviors where appropriate.
8
 */
9
export type Cancelled = {
10
  kind: "cancelled";
11
  reason?: unknown;
12
};
13

14
/**
15
 * Runtime error returned when user code throws.
16
 *
17
 * Thrown exceptions are kept separate from expected domain errors so recovery helpers do not hide
18
 * programming or platform failures.
19
 */
20
export type Thrown = {
21
  kind: "thrown";
22
  error: unknown;
23
};
24

25
/**
26
 * Runtime-level failure union added around every behavior's domain error type.
27
 *
28
 * Domain errors describe expected application failures. `RuntimeError` describes cancellation or
29
 * unexpected thrown exceptions observed by the Flow runtime.
30
 */
31
export type RuntimeError = Cancelled | Thrown;
32

33
/**
34
 * Execution context passed to every behavior.
35
 *
36
 * The context always includes an `AbortSignal` and may include application-specific fields.
37
 *
38
 * @typeParam C - Custom context object type.
39
 */
40
export type RuntimeContext<C extends object = {}> = C & {
41
  signal: AbortSignal;
42
};
43

44
/**
45
 * Executable Flow workflow unit.
46
 *
47
 * A behavior receives typed input, reads runtime context, and resolves to a `Result` containing
48
 * either typed output, typed domain error, or a runtime error.
49
 *
50
 * @typeParam I - Input type.
51
 * @typeParam O - Output type.
52
 * @typeParam E - Expected domain error type.
53
 * @typeParam C - Custom context type.
54
 */
55
export type Behavior<I, O, E = unknown, C extends object = {}> = (
56
  input: I,
57
  context: RuntimeContext<C>,
58
) => Promise<Result<O, E | RuntimeError>>;
59

60
/**
61
 * Extracts the input type from a behavior.
62
 *
63
 * @typeParam T - Behavior type to inspect.
64
 */
65
export type BehaviorInput<T> =
66
  T extends Behavior<infer I, infer _O, infer _E, infer _C> ? I : never;
67

68
/**
69
 * Extracts the output type from a behavior.
70
 *
71
 * @typeParam T - Behavior type to inspect.
72
 */
73
export type BehaviorOutput<T> =
74
  T extends Behavior<infer _I, infer O, infer _E, infer _C> ? O : never;
75

76
/**
77
 * Extracts the expected domain error type from a behavior.
78
 *
79
 * @typeParam T - Behavior type to inspect.
80
 */
81
export type BehaviorError<T> =
82
  T extends Behavior<infer _I, infer _O, infer E, infer _C> ? E : never;
83

84
/**
85
 * Extracts the custom context type from a behavior.
86
 *
87
 * @typeParam T - Behavior type to inspect.
88
 */
89
export type BehaviorContext<T> =
90
  T extends Behavior<infer _I, infer _O, infer _E, infer C> ? C : never;
91

92
/**
93
 * Executes a behavior with runtime error protection.
94
 *
95
 * The runner checks cancellation before and after behavior execution and converts thrown
96
 * exceptions into `Thrown` results.
97
 *
98
 * @typeParam I - Input type.
99
 * @typeParam O - Output type.
100
 * @typeParam E - Expected domain error type.
101
 * @typeParam C - Custom context type.
102
 * @param behavior - Behavior to execute.
103
 * @param input - Input passed to the behavior.
104
 * @param context - Runtime context containing an `AbortSignal`.
105
 * @returns The behavior result, cancellation result, or thrown runtime result.
106
 */
107
export async function runBehavior<I, O, E, C extends object>(
108
  behavior: Behavior<I, O, E, C>,
109
  input: I,
110
  context: RuntimeContext<C>,
111
): Promise<Result<O, E | RuntimeError>> {
112
  if (context.signal.aborted) {
113
    return resultFromSignal(context.signal);
114
  }
115

116
  try {
117
    const result = await behavior(input, context);
118

119
    if (context.signal.aborted) {
120
      return resultFromSignal(context.signal);
121
    }
122

123
    return result;
124
  } catch (error) {
125
    if (context.signal.aborted) {
126
      return resultFromSignal(context.signal);
127
    }
128

129
    return thrown(error);
130
  }
131
}
132

133
/**
134
 * Defines a behavior from a callback that returns a `Result`.
135
 *
136
 * Use `define` for low-level helpers that already operate in the result channel. Most application
137
 * code should use `task`, which also accepts plain successful values.
138
 *
139
 * @typeParam I - Input type.
140
 * @typeParam O - Output type.
141
 * @typeParam E - Expected domain error type.
142
 * @typeParam C - Custom context type.
143
 * @param run - Callback invoked for each behavior execution.
144
 * @returns A behavior protected by cancellation and thrown-exception handling.
145
 */
146
export function define<I, O, E = unknown, C extends object = {}>(
147
  run: (input: I, context: RuntimeContext<C>) => Awaitable<Result<O, E>>,
148
): Behavior<I, O, E, C> {
149
  return async (input, context) => {
150
    if (context.signal.aborted) {
151
      return resultFromSignal(context.signal);
152
    }
153

154
    try {
155
      const result = await run(input, context);
156

157
      if (context.signal.aborted) {
158
        return resultFromSignal(context.signal);
159
      }
160

161
      return result;
162
    } catch (error) {
163
      if (context.signal.aborted) {
164
        return cancelled(context.signal.reason);
165
      }
166

167
      return thrown(error);
168
    }
169
  };
170
}
171

172
/**
173
 * Runs a behavior with an optional application context.
174
 *
175
 * If no signal is provided, Flow creates a fresh non-aborted signal. Expected failures remain in
176
 * the returned `Result`; thrown exceptions are converted to `Thrown`.
177
 *
178
 * @typeParam I - Input type.
179
 * @typeParam O - Output type.
180
 * @typeParam E - Expected domain error type.
181
 * @typeParam C - Custom context type.
182
 * @param behavior - Behavior to execute.
183
 * @param input - Input passed to the behavior.
184
 * @param context - Optional custom context and optional `AbortSignal`.
185
 * @returns A result containing behavior output, domain error, or runtime error.
186
 *
187
 * @example
188
 * ```ts
189
 * const result = await run(loadUser, "user_1");
190
 * ```
191
 */
192
export async function run<I, O, E, C extends object = {}>(
193
  behavior: Behavior<I, O, E, C>,
194
  input: I,
195
  context: C & { signal?: AbortSignal } = {} as C & { signal?: AbortSignal },
196
): Promise<Result<O, E | RuntimeError>> {
197
  const { signal = new AbortController().signal, ...rest } = context;
198

199
  return runBehavior(behavior, input, {
200
    ...(rest as C),
201
    signal,
202
  });
203
}
204

205
/**
206
 * Creates a cancellation result.
207
 *
208
 * @param reason - Optional cancellation reason from an `AbortSignal`.
209
 * @returns A failed result containing `Cancelled`.
210
 */
211
export function cancelled(reason?: unknown): Err<Cancelled> {
212
  if (reason === undefined) {
213
    return err({ kind: "cancelled" });
214
  }
215

216
  return err({ kind: "cancelled", reason });
217
}
218

219
/**
220
 * Narrows an error value to `Cancelled`.
221
 *
222
 * @param error - Error value to inspect.
223
 * @returns `true` when the value is a cancellation runtime error.
224
 */
225
export function isCancelled(error: unknown): error is Cancelled {
226
  return (
227
    typeof error === "object" && error !== null && "kind" in error && error.kind === "cancelled"
228
  );
229
}
230

231
/**
232
 * Creates a thrown-exception runtime result.
233
 *
234
 * @param error - Exception or thrown value.
235
 * @returns A failed result containing `Thrown`.
236
 */
237
export function thrown(error: unknown): Err<Thrown> {
238
  return err({ kind: "thrown", error });
239
}
240

241
/**
242
 * Narrows an error value to `Thrown`.
243
 *
244
 * @param error - Error value to inspect.
245
 * @returns `true` when the value is a thrown runtime error.
246
 */
247
export function isThrown(error: unknown): error is Thrown {
248
  return typeof error === "object" && error !== null && "kind" in error && error.kind === "thrown";
249
}
250

251
/**
252
 * Narrows an error value to a Flow runtime error.
253
 *
254
 * Recovery helpers use this guard so they only handle expected domain errors.
255
 *
256
 * @param error - Error value to inspect.
257
 * @returns `true` for `Cancelled` or `Thrown`.
258
 */
259
export function isRuntimeError(error: unknown): error is RuntimeError {
260
  return isCancelled(error) || isThrown(error);
261
}
262

263
/**
264
 * Converts an aborted signal into a cancellation result.
265
 *
266
 * @param signal - Aborted signal whose reason should be preserved.
267
 * @returns A failed result containing `Cancelled`.
268
 */
269
export function resultFromSignal(signal: AbortSignal): Err<Cancelled> {
270
  return cancelled(signal.reason);
271
}
272

273
/**
274
 * Replaces the signal on a runtime context.
275
 *
276
 * This advanced helper is used by timeout and parallel helpers when they create child abort
277
 * controllers.
278
 *
279
 * @typeParam C - Custom context type.
280
 * @param context - Existing runtime context.
281
 * @param signal - Replacement signal.
282
 * @returns A context with the same custom fields and the replacement signal.
283
 */
284
export function contextWithSignal<C extends object>(
285
  context: RuntimeContext<C>,
286
  signal: AbortSignal,
287
): RuntimeContext<C> {
288
  return { ...context, signal };
289
}
290

291
/**
292
 * Aborts a controller only when it has not already been aborted.
293
 *
294
 * @param controller - Controller to abort.
295
 * @param reason - Optional abort reason.
296
 */
297
export function abortController(controller: AbortController, reason?: unknown): void {
298
  if (!controller.signal.aborted) {
299
    controller.abort(reason);
300
  }
301
}
302

303
/**
304
 * Links a parent signal to a child controller.
305
 *
306
 * The returned cleanup function removes the listener when the child work has settled.
307
 *
308
 * @param parent - Parent signal to observe.
309
 * @param controller - Child controller to abort when the parent aborts.
310
 * @returns Cleanup function that unlinks the abort listener.
311
 */
312
export function linkAbortSignal(parent: AbortSignal, controller: AbortController): () => void {
313
  if (parent.aborted) {
314
    abortController(controller, parent.reason);
315
    return () => {};
316
  }
317

318
  const onAbort = () => abortController(controller, parent.reason);
319
  parent.addEventListener("abort", onAbort, { once: true });
320

321
  return () => parent.removeEventListener("abort", onAbort);
322
}
323

324
/**
325
 * Creates a child controller linked to a parent signal.
326
 *
327
 * This advanced helper powers timeout, race, and parallel execution helpers.
328
 *
329
 * @param parent - Parent signal to link from.
330
 * @returns The child controller and an unlink cleanup function.
331
 */
332
export function createLinkedController(parent: AbortSignal): {
333
  controller: AbortController;
334
  unlink: () => void;
335
} {
336
  const controller = new AbortController();
337
  const unlink = linkAbortSignal(parent, controller);
338

339
  return { controller, unlink };
340
}