deltafold 0.0.1 → 0.2.0

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,19 +1,48 @@
1
- import { Context, Data, Effect, Predicate, Schema } from "effect";
1
+ import { Data, Effect, Predicate, Scope } from "effect";
2
2
 
3
3
  import type * as Action from "../../foundation/action.ts";
4
- import type { ValueOf } from "../../types.ts";
5
- import { trackPromise } from "./settlement.ts";
4
+ import type * as Callback from "./promise-callback.ts";
5
+ import { adaptPromise } from "./promise-callback.ts";
6
+
7
+ type NoServices = Callback.NoServices;
8
+ type ServiceIds<S extends ServiceMap> = Callback.ServiceIds<S>;
9
+ type GuardedError<G> = Callback.GuardedError<G>;
10
+
11
+ /**
12
+ * Where a handler failure or interruption happened: the read-only prepare phase, or the
13
+ * apply phase that changes state. A manual handler has neither: the executor waits for a
14
+ * person in `confirmation`, then runs the handler's optional check in `verification`.
15
+ *
16
+ * @since @next
17
+ */
18
+ export type Phase = "prepare" | "apply" | "confirmation" | "verification";
19
+
20
+ /**
21
+ * Who performs an action: a handler's apply phase, or a person whose confirmation the
22
+ * executor waits for.
23
+ *
24
+ * @since @next
25
+ */
26
+ export type Performer = "automated" | "manual";
6
27
 
7
28
  /**
8
- * Where a handler failure happened.
29
+ * A person confirmed manual work, and the handler's `verify` check returned `false`.
9
30
  *
10
31
  * @since @next
11
32
  */
12
- export type Phase = "precondition" | "body";
33
+ export class VerificationFailed extends Data.TaggedError("VerificationFailed")<{
34
+ readonly actionId: string;
35
+ readonly kind: string;
36
+ }> {
37
+ override get message() {
38
+ return `Manual work for action "${this.actionId}" was confirmed, but its verification check did not pass`;
39
+ }
40
+ }
13
41
 
14
42
  /**
15
43
  * A Promise handler rejected or threw a value that none of its declared error guards
16
- * recognized.
44
+ * recognized, or its prepare phase returned something other than `Handler.prepared` or
45
+ * `Handler.skip`.
17
46
  *
18
47
  * @since @next
19
48
  */
@@ -24,27 +53,114 @@ export class UnexpectedHandlerError extends Data.TaggedError("UnexpectedHandlerE
24
53
  readonly cause: unknown;
25
54
  }> {
26
55
  override get message() {
27
- return `Handler for action "${this.actionId}" failed unexpectedly in its ${this.phase}`;
56
+ return `Handler for action "${this.actionId}" failed unexpectedly in its ${this.phase} phase`;
28
57
  }
29
58
  }
30
59
 
60
+ const PreparationTypeId = "~deltafold/Preparation";
61
+
62
+ /**
63
+ * A prepare phase decided to apply. The apply phase receives `value` unchanged; the
64
+ * executor never reads, validates, or serializes it.
65
+ *
66
+ * @since @next
67
+ */
68
+ export type Prepared<out P> = {
69
+ readonly [PreparationTypeId]: typeof PreparationTypeId;
70
+ readonly _tag: "Prepared";
71
+ readonly value: P;
72
+ };
73
+
74
+ /**
75
+ * A prepare phase decided that the action does not apply. The occurrence is skipped
76
+ * with `reason`.
77
+ *
78
+ * @since @next
79
+ */
80
+ export type Skip = {
81
+ readonly [PreparationTypeId]: typeof PreparationTypeId;
82
+ readonly _tag: "Skip";
83
+ readonly reason: string;
84
+ };
85
+
86
+ /**
87
+ * What a prepare phase returns: `Handler.prepared(value)` or `Handler.skip(reason)`.
88
+ *
89
+ * @since @next
90
+ */
91
+ export type Preparation<P> = Prepared<P> | Skip;
92
+
93
+ /** The value that a prepare phase passes to its apply phase. */
94
+ type PreparedValue<T> = T extends Prepared<infer P> ? P : never;
95
+
96
+ /**
97
+ * Ends a prepare phase with the value its apply phase receives. Wrapping the value keeps
98
+ * it apart from a skip, whatever its shape.
99
+ *
100
+ * @since @next
101
+ */
102
+ export function prepared(): Prepared<void>;
103
+ export function prepared<P>(value: P): Prepared<P>;
104
+ export function prepared(value?: unknown): Prepared<unknown> {
105
+ return { [PreparationTypeId]: PreparationTypeId, _tag: "Prepared", value };
106
+ }
107
+
108
+ /**
109
+ * Ends a prepare phase by skipping the occurrence. The apply phase does not run.
110
+ *
111
+ * @since @next
112
+ */
113
+ export const skip = (reason: string): Skip => ({
114
+ [PreparationTypeId]: PreparationTypeId,
115
+ _tag: "Skip",
116
+ reason,
117
+ });
118
+
119
+ const isPreparation = (value: unknown): value is Preparation<unknown> =>
120
+ Predicate.hasProperty(value, PreparationTypeId);
121
+
122
+ const notAPreparation = () =>
123
+ new TypeError("A prepare phase must return Handler.prepared(value) or Handler.skip(reason)");
124
+
125
+ /**
126
+ * How an occurrence continues after its prepare phase: skipped, applied by an effect
127
+ * that already holds the prepared value, or confirmed by a person. `verify` checks
128
+ * confirmed work and fails when the check does not pass.
129
+ *
130
+ * @since @next
131
+ */
132
+ export type Step<E, R> =
133
+ | Skip
134
+ | { readonly _tag: "Apply"; readonly apply: Effect.Effect<void, E, R> }
135
+ | { readonly _tag: "Confirm"; readonly verify: Effect.Effect<void, E, R> | undefined };
136
+
137
+ const applyStep = <E, R>(apply: Effect.Effect<void, E, R>): Step<E, R> => ({
138
+ _tag: "Apply",
139
+ apply,
140
+ });
141
+
31
142
  const TypeId = "~deltafold/Handler";
32
143
 
33
144
  /**
34
- * Implements one action instance. `E` and `R` are the errors and Effect services of the
35
- * body and precondition together.
145
+ * Implements one action instance. `E` and `R` are the errors and Effect services of both
146
+ * phases together. A prepared value stays inside the handler, so handlers with
147
+ * different prepared values share this type.
36
148
  *
37
149
  * @since @next
38
150
  */
39
151
  export type Handler<out A extends Action.Any, out E = never, out R = never> = {
40
152
  readonly [TypeId]: typeof TypeId;
41
153
  readonly action: A;
42
- /** Runs the action body. */
43
- readonly body: Effect.Effect<void, E, R>;
44
- /** Decides whether the body applies. `false` skips the occurrence. */
45
- readonly precondition: Effect.Effect<boolean, E, R> | undefined;
46
- /** Explains a skip when the precondition returns `false`. */
47
- readonly skipReason: string;
154
+ /** A `manual` handler has no phases of its own: a person does the work. */
155
+ readonly performer: Performer;
156
+ /** Whether the handler has a prepare phase. */
157
+ readonly prepares: boolean;
158
+ /**
159
+ * Runs the prepare phase, if any, and resolves to the next step. Both phases share
160
+ * `scope`, the occurrence's scope, so resources acquired while preparing stay open
161
+ * until the executor closes it after the occurrence ends.
162
+ */
163
+ readonly prepare: (scope: Scope.Scope) => Effect.Effect<Step<E, R>, E, R>;
48
164
  };
49
165
 
50
166
  /**
@@ -78,23 +194,18 @@ export type ActionId<H> = H extends Handler<infer A, any, any> ? A["id"] : never
78
194
  /** @since @next */
79
195
  export const isHandler = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
80
196
 
81
- type SkipReason<P> = string | ((payload: P) => string);
82
-
83
- const skipReasonOf = <P>(action: Action.Action<string, P>, reason: SkipReason<P> | undefined) => {
84
- if (reason === undefined) return "Precondition returned false";
85
-
86
- return typeof reason === "string" ? reason : reason(action.payload);
87
- };
197
+ const make = <A extends Action.Any, E, R>(
198
+ action: A,
199
+ prepares: boolean,
200
+ prepare: (scope: Scope.Scope) => Effect.Effect<Step<E, R>, E, R>,
201
+ ): Handler<A, E, R> => ({ [TypeId]: TypeId, action, performer: "automated", prepares, prepare });
88
202
 
89
203
  /**
90
204
  * Named Effect services that a Promise handler declares.
91
205
  *
92
206
  * @since @next
93
207
  */
94
- export type ServiceMap = { readonly [name: string | symbol]: Context.Key<any, any> };
95
-
96
- // oxlint-disable-next-line typescript/no-generated-empty-object-type -- A handler without services declares an empty service map.
97
- type NoServices = Record<never, never>;
208
+ export type ServiceMap = Callback.ServiceMap;
98
209
 
99
210
  /**
100
211
  * The second argument of Promise handler callbacks: the `AbortSignal` that
@@ -102,14 +213,32 @@ type NoServices = Record<never, never>;
102
213
  *
103
214
  * @since @next
104
215
  */
105
- export type PromiseContext<S extends ServiceMap = NoServices> = {
106
- readonly signal: AbortSignal;
107
- readonly services: { readonly [K in keyof S]: S[K]["Service"] };
216
+ export type PromiseContext<S extends ServiceMap = NoServices> = Callback.PromiseContext<S>;
217
+
218
+ /**
219
+ * The second argument of a Promise apply phase: the Promise context and the action
220
+ * payload.
221
+ *
222
+ * @since @next
223
+ */
224
+ export type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = PromiseContext<S> & {
225
+ readonly payload: Payload;
108
226
  };
109
227
 
110
- type ServiceIds<S extends ServiceMap> = ValueOf<{
111
- [K in keyof S]: S[K] extends Context.Key<infer I, any> ? I : never;
112
- }>;
228
+ /**
229
+ * A Promise handler with a prepare phase. `prepare` reads state and returns
230
+ * `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value. Each
231
+ * phase gets its own signal.
232
+ *
233
+ * @since @next
234
+ */
235
+ export type PromisePhases<Payload, T extends Preparation<unknown>, S extends ServiceMap> = {
236
+ readonly prepare: (payload: Payload, context: PromiseContext<S>) => PromiseLike<T> | T;
237
+ readonly apply: (
238
+ prepared: PreparedValue<T>,
239
+ context: PromiseApplyContext<Payload, S>,
240
+ ) => PromiseLike<unknown>;
241
+ };
113
242
 
114
243
  /**
115
244
  * Recognizes a declared rejection: a schema, or a type guard such as an `instanceof`
@@ -118,16 +247,10 @@ type ServiceIds<S extends ServiceMap> = ValueOf<{
118
247
  *
119
248
  * @since @next
120
249
  */
121
- export type ErrorGuard = Schema.Top | ((cause: unknown) => cause is any);
122
-
123
- type GuardedError<G> = G extends Schema.Top
124
- ? G["Type"]
125
- : G extends ((cause: unknown) => cause is infer E)
126
- ? E
127
- : never;
250
+ export type ErrorGuard = Callback.ErrorGuard;
128
251
 
129
252
  /** @since @next */
130
- export type PromiseOptions<P, S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
253
+ export type PromiseOptions<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
131
254
  /** Effect services resolved for the callbacks and added to the handler requirements. */
132
255
  readonly services?: S;
133
256
  /**
@@ -136,20 +259,21 @@ export type PromiseOptions<P, S extends ServiceMap, G extends ReadonlyArray<Erro
136
259
  * those errors.
137
260
  */
138
261
  readonly errors?: G;
139
- /** Read-only precondition. Returning `false` skips the occurrence. */
140
- readonly when?: (payload: P, context: PromiseContext<S>) => boolean | PromiseLike<boolean>;
141
- readonly skipReason?: SkipReason<P>;
142
262
  };
143
263
 
144
- const declaredError =
145
- <G extends ReadonlyArray<ErrorGuard>>(guards: G) =>
146
- (cause: unknown): cause is GuardedError<G[number]> =>
147
- guards.some((guard) => (Schema.isSchema(guard) ? Schema.is(guard)(cause) : guard(cause)));
264
+ type PromiseHandler<A extends Action.Any, S extends ServiceMap, G> = Handler<
265
+ A,
266
+ GuardedError<G> | UnexpectedHandlerError,
267
+ ServiceIds<S>
268
+ >;
148
269
 
149
270
  /**
150
271
  * Implements an action with Promise callbacks. The callbacks run lazily through
151
- * `Effect.tryPromise`, and receive its `AbortSignal` and the declared services in
152
- * their second argument.
272
+ * `Effect.tryPromise`, and receive its `AbortSignal` and the declared services.
273
+ *
274
+ * Pass one callback to apply the action directly, or `{ prepare, apply }` to decide
275
+ * first. `prepare` must only read: a dry run calls it and never calls `apply`. A real
276
+ * run calls `apply` once with the prepared value.
153
277
  *
154
278
  * @example
155
279
  * ```ts
@@ -162,96 +286,321 @@ const declaredError =
162
286
  * );
163
287
  * ```
164
288
  *
289
+ * @example
290
+ * ```ts
291
+ * Handler.promise(renameTimeout, {
292
+ * prepare: async ({ file, from }, { signal }) => {
293
+ * const config = await readConfig(file, { signal });
294
+ * return from in config ? Handler.prepared(config) : Handler.skip(`${file} has no ${from}`);
295
+ * },
296
+ * apply: async (config, { payload, signal }) => {
297
+ * await writeConfig(payload.file, rename(config, payload), { signal });
298
+ * },
299
+ * });
300
+ * ```
301
+ *
165
302
  * @since @next
166
303
  */
167
- export const promise = <
304
+ export function promise<
168
305
  A extends Action.Any,
169
306
  const S extends ServiceMap = NoServices,
170
307
  const G extends ReadonlyArray<ErrorGuard> = [],
171
308
  >(
172
309
  action: A,
173
- run: (payload: A["payload"], context: PromiseContext<S>) => PromiseLike<unknown>,
174
- options?: PromiseOptions<A["payload"], S, G>,
175
- ): Handler<A, GuardedError<G[number]> | UnexpectedHandlerError, ServiceIds<S>> => {
176
- const isDeclared = declaredError(options?.errors ?? []);
177
- const services: ServiceMap = options?.services ?? {};
178
- // The handler requires exactly the declared services. Reading them from its context
179
- // keeps that requirement typed; only the record of resolved services needs a cast,
180
- // because Object.fromEntries does not track keys.
181
- const resolve = Effect.map(
182
- Effect.context<ServiceIds<S>>(),
183
- (context) =>
184
- // oxlint-disable-next-line typescript/no-unsafe-type-assertion
185
- Object.fromEntries(
186
- Reflect.ownKeys(services).map((name) => [
187
- name,
188
- Context.get(context, services[name]!),
189
- ]),
190
- ) as { readonly [K in keyof S]: S[K]["Service"] },
191
- );
310
+ apply: (payload: A["payload"], context: PromiseContext<S>) => PromiseLike<unknown>,
311
+ options?: PromiseOptions<S, G>,
312
+ ): PromiseHandler<A, S, G[number]>;
313
+ export function promise<
314
+ A extends Action.Any,
315
+ T extends Preparation<unknown> = Skip,
316
+ const S extends ServiceMap = NoServices,
317
+ const G extends ReadonlyArray<ErrorGuard> = [],
318
+ >(
319
+ action: A,
320
+ phases: PromisePhases<A["payload"], T, S>,
321
+ options?: PromiseOptions<S, G>,
322
+ ): PromiseHandler<A, S, G[number]>;
323
+ export function promise<
324
+ A extends Action.Any,
325
+ S extends ServiceMap,
326
+ G extends ReadonlyArray<ErrorGuard>,
327
+ >(
328
+ action: A,
329
+ run:
330
+ | ((payload: A["payload"], context: PromiseContext<S>) => PromiseLike<unknown>)
331
+ | PromisePhases<A["payload"], Preparation<unknown>, S>,
332
+ options?: PromiseOptions<S, G>,
333
+ ): PromiseHandler<A, S, G[number]> {
334
+ type E = GuardedError<G[number]> | UnexpectedHandlerError;
335
+
336
+ const adaptCallback = adaptPromise(options ?? {});
337
+ const unexpected = (phase: Phase, cause: unknown) =>
338
+ new UnexpectedHandlerError({ actionId: action.id, kind: action.kind, phase, cause });
192
339
 
193
340
  const adapt = <T>(
194
341
  phase: Phase,
195
342
  callback: (context: PromiseContext<S>) => PromiseLike<T> | T,
196
- ): Effect.Effect<T, GuardedError<G[number]> | UnexpectedHandlerError, ServiceIds<S>> =>
197
- Effect.flatMap(resolve, (resolved) =>
198
- trackPromise((capture) =>
199
- Effect.tryPromise({
200
- // Declaring `signal` makes Effect.tryPromise allocate an AbortController.
201
- try: (signal) =>
202
- capture(Promise.resolve(callback({ signal, services: resolved }))),
203
- catch: (cause) =>
204
- isDeclared(cause)
205
- ? cause
206
- : new UnexpectedHandlerError({
207
- actionId: action.id,
208
- kind: action.kind,
209
- phase,
210
- cause,
343
+ ): Effect.Effect<T, E, ServiceIds<S>> =>
344
+ adaptCallback(callback, (cause) => unexpected(phase, cause));
345
+
346
+ if (Predicate.isFunction(run)) {
347
+ const apply = Effect.asVoid(adapt("apply", (context) => run(action.payload, context)));
348
+
349
+ return make(action, false, () => Effect.succeed(applyStep(apply)));
350
+ }
351
+
352
+ const prepare = adapt("prepare", (context) => run.prepare(action.payload, context)).pipe(
353
+ Effect.filterOrFail(isPreparation, () => unexpected("prepare", notAPreparation())),
354
+ Effect.map((preparation): Step<E, ServiceIds<S>> =>
355
+ preparation._tag === "Skip"
356
+ ? preparation
357
+ : applyStep(
358
+ Effect.asVoid(
359
+ adapt("apply", (context) =>
360
+ run.apply(preparation.value, {
361
+ ...context,
362
+ payload: action.payload,
211
363
  }),
212
- }),
213
- ),
214
- );
364
+ ),
365
+ ),
366
+ ),
367
+ ),
368
+ );
215
369
 
216
- const when = options?.when;
370
+ return make(action, true, () => prepare);
371
+ }
217
372
 
218
- return {
219
- [TypeId]: TypeId,
220
- action,
221
- body: Effect.asVoid(adapt("body", (context) => run(action.payload, context))),
222
- precondition:
223
- when === undefined
224
- ? undefined
225
- : adapt("precondition", (context) => when(action.payload, context)),
226
- skipReason: skipReasonOf(action, options?.skipReason),
227
- };
373
+ /**
374
+ * The second argument of an Effect apply phase.
375
+ *
376
+ * @since @next
377
+ */
378
+ export type EffectApplyContext<Payload> = { readonly payload: Payload };
379
+
380
+ /**
381
+ * An Effect handler with a prepare phase. `prepare` reads state and succeeds with
382
+ * `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value.
383
+ *
384
+ * @since @next
385
+ */
386
+ export type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2> = {
387
+ readonly prepare: (payload: Payload) => Effect.Effect<T, E1, R1>;
388
+ readonly apply: (
389
+ prepared: PreparedValue<T>,
390
+ context: EffectApplyContext<Payload>,
391
+ ) => Effect.Effect<unknown, E2, R2>;
228
392
  };
229
393
 
394
+ /**
395
+ * Implements an action with an Effect. The handler keeps its own errors and services,
396
+ * and stops through native Effect interruption.
397
+ *
398
+ * Pass one function to apply the action directly, or `{ prepare, apply }` to decide
399
+ * first. `prepare` must only read: a dry run runs it and never runs `apply`. A real run
400
+ * runs `apply` once with the prepared value. Both phases run in the occurrence's
401
+ * `Scope`, so a resource acquired while preparing, such as a lock, stays open until the
402
+ * occurrence ends; the handler does not require `Scope`.
403
+ *
404
+ * @example
405
+ * ```ts
406
+ * Handler.effect(renameTimeout, {
407
+ * prepare: ({ file, from }) =>
408
+ * Effect.gen(function* () {
409
+ * const files = yield* ConfigFiles;
410
+ * const config = yield* files.lock(file);
411
+ * return from in config.data ? Handler.prepared(config) : Handler.skip(`${file} has no ${from}`);
412
+ * }),
413
+ * apply: (config, { payload }) => config.write(rename(config.data, payload)),
414
+ * });
415
+ * ```
416
+ *
417
+ * @since @next
418
+ */
419
+ export function effect<A extends Action.Any, E = never, R = never>(
420
+ action: A,
421
+ apply: (payload: A["payload"]) => Effect.Effect<unknown, E, R>,
422
+ ): Handler<A, E, Exclude<R, Scope.Scope>>;
423
+ export function effect<
424
+ A extends Action.Any,
425
+ T extends Preparation<unknown> = Skip,
426
+ E1 = never,
427
+ R1 = never,
428
+ E2 = never,
429
+ R2 = never,
430
+ >(
431
+ action: A,
432
+ phases: EffectPhases<A["payload"], T, E1, R1, E2, R2>,
433
+ ): Handler<A, E1 | E2, Exclude<R1 | R2, Scope.Scope>>;
434
+ export function effect<A extends Action.Any, E1, R1, E2, R2>(
435
+ action: A,
436
+ run:
437
+ | ((payload: A["payload"]) => Effect.Effect<unknown, E1, R1>)
438
+ | EffectPhases<A["payload"], Preparation<unknown>, E1, R1, E2, R2>,
439
+ ): Handler<A, E1 | E2, Exclude<R1 | R2, Scope.Scope>> {
440
+ type E = E1 | E2;
441
+ type R = Exclude<R1 | R2, Scope.Scope>;
442
+
443
+ if (Predicate.isFunction(run)) {
444
+ const apply = Effect.asVoid(Effect.suspend(() => run(action.payload)));
445
+
446
+ return make(action, false, (scope) =>
447
+ Effect.succeed(applyStep<E, R>(Scope.provide(apply, scope))),
448
+ );
449
+ }
450
+
451
+ return make(action, true, (scope) =>
452
+ Effect.suspend(() => run.prepare(action.payload)).pipe(
453
+ Scope.provide(scope),
454
+ Effect.filterOrElse(isPreparation, () => Effect.die(notAPreparation())),
455
+ Effect.map((preparation): Step<E, R> =>
456
+ preparation._tag === "Skip"
457
+ ? preparation
458
+ : applyStep(
459
+ Scope.provide(
460
+ Effect.asVoid(
461
+ Effect.suspend(() =>
462
+ run.apply(preparation.value, { payload: action.payload }),
463
+ ),
464
+ ),
465
+ scope,
466
+ ),
467
+ ),
468
+ ),
469
+ ),
470
+ );
471
+ }
472
+
473
+ const verified = <E, R>(action: Action.Any, check: Effect.Effect<boolean, E, R>) =>
474
+ Effect.flatMap(check, (passed) =>
475
+ passed
476
+ ? Effect.void
477
+ : Effect.fail(new VerificationFailed({ actionId: action.id, kind: action.kind })),
478
+ );
479
+
480
+ const makeManual = <A extends Action.Any, E, R>(
481
+ action: A,
482
+ verify: ((scope: Scope.Scope) => Effect.Effect<void, E, R>) | undefined,
483
+ ): Handler<A, E, R> => ({
484
+ [TypeId]: TypeId,
485
+ action,
486
+ performer: "manual",
487
+ prepares: false,
488
+ prepare: (scope) => Effect.succeed({ _tag: "Confirm", verify: verify?.(scope) }),
489
+ });
490
+
230
491
  /** @since @next */
231
- export type EffectOptions<P, E, R> = {
232
- /** Read-only precondition. Succeeding with `false` skips the occurrence. */
233
- readonly when?: (payload: P) => Effect.Effect<boolean, E, R>;
234
- readonly skipReason?: SkipReason<P>;
492
+ export type ManualOptions<Payload, S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
493
+ /** Effect services resolved for `verify` and added to the handler requirements. */
494
+ readonly services?: S;
495
+ /** Guards for rejections of `verify` that keep their own type. */
496
+ readonly errors?: G;
497
+ /**
498
+ * Read-only check that runs after the person confirms. Returning `false` fails the
499
+ * occurrence with `VerificationFailed`. A passing check is evidence that the work is
500
+ * in place, not proof of how it was done.
501
+ */
502
+ readonly verify?: (
503
+ payload: Payload,
504
+ context: PromiseContext<S>,
505
+ ) => boolean | PromiseLike<boolean>;
235
506
  };
236
507
 
237
508
  /**
238
- * Implements an action with an Effect. The body keeps its own errors and services, and
239
- * stops through native Effect interruption.
509
+ * Declares that a person performs the action. A manual handler has no prepare or apply
510
+ * phase. In a real run the executor asks its `interaction` to confirm the work, showing
511
+ * the occurrence's own instruction or description, and never completes the occurrence
512
+ * on its own. A dry run reports that a person would be asked. The optional `verify`
513
+ * check is a Promise callback that runs only after the confirmation.
514
+ *
515
+ * The same action can have a manual handler in one environment and an automated one in
516
+ * another.
517
+ *
518
+ * @example
519
+ * ```ts
520
+ * Handler.manual(rotateApiKey, {
521
+ * services: { keys: KeyStore },
522
+ * verify: (payload, { services: { keys } }) => keys.isFresh(payload.service),
523
+ * });
524
+ * ```
240
525
  *
241
526
  * @since @next
242
527
  */
243
- export const effect = <A extends Action.Any, E = never, R = never, E2 = never, R2 = never>(
528
+ export function manual<A extends Action.Any>(action: A): Handler<A>;
529
+ export function manual<
530
+ A extends Action.Any,
531
+ const S extends ServiceMap = NoServices,
532
+ const G extends ReadonlyArray<ErrorGuard> = [],
533
+ >(
534
+ action: A,
535
+ options: ManualOptions<A["payload"], S, G>,
536
+ ): Handler<A, GuardedError<G[number]> | UnexpectedHandlerError | VerificationFailed, ServiceIds<S>>;
537
+ export function manual<
538
+ A extends Action.Any,
539
+ S extends ServiceMap,
540
+ G extends ReadonlyArray<ErrorGuard>,
541
+ >(
244
542
  action: A,
245
- run: (payload: A["payload"]) => Effect.Effect<unknown, E, R>,
246
- options: EffectOptions<A["payload"], E2, R2> = {},
247
- ): Handler<A, E | E2, R | R2> => {
248
- const when = options.when;
543
+ options?: ManualOptions<A["payload"], S, G>,
544
+ ): Handler<
545
+ A,
546
+ GuardedError<G[number]> | UnexpectedHandlerError | VerificationFailed,
547
+ ServiceIds<S>
548
+ > {
549
+ const adapt = adaptPromise(options ?? {});
550
+ const verify = options?.verify;
551
+ if (verify === undefined) return makeManual(action, undefined);
249
552
 
250
- return {
251
- [TypeId]: TypeId,
553
+ const check = verified(
252
554
  action,
253
- body: Effect.asVoid(Effect.suspend(() => run(action.payload))),
254
- precondition: when === undefined ? undefined : Effect.suspend(() => when(action.payload)),
255
- skipReason: skipReasonOf(action, options.skipReason),
256
- };
555
+ adapt(
556
+ (context) => verify(action.payload, context),
557
+ (cause) =>
558
+ new UnexpectedHandlerError({
559
+ actionId: action.id,
560
+ kind: action.kind,
561
+ phase: "verification",
562
+ cause,
563
+ }),
564
+ ),
565
+ );
566
+
567
+ return makeManual(action, () => check);
568
+ }
569
+
570
+ /** @since @next */
571
+ export type ManualEffectOptions<Payload, E, R> = {
572
+ /**
573
+ * Read-only check that runs after the person confirms. Succeeding with `false` fails
574
+ * the occurrence with `VerificationFailed`. It runs in the occurrence's `Scope`.
575
+ */
576
+ readonly verify?: (payload: Payload) => Effect.Effect<boolean, E, R>;
257
577
  };
578
+
579
+ /**
580
+ * `Handler.manual` with an Effect `verify` check, which keeps its own errors and
581
+ * services.
582
+ *
583
+ * @since @next
584
+ */
585
+ export function manualEffect<A extends Action.Any>(action: A): Handler<A>;
586
+ export function manualEffect<A extends Action.Any, E = never, R = never>(
587
+ action: A,
588
+ options: ManualEffectOptions<A["payload"], E, R>,
589
+ ): Handler<A, E | VerificationFailed, Exclude<R, Scope.Scope>>;
590
+ export function manualEffect<A extends Action.Any, E, R>(
591
+ action: A,
592
+ options?: ManualEffectOptions<A["payload"], E, R>,
593
+ ): Handler<A, E | VerificationFailed, Exclude<R, Scope.Scope>> {
594
+ const verify = options?.verify;
595
+ if (verify === undefined) return makeManual(action, undefined);
596
+
597
+ return makeManual(action, (scope) =>
598
+ Scope.provide(
599
+ verified(
600
+ action,
601
+ Effect.suspend(() => verify(action.payload)),
602
+ ),
603
+ scope,
604
+ ),
605
+ );
606
+ }