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.
- package/README.md +84 -17
- package/dist/index.d.ts +475 -89
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +474 -210
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/features/execution/executor.ts +515 -186
- package/src/features/execution/handler.ts +464 -115
- package/src/features/execution/interaction.ts +174 -0
- package/src/features/execution/promise-callback.ts +76 -0
- package/src/features/execution/settlement.ts +13 -10
- package/src/features/planning/rewrite.ts +1 -1
- package/src/index.ts +2 -0
|
@@ -1,19 +1,48 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { Data, Effect, Predicate, Scope } from "effect";
|
|
2
2
|
|
|
3
3
|
import type * as Action from "../../foundation/action.ts";
|
|
4
|
-
import type
|
|
5
|
-
import {
|
|
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
|
-
*
|
|
29
|
+
* A person confirmed manual work, and the handler's `verify` check returned `false`.
|
|
9
30
|
*
|
|
10
31
|
* @since @next
|
|
11
32
|
*/
|
|
12
|
-
export
|
|
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
|
|
35
|
-
*
|
|
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
|
-
/**
|
|
43
|
-
readonly
|
|
44
|
-
/**
|
|
45
|
-
readonly
|
|
46
|
-
/**
|
|
47
|
-
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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 =
|
|
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
|
-
|
|
107
|
-
|
|
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
|
-
|
|
111
|
-
|
|
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 =
|
|
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<
|
|
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
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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
|
|
152
|
-
*
|
|
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
|
|
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
|
-
|
|
174
|
-
options?: PromiseOptions<
|
|
175
|
-
):
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
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,
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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
|
-
|
|
370
|
+
return make(action, true, () => prepare);
|
|
371
|
+
}
|
|
217
372
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
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
|
|
232
|
-
/**
|
|
233
|
-
readonly
|
|
234
|
-
|
|
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
|
-
*
|
|
239
|
-
*
|
|
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
|
|
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
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
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
|
-
|
|
251
|
-
[TypeId]: TypeId,
|
|
553
|
+
const check = verified(
|
|
252
554
|
action,
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
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
|
+
}
|