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
|
@@ -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
|
+
};
|
|
@@ -7,16 +7,18 @@ import { Context, Duration, Effect, Option } from "effect";
|
|
|
7
7
|
export type Settlement = {
|
|
8
8
|
/** How long to keep waiting for an interrupted Promise before reporting it pending. */
|
|
9
9
|
readonly grace: Duration.Input;
|
|
10
|
-
|
|
10
|
+
/** Receives an interrupted Promise that did not settle within the grace period. */
|
|
11
|
+
readonly unsettled: (promise: Promise<void>) => void;
|
|
11
12
|
};
|
|
12
13
|
|
|
13
14
|
export const SettlementReference = Context.Reference<Settlement>("deltafold/Settlement", {
|
|
14
|
-
defaultValue: () => ({ grace: Duration.zero,
|
|
15
|
+
defaultValue: () => ({ grace: Duration.zero, unsettled: () => {} }),
|
|
15
16
|
});
|
|
16
17
|
|
|
17
18
|
/**
|
|
18
19
|
* Runs a Promise-producing effect. If it is interrupted after the Promise started,
|
|
19
|
-
* waits up to the settlement grace period and
|
|
20
|
+
* waits up to the settlement grace period and hands a still-pending Promise to the
|
|
21
|
+
* settlement, which can hold resources until it settles.
|
|
20
22
|
*/
|
|
21
23
|
export const trackPromise = <T, E, R>(
|
|
22
24
|
start: (capture: (promise: Promise<T>) => Promise<T>) => Effect.Effect<T, E, R>,
|
|
@@ -35,14 +37,15 @@ export const trackPromise = <T, E, R>(
|
|
|
35
37
|
const started = pending;
|
|
36
38
|
if (started === undefined) return;
|
|
37
39
|
|
|
40
|
+
const settles = started.then(
|
|
41
|
+
() => undefined,
|
|
42
|
+
() => undefined,
|
|
43
|
+
);
|
|
38
44
|
const settlement = yield* SettlementReference;
|
|
39
|
-
const settled = yield* Effect.promise(() =>
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
),
|
|
44
|
-
).pipe(Effect.timeoutOption(settlement.grace));
|
|
45
|
-
settlement.record(Option.isSome(settled));
|
|
45
|
+
const settled = yield* Effect.promise(() => settles).pipe(
|
|
46
|
+
Effect.timeoutOption(settlement.grace),
|
|
47
|
+
);
|
|
48
|
+
if (Option.isNone(settled)) settlement.unsettled(settles);
|
|
46
49
|
}),
|
|
47
50
|
),
|
|
48
51
|
);
|
|
@@ -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";
|