Wait

Install

pnpm dlx shadcn@latest add https://archyn.net/r/wait.json

Copy the files below into the target paths shown in each tab.

ts@lib/flow/wait.ts

1
import { type Result, ok } from "./core/result";
2
import { type Cancelled, resultFromSignal } from "./core/runtime";
3

4
/**
5
 * Waits for a duration while observing an `AbortSignal`.
6
 *
7
 * Non-positive durations resolve immediately with success. If the signal aborts before the timer
8
 * completes, the promise resolves with a cancellation result instead of throwing.
9
 *
10
 * @param ms - Duration in milliseconds.
11
 * @param signal - Signal used to cancel the wait.
12
 * @returns A promise resolving to success or cancellation.
13
 *
14
 * @example
15
 * ```ts
16
 * const waited = await wait(250, signal);
17
 * ```
18
 */
19
export function wait(ms: number, signal: AbortSignal): Promise<Result<void, Cancelled>> {
20
  if (signal.aborted) {
21
    return Promise.resolve(resultFromSignal(signal));
22
  }
23

24
  if (ms <= 0) {
25
    return Promise.resolve(ok(undefined));
26
  }
27

28
  return new Promise((resolve) => {
29
    const timeout = setTimeout(() => {
30
      signal.removeEventListener("abort", onAbort);
31
      resolve(ok(undefined));
32
    }, ms);
33

34
    const onAbort = () => {
35
      clearTimeout(timeout);
36
      signal.removeEventListener("abort", onAbort);
37
      resolve(resultFromSignal(signal));
38
    };
39

40
    signal.addEventListener("abort", onAbort, { once: true });
41
  });
42
}

ts@lib/flow/core/result.ts

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
}

ts@lib/flow/core/runtime.ts

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
}

Update the import paths to match your project setup.

Wait for a duration while respecting AbortSignal cancellation.

Usage

wait is the low-level timing primitive used by retry, timeout-adjacent flows, and any workflow that needs a cancellable delay. It returns a typed Result rather than throwing on abort.

Use it when:

Pause between attempts in retry logic.
Add cancellation-aware sleeps inside custom Behavior values.
Avoid untracked setTimeout calls that keep running after a parent flow aborts.

1
import { wait } from "@/lib/flow/wait";
2

3
const controller = new AbortController();
4
const result = await wait(250, controller.signal);
5

6
if (!result.ok && result.error.kind === "cancelled") {
7
  console.log("wait was cancelled");
8
}

Behavior

If the signal is already aborted, wait resolves immediately with Cancelled. Otherwise it starts a timer and removes its abort listener when the timer settles or cancellation occurs.

wait has no domain failure type. Its only failure is Cancelled, which preserves the signal reason when one is provided.

Types

The result is Promise<Result<void, Cancelled>>, so cancellation stays explicit and typed.

Import from @/lib/flow/wait.

Composition Notes

Use wait inside custom helpers or tasks that need AbortSignal-aware sleeping.

Do not use wait for domain retry policy by itself; use retry when the delay is tied to a failed attempt.

wait

Source