Task

1
/**
2
 * Represents a value that may be returned directly or through a Promise.
3
 *
4
 * Flow helpers accept `Awaitable` callbacks so synchronous and asynchronous logic can share the
5
 * same behavior authoring APIs.
6
 *
7
 * @typeParam T - Value produced either immediately or asynchronously.
8
 */
9
export type Awaitable<T> = T | Promise<T>;
10

11
/**
12
 * Successful `Result` variant.
13
 *
14
 * `Ok` carries the typed success value through Flow pipelines. Use `ok` to create branded values
15
 * that can be detected by `isResult`.
16
 *
17
 * @typeParam T - Success value type.
18
 */
19
export type Ok<T> = {
20
  ok: true;
21
  value: T;
22
};
23

24
/**
25
 * Failed `Result` variant.
26
 *
27
 * `Err` carries expected domain errors. Runtime failures such as cancellation and thrown
28
 * exceptions are modeled separately by the runtime helpers.
29
 *
30
 * @typeParam E - Expected error value type.
31
 */
32
export type Err<E> = {
33
  ok: false;
34
  error: E;
35
};
36

37
/**
38
 * Explicit success-or-failure outcome used throughout Flow.
39
 *
40
 * Flow behaviors return `Result` values instead of throwing for expected application failures.
41
 *
42
 * @typeParam T - Success value type.
43
 * @typeParam E - Expected error value type.
44
 */
45
export type Result<T, E> = Ok<T> | Err<E>;
46

47
/**
48
 * Structural result shape accepted by `from`.
49
 *
50
 * Use this when adapting unbranded result-like values into branded Flow results.
51
 *
52
 * @typeParam T - Success value type.
53
 * @typeParam E - Expected error value type.
54
 */
55
export type ResultLike<T, E> = Ok<T> | Err<E>;
56

57
const resultBrand = Symbol("archyn.result");
58

59
/**
60
 * Creates a branded successful result.
61
 *
62
 * Branded results are recognized by `isResult`, which allows `task` callbacks to distinguish
63
 * explicit `Result` returns from plain successful values.
64
 *
65
 * @typeParam T - Success value type.
66
 * @param value - Value to carry in the success variant.
67
 * @returns A branded `Ok` result.
68
 *
69
 * @example
70
 * ```ts
71
 * const result = ok({ id: "user_1" });
72
 * ```
73
 */
74
export function ok<T>(value: T): Ok<T> {
75
  return brandResult({ ok: true, value });
76
}
77

78
/**
79
 * Creates a branded failed result.
80
 *
81
 * Use `err` for expected domain failures that should stay typed and recoverable by Flow helpers.
82
 *
83
 * @typeParam E - Expected error value type.
84
 * @param error - Error value to carry in the failure variant.
85
 * @returns A branded `Err` result.
86
 *
87
 * @example
88
 * ```ts
89
 * const result = err({ kind: "not-found" });
90
 * ```
91
 */
92
export function err<E>(error: E): Err<E> {
93
  return brandResult({ ok: false, error });
94
}
95

96
/**
97
 * Converts a structural result-like value into a branded Flow result.
98
 *
99
 * This is useful when adapting results from another library or from plain object literals.
100
 *
101
 * @typeParam T - Success value type.
102
 * @typeParam E - Expected error value type.
103
 * @param result - Structural success or failure object.
104
 * @returns A branded Flow `Result`.
105
 */
106
export function from<T, E>(result: ResultLike<T, E>): Result<T, E> {
107
  return result.ok ? ok(result.value) : err(result.error);
108
}
109

110
/**
111
 * Narrows a result to the successful variant.
112
 *
113
 * @typeParam T - Success value type.
114
 * @typeParam E - Expected error value type.
115
 * @param result - Result to inspect.
116
 * @returns `true` when the result is `Ok`.
117
 */
118
export function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
119
  return result.ok;
120
}
121

122
/**
123
 * Narrows a result to the failed variant.
124
 *
125
 * @typeParam T - Success value type.
126
 * @typeParam E - Expected error value type.
127
 * @param result - Result to inspect.
128
 * @returns `true` when the result is `Err`.
129
 */
130
export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
131
  return !result.ok;
132
}
133

134
/**
135
 * Exhaustively handles both result variants and returns one value.
136
 *
137
 * `match` keeps success and error handling explicit without manual branching at the call site.
138
 *
139
 * @typeParam T - Success value type.
140
 * @typeParam E - Expected error value type.
141
 * @typeParam R - Handler return type.
142
 * @param result - Result to handle.
143
 * @param handlers - Callbacks for the success and failure variants.
144
 * @returns The value returned by the matching handler.
145
 *
146
 * @example
147
 * ```ts
148
 * const label = match(result, {
149
 *   ok: (user) => user.name,
150
 *   err: (error) => error.kind,
151
 * });
152
 * ```
153
 */
154
export function match<T, E, R>(
155
  result: Result<T, E>,
156
  handlers: {
157
    ok: (value: T) => R;
158
    err: (error: E) => R;
159
  },
160
): R {
161
  return result.ok ? handlers.ok(result.value) : handlers.err(result.error);
162
}
163

164
/**
165
 * Returns the success value or throws the error value.
166
 *
167
 * Prefer typed recovery helpers for expected failures. `unwrap` is best reserved for tests,
168
 * boundaries that intentionally throw, or places where a failure is impossible by construction.
169
 *
170
 * @typeParam T - Success value type.
171
 * @typeParam E - Expected error value type.
172
 * @param result - Result to unwrap.
173
 * @returns The success value.
174
 * @throws The `Err.error` value when the result failed.
175
 */
176
export function unwrap<T, E>(result: Result<T, E>): T {
177
  if (result.ok) {
178
    return result.value;
179
  }
180

181
  throw result.error;
182
}
183

184
/**
185
 * Returns the success value or a fallback.
186
 *
187
 * Use this when a failure can be safely collapsed into a default value.
188
 *
189
 * @typeParam T - Success value type.
190
 * @typeParam E - Expected error value type.
191
 * @param result - Result to read.
192
 * @param fallback - Value returned when the result failed.
193
 * @returns The success value or fallback.
194
 *
195
 * @example
196
 * ```ts
197
 * const count = unwrapOr(result, 0);
198
 * ```
199
 */
200
export function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T {
201
  return result.ok ? result.value : fallback;
202
}
203

204
/**
205
 * Namespace-style collection of core result helpers.
206
 *
207
 * This object is convenient when passing the result toolkit as a single value. The individual
208
 * named functions remain the preferred imports for tree-shakeable application code.
209
 */
210
export const Result = {
211
  ok,
212
  err,
213
  from,
214
  isOk,
215
  isErr,
216
  match,
217
  unwrap,
218
  unwrapOr,
219
};
220

221
/**
222
 * Detects branded Flow results created by `ok`, `err`, or `from`.
223
 *
224
 * `task` uses this guard to preserve explicit results while wrapping plain callback returns in
225
 * `ok`.
226
 *
227
 * @typeParam T - Success value type.
228
 * @typeParam E - Expected error value type.
229
 * @param value - Plain value or potential result.
230
 * @returns `true` when the value is a branded Flow `Result`.
231
 */
232
export function isResult<T, E>(value: T | Result<T, E>): value is Result<T, E> {
233
  return typeof value === "object" && value !== null && resultBrand in value;
234
}
235

236
function brandResult<R extends Ok<unknown> | Err<unknown>>(result: R): R {
237
  Object.defineProperty(result, resultBrand, {
238
    value: true,
239
  });
240

241
  return result;
242
}

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
}