deltafold 0.1.0 → 0.2.1
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 +96 -1
- package/dist/changelog.d.ts +10 -10
- package/dist/changelog.js +4 -4
- package/dist/changelog.js.map +1 -1
- package/dist/{document-BZcZo9nr.js → document-HfPyYxEd.js} +20 -20
- package/dist/{document-BZcZo9nr.js.map → document-HfPyYxEd.js.map} +1 -1
- package/dist/{document-DWHsgywm.d.ts → document-gtXeGFJR.d.ts} +41 -41
- package/dist/{document-DWHsgywm.d.ts.map → document-gtXeGFJR.d.ts.map} +1 -1
- package/dist/html.d.ts +2 -2
- package/dist/html.js +2 -2
- package/dist/html.js.map +1 -1
- package/dist/index.d.ts +681 -102
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +908 -235
- package/dist/index.js.map +1 -1
- package/dist/markdown.d.ts +2 -2
- package/dist/markdown.js +2 -2
- package/dist/markdown.js.map +1 -1
- package/dist/{mdast-DiRsYwPU.js → mdast-Oqkh0Gs1.js} +2 -2
- package/dist/{mdast-DiRsYwPU.js.map → mdast-Oqkh0Gs1.js.map} +1 -1
- package/dist/{package-BfBYnaCz.d.ts → package-CA5R57IC.d.ts} +117 -112
- package/dist/{package-BfBYnaCz.d.ts.map → package-CA5R57IC.d.ts.map} +1 -1
- package/package.json +3 -3
- package/src/features/documents/changelog.ts +8 -8
- package/src/features/documents/document.ts +39 -39
- package/src/features/documents/index.ts +2 -2
- package/src/features/execution/executor.ts +631 -272
- package/src/features/execution/handler.ts +205 -84
- package/src/features/execution/interaction.ts +174 -0
- package/src/features/execution/observation.ts +489 -0
- package/src/features/execution/observer.ts +395 -0
- package/src/features/execution/promise-callback.ts +76 -0
- package/src/features/package.ts +3 -3
- package/src/features/planning/history.ts +10 -10
- package/src/features/planning/identifiers.ts +7 -4
- package/src/features/planning/resolve-error.ts +13 -13
- package/src/features/planning/resolve.ts +11 -4
- package/src/features/planning/rewrite.ts +1 -1
- package/src/features/planning/validate.ts +1 -1
- package/src/foundation/action.ts +17 -17
- package/src/foundation/change.ts +10 -10
- package/src/foundation/instruction.ts +5 -5
- package/src/foundation/migration.ts +12 -12
- package/src/foundation/plan.ts +23 -18
- package/src/foundation/rule.ts +6 -6
- package/src/foundation/shortcut.ts +6 -6
- package/src/foundation/version.ts +6 -6
- package/src/index.ts +15 -11
- package/src/renderers/html.ts +1 -1
- package/src/renderers/markdown.ts +1 -1
|
@@ -1,23 +1,50 @@
|
|
|
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 0.0.1
|
|
17
|
+
*/
|
|
18
|
+
export type Phase = "prepare" | "apply" | "confirmation" | "verification";
|
|
6
19
|
|
|
7
20
|
/**
|
|
8
|
-
*
|
|
9
|
-
*
|
|
21
|
+
* Who performs an action: a handler's apply phase, or a person whose confirmation the
|
|
22
|
+
* executor waits for.
|
|
10
23
|
*
|
|
11
|
-
* @since
|
|
24
|
+
* @since 0.2.0
|
|
12
25
|
*/
|
|
13
|
-
export type
|
|
26
|
+
export type Performer = "automated" | "manual";
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* A person confirmed manual work, and the handler's `verify` check returned `false`.
|
|
30
|
+
*
|
|
31
|
+
* @since 0.2.0
|
|
32
|
+
*/
|
|
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
|
+
}
|
|
14
41
|
|
|
15
42
|
/**
|
|
16
43
|
* A Promise handler rejected or threw a value that none of its declared error guards
|
|
17
44
|
* recognized, or its prepare phase returned something other than `Handler.prepared` or
|
|
18
45
|
* `Handler.skip`.
|
|
19
46
|
*
|
|
20
|
-
* @since
|
|
47
|
+
* @since 0.0.1
|
|
21
48
|
*/
|
|
22
49
|
export class UnexpectedHandlerError extends Data.TaggedError("UnexpectedHandlerError")<{
|
|
23
50
|
readonly actionId: string;
|
|
@@ -36,7 +63,7 @@ const PreparationTypeId = "~deltafold/Preparation";
|
|
|
36
63
|
* A prepare phase decided to apply. The apply phase receives `value` unchanged; the
|
|
37
64
|
* executor never reads, validates, or serializes it.
|
|
38
65
|
*
|
|
39
|
-
* @since
|
|
66
|
+
* @since 0.1.0
|
|
40
67
|
*/
|
|
41
68
|
export type Prepared<out P> = {
|
|
42
69
|
readonly [PreparationTypeId]: typeof PreparationTypeId;
|
|
@@ -48,7 +75,7 @@ export type Prepared<out P> = {
|
|
|
48
75
|
* A prepare phase decided that the action does not apply. The occurrence is skipped
|
|
49
76
|
* with `reason`.
|
|
50
77
|
*
|
|
51
|
-
* @since
|
|
78
|
+
* @since 0.1.0
|
|
52
79
|
*/
|
|
53
80
|
export type Skip = {
|
|
54
81
|
readonly [PreparationTypeId]: typeof PreparationTypeId;
|
|
@@ -59,7 +86,7 @@ export type Skip = {
|
|
|
59
86
|
/**
|
|
60
87
|
* What a prepare phase returns: `Handler.prepared(value)` or `Handler.skip(reason)`.
|
|
61
88
|
*
|
|
62
|
-
* @since
|
|
89
|
+
* @since 0.1.0
|
|
63
90
|
*/
|
|
64
91
|
export type Preparation<P> = Prepared<P> | Skip;
|
|
65
92
|
|
|
@@ -70,7 +97,7 @@ type PreparedValue<T> = T extends Prepared<infer P> ? P : never;
|
|
|
70
97
|
* Ends a prepare phase with the value its apply phase receives. Wrapping the value keeps
|
|
71
98
|
* it apart from a skip, whatever its shape.
|
|
72
99
|
*
|
|
73
|
-
* @since
|
|
100
|
+
* @since 0.1.0
|
|
74
101
|
*/
|
|
75
102
|
export function prepared(): Prepared<void>;
|
|
76
103
|
export function prepared<P>(value: P): Prepared<P>;
|
|
@@ -81,7 +108,7 @@ export function prepared(value?: unknown): Prepared<unknown> {
|
|
|
81
108
|
/**
|
|
82
109
|
* Ends a prepare phase by skipping the occurrence. The apply phase does not run.
|
|
83
110
|
*
|
|
84
|
-
* @since
|
|
111
|
+
* @since 0.1.0
|
|
85
112
|
*/
|
|
86
113
|
export const skip = (reason: string): Skip => ({
|
|
87
114
|
[PreparationTypeId]: PreparationTypeId,
|
|
@@ -96,14 +123,16 @@ const notAPreparation = () =>
|
|
|
96
123
|
new TypeError("A prepare phase must return Handler.prepared(value) or Handler.skip(reason)");
|
|
97
124
|
|
|
98
125
|
/**
|
|
99
|
-
* How an occurrence continues after its prepare phase: skipped,
|
|
100
|
-
* that already holds the prepared value.
|
|
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.
|
|
101
129
|
*
|
|
102
|
-
* @since
|
|
130
|
+
* @since 0.1.0
|
|
103
131
|
*/
|
|
104
132
|
export type Step<E, R> =
|
|
105
133
|
| Skip
|
|
106
|
-
| { readonly _tag: "Apply"; readonly apply: Effect.Effect<void, E, R> }
|
|
134
|
+
| { readonly _tag: "Apply"; readonly apply: Effect.Effect<void, E, R> }
|
|
135
|
+
| { readonly _tag: "Confirm"; readonly verify: Effect.Effect<void, E, R> | undefined };
|
|
107
136
|
|
|
108
137
|
const applyStep = <E, R>(apply: Effect.Effect<void, E, R>): Step<E, R> => ({
|
|
109
138
|
_tag: "Apply",
|
|
@@ -117,11 +146,13 @@ const TypeId = "~deltafold/Handler";
|
|
|
117
146
|
* phases together. A prepared value stays inside the handler, so handlers with
|
|
118
147
|
* different prepared values share this type.
|
|
119
148
|
*
|
|
120
|
-
* @since
|
|
149
|
+
* @since 0.0.1
|
|
121
150
|
*/
|
|
122
151
|
export type Handler<out A extends Action.Any, out E = never, out R = never> = {
|
|
123
152
|
readonly [TypeId]: typeof TypeId;
|
|
124
153
|
readonly action: A;
|
|
154
|
+
/** A `manual` handler has no phases of its own: a person does the work. */
|
|
155
|
+
readonly performer: Performer;
|
|
125
156
|
/** Whether the handler has a prepare phase. */
|
|
126
157
|
readonly prepares: boolean;
|
|
127
158
|
/**
|
|
@@ -135,66 +166,60 @@ export type Handler<out A extends Action.Any, out E = never, out R = never> = {
|
|
|
135
166
|
/**
|
|
136
167
|
* Any handler.
|
|
137
168
|
*
|
|
138
|
-
* @since
|
|
169
|
+
* @since 0.0.1
|
|
139
170
|
*/
|
|
140
171
|
export type Any = Handler<Action.Any, any, any>;
|
|
141
172
|
|
|
142
173
|
/**
|
|
143
174
|
* The errors of a handler or a union of handlers.
|
|
144
175
|
*
|
|
145
|
-
* @since
|
|
176
|
+
* @since 0.0.1
|
|
146
177
|
*/
|
|
147
178
|
export type Error<H> = H extends Handler<any, infer E, any> ? E : never;
|
|
148
179
|
|
|
149
180
|
/**
|
|
150
181
|
* The Effect services of a handler or a union of handlers.
|
|
151
182
|
*
|
|
152
|
-
* @since
|
|
183
|
+
* @since 0.0.1
|
|
153
184
|
*/
|
|
154
185
|
export type Services<H> = H extends Handler<any, any, infer R> ? R : never;
|
|
155
186
|
|
|
156
187
|
/**
|
|
157
188
|
* The action identifiers implemented by a handler or a union of handlers.
|
|
158
189
|
*
|
|
159
|
-
* @since
|
|
190
|
+
* @since 0.0.1
|
|
160
191
|
*/
|
|
161
192
|
export type ActionId<H> = H extends Handler<infer A, any, any> ? A["id"] : never;
|
|
162
193
|
|
|
163
|
-
/** @since
|
|
194
|
+
/** @since 0.0.1 */
|
|
164
195
|
export const isHandler = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
|
|
165
196
|
|
|
166
197
|
const make = <A extends Action.Any, E, R>(
|
|
167
198
|
action: A,
|
|
168
199
|
prepares: boolean,
|
|
169
200
|
prepare: (scope: Scope.Scope) => Effect.Effect<Step<E, R>, E, R>,
|
|
170
|
-
): Handler<A, E, R> => ({ [TypeId]: TypeId, action, prepares, prepare });
|
|
201
|
+
): Handler<A, E, R> => ({ [TypeId]: TypeId, action, performer: "automated", prepares, prepare });
|
|
171
202
|
|
|
172
203
|
/**
|
|
173
204
|
* Named Effect services that a Promise handler declares.
|
|
174
205
|
*
|
|
175
|
-
* @since
|
|
206
|
+
* @since 0.0.1
|
|
176
207
|
*/
|
|
177
|
-
export type ServiceMap =
|
|
178
|
-
|
|
179
|
-
// oxlint-disable-next-line typescript/no-generated-empty-object-type -- A handler without services declares an empty service map.
|
|
180
|
-
type NoServices = Record<never, never>;
|
|
208
|
+
export type ServiceMap = Callback.ServiceMap;
|
|
181
209
|
|
|
182
210
|
/**
|
|
183
211
|
* The second argument of Promise handler callbacks: the `AbortSignal` that
|
|
184
212
|
* `Effect.tryPromise` aborts on interruption, and the declared services, resolved.
|
|
185
213
|
*
|
|
186
|
-
* @since
|
|
214
|
+
* @since 0.0.1
|
|
187
215
|
*/
|
|
188
|
-
export type PromiseContext<S extends ServiceMap = NoServices> =
|
|
189
|
-
readonly signal: AbortSignal;
|
|
190
|
-
readonly services: { readonly [K in keyof S]: S[K]["Service"] };
|
|
191
|
-
};
|
|
216
|
+
export type PromiseContext<S extends ServiceMap = NoServices> = Callback.PromiseContext<S>;
|
|
192
217
|
|
|
193
218
|
/**
|
|
194
219
|
* The second argument of a Promise apply phase: the Promise context and the action
|
|
195
220
|
* payload.
|
|
196
221
|
*
|
|
197
|
-
* @since
|
|
222
|
+
* @since 0.1.0
|
|
198
223
|
*/
|
|
199
224
|
export type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = PromiseContext<S> & {
|
|
200
225
|
readonly payload: Payload;
|
|
@@ -205,7 +230,7 @@ export type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = Pr
|
|
|
205
230
|
* `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value. Each
|
|
206
231
|
* phase gets its own signal.
|
|
207
232
|
*
|
|
208
|
-
* @since
|
|
233
|
+
* @since 0.1.0
|
|
209
234
|
*/
|
|
210
235
|
export type PromisePhases<Payload, T extends Preparation<unknown>, S extends ServiceMap> = {
|
|
211
236
|
readonly prepare: (payload: Payload, context: PromiseContext<S>) => PromiseLike<T> | T;
|
|
@@ -215,26 +240,16 @@ export type PromisePhases<Payload, T extends Preparation<unknown>, S extends Ser
|
|
|
215
240
|
) => PromiseLike<unknown>;
|
|
216
241
|
};
|
|
217
242
|
|
|
218
|
-
type ServiceIds<S extends ServiceMap> = ValueOf<{
|
|
219
|
-
[K in keyof S]: S[K] extends Context.Key<infer I, any> ? I : never;
|
|
220
|
-
}>;
|
|
221
|
-
|
|
222
243
|
/**
|
|
223
244
|
* Recognizes a declared rejection: a schema, or a type guard such as an `instanceof`
|
|
224
245
|
* check. Guards must declare their parameter type, for example
|
|
225
246
|
* `(cause: unknown): cause is NotFound => cause instanceof NotFound`.
|
|
226
247
|
*
|
|
227
|
-
* @since
|
|
248
|
+
* @since 0.0.1
|
|
228
249
|
*/
|
|
229
|
-
export type ErrorGuard =
|
|
230
|
-
|
|
231
|
-
type GuardedError<G> = G extends Schema.Top
|
|
232
|
-
? G["Type"]
|
|
233
|
-
: G extends ((cause: unknown) => cause is infer E)
|
|
234
|
-
? E
|
|
235
|
-
: never;
|
|
250
|
+
export type ErrorGuard = Callback.ErrorGuard;
|
|
236
251
|
|
|
237
|
-
/** @since
|
|
252
|
+
/** @since 0.0.1 */
|
|
238
253
|
export type PromiseOptions<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
|
|
239
254
|
/** Effect services resolved for the callbacks and added to the handler requirements. */
|
|
240
255
|
readonly services?: S;
|
|
@@ -246,11 +261,6 @@ export type PromiseOptions<S extends ServiceMap, G extends ReadonlyArray<ErrorGu
|
|
|
246
261
|
readonly errors?: G;
|
|
247
262
|
};
|
|
248
263
|
|
|
249
|
-
const declaredError =
|
|
250
|
-
<G extends ReadonlyArray<ErrorGuard>>(guards: G) =>
|
|
251
|
-
(cause: unknown): cause is GuardedError<G[number]> =>
|
|
252
|
-
guards.some((guard) => (Schema.isSchema(guard) ? Schema.is(guard)(cause) : guard(cause)));
|
|
253
|
-
|
|
254
264
|
type PromiseHandler<A extends Action.Any, S extends ServiceMap, G> = Handler<
|
|
255
265
|
A,
|
|
256
266
|
GuardedError<G> | UnexpectedHandlerError,
|
|
@@ -289,7 +299,7 @@ type PromiseHandler<A extends Action.Any, S extends ServiceMap, G> = Handler<
|
|
|
289
299
|
* });
|
|
290
300
|
* ```
|
|
291
301
|
*
|
|
292
|
-
* @since
|
|
302
|
+
* @since 0.0.1
|
|
293
303
|
*/
|
|
294
304
|
export function promise<
|
|
295
305
|
A extends Action.Any,
|
|
@@ -323,22 +333,7 @@ export function promise<
|
|
|
323
333
|
): PromiseHandler<A, S, G[number]> {
|
|
324
334
|
type E = GuardedError<G[number]> | UnexpectedHandlerError;
|
|
325
335
|
|
|
326
|
-
const
|
|
327
|
-
const services: ServiceMap = options?.services ?? {};
|
|
328
|
-
// The handler requires exactly the declared services. Reading them from its context
|
|
329
|
-
// keeps that requirement typed; only the record of resolved services needs a cast,
|
|
330
|
-
// because Object.fromEntries does not track keys.
|
|
331
|
-
const resolve = Effect.map(
|
|
332
|
-
Effect.context<ServiceIds<S>>(),
|
|
333
|
-
(context) =>
|
|
334
|
-
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
|
|
335
|
-
Object.fromEntries(
|
|
336
|
-
Reflect.ownKeys(services).map((name) => [
|
|
337
|
-
name,
|
|
338
|
-
Context.get(context, services[name]!),
|
|
339
|
-
]),
|
|
340
|
-
) as { readonly [K in keyof S]: S[K]["Service"] },
|
|
341
|
-
);
|
|
336
|
+
const adaptCallback = adaptPromise(options ?? {});
|
|
342
337
|
const unexpected = (phase: Phase, cause: unknown) =>
|
|
343
338
|
new UnexpectedHandlerError({ actionId: action.id, kind: action.kind, phase, cause });
|
|
344
339
|
|
|
@@ -346,16 +341,7 @@ export function promise<
|
|
|
346
341
|
phase: Phase,
|
|
347
342
|
callback: (context: PromiseContext<S>) => PromiseLike<T> | T,
|
|
348
343
|
): Effect.Effect<T, E, ServiceIds<S>> =>
|
|
349
|
-
|
|
350
|
-
trackPromise((capture) =>
|
|
351
|
-
Effect.tryPromise({
|
|
352
|
-
// Declaring `signal` makes Effect.tryPromise allocate an AbortController.
|
|
353
|
-
try: (signal) =>
|
|
354
|
-
capture(Promise.resolve(callback({ signal, services: resolved }))),
|
|
355
|
-
catch: (cause) => (isDeclared(cause) ? cause : unexpected(phase, cause)),
|
|
356
|
-
}),
|
|
357
|
-
),
|
|
358
|
-
);
|
|
344
|
+
adaptCallback(callback, (cause) => unexpected(phase, cause));
|
|
359
345
|
|
|
360
346
|
if (Predicate.isFunction(run)) {
|
|
361
347
|
const apply = Effect.asVoid(adapt("apply", (context) => run(action.payload, context)));
|
|
@@ -387,7 +373,7 @@ export function promise<
|
|
|
387
373
|
/**
|
|
388
374
|
* The second argument of an Effect apply phase.
|
|
389
375
|
*
|
|
390
|
-
* @since
|
|
376
|
+
* @since 0.1.0
|
|
391
377
|
*/
|
|
392
378
|
export type EffectApplyContext<Payload> = { readonly payload: Payload };
|
|
393
379
|
|
|
@@ -395,7 +381,7 @@ export type EffectApplyContext<Payload> = { readonly payload: Payload };
|
|
|
395
381
|
* An Effect handler with a prepare phase. `prepare` reads state and succeeds with
|
|
396
382
|
* `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value.
|
|
397
383
|
*
|
|
398
|
-
* @since
|
|
384
|
+
* @since 0.1.0
|
|
399
385
|
*/
|
|
400
386
|
export type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2> = {
|
|
401
387
|
readonly prepare: (payload: Payload) => Effect.Effect<T, E1, R1>;
|
|
@@ -428,7 +414,7 @@ export type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2
|
|
|
428
414
|
* });
|
|
429
415
|
* ```
|
|
430
416
|
*
|
|
431
|
-
* @since
|
|
417
|
+
* @since 0.0.1
|
|
432
418
|
*/
|
|
433
419
|
export function effect<A extends Action.Any, E = never, R = never>(
|
|
434
420
|
action: A,
|
|
@@ -483,3 +469,138 @@ export function effect<A extends Action.Any, E1, R1, E2, R2>(
|
|
|
483
469
|
),
|
|
484
470
|
);
|
|
485
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
|
+
|
|
491
|
+
/** @since 0.2.0 */
|
|
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>;
|
|
506
|
+
};
|
|
507
|
+
|
|
508
|
+
/**
|
|
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
|
+
* ```
|
|
525
|
+
*
|
|
526
|
+
* @since 0.2.0
|
|
527
|
+
*/
|
|
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
|
+
>(
|
|
542
|
+
action: A,
|
|
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);
|
|
552
|
+
|
|
553
|
+
const check = verified(
|
|
554
|
+
action,
|
|
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 0.2.0 */
|
|
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>;
|
|
577
|
+
};
|
|
578
|
+
|
|
579
|
+
/**
|
|
580
|
+
* `Handler.manual` with an Effect `verify` check, which keeps its own errors and
|
|
581
|
+
* services.
|
|
582
|
+
*
|
|
583
|
+
* @since 0.2.0
|
|
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
|
+
}
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
import { Data, Effect, Predicate } from "effect";
|
|
2
|
+
|
|
3
|
+
import type * as Action from "../../foundation/action.ts";
|
|
4
|
+
import type { Occurrence } from "../../foundation/plan.ts";
|
|
5
|
+
import type * as Callback from "./promise-callback.ts";
|
|
6
|
+
import { adaptPromise } from "./promise-callback.ts";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* What a person says about manual work. There is no other answer: free-form input never
|
|
10
|
+
* reaches a report.
|
|
11
|
+
*
|
|
12
|
+
* @since 0.2.0
|
|
13
|
+
*/
|
|
14
|
+
export type Answer = "confirmed" | "declined";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* A request to confirm manual work. The occurrence carries the action, its description,
|
|
18
|
+
* and the migration instruction that declared it, which is what to show the person.
|
|
19
|
+
*
|
|
20
|
+
* @since 0.2.0
|
|
21
|
+
*/
|
|
22
|
+
export type Request<A extends Action.Any = Action.Any> = {
|
|
23
|
+
readonly occurrence: Occurrence<A>;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* A Promise interaction rejected with a value that none of its declared error guards
|
|
28
|
+
* recognized (`rejected`), or an interaction answered with something other than
|
|
29
|
+
* `"confirmed"` or `"declined"` (`invalid-answer`). An invalid answer is never kept: it
|
|
30
|
+
* may be text that the person typed.
|
|
31
|
+
*
|
|
32
|
+
* @since 0.2.0
|
|
33
|
+
*/
|
|
34
|
+
export class UnexpectedInteractionError extends Data.TaggedError("UnexpectedInteractionError")<{
|
|
35
|
+
readonly occurrenceId: string;
|
|
36
|
+
readonly reason: "rejected" | "invalid-answer";
|
|
37
|
+
/** The rejection. Always `undefined` for an invalid answer. */
|
|
38
|
+
readonly cause: unknown;
|
|
39
|
+
}> {
|
|
40
|
+
override get message() {
|
|
41
|
+
return this.reason === "rejected"
|
|
42
|
+
? `The interaction failed unexpectedly while confirming "${this.occurrenceId}"`
|
|
43
|
+
: `The interaction answered neither "confirmed" nor "declined" for "${this.occurrenceId}"`;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const isAnswer = (value: unknown): value is Answer => value === "confirmed" || value === "declined";
|
|
48
|
+
|
|
49
|
+
const checkAnswer = (request: Request) => (answer: unknown) =>
|
|
50
|
+
isAnswer(answer)
|
|
51
|
+
? Effect.succeed(answer)
|
|
52
|
+
: Effect.fail(
|
|
53
|
+
new UnexpectedInteractionError({
|
|
54
|
+
occurrenceId: request.occurrence.id,
|
|
55
|
+
reason: "invalid-answer",
|
|
56
|
+
cause: undefined,
|
|
57
|
+
}),
|
|
58
|
+
);
|
|
59
|
+
|
|
60
|
+
const TypeId = "~deltafold/Interaction";
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Asks a person to confirm the manual work of a plan. The executor has no terminal or
|
|
64
|
+
* user interface of its own: the consumer running the plan supplies one of these.
|
|
65
|
+
*
|
|
66
|
+
* Parallel branches can ask at the same time. An interaction that owns one terminal
|
|
67
|
+
* serializes its own prompts. A failure or a decline elsewhere stops new actions but
|
|
68
|
+
* does not withdraw a request that was already made; only cancellation does.
|
|
69
|
+
*
|
|
70
|
+
* @since 0.2.0
|
|
71
|
+
*/
|
|
72
|
+
export type Interaction<out E = never, out R = never> = {
|
|
73
|
+
readonly [TypeId]: typeof TypeId;
|
|
74
|
+
readonly confirm: (request: Request) => Effect.Effect<Answer, E, R>;
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Any interaction.
|
|
79
|
+
*
|
|
80
|
+
* @since 0.2.0
|
|
81
|
+
*/
|
|
82
|
+
export type Any = Interaction<any, any>;
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The errors of an interaction.
|
|
86
|
+
*
|
|
87
|
+
* @since 0.2.0
|
|
88
|
+
*/
|
|
89
|
+
export type Error<I> = I extends Interaction<infer E, any> ? E : never;
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* The Effect services of an interaction.
|
|
93
|
+
*
|
|
94
|
+
* @since 0.2.0
|
|
95
|
+
*/
|
|
96
|
+
export type Services<I> = I extends Interaction<any, infer R> ? R : never;
|
|
97
|
+
|
|
98
|
+
/** @since 0.2.0 */
|
|
99
|
+
export const isInteraction = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
|
|
100
|
+
|
|
101
|
+
/** @since 0.2.0 */
|
|
102
|
+
export type PromiseOptions<
|
|
103
|
+
S extends Callback.ServiceMap,
|
|
104
|
+
G extends ReadonlyArray<Callback.ErrorGuard>,
|
|
105
|
+
> = {
|
|
106
|
+
/** Effect services resolved for the callback and added to the run's requirements. */
|
|
107
|
+
readonly services?: S;
|
|
108
|
+
/** Guards for rejections that keep their own type. */
|
|
109
|
+
readonly errors?: G;
|
|
110
|
+
};
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Confirms manual work with a Promise callback. It receives `{ signal, services }`: an
|
|
114
|
+
* `AbortSignal` that aborts when the run is cancelled, so it can stop asking, and the
|
|
115
|
+
* declared services.
|
|
116
|
+
*
|
|
117
|
+
* @example
|
|
118
|
+
* ```ts
|
|
119
|
+
* // The migration's instruction for this action, or the action's description.
|
|
120
|
+
* const textOf = ({ action, instruction }: Plan.Occurrence) =>
|
|
121
|
+
* instruction?.content
|
|
122
|
+
* .map((part) => (part._tag === "Text" ? part.text : part.action.description))
|
|
123
|
+
* .join("") ?? action.description;
|
|
124
|
+
*
|
|
125
|
+
* const interaction = Interaction.promise(async ({ occurrence }, { signal }) =>
|
|
126
|
+
* (await ask(textOf(occurrence), { signal })) ? "confirmed" : "declined",
|
|
127
|
+
* );
|
|
128
|
+
* ```
|
|
129
|
+
*
|
|
130
|
+
* @since 0.2.0
|
|
131
|
+
*/
|
|
132
|
+
export const promise = <
|
|
133
|
+
const S extends Callback.ServiceMap = Callback.NoServices,
|
|
134
|
+
const G extends ReadonlyArray<Callback.ErrorGuard> = [],
|
|
135
|
+
>(
|
|
136
|
+
confirm: (request: Request, context: Callback.PromiseContext<S>) => PromiseLike<Answer>,
|
|
137
|
+
options?: PromiseOptions<S, G>,
|
|
138
|
+
): Interaction<
|
|
139
|
+
Callback.GuardedError<G[number]> | UnexpectedInteractionError,
|
|
140
|
+
Callback.ServiceIds<S>
|
|
141
|
+
> => {
|
|
142
|
+
const adapt = adaptPromise(options ?? {});
|
|
143
|
+
|
|
144
|
+
return {
|
|
145
|
+
[TypeId]: TypeId,
|
|
146
|
+
confirm: (request) =>
|
|
147
|
+
adapt<unknown, UnexpectedInteractionError>(
|
|
148
|
+
(context) => confirm(request, context),
|
|
149
|
+
(cause) =>
|
|
150
|
+
new UnexpectedInteractionError({
|
|
151
|
+
occurrenceId: request.occurrence.id,
|
|
152
|
+
reason: "rejected",
|
|
153
|
+
cause,
|
|
154
|
+
}),
|
|
155
|
+
).pipe(Effect.flatMap(checkAnswer(request))),
|
|
156
|
+
};
|
|
157
|
+
};
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Confirms manual work with an Effect, which keeps its own errors and services and
|
|
161
|
+
* stops through Effect interruption when the run is cancelled.
|
|
162
|
+
*
|
|
163
|
+
* @since 0.2.0
|
|
164
|
+
*/
|
|
165
|
+
export const effect = <E = never, R = never>(
|
|
166
|
+
confirm: (request: Request) => Effect.Effect<Answer, E, R>,
|
|
167
|
+
): Interaction<E | UnexpectedInteractionError, R> => ({
|
|
168
|
+
[TypeId]: TypeId,
|
|
169
|
+
confirm: (request) =>
|
|
170
|
+
Effect.flatMap(
|
|
171
|
+
Effect.suspend(() => confirm(request)),
|
|
172
|
+
checkAnswer(request),
|
|
173
|
+
),
|
|
174
|
+
});
|