deltafold 0.1.0 → 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 +64 -1
- package/dist/index.d.ts +307 -60
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +232 -36
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/features/execution/executor.ts +232 -45
- package/src/features/execution/handler.ts +181 -60
- package/src/features/execution/interaction.ts +174 -0
- package/src/features/execution/promise-callback.ts +76 -0
- package/src/features/planning/rewrite.ts +1 -1
- package/src/index.ts +2 -0
|
@@ -1,16 +1,43 @@
|
|
|
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";
|
|
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
24
|
* @since @next
|
|
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 @next
|
|
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
|
|
@@ -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
130
|
* @since @next
|
|
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",
|
|
@@ -122,6 +151,8 @@ const TypeId = "~deltafold/Handler";
|
|
|
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
|
/**
|
|
@@ -167,17 +198,14 @@ 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
206
|
* @since @next
|
|
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
|
|
@@ -185,10 +213,7 @@ type NoServices = Record<never, never>;
|
|
|
185
213
|
*
|
|
186
214
|
* @since @next
|
|
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
|
|
@@ -215,10 +240,6 @@ 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
|
|
@@ -226,13 +247,7 @@ type ServiceIds<S extends ServiceMap> = ValueOf<{
|
|
|
226
247
|
*
|
|
227
248
|
* @since @next
|
|
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
252
|
/** @since @next */
|
|
238
253
|
export type PromiseOptions<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
|
|
@@ -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,
|
|
@@ -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)));
|
|
@@ -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 @next */
|
|
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 @next
|
|
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 @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>;
|
|
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
|
+
}
|
|
@@ -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 @next
|
|
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 @next
|
|
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 @next
|
|
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 @next
|
|
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 @next
|
|
81
|
+
*/
|
|
82
|
+
export type Any = Interaction<any, any>;
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The errors of an interaction.
|
|
86
|
+
*
|
|
87
|
+
* @since @next
|
|
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 @next
|
|
95
|
+
*/
|
|
96
|
+
export type Services<I> = I extends Interaction<any, infer R> ? R : never;
|
|
97
|
+
|
|
98
|
+
/** @since @next */
|
|
99
|
+
export const isInteraction = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
|
|
100
|
+
|
|
101
|
+
/** @since @next */
|
|
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 @next
|
|
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 @next
|
|
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
|
+
});
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { Context, Effect, Schema } from "effect";
|
|
2
|
+
|
|
3
|
+
import type { ValueOf } from "../../types.ts";
|
|
4
|
+
import { trackPromise } from "./settlement.ts";
|
|
5
|
+
|
|
6
|
+
/** Named Effect services that Promise callbacks declare. */
|
|
7
|
+
export type ServiceMap = { readonly [name: string | symbol]: Context.Key<any, any> };
|
|
8
|
+
|
|
9
|
+
// oxlint-disable-next-line typescript/no-generated-empty-object-type -- Callbacks without services declare an empty service map.
|
|
10
|
+
export type NoServices = Record<never, never>;
|
|
11
|
+
|
|
12
|
+
/** The `AbortSignal` aborted on interruption, and the declared services, resolved. */
|
|
13
|
+
export type PromiseContext<S extends ServiceMap = NoServices> = {
|
|
14
|
+
readonly signal: AbortSignal;
|
|
15
|
+
readonly services: { readonly [K in keyof S]: S[K]["Service"] };
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
export type ServiceIds<S extends ServiceMap> = ValueOf<{
|
|
19
|
+
[K in keyof S]: S[K] extends Context.Key<infer I, any> ? I : never;
|
|
20
|
+
}>;
|
|
21
|
+
|
|
22
|
+
/** Recognizes a declared rejection: a schema, or a type guard. */
|
|
23
|
+
export type ErrorGuard = Schema.Top | ((cause: unknown) => cause is any);
|
|
24
|
+
|
|
25
|
+
export type GuardedError<G> = G extends Schema.Top
|
|
26
|
+
? G["Type"]
|
|
27
|
+
: G extends ((cause: unknown) => cause is infer E)
|
|
28
|
+
? E
|
|
29
|
+
: never;
|
|
30
|
+
|
|
31
|
+
const declaredError =
|
|
32
|
+
<G extends ReadonlyArray<ErrorGuard>>(guards: G) =>
|
|
33
|
+
(cause: unknown): cause is GuardedError<G[number]> =>
|
|
34
|
+
guards.some((guard) => (Schema.isSchema(guard) ? Schema.is(guard)(cause) : guard(cause)));
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Turns Promise callbacks into Effects. Declared services are resolved before each
|
|
38
|
+
* call, rejections that a guard recognizes keep their type, and `unexpected` wraps the
|
|
39
|
+
* rest.
|
|
40
|
+
*/
|
|
41
|
+
export const adaptPromise = <S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>>(options: {
|
|
42
|
+
readonly services?: S | undefined;
|
|
43
|
+
readonly errors?: G | undefined;
|
|
44
|
+
}) => {
|
|
45
|
+
const isDeclared = declaredError(options.errors ?? []);
|
|
46
|
+
const services: ServiceMap = options.services ?? {};
|
|
47
|
+
// The callbacks require exactly the declared services. Reading them from the context
|
|
48
|
+
// keeps that requirement typed; only the record of resolved services needs a cast,
|
|
49
|
+
// because Object.fromEntries does not track keys.
|
|
50
|
+
const resolve = Effect.map(
|
|
51
|
+
Effect.context<ServiceIds<S>>(),
|
|
52
|
+
(context) =>
|
|
53
|
+
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
|
|
54
|
+
Object.fromEntries(
|
|
55
|
+
Reflect.ownKeys(services).map((name) => [
|
|
56
|
+
name,
|
|
57
|
+
Context.get(context, services[name]!),
|
|
58
|
+
]),
|
|
59
|
+
) as { readonly [K in keyof S]: S[K]["Service"] },
|
|
60
|
+
);
|
|
61
|
+
|
|
62
|
+
return <T, U>(
|
|
63
|
+
callback: (context: PromiseContext<S>) => PromiseLike<T> | T,
|
|
64
|
+
unexpected: (cause: unknown) => U,
|
|
65
|
+
): Effect.Effect<T, GuardedError<G[number]> | U, ServiceIds<S>> =>
|
|
66
|
+
Effect.flatMap(resolve, (resolved) =>
|
|
67
|
+
trackPromise((capture) =>
|
|
68
|
+
Effect.tryPromise({
|
|
69
|
+
// Declaring `signal` makes Effect.tryPromise allocate an AbortController.
|
|
70
|
+
try: (signal) =>
|
|
71
|
+
capture(Promise.resolve(callback({ signal, services: resolved }))),
|
|
72
|
+
catch: (cause) => (isDeclared(cause) ? cause : unexpected(cause)),
|
|
73
|
+
}),
|
|
74
|
+
),
|
|
75
|
+
);
|
|
76
|
+
};
|
|
@@ -18,7 +18,7 @@ export type Item =
|
|
|
18
18
|
readonly concurrency: Action.Concurrency;
|
|
19
19
|
readonly step: number;
|
|
20
20
|
}
|
|
21
|
-
/** A text-only migration:
|
|
21
|
+
/** A text-only migration: prose instructions that rules must not match around. */
|
|
22
22
|
| { readonly _tag: "Barrier"; readonly step: number };
|
|
23
23
|
|
|
24
24
|
export type Application = {
|
package/src/index.ts
CHANGED
|
@@ -7,6 +7,8 @@ export * as Executor from "./features/execution/executor.ts";
|
|
|
7
7
|
/** @since @next */
|
|
8
8
|
export * as Handler from "./features/execution/handler.ts";
|
|
9
9
|
/** @since @next */
|
|
10
|
+
export * as Interaction from "./features/execution/interaction.ts";
|
|
11
|
+
/** @since @next */
|
|
10
12
|
export * as History from "./features/planning/history.ts";
|
|
11
13
|
/** @since @next */
|
|
12
14
|
export * as Migration from "./foundation/migration.ts";
|