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
package/dist/index.d.ts
CHANGED
|
@@ -1,17 +1,56 @@
|
|
|
1
|
-
import { _ as
|
|
2
|
-
import { Cause, Context, Duration, Effect, Layer, Schema, Scope } from "effect";
|
|
1
|
+
import { _ as change_d_exports, a as Direction, c as plan_d_exports, d as migration_d_exports, i as Coverage, l as shortcut_d_exports, m as version_d_exports, n as package_d_exports, o as Occurrence, r as history_d_exports, s as Plan, u as rule_d_exports, v as Any$3, y as action_d_exports } from "./package-CA5R57IC.js";
|
|
2
|
+
import { Cause, Context, Duration, Effect, Exit, Layer, Schema, Scope } from "effect";
|
|
3
3
|
/** The union of an object type's property values. */
|
|
4
4
|
type ValueOf<T> = T[keyof T];
|
|
5
|
+
/** Named Effect services that Promise callbacks declare. */
|
|
6
|
+
type ServiceMap$1 = {
|
|
7
|
+
readonly [name: string | symbol]: Context.Key<any, any>;
|
|
8
|
+
};
|
|
9
|
+
type NoServices$1 = Record<never, never>;
|
|
10
|
+
/** The `AbortSignal` aborted on interruption, and the declared services, resolved. */
|
|
11
|
+
type PromiseContext$1<S extends ServiceMap$1 = NoServices$1> = {
|
|
12
|
+
readonly signal: AbortSignal;
|
|
13
|
+
readonly services: { readonly [K in keyof S]: S[K]["Service"]; };
|
|
14
|
+
};
|
|
15
|
+
type ServiceIds$1<S extends ServiceMap$1> = ValueOf<{ [K in keyof S]: S[K] extends Context.Key<infer I, any> ? I : never; }>;
|
|
16
|
+
/** Recognizes a declared rejection: a schema, or a type guard. */
|
|
17
|
+
type ErrorGuard$1 = Schema.Top | ((cause: unknown) => cause is any);
|
|
18
|
+
type GuardedError$1<G> = G extends Schema.Top ? G["Type"] : G extends ((cause: unknown) => cause is infer E) ? E : never;
|
|
5
19
|
declare namespace handler_d_exports {
|
|
6
|
-
export { ActionId, Any, EffectApplyContext, EffectPhases, Error, ErrorGuard, Handler, Phase, Preparation, Prepared, PromiseApplyContext, PromiseContext, PromiseOptions$
|
|
20
|
+
export { ActionId, Any$2 as Any, EffectApplyContext, EffectPhases, Error$1 as Error, ErrorGuard, Handler, ManualEffectOptions, ManualOptions, Performer, Phase, Preparation, Prepared, PromiseApplyContext, PromiseContext, PromiseOptions$2 as PromiseOptions, PromisePhases, ServiceMap, Services$2 as Services, Skip, Step, UnexpectedHandlerError, VerificationFailed, effect$3 as effect, isHandler, manual, manualEffect, prepared, promise$2 as promise, skip };
|
|
7
21
|
}
|
|
22
|
+
type NoServices = NoServices$1;
|
|
23
|
+
type ServiceIds<S extends ServiceMap> = ServiceIds$1<S>;
|
|
24
|
+
type GuardedError<G> = GuardedError$1<G>;
|
|
25
|
+
/**
|
|
26
|
+
* Where a handler failure or interruption happened: the read-only prepare phase, or the
|
|
27
|
+
* apply phase that changes state. A manual handler has neither: the executor waits for a
|
|
28
|
+
* person in `confirmation`, then runs the handler's optional check in `verification`.
|
|
29
|
+
*
|
|
30
|
+
* @since 0.0.1
|
|
31
|
+
*/
|
|
32
|
+
type Phase = "prepare" | "apply" | "confirmation" | "verification";
|
|
8
33
|
/**
|
|
9
|
-
*
|
|
10
|
-
*
|
|
34
|
+
* Who performs an action: a handler's apply phase, or a person whose confirmation the
|
|
35
|
+
* executor waits for.
|
|
11
36
|
*
|
|
12
|
-
* @since
|
|
37
|
+
* @since 0.2.0
|
|
13
38
|
*/
|
|
14
|
-
type
|
|
39
|
+
type Performer = "automated" | "manual";
|
|
40
|
+
declare const VerificationFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
|
|
41
|
+
readonly _tag: "VerificationFailed";
|
|
42
|
+
} & Readonly<A>;
|
|
43
|
+
/**
|
|
44
|
+
* A person confirmed manual work, and the handler's `verify` check returned `false`.
|
|
45
|
+
*
|
|
46
|
+
* @since 0.2.0
|
|
47
|
+
*/
|
|
48
|
+
declare class VerificationFailed extends VerificationFailed_base<{
|
|
49
|
+
readonly actionId: string;
|
|
50
|
+
readonly kind: string;
|
|
51
|
+
}> {
|
|
52
|
+
get message(): string;
|
|
53
|
+
}
|
|
15
54
|
declare const UnexpectedHandlerError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
|
|
16
55
|
readonly _tag: "UnexpectedHandlerError";
|
|
17
56
|
} & Readonly<A>;
|
|
@@ -20,7 +59,7 @@ declare const UnexpectedHandlerError_base: new <A extends Record<string, any> =
|
|
|
20
59
|
* recognized, or its prepare phase returned something other than `Handler.prepared` or
|
|
21
60
|
* `Handler.skip`.
|
|
22
61
|
*
|
|
23
|
-
* @since
|
|
62
|
+
* @since 0.0.1
|
|
24
63
|
*/
|
|
25
64
|
declare class UnexpectedHandlerError extends UnexpectedHandlerError_base<{
|
|
26
65
|
readonly actionId: string;
|
|
@@ -35,7 +74,7 @@ declare const PreparationTypeId = "~deltafold/Preparation";
|
|
|
35
74
|
* A prepare phase decided to apply. The apply phase receives `value` unchanged; the
|
|
36
75
|
* executor never reads, validates, or serializes it.
|
|
37
76
|
*
|
|
38
|
-
* @since
|
|
77
|
+
* @since 0.1.0
|
|
39
78
|
*/
|
|
40
79
|
type Prepared<out P> = {
|
|
41
80
|
readonly [PreparationTypeId]: typeof PreparationTypeId;
|
|
@@ -46,7 +85,7 @@ type Prepared<out P> = {
|
|
|
46
85
|
* A prepare phase decided that the action does not apply. The occurrence is skipped
|
|
47
86
|
* with `reason`.
|
|
48
87
|
*
|
|
49
|
-
* @since
|
|
88
|
+
* @since 0.1.0
|
|
50
89
|
*/
|
|
51
90
|
type Skip = {
|
|
52
91
|
readonly [PreparationTypeId]: typeof PreparationTypeId;
|
|
@@ -56,7 +95,7 @@ type Skip = {
|
|
|
56
95
|
/**
|
|
57
96
|
* What a prepare phase returns: `Handler.prepared(value)` or `Handler.skip(reason)`.
|
|
58
97
|
*
|
|
59
|
-
* @since
|
|
98
|
+
* @since 0.1.0
|
|
60
99
|
*/
|
|
61
100
|
type Preparation<P> = Prepared<P> | Skip;
|
|
62
101
|
/** The value that a prepare phase passes to its apply phase. */
|
|
@@ -65,37 +104,43 @@ type PreparedValue<T> = T extends Prepared<infer P> ? P : never;
|
|
|
65
104
|
* Ends a prepare phase with the value its apply phase receives. Wrapping the value keeps
|
|
66
105
|
* it apart from a skip, whatever its shape.
|
|
67
106
|
*
|
|
68
|
-
* @since
|
|
107
|
+
* @since 0.1.0
|
|
69
108
|
*/
|
|
70
109
|
declare function prepared(): Prepared<void>;
|
|
71
110
|
declare function prepared<P>(value: P): Prepared<P>;
|
|
72
111
|
/**
|
|
73
112
|
* Ends a prepare phase by skipping the occurrence. The apply phase does not run.
|
|
74
113
|
*
|
|
75
|
-
* @since
|
|
114
|
+
* @since 0.1.0
|
|
76
115
|
*/
|
|
77
116
|
declare const skip: (reason: string) => Skip;
|
|
78
117
|
/**
|
|
79
|
-
* How an occurrence continues after its prepare phase: skipped,
|
|
80
|
-
* that already holds the prepared value.
|
|
118
|
+
* How an occurrence continues after its prepare phase: skipped, applied by an effect
|
|
119
|
+
* that already holds the prepared value, or confirmed by a person. `verify` checks
|
|
120
|
+
* confirmed work and fails when the check does not pass.
|
|
81
121
|
*
|
|
82
|
-
* @since
|
|
122
|
+
* @since 0.1.0
|
|
83
123
|
*/
|
|
84
124
|
type Step<E, R> = Skip | {
|
|
85
125
|
readonly _tag: "Apply";
|
|
86
126
|
readonly apply: Effect.Effect<void, E, R>;
|
|
127
|
+
} | {
|
|
128
|
+
readonly _tag: "Confirm";
|
|
129
|
+
readonly verify: Effect.Effect<void, E, R> | undefined;
|
|
87
130
|
};
|
|
88
|
-
declare const TypeId = "~deltafold/Handler";
|
|
131
|
+
declare const TypeId$2 = "~deltafold/Handler";
|
|
89
132
|
/**
|
|
90
133
|
* Implements one action instance. `E` and `R` are the errors and Effect services of both
|
|
91
134
|
* phases together. A prepared value stays inside the handler, so handlers with
|
|
92
135
|
* different prepared values share this type.
|
|
93
136
|
*
|
|
94
|
-
* @since
|
|
137
|
+
* @since 0.0.1
|
|
95
138
|
*/
|
|
96
|
-
type Handler<out A extends Any$
|
|
97
|
-
readonly [TypeId]: typeof TypeId;
|
|
139
|
+
type Handler<out A extends Any$3, out E = never, out R = never> = {
|
|
140
|
+
readonly [TypeId$2]: typeof TypeId$2;
|
|
98
141
|
readonly action: A;
|
|
142
|
+
/** A `manual` handler has no phases of its own: a person does the work. */
|
|
143
|
+
readonly performer: Performer;
|
|
99
144
|
/** Whether the handler has a prepare phase. */
|
|
100
145
|
readonly prepares: boolean;
|
|
101
146
|
/**
|
|
@@ -108,53 +153,47 @@ type Handler<out A extends Any$1, out E = never, out R = never> = {
|
|
|
108
153
|
/**
|
|
109
154
|
* Any handler.
|
|
110
155
|
*
|
|
111
|
-
* @since
|
|
156
|
+
* @since 0.0.1
|
|
112
157
|
*/
|
|
113
|
-
type Any = Handler<Any$
|
|
158
|
+
type Any$2 = Handler<Any$3, any, any>;
|
|
114
159
|
/**
|
|
115
160
|
* The errors of a handler or a union of handlers.
|
|
116
161
|
*
|
|
117
|
-
* @since
|
|
162
|
+
* @since 0.0.1
|
|
118
163
|
*/
|
|
119
|
-
type Error<H> = H extends Handler<any, infer E, any> ? E : never;
|
|
164
|
+
type Error$1<H> = H extends Handler<any, infer E, any> ? E : never;
|
|
120
165
|
/**
|
|
121
166
|
* The Effect services of a handler or a union of handlers.
|
|
122
167
|
*
|
|
123
|
-
* @since
|
|
168
|
+
* @since 0.0.1
|
|
124
169
|
*/
|
|
125
|
-
type Services<H> = H extends Handler<any, any, infer R> ? R : never;
|
|
170
|
+
type Services$2<H> = H extends Handler<any, any, infer R> ? R : never;
|
|
126
171
|
/**
|
|
127
172
|
* The action identifiers implemented by a handler or a union of handlers.
|
|
128
173
|
*
|
|
129
|
-
* @since
|
|
174
|
+
* @since 0.0.1
|
|
130
175
|
*/
|
|
131
176
|
type ActionId<H> = H extends Handler<infer A, any, any> ? A["id"] : never;
|
|
132
|
-
/** @since
|
|
133
|
-
declare const isHandler: (value: unknown) => value is Any;
|
|
177
|
+
/** @since 0.0.1 */
|
|
178
|
+
declare const isHandler: (value: unknown) => value is Any$2;
|
|
134
179
|
/**
|
|
135
180
|
* Named Effect services that a Promise handler declares.
|
|
136
181
|
*
|
|
137
|
-
* @since
|
|
182
|
+
* @since 0.0.1
|
|
138
183
|
*/
|
|
139
|
-
type ServiceMap =
|
|
140
|
-
readonly [name: string | symbol]: Context.Key<any, any>;
|
|
141
|
-
};
|
|
142
|
-
type NoServices = Record<never, never>;
|
|
184
|
+
type ServiceMap = ServiceMap$1;
|
|
143
185
|
/**
|
|
144
186
|
* The second argument of Promise handler callbacks: the `AbortSignal` that
|
|
145
187
|
* `Effect.tryPromise` aborts on interruption, and the declared services, resolved.
|
|
146
188
|
*
|
|
147
|
-
* @since
|
|
189
|
+
* @since 0.0.1
|
|
148
190
|
*/
|
|
149
|
-
type PromiseContext<S extends ServiceMap = NoServices> =
|
|
150
|
-
readonly signal: AbortSignal;
|
|
151
|
-
readonly services: { readonly [K in keyof S]: S[K]["Service"]; };
|
|
152
|
-
};
|
|
191
|
+
type PromiseContext<S extends ServiceMap = NoServices> = PromiseContext$1<S>;
|
|
153
192
|
/**
|
|
154
193
|
* The second argument of a Promise apply phase: the Promise context and the action
|
|
155
194
|
* payload.
|
|
156
195
|
*
|
|
157
|
-
* @since
|
|
196
|
+
* @since 0.1.0
|
|
158
197
|
*/
|
|
159
198
|
type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = PromiseContext<S> & {
|
|
160
199
|
readonly payload: Payload;
|
|
@@ -164,24 +203,22 @@ type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = PromiseCo
|
|
|
164
203
|
* `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value. Each
|
|
165
204
|
* phase gets its own signal.
|
|
166
205
|
*
|
|
167
|
-
* @since
|
|
206
|
+
* @since 0.1.0
|
|
168
207
|
*/
|
|
169
208
|
type PromisePhases<Payload, T extends Preparation<unknown>, S extends ServiceMap> = {
|
|
170
209
|
readonly prepare: (payload: Payload, context: PromiseContext<S>) => PromiseLike<T> | T;
|
|
171
210
|
readonly apply: (prepared: PreparedValue<T>, context: PromiseApplyContext<Payload, S>) => PromiseLike<unknown>;
|
|
172
211
|
};
|
|
173
|
-
type ServiceIds<S extends ServiceMap> = ValueOf<{ [K in keyof S]: S[K] extends Context.Key<infer I, any> ? I : never; }>;
|
|
174
212
|
/**
|
|
175
213
|
* Recognizes a declared rejection: a schema, or a type guard such as an `instanceof`
|
|
176
214
|
* check. Guards must declare their parameter type, for example
|
|
177
215
|
* `(cause: unknown): cause is NotFound => cause instanceof NotFound`.
|
|
178
216
|
*
|
|
179
|
-
* @since
|
|
217
|
+
* @since 0.0.1
|
|
180
218
|
*/
|
|
181
|
-
type ErrorGuard =
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
type PromiseOptions$1<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
|
|
219
|
+
type ErrorGuard = ErrorGuard$1;
|
|
220
|
+
/** @since 0.0.1 */
|
|
221
|
+
type PromiseOptions$2<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
|
|
185
222
|
/** Effect services resolved for the callbacks and added to the handler requirements. */
|
|
186
223
|
readonly services?: S;
|
|
187
224
|
/**
|
|
@@ -191,7 +228,7 @@ type PromiseOptions$1<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>>
|
|
|
191
228
|
*/
|
|
192
229
|
readonly errors?: G;
|
|
193
230
|
};
|
|
194
|
-
type PromiseHandler<A extends Any$
|
|
231
|
+
type PromiseHandler<A extends Any$3, S extends ServiceMap, G> = Handler<A, GuardedError<G> | UnexpectedHandlerError, ServiceIds<S>>;
|
|
195
232
|
/**
|
|
196
233
|
* Implements an action with Promise callbacks. The callbacks run lazily through
|
|
197
234
|
* `Effect.tryPromise`, and receive its `AbortSignal` and the declared services.
|
|
@@ -224,14 +261,14 @@ type PromiseHandler<A extends Any$1, S extends ServiceMap, G> = Handler<A, Guard
|
|
|
224
261
|
* });
|
|
225
262
|
* ```
|
|
226
263
|
*
|
|
227
|
-
* @since
|
|
264
|
+
* @since 0.0.1
|
|
228
265
|
*/
|
|
229
|
-
declare function promise<A extends Any$
|
|
230
|
-
declare function promise<A extends Any$
|
|
266
|
+
declare function promise$2<A extends Any$3, const S extends ServiceMap = NoServices, const G extends ReadonlyArray<ErrorGuard> = []>(action: A, apply: (payload: A["payload"], context: PromiseContext<S>) => PromiseLike<unknown>, options?: PromiseOptions$2<S, G>): PromiseHandler<A, S, G[number]>;
|
|
267
|
+
declare function promise$2<A extends Any$3, T extends Preparation<unknown> = Skip, const S extends ServiceMap = NoServices, const G extends ReadonlyArray<ErrorGuard> = []>(action: A, phases: PromisePhases<A["payload"], T, S>, options?: PromiseOptions$2<S, G>): PromiseHandler<A, S, G[number]>;
|
|
231
268
|
/**
|
|
232
269
|
* The second argument of an Effect apply phase.
|
|
233
270
|
*
|
|
234
|
-
* @since
|
|
271
|
+
* @since 0.1.0
|
|
235
272
|
*/
|
|
236
273
|
type EffectApplyContext<Payload> = {
|
|
237
274
|
readonly payload: Payload;
|
|
@@ -240,7 +277,7 @@ type EffectApplyContext<Payload> = {
|
|
|
240
277
|
* An Effect handler with a prepare phase. `prepare` reads state and succeeds with
|
|
241
278
|
* `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value.
|
|
242
279
|
*
|
|
243
|
-
* @since
|
|
280
|
+
* @since 0.1.0
|
|
244
281
|
*/
|
|
245
282
|
type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2> = {
|
|
246
283
|
readonly prepare: (payload: Payload) => Effect.Effect<T, E1, R1>;
|
|
@@ -269,23 +306,517 @@ type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2> = {
|
|
|
269
306
|
* });
|
|
270
307
|
* ```
|
|
271
308
|
*
|
|
272
|
-
* @since
|
|
309
|
+
* @since 0.0.1
|
|
310
|
+
*/
|
|
311
|
+
declare function effect$3<A extends Any$3, E = never, R = never>(action: A, apply: (payload: A["payload"]) => Effect.Effect<unknown, E, R>): Handler<A, E, Exclude<R, Scope.Scope>>;
|
|
312
|
+
declare function effect$3<A extends Any$3, T extends Preparation<unknown> = Skip, E1 = never, R1 = never, E2 = never, R2 = never>(action: A, phases: EffectPhases<A["payload"], T, E1, R1, E2, R2>): Handler<A, E1 | E2, Exclude<R1 | R2, Scope.Scope>>;
|
|
313
|
+
/** @since 0.2.0 */
|
|
314
|
+
type ManualOptions<Payload, S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
|
|
315
|
+
/** Effect services resolved for `verify` and added to the handler requirements. */
|
|
316
|
+
readonly services?: S;
|
|
317
|
+
/** Guards for rejections of `verify` that keep their own type. */
|
|
318
|
+
readonly errors?: G;
|
|
319
|
+
/**
|
|
320
|
+
* Read-only check that runs after the person confirms. Returning `false` fails the
|
|
321
|
+
* occurrence with `VerificationFailed`. A passing check is evidence that the work is
|
|
322
|
+
* in place, not proof of how it was done.
|
|
323
|
+
*/
|
|
324
|
+
readonly verify?: (payload: Payload, context: PromiseContext<S>) => boolean | PromiseLike<boolean>;
|
|
325
|
+
};
|
|
326
|
+
/**
|
|
327
|
+
* Declares that a person performs the action. A manual handler has no prepare or apply
|
|
328
|
+
* phase. In a real run the executor asks its `interaction` to confirm the work, showing
|
|
329
|
+
* the occurrence's own instruction or description, and never completes the occurrence
|
|
330
|
+
* on its own. A dry run reports that a person would be asked. The optional `verify`
|
|
331
|
+
* check is a Promise callback that runs only after the confirmation.
|
|
332
|
+
*
|
|
333
|
+
* The same action can have a manual handler in one environment and an automated one in
|
|
334
|
+
* another.
|
|
335
|
+
*
|
|
336
|
+
* @example
|
|
337
|
+
* ```ts
|
|
338
|
+
* Handler.manual(rotateApiKey, {
|
|
339
|
+
* services: { keys: KeyStore },
|
|
340
|
+
* verify: (payload, { services: { keys } }) => keys.isFresh(payload.service),
|
|
341
|
+
* });
|
|
342
|
+
* ```
|
|
343
|
+
*
|
|
344
|
+
* @since 0.2.0
|
|
345
|
+
*/
|
|
346
|
+
declare function manual<A extends Any$3>(action: A): Handler<A>;
|
|
347
|
+
declare function manual<A extends Any$3, const S extends ServiceMap = NoServices, const G extends ReadonlyArray<ErrorGuard> = []>(action: A, options: ManualOptions<A["payload"], S, G>): Handler<A, GuardedError<G[number]> | UnexpectedHandlerError | VerificationFailed, ServiceIds<S>>;
|
|
348
|
+
/** @since 0.2.0 */
|
|
349
|
+
type ManualEffectOptions<Payload, E, R> = {
|
|
350
|
+
/**
|
|
351
|
+
* Read-only check that runs after the person confirms. Succeeding with `false` fails
|
|
352
|
+
* the occurrence with `VerificationFailed`. It runs in the occurrence's `Scope`.
|
|
353
|
+
*/
|
|
354
|
+
readonly verify?: (payload: Payload) => Effect.Effect<boolean, E, R>;
|
|
355
|
+
};
|
|
356
|
+
/**
|
|
357
|
+
* `Handler.manual` with an Effect `verify` check, which keeps its own errors and
|
|
358
|
+
* services.
|
|
359
|
+
*
|
|
360
|
+
* @since 0.2.0
|
|
361
|
+
*/
|
|
362
|
+
declare function manualEffect<A extends Any$3>(action: A): Handler<A>;
|
|
363
|
+
declare function manualEffect<A extends Any$3, E = never, R = never>(action: A, options: ManualEffectOptions<A["payload"], E, R>): Handler<A, E | VerificationFailed, Exclude<R, Scope.Scope>>;
|
|
364
|
+
declare namespace interaction_d_exports {
|
|
365
|
+
export { Answer, Any$1 as Any, Error, Interaction, PromiseOptions$1 as PromiseOptions, Request, Services$1 as Services, UnexpectedInteractionError, effect$2 as effect, isInteraction, promise$1 as promise };
|
|
366
|
+
}
|
|
367
|
+
/**
|
|
368
|
+
* What a person says about manual work. There is no other answer: free-form input never
|
|
369
|
+
* reaches a report.
|
|
370
|
+
*
|
|
371
|
+
* @since 0.2.0
|
|
372
|
+
*/
|
|
373
|
+
type Answer = "confirmed" | "declined";
|
|
374
|
+
/**
|
|
375
|
+
* A request to confirm manual work. The occurrence carries the action, its description,
|
|
376
|
+
* and the migration instruction that declared it, which is what to show the person.
|
|
377
|
+
*
|
|
378
|
+
* @since 0.2.0
|
|
273
379
|
*/
|
|
274
|
-
|
|
275
|
-
|
|
380
|
+
type Request<A extends Any$3 = Any$3> = {
|
|
381
|
+
readonly occurrence: Occurrence<A>;
|
|
382
|
+
};
|
|
383
|
+
declare const UnexpectedInteractionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
|
|
384
|
+
readonly _tag: "UnexpectedInteractionError";
|
|
385
|
+
} & Readonly<A>;
|
|
386
|
+
/**
|
|
387
|
+
* A Promise interaction rejected with a value that none of its declared error guards
|
|
388
|
+
* recognized (`rejected`), or an interaction answered with something other than
|
|
389
|
+
* `"confirmed"` or `"declined"` (`invalid-answer`). An invalid answer is never kept: it
|
|
390
|
+
* may be text that the person typed.
|
|
391
|
+
*
|
|
392
|
+
* @since 0.2.0
|
|
393
|
+
*/
|
|
394
|
+
declare class UnexpectedInteractionError extends UnexpectedInteractionError_base<{
|
|
395
|
+
readonly occurrenceId: string;
|
|
396
|
+
readonly reason: "rejected" | "invalid-answer";
|
|
397
|
+
/** The rejection. Always `undefined` for an invalid answer. */
|
|
398
|
+
readonly cause: unknown;
|
|
399
|
+
}> {
|
|
400
|
+
get message(): string;
|
|
401
|
+
}
|
|
402
|
+
declare const TypeId$1 = "~deltafold/Interaction";
|
|
403
|
+
/**
|
|
404
|
+
* Asks a person to confirm the manual work of a plan. The executor has no terminal or
|
|
405
|
+
* user interface of its own: the consumer running the plan supplies one of these.
|
|
406
|
+
*
|
|
407
|
+
* Parallel branches can ask at the same time. An interaction that owns one terminal
|
|
408
|
+
* serializes its own prompts. A failure or a decline elsewhere stops new actions but
|
|
409
|
+
* does not withdraw a request that was already made; only cancellation does.
|
|
410
|
+
*
|
|
411
|
+
* @since 0.2.0
|
|
412
|
+
*/
|
|
413
|
+
type Interaction<out E = never, out R = never> = {
|
|
414
|
+
readonly [TypeId$1]: typeof TypeId$1;
|
|
415
|
+
readonly confirm: (request: Request) => Effect.Effect<Answer, E, R>;
|
|
416
|
+
};
|
|
417
|
+
/**
|
|
418
|
+
* Any interaction.
|
|
419
|
+
*
|
|
420
|
+
* @since 0.2.0
|
|
421
|
+
*/
|
|
422
|
+
type Any$1 = Interaction<any, any>;
|
|
423
|
+
/**
|
|
424
|
+
* The errors of an interaction.
|
|
425
|
+
*
|
|
426
|
+
* @since 0.2.0
|
|
427
|
+
*/
|
|
428
|
+
type Error<I> = I extends Interaction<infer E, any> ? E : never;
|
|
429
|
+
/**
|
|
430
|
+
* The Effect services of an interaction.
|
|
431
|
+
*
|
|
432
|
+
* @since 0.2.0
|
|
433
|
+
*/
|
|
434
|
+
type Services$1<I> = I extends Interaction<any, infer R> ? R : never;
|
|
435
|
+
/** @since 0.2.0 */
|
|
436
|
+
declare const isInteraction: (value: unknown) => value is Any$1;
|
|
437
|
+
/** @since 0.2.0 */
|
|
438
|
+
type PromiseOptions$1<S extends ServiceMap$1, G extends ReadonlyArray<ErrorGuard$1>> = {
|
|
439
|
+
/** Effect services resolved for the callback and added to the run's requirements. */
|
|
440
|
+
readonly services?: S;
|
|
441
|
+
/** Guards for rejections that keep their own type. */
|
|
442
|
+
readonly errors?: G;
|
|
443
|
+
};
|
|
444
|
+
/**
|
|
445
|
+
* Confirms manual work with a Promise callback. It receives `{ signal, services }`: an
|
|
446
|
+
* `AbortSignal` that aborts when the run is cancelled, so it can stop asking, and the
|
|
447
|
+
* declared services.
|
|
448
|
+
*
|
|
449
|
+
* @example
|
|
450
|
+
* ```ts
|
|
451
|
+
* // The migration's instruction for this action, or the action's description.
|
|
452
|
+
* const textOf = ({ action, instruction }: Plan.Occurrence) =>
|
|
453
|
+
* instruction?.content
|
|
454
|
+
* .map((part) => (part._tag === "Text" ? part.text : part.action.description))
|
|
455
|
+
* .join("") ?? action.description;
|
|
456
|
+
*
|
|
457
|
+
* const interaction = Interaction.promise(async ({ occurrence }, { signal }) =>
|
|
458
|
+
* (await ask(textOf(occurrence), { signal })) ? "confirmed" : "declined",
|
|
459
|
+
* );
|
|
460
|
+
* ```
|
|
461
|
+
*
|
|
462
|
+
* @since 0.2.0
|
|
463
|
+
*/
|
|
464
|
+
declare const promise$1: <const S extends ServiceMap$1 = NoServices$1, const G extends ReadonlyArray<ErrorGuard$1> = []>(confirm: (request: Request, context: PromiseContext$1<S>) => PromiseLike<Answer>, options?: PromiseOptions$1<S, G>) => Interaction<GuardedError$1<G[number]> | UnexpectedInteractionError, ServiceIds$1<S>>;
|
|
465
|
+
/**
|
|
466
|
+
* Confirms manual work with an Effect, which keeps its own errors and services and
|
|
467
|
+
* stops through Effect interruption when the run is cancelled.
|
|
468
|
+
*
|
|
469
|
+
* @since 0.2.0
|
|
470
|
+
*/
|
|
471
|
+
declare const effect$2: <E = never, R = never>(confirm: (request: Request) => Effect.Effect<Answer, E, R>) => Interaction<E | UnexpectedInteractionError, R>;
|
|
472
|
+
declare namespace observer_d_exports {
|
|
473
|
+
export { ActionInfo, ActionPhaseStarted, ActionSettled, Any, Counts, Event, ObservationFailure, Observer, OutcomeSummary, Progress, Run, RunFinished, RunStarted, Services, StepInfo, StepSettled, StepStarted, effect$1 as effect, isObserver, promise, sync };
|
|
474
|
+
}
|
|
475
|
+
declare const TypeId = "~deltafold/Observer";
|
|
476
|
+
/**
|
|
477
|
+
* The run that emitted an event.
|
|
478
|
+
*
|
|
479
|
+
* @since 0.2.1
|
|
480
|
+
*/
|
|
481
|
+
type Run = {
|
|
482
|
+
/** The `runId` passed to the executor, if any. Shared observers use it to tell runs apart. */
|
|
483
|
+
readonly id: string | undefined;
|
|
484
|
+
readonly mode: Report["mode"];
|
|
485
|
+
readonly from: string;
|
|
486
|
+
readonly to: string;
|
|
487
|
+
readonly route: string;
|
|
488
|
+
};
|
|
489
|
+
/**
|
|
490
|
+
* Counters at the moment an event was emitted. Counters never decrease during a run.
|
|
491
|
+
*
|
|
492
|
+
* @since 0.2.1
|
|
493
|
+
*/
|
|
494
|
+
type Progress = {
|
|
495
|
+
/** Steps with actions and prose-only steps. Omitted steps are not counted. */
|
|
496
|
+
readonly steps: {
|
|
497
|
+
readonly total: number;
|
|
498
|
+
readonly finished: number;
|
|
499
|
+
};
|
|
500
|
+
readonly actions: {
|
|
501
|
+
readonly total: number;
|
|
502
|
+
/** Occurrences whose prepare or apply phase has started and that have not settled. */
|
|
503
|
+
readonly running: number;
|
|
504
|
+
readonly finished: number;
|
|
505
|
+
};
|
|
506
|
+
};
|
|
507
|
+
/**
|
|
508
|
+
* One step of the route, as observers see it.
|
|
509
|
+
*
|
|
510
|
+
* - `execute`: the step has actions after optimization.
|
|
511
|
+
* - `prose`: the step has instruction prose but no actions. The executor runs nothing
|
|
512
|
+
* for it and does not wait at it.
|
|
513
|
+
* - `omitted`: a noop, or a step whose actions rules removed or moved into another step.
|
|
514
|
+
*
|
|
515
|
+
* @since 0.2.1
|
|
516
|
+
*/
|
|
517
|
+
type StepInfo = {
|
|
518
|
+
/** The plan step's `id`. */
|
|
519
|
+
readonly id: string;
|
|
520
|
+
/** Position in `plan.steps`, including omitted steps. */
|
|
521
|
+
readonly index: number;
|
|
522
|
+
readonly migration: string;
|
|
523
|
+
readonly direction: Direction;
|
|
524
|
+
readonly from: string;
|
|
525
|
+
readonly to: string;
|
|
526
|
+
/** Occurrence identifiers of the step, in plan order. */
|
|
527
|
+
readonly occurrences: ReadonlyArray<string>;
|
|
528
|
+
/**
|
|
529
|
+
* Other steps whose declared actions this step's replacements stand for. Running this
|
|
530
|
+
* step performs work that those steps declared.
|
|
531
|
+
*/
|
|
532
|
+
readonly absorbs: ReadonlyArray<string>;
|
|
533
|
+
} & ({
|
|
534
|
+
readonly kind: "execute" | "prose";
|
|
535
|
+
} | {
|
|
536
|
+
readonly kind: "omitted";
|
|
537
|
+
readonly reason: "noop" | "all-actions-removed";
|
|
538
|
+
});
|
|
539
|
+
/**
|
|
540
|
+
* One occurrence of the plan, as observers see it.
|
|
541
|
+
*
|
|
542
|
+
* @since 0.2.1
|
|
543
|
+
*/
|
|
544
|
+
type ActionInfo = {
|
|
545
|
+
readonly occurrence: string;
|
|
546
|
+
readonly action: string;
|
|
547
|
+
readonly kind: string;
|
|
548
|
+
readonly description: string;
|
|
549
|
+
readonly migration: string;
|
|
550
|
+
readonly direction: Direction;
|
|
551
|
+
/** The step that runs the occurrence. */
|
|
552
|
+
readonly step: string;
|
|
553
|
+
readonly origin: {
|
|
554
|
+
readonly _tag: "Declared";
|
|
555
|
+
} | {
|
|
556
|
+
readonly _tag: "Replacement";
|
|
557
|
+
readonly rule: string;
|
|
558
|
+
/** Identifiers of the replaced occurrences, in order. */
|
|
559
|
+
readonly replaces: ReadonlyArray<string>;
|
|
560
|
+
};
|
|
561
|
+
/** Steps that declared the actions behind this occurrence, in plan order. */
|
|
562
|
+
readonly sources: ReadonlyArray<string>;
|
|
563
|
+
};
|
|
564
|
+
/**
|
|
565
|
+
* An outcome as observers see it. Each variant lists its fields explicitly, so a field
|
|
566
|
+
* added to the report's outcome never reaches observers unreviewed. A failure keeps only
|
|
567
|
+
* the error's string `_tag`; the full error is in the execution's report.
|
|
568
|
+
*
|
|
569
|
+
* @since 0.2.1
|
|
570
|
+
*/
|
|
571
|
+
type OutcomeSummary = {
|
|
572
|
+
readonly _tag: "Completed";
|
|
573
|
+
readonly performer: "automated";
|
|
574
|
+
} | {
|
|
575
|
+
readonly _tag: "Completed";
|
|
576
|
+
readonly performer: "manual";
|
|
577
|
+
readonly confirmation: "asserted" | "verified";
|
|
578
|
+
} | {
|
|
579
|
+
readonly _tag: "Skipped";
|
|
580
|
+
readonly reason: string;
|
|
581
|
+
} | {
|
|
582
|
+
readonly _tag: "Declined";
|
|
583
|
+
} | {
|
|
584
|
+
readonly _tag: "Failed";
|
|
585
|
+
readonly phase: Phase;
|
|
586
|
+
readonly errorTag: string | undefined;
|
|
587
|
+
} | {
|
|
588
|
+
readonly _tag: "Interrupted";
|
|
589
|
+
readonly phase: Phase;
|
|
590
|
+
readonly reason: InterruptReason;
|
|
591
|
+
readonly settled: boolean;
|
|
592
|
+
} | {
|
|
593
|
+
readonly _tag: "Unattempted";
|
|
594
|
+
} | {
|
|
595
|
+
readonly _tag: "WouldExecute";
|
|
596
|
+
readonly evaluated: boolean;
|
|
597
|
+
readonly performer: Performer;
|
|
598
|
+
} | {
|
|
599
|
+
readonly _tag: "WouldSkip";
|
|
600
|
+
readonly reason: string;
|
|
601
|
+
} | {
|
|
602
|
+
readonly _tag: "Undetermined";
|
|
603
|
+
readonly reason: string;
|
|
604
|
+
readonly performer: Performer;
|
|
605
|
+
} | {
|
|
606
|
+
readonly _tag: "PreparationFailed";
|
|
607
|
+
readonly errorTag: string | undefined;
|
|
608
|
+
};
|
|
609
|
+
/**
|
|
610
|
+
* Occurrences by outcome tag. `unsettled` counts interrupted occurrences that may still be
|
|
611
|
+
* running.
|
|
612
|
+
*
|
|
613
|
+
* @since 0.2.1
|
|
614
|
+
*/
|
|
615
|
+
type Counts = { readonly [K in Outcome["_tag"]]: number; } & {
|
|
616
|
+
readonly unsettled: number;
|
|
617
|
+
};
|
|
618
|
+
type Base = {
|
|
619
|
+
readonly run: Run;
|
|
620
|
+
/** Position of the event in its run, starting at 0. */
|
|
621
|
+
readonly seq: number;
|
|
622
|
+
/** Milliseconds since the Unix epoch, from Effect's `Clock`. */
|
|
623
|
+
readonly timestamp: number;
|
|
624
|
+
readonly progress: Progress;
|
|
625
|
+
};
|
|
626
|
+
/**
|
|
627
|
+
* The run is starting: every action has a handler, and manual work has an interaction to
|
|
628
|
+
* ask with. A run that fails either check emits no events. Lists every step of the route,
|
|
629
|
+
* including omitted ones.
|
|
630
|
+
*
|
|
631
|
+
* @since 0.2.1
|
|
632
|
+
*/
|
|
633
|
+
type RunStarted = Base & {
|
|
634
|
+
readonly _tag: "RunStarted";
|
|
635
|
+
readonly steps: ReadonlyArray<StepInfo>;
|
|
636
|
+
};
|
|
637
|
+
/** @since 0.2.1 */
|
|
638
|
+
type StepStarted = Base & {
|
|
639
|
+
readonly _tag: "StepStarted";
|
|
640
|
+
readonly step: StepInfo;
|
|
641
|
+
};
|
|
642
|
+
/**
|
|
643
|
+
* A phase of an occurrence started: its prepare or apply phase, the confirmation of
|
|
644
|
+
* manual work, or its verification. `prepare` appears only for handlers that have a
|
|
645
|
+
* prepare phase. `confirmation` means the run is waiting for a person. An occurrence
|
|
646
|
+
* emits this once per phase that starts.
|
|
647
|
+
*
|
|
648
|
+
* @since 0.2.1
|
|
649
|
+
*/
|
|
650
|
+
type ActionPhaseStarted = Base & {
|
|
651
|
+
readonly _tag: "ActionPhaseStarted";
|
|
652
|
+
readonly action: ActionInfo;
|
|
653
|
+
readonly phase: Phase;
|
|
654
|
+
};
|
|
655
|
+
/**
|
|
656
|
+
* An occurrence has its final outcome. Emitted once for each occurrence whose outcome is
|
|
657
|
+
* known, and as `Unattempted` for an occurrence that started but stopped before applying
|
|
658
|
+
* or asking. It arrives after the occurrence's scope has closed, except when an
|
|
659
|
+
* interrupted Promise has not settled: then the scope stays open until it does, the
|
|
660
|
+
* reported outcome is already final, and a later cleanup failure is only logged. Dry-run
|
|
661
|
+
* outcomes that need no prepare phase arrive without a start.
|
|
662
|
+
*
|
|
663
|
+
* @since 0.2.1
|
|
664
|
+
*/
|
|
665
|
+
type ActionSettled = Base & {
|
|
666
|
+
readonly _tag: "ActionSettled";
|
|
667
|
+
readonly action: ActionInfo;
|
|
668
|
+
readonly outcome: OutcomeSummary;
|
|
669
|
+
};
|
|
670
|
+
/**
|
|
671
|
+
* A started step ended. `counts` covers the step's occurrences.
|
|
672
|
+
*
|
|
673
|
+
* @since 0.2.1
|
|
674
|
+
*/
|
|
675
|
+
type StepSettled = Base & {
|
|
676
|
+
readonly _tag: "StepSettled";
|
|
677
|
+
readonly step: StepInfo;
|
|
678
|
+
readonly counts: Counts;
|
|
679
|
+
};
|
|
680
|
+
/**
|
|
681
|
+
* The run ended. `status` and `counts` match the execution's report. When the fiber of
|
|
682
|
+
* `Executor.effect` is interrupted, there is no report: `report` is `false`, the status is
|
|
683
|
+
* `"interrupted"`, and running occurrences count as unsettled interruptions. If the
|
|
684
|
+
* interruption cuts short the delivery of `RunFinished`, the observers that had not yet
|
|
685
|
+
* received it get the report-less one with the same `seq`, so each observer receives
|
|
686
|
+
* exactly one.
|
|
687
|
+
*
|
|
688
|
+
* @since 0.2.1
|
|
689
|
+
*/
|
|
690
|
+
type RunFinished = Base & {
|
|
691
|
+
readonly _tag: "RunFinished";
|
|
692
|
+
readonly status: Report["status"];
|
|
693
|
+
readonly counts: Counts;
|
|
694
|
+
readonly report: boolean;
|
|
695
|
+
};
|
|
696
|
+
/**
|
|
697
|
+
* What an observer receives. A run emits `RunStarted`; then, for each step that is not
|
|
698
|
+
* omitted, `StepStarted`, an `ActionPhaseStarted` for each phase that starts, an
|
|
699
|
+
* `ActionSettled` for each occurrence, and `StepSettled`; and finally `RunFinished`. Action
|
|
700
|
+
* events of parallel branches interleave.
|
|
701
|
+
*
|
|
702
|
+
* Events carry identifiers and plain data, never payloads, errors, or causes. Action
|
|
703
|
+
* descriptions are included, so they must not contain secrets.
|
|
704
|
+
*
|
|
705
|
+
* @since 0.2.1
|
|
706
|
+
*/
|
|
707
|
+
type Event = RunStarted | StepStarted | ActionPhaseStarted | ActionSettled | StepSettled | RunFinished;
|
|
708
|
+
/**
|
|
709
|
+
* An observer that failed, or that was abandoned after cancellation or a timeout because
|
|
710
|
+
* it did not finish within the settlement grace period. An abandoned callback is
|
|
711
|
+
* interrupted but not awaited, so one that cannot be interrupted may keep running. The
|
|
712
|
+
* cause can hold arbitrary values, so do not serialize it as a whole.
|
|
713
|
+
*
|
|
714
|
+
* @since 0.2.1
|
|
715
|
+
*/
|
|
716
|
+
type ObservationFailure = {
|
|
717
|
+
/** Position of the observer in the `observers` array. */
|
|
718
|
+
readonly observer: number;
|
|
719
|
+
readonly event: Event["_tag"];
|
|
720
|
+
readonly seq: number;
|
|
721
|
+
readonly reason: "failed" | "abandoned";
|
|
722
|
+
readonly cause: Cause.Cause<unknown>;
|
|
723
|
+
};
|
|
724
|
+
/**
|
|
725
|
+
* Receives the events of a run. Pass observers to the executor's `observers` option. `R`
|
|
726
|
+
* is the Effect services an observer requires, which become requirements of the execution.
|
|
727
|
+
*
|
|
728
|
+
* The executor delivers one event at a time, to each observer in array order, and waits
|
|
729
|
+
* for each delivery before it continues, so every observer sees the same order. After
|
|
730
|
+
* cancellation or a timeout, each delivery waits at most `settleTimeout` and is then
|
|
731
|
+
* abandoned. A failed or abandoned delivery is listed in the report's `observation` and
|
|
732
|
+
* never changes an outcome. Observers only receive events: they cannot answer a manual
|
|
733
|
+
* confirmation.
|
|
734
|
+
*
|
|
735
|
+
* @since 0.2.1
|
|
736
|
+
*/
|
|
737
|
+
type Observer<out R = never> = {
|
|
738
|
+
readonly [TypeId]: typeof TypeId;
|
|
739
|
+
/** Delivers one event and captures how the delivery ended. It never fails. */
|
|
740
|
+
readonly notify: (event: Event) => Effect.Effect<Exit.Exit<unknown, unknown>, never, R>;
|
|
741
|
+
};
|
|
742
|
+
/**
|
|
743
|
+
* Any observer.
|
|
744
|
+
*
|
|
745
|
+
* @since 0.2.1
|
|
746
|
+
*/
|
|
747
|
+
type Any = Observer<any>;
|
|
748
|
+
/**
|
|
749
|
+
* The Effect services of an observer or a union of observers.
|
|
750
|
+
*
|
|
751
|
+
* @since 0.2.1
|
|
752
|
+
*/
|
|
753
|
+
type Services<O> = O extends Observer<infer R> ? R : never;
|
|
754
|
+
/** @since 0.2.1 */
|
|
755
|
+
declare const isObserver: (value: unknown) => value is Any;
|
|
756
|
+
/**
|
|
757
|
+
* Observes with a synchronous callback. A thrown value is recorded as an observation
|
|
758
|
+
* failure.
|
|
759
|
+
*
|
|
760
|
+
* @example
|
|
761
|
+
* ```ts
|
|
762
|
+
* Observer.sync((event) => {
|
|
763
|
+
* if (event._tag === "ActionSettled") console.error(event.action.occurrence, event.outcome._tag);
|
|
764
|
+
* });
|
|
765
|
+
* ```
|
|
766
|
+
*
|
|
767
|
+
* @since 0.2.1
|
|
768
|
+
*/
|
|
769
|
+
declare const sync: (callback: (event: Event) => void) => Observer;
|
|
770
|
+
/**
|
|
771
|
+
* Observes with a Promise callback. The executor waits for the Promise. The `signal`
|
|
772
|
+
* aborts when the executor stops waiting: after cancellation or a timeout, once the
|
|
773
|
+
* settlement grace period has passed, or when the execution is interrupted. A services
|
|
774
|
+
* layer that `Executor.runPromise` built stays open until an abandoned Promise settles.
|
|
775
|
+
*
|
|
776
|
+
* @since 0.2.1
|
|
777
|
+
*/
|
|
778
|
+
declare const promise: (callback: (event: Event, context: {
|
|
779
|
+
readonly signal: AbortSignal;
|
|
780
|
+
}) => PromiseLike<unknown>) => Observer;
|
|
781
|
+
/**
|
|
782
|
+
* Observes with an Effect. Its services become requirements of the execution. Its
|
|
783
|
+
* failures are recorded as observation failures and never fail the execution.
|
|
784
|
+
*
|
|
785
|
+
* @example
|
|
786
|
+
* ```ts
|
|
787
|
+
* Observer.effect((event) => Effect.logDebug(event._tag));
|
|
788
|
+
* ```
|
|
789
|
+
*
|
|
790
|
+
* @since 0.2.1
|
|
791
|
+
*/
|
|
792
|
+
declare const effect$1: <E = never, R = never>(callback: (event: Event) => Effect.Effect<unknown, E, R>) => Observer<R>;
|
|
276
793
|
declare namespace executor_d_exports {
|
|
277
|
-
export { CoverageIssue, Errors, ExecutionError, ExecutionFailed, ExecutionInterrupted, HandlerCoverageError, InterruptReason, OccurrenceReport, Options, Outcome, PromiseOptions, Report, Requirements, Uncovered, effect, runPromise };
|
|
794
|
+
export { CoverageIssue, Errors, ExecutionError, ExecutionFailed, ExecutionInterrupted, HandlerCoverageError, InteractionUnavailable, InterruptReason, OccurrenceReport, Options, Outcome, PromiseOptions, Report, Requirements, Uncovered, effect, runPromise };
|
|
278
795
|
}
|
|
279
796
|
/**
|
|
280
797
|
* What happened to one occurrence, or what a dry run predicts.
|
|
281
798
|
*
|
|
282
|
-
* @since
|
|
799
|
+
* @since 0.0.1
|
|
283
800
|
*/
|
|
284
801
|
type Outcome<E = unknown> = {
|
|
285
802
|
readonly _tag: "Completed";
|
|
803
|
+
readonly performer: "automated";
|
|
804
|
+
} | {
|
|
805
|
+
readonly _tag: "Completed";
|
|
806
|
+
readonly performer: "manual";
|
|
807
|
+
/**
|
|
808
|
+
* What supports completion. `asserted`: the person said so and nothing checked
|
|
809
|
+
* it. `verified`: the person said so and the handler's `verify` check passed.
|
|
810
|
+
* Neither proves how the work was done.
|
|
811
|
+
*/
|
|
812
|
+
readonly confirmation: "asserted" | "verified";
|
|
286
813
|
} | {
|
|
287
814
|
readonly _tag: "Skipped";
|
|
288
815
|
readonly reason: string;
|
|
816
|
+
} |
|
|
817
|
+
/** The person asked to confirm manual work answered that it is not done. */
|
|
818
|
+
{
|
|
819
|
+
readonly _tag: "Declined";
|
|
289
820
|
} | {
|
|
290
821
|
readonly _tag: "Failed";
|
|
291
822
|
readonly phase: Phase;
|
|
@@ -308,28 +839,34 @@ type Outcome<E = unknown> = {
|
|
|
308
839
|
{
|
|
309
840
|
readonly _tag: "Unattempted";
|
|
310
841
|
} |
|
|
311
|
-
/**
|
|
842
|
+
/**
|
|
843
|
+
* `evaluated`: whether a prepare phase ran and decided to apply. A `manual` occurrence
|
|
844
|
+
* would wait for a person; a dry run never asks.
|
|
845
|
+
*/
|
|
312
846
|
{
|
|
313
847
|
readonly _tag: "WouldExecute";
|
|
314
848
|
readonly evaluated: boolean;
|
|
849
|
+
readonly performer: Performer;
|
|
315
850
|
} | {
|
|
316
851
|
readonly _tag: "WouldSkip";
|
|
317
852
|
readonly reason: string;
|
|
318
853
|
} | {
|
|
319
854
|
readonly _tag: "Undetermined";
|
|
320
855
|
readonly reason: string;
|
|
856
|
+
/** A `manual` occurrence would wait for a person if it executes. */
|
|
857
|
+
readonly performer: Performer;
|
|
321
858
|
} | {
|
|
322
859
|
readonly _tag: "PreparationFailed";
|
|
323
860
|
readonly error: E | undefined;
|
|
324
861
|
readonly cause: Cause.Cause<E>;
|
|
325
862
|
};
|
|
326
|
-
/** @since
|
|
327
|
-
type OccurrenceReport<A extends Any$
|
|
863
|
+
/** @since 0.0.1 */
|
|
864
|
+
type OccurrenceReport<A extends Any$3 = Any$3, E = unknown> = {
|
|
328
865
|
readonly occurrence: Occurrence<A>;
|
|
329
866
|
readonly outcome: Outcome<E>;
|
|
330
867
|
};
|
|
331
|
-
/** @since
|
|
332
|
-
type Report<A extends Any$
|
|
868
|
+
/** @since 0.0.1 */
|
|
869
|
+
type Report<A extends Any$3 = Any$3, E = unknown> = {
|
|
333
870
|
readonly _tag: "Report";
|
|
334
871
|
readonly mode: "execute" | "dry-run";
|
|
335
872
|
readonly status: "completed" | "failed" | "interrupted" | "not-started" | "would-complete" | "would-fail";
|
|
@@ -339,17 +876,19 @@ type Report<A extends Any$1 = Any$1, E = unknown> = {
|
|
|
339
876
|
/** Every occurrence in plan order. */
|
|
340
877
|
readonly occurrences: ReadonlyArray<OccurrenceReport<A, E>>;
|
|
341
878
|
/**
|
|
342
|
-
* Whether any apply phase started
|
|
343
|
-
* state.
|
|
879
|
+
* Whether any apply phase started or any person was asked to do manual work. Either
|
|
880
|
+
* may have partially changed state.
|
|
344
881
|
*/
|
|
345
882
|
readonly bodiesStarted: boolean;
|
|
346
883
|
/** Progress is not persisted. Rerunning the plan repeats completed actions. */
|
|
347
884
|
readonly persistence: "none";
|
|
885
|
+
/** Observers that failed or were abandoned. Never affects outcomes or status. */
|
|
886
|
+
readonly observation: ReadonlyArray<ObservationFailure>;
|
|
348
887
|
};
|
|
349
888
|
/**
|
|
350
889
|
* A handler is missing, duplicated, or bound to a different definition.
|
|
351
890
|
*
|
|
352
|
-
* @since
|
|
891
|
+
* @since 0.0.1
|
|
353
892
|
*/
|
|
354
893
|
type CoverageIssue = {
|
|
355
894
|
readonly _tag: "Missing" | "Duplicate" | "Mismatched";
|
|
@@ -374,24 +913,43 @@ declare const HandlerCoverageBase: new <A extends Record<string, any> = {}>(args
|
|
|
374
913
|
* For an occurrence that a rule produced, the issue names the rule and the occurrences
|
|
375
914
|
* it replaced.
|
|
376
915
|
*
|
|
377
|
-
* @since
|
|
916
|
+
* @since 0.0.1
|
|
378
917
|
*/
|
|
379
|
-
declare class HandlerCoverageError<A extends Any$
|
|
918
|
+
declare class HandlerCoverageError<A extends Any$3 = Any$3> extends HandlerCoverageBase<{
|
|
380
919
|
readonly issues: ReadonlyArray<CoverageIssue>;
|
|
381
920
|
readonly report: Report<A, never>;
|
|
382
921
|
}> {
|
|
383
922
|
get message(): string;
|
|
384
923
|
}
|
|
924
|
+
declare const InteractionUnavailableBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
|
|
925
|
+
readonly _tag: "InteractionUnavailable";
|
|
926
|
+
} & Readonly<A>;
|
|
927
|
+
/**
|
|
928
|
+
* The plan has manual handlers, and the run has no `interaction` to ask a person. The
|
|
929
|
+
* run fails before any handler phase or prompt.
|
|
930
|
+
*
|
|
931
|
+
* @since 0.2.0
|
|
932
|
+
*/
|
|
933
|
+
declare class InteractionUnavailable<A extends Any$3 = Any$3> extends InteractionUnavailableBase<{
|
|
934
|
+
/** The occurrences that a manual handler covers, in plan order. */
|
|
935
|
+
readonly occurrences: ReadonlyArray<Occurrence<A>>;
|
|
936
|
+
readonly report: Report<A, never>;
|
|
937
|
+
}> {
|
|
938
|
+
get message(): string;
|
|
939
|
+
}
|
|
385
940
|
declare const ExecutionFailedBase: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
|
|
386
941
|
readonly _tag: "ExecutionFailed";
|
|
387
942
|
} & Readonly<A>;
|
|
388
943
|
/**
|
|
389
|
-
* An occurrence failed
|
|
944
|
+
* An occurrence failed, or a person declined manual work. Execution stopped admitting
|
|
945
|
+
* new actions; started ones settled.
|
|
390
946
|
*
|
|
391
|
-
* @since
|
|
947
|
+
* @since 0.0.1
|
|
392
948
|
*/
|
|
393
|
-
declare class ExecutionFailed<A extends Any$
|
|
949
|
+
declare class ExecutionFailed<A extends Any$3 = Any$3, E = unknown> extends ExecutionFailedBase<{
|
|
394
950
|
readonly failures: ReadonlyArray<OccurrenceReport<A, E>>;
|
|
951
|
+
/** Manual occurrences that a person declined. */
|
|
952
|
+
readonly declined: ReadonlyArray<OccurrenceReport<A, E>>;
|
|
395
953
|
readonly report: Report<A, E>;
|
|
396
954
|
}> {
|
|
397
955
|
get message(): string;
|
|
@@ -403,49 +961,64 @@ declare const ExecutionInterruptedBase: new <A extends Record<string, any> = {}>
|
|
|
403
961
|
* Why an execution or an occurrence was interrupted: explicit cancellation, a configured
|
|
404
962
|
* timeout, or an Effect handler that interrupted itself.
|
|
405
963
|
*
|
|
406
|
-
* @since
|
|
964
|
+
* @since 0.0.1
|
|
407
965
|
*/
|
|
408
966
|
type InterruptReason = "cancelled" | "timeout" | "handler";
|
|
409
967
|
/**
|
|
410
968
|
* Explicit cancellation, a configured timeout, or a handler's own interruption stopped
|
|
411
969
|
* execution.
|
|
412
970
|
*
|
|
413
|
-
* @since
|
|
971
|
+
* @since 0.0.1
|
|
414
972
|
*/
|
|
415
|
-
declare class ExecutionInterrupted<A extends Any$
|
|
973
|
+
declare class ExecutionInterrupted<A extends Any$3 = Any$3, E = unknown> extends ExecutionInterruptedBase<{
|
|
416
974
|
readonly reason: InterruptReason;
|
|
417
975
|
readonly report: Report<A, E>;
|
|
418
976
|
}> {
|
|
419
977
|
get message(): string;
|
|
420
978
|
}
|
|
421
|
-
/** @since
|
|
422
|
-
type ExecutionError<A extends Any$
|
|
979
|
+
/** @since 0.0.1 */
|
|
980
|
+
type ExecutionError<A extends Any$3, E> = HandlerCoverageError<A> | InteractionUnavailable<A> | ExecutionFailed<A, E> | ExecutionInterrupted<A, E>;
|
|
423
981
|
/**
|
|
424
982
|
* Action identifiers of a statically covered plan that no handler in the array
|
|
425
983
|
* implements.
|
|
426
984
|
*
|
|
427
|
-
* @since
|
|
985
|
+
* @since 0.0.1
|
|
428
986
|
*/
|
|
429
|
-
type Uncovered<A extends Any$
|
|
987
|
+
type Uncovered<A extends Any$3, H, C extends Coverage> = "runtime" extends C ? never : A extends Any$3 ? string extends A["id"] ? never : A["id"] extends ActionId<H> ? never : A["id"] : never;
|
|
430
988
|
/** Rejects a handler array that leaves statically known actions uncovered, naming them. */
|
|
431
|
-
type CoverageCheck<A extends Any$
|
|
989
|
+
type CoverageCheck<A extends Any$3, H, C extends Coverage> = [Uncovered<A, H, C>] extends [never] ? unknown : {
|
|
432
990
|
readonly handlers: `Missing a handler for action "${Uncovered<A, H, C>}"`;
|
|
433
991
|
};
|
|
434
992
|
/**
|
|
435
993
|
* Errors an execution can report for its occurrences.
|
|
436
994
|
*
|
|
437
|
-
* @since
|
|
995
|
+
* @since 0.0.1
|
|
438
996
|
*/
|
|
439
|
-
type Errors<H> = Error<H>;
|
|
997
|
+
type Errors<H, I = never> = Error$1<H> | Error<I>;
|
|
440
998
|
/**
|
|
441
|
-
* Effect services an execution requires: the services of its handlers
|
|
999
|
+
* Effect services an execution requires: the services of its handlers, its
|
|
1000
|
+
* interaction, and its observers.
|
|
442
1001
|
*
|
|
443
|
-
* @since
|
|
1002
|
+
* @since 0.0.1
|
|
444
1003
|
*/
|
|
445
|
-
type Requirements<H> = Services<H>;
|
|
446
|
-
/** @since
|
|
447
|
-
type Options<H extends Any> = {
|
|
1004
|
+
type Requirements<H, I = never, O = never> = Services$2<H> | Services$1<I> | Services<O>;
|
|
1005
|
+
/** @since 0.0.1 */
|
|
1006
|
+
type Options<H extends Any$2, I extends Any$1 = never, O extends Any = never> = {
|
|
448
1007
|
readonly handlers?: ReadonlyArray<H>;
|
|
1008
|
+
/**
|
|
1009
|
+
* Asks a person to confirm the work of manual handlers. A run whose plan has manual
|
|
1010
|
+
* handlers fails with `InteractionUnavailable` before it starts when this is absent.
|
|
1011
|
+
* A dry run never asks and does not need it.
|
|
1012
|
+
*/
|
|
1013
|
+
readonly interaction?: I;
|
|
1014
|
+
/**
|
|
1015
|
+
* Receive the run's events, in array order. The executor waits for each observer
|
|
1016
|
+
* before it continues; an observer failure is recorded in `report.observation` and never changes
|
|
1017
|
+
* the outcome.
|
|
1018
|
+
*/
|
|
1019
|
+
readonly observers?: ReadonlyArray<O>;
|
|
1020
|
+
/** Identifies the run in observer events. */
|
|
1021
|
+
readonly runId?: string;
|
|
449
1022
|
/**
|
|
450
1023
|
* Run prepare phases without running any apply phase. A prepare phase that may
|
|
451
1024
|
* depend on an earlier action is reported `Undetermined`, because the dry run does
|
|
@@ -454,8 +1027,10 @@ type Options<H extends Any> = {
|
|
|
454
1027
|
readonly dryRun?: boolean;
|
|
455
1028
|
/**
|
|
456
1029
|
* Limit for each phase of an occurrence: the prepare phase and the apply phase each
|
|
457
|
-
* get the full limit
|
|
458
|
-
* ones. It applies to dry-run prepare
|
|
1030
|
+
* get the full limit, and so does the verification of manual work. Exceeding it
|
|
1031
|
+
* interrupts that action and stops admitting new ones. It applies to dry-run prepare
|
|
1032
|
+
* phases too. It never limits the wait for a person to confirm manual work; cancel
|
|
1033
|
+
* the run to end that wait.
|
|
459
1034
|
*/
|
|
460
1035
|
readonly timeout?: Duration.Input;
|
|
461
1036
|
/**
|
|
@@ -465,7 +1040,8 @@ type Options<H extends Any> = {
|
|
|
465
1040
|
readonly settleTimeout?: Duration.Input;
|
|
466
1041
|
};
|
|
467
1042
|
/**
|
|
468
|
-
* Runs a plan as an Effect. Coverage
|
|
1043
|
+
* Runs a plan as an Effect. Coverage, and the interaction that manual handlers need,
|
|
1044
|
+
* are checked before any handler phase runs. Steps
|
|
469
1045
|
* are sequential barriers; parallel groups run their branches concurrently. On failure,
|
|
470
1046
|
* no new action starts, and actions already running settle before the effect fails
|
|
471
1047
|
* with the partial report.
|
|
@@ -477,29 +1053,32 @@ type Options<H extends Any> = {
|
|
|
477
1053
|
*
|
|
478
1054
|
* To cancel, interrupt the fiber. Interruption reaches running actions and aborts the
|
|
479
1055
|
* signal passed to Promise callbacks. The effect then ends as interrupted, without a
|
|
480
|
-
* report.
|
|
1056
|
+
* report. Observers receive a final `RunFinished` event without a report, delivered
|
|
1057
|
+
* within `settleTimeout`.
|
|
481
1058
|
*
|
|
482
|
-
* @since
|
|
1059
|
+
* @since 0.0.1
|
|
483
1060
|
*/
|
|
484
|
-
declare const effect: <A extends Any$
|
|
1061
|
+
declare const effect: <A extends Any$3, C extends Coverage, H extends Any$2 = never, I extends Any$1 = never, O extends Any = never>(plan: Plan<A, C>, options: Options<H, I, O> & CoverageCheck<A, H, C>) => Effect.Effect<Report<A, Errors<H, I>>, ExecutionError<A, Errors<H, I>>, Requirements<H, I, O>>;
|
|
485
1062
|
type ServicesOption<R, LE> = [R] extends [never] ? {
|
|
486
|
-
/** Handlers without Effect services need none. */
|
|
1063
|
+
/** Handlers, interactions, and observers without Effect services need none. */
|
|
487
1064
|
readonly services?: Context.Context<never> | Layer.Layer<never, LE>;
|
|
488
1065
|
} : {
|
|
489
|
-
/** Supplies the handlers
|
|
1066
|
+
/** Supplies the Effect services of the handlers, the interaction, and the observers. */
|
|
490
1067
|
readonly services: Context.Context<R> | Layer.Layer<R, LE>;
|
|
491
1068
|
};
|
|
492
|
-
/** @since
|
|
493
|
-
type PromiseOptions<H extends Any> = Options<H> & {
|
|
1069
|
+
/** @since 0.0.1 */
|
|
1070
|
+
type PromiseOptions<H extends Any$2, I extends Any$1 = never, O extends Any = never> = Options<H, I, O> & {
|
|
494
1071
|
/**
|
|
495
|
-
* Explicit cancellation. Aborting stops admission, interrupts running actions
|
|
496
|
-
* rejects with `ExecutionInterrupted` and the partial
|
|
1072
|
+
* Explicit cancellation. Aborting stops admission, interrupts running actions and
|
|
1073
|
+
* pending confirmations, and rejects with `ExecutionInterrupted` and the partial
|
|
1074
|
+
* report.
|
|
497
1075
|
*/
|
|
498
1076
|
readonly signal?: AbortSignal;
|
|
499
1077
|
};
|
|
500
1078
|
/**
|
|
501
1079
|
* Runs a plan and returns a Promise. It rejects with `HandlerCoverageError`,
|
|
502
|
-
* `ExecutionFailed`, or `ExecutionInterrupted`, each carrying
|
|
1080
|
+
* `InteractionUnavailable`, `ExecutionFailed`, or `ExecutionInterrupted`, each carrying
|
|
1081
|
+
* the partial report.
|
|
503
1082
|
* Building a supplied services layer can also reject with the layer's own error,
|
|
504
1083
|
* without a report.
|
|
505
1084
|
*
|
|
@@ -510,8 +1089,8 @@ type PromiseOptions<H extends Any> = Options<H> & {
|
|
|
510
1089
|
* until it settles, possibly forever, and close in that order. A cleanup failure after
|
|
511
1090
|
* the Promise resolved is logged through Effect.
|
|
512
1091
|
*
|
|
513
|
-
* @since
|
|
1092
|
+
* @since 0.0.1
|
|
514
1093
|
*/
|
|
515
|
-
declare const runPromise: <A extends Any$
|
|
516
|
-
export { action_d_exports as Action, change_d_exports as Change, executor_d_exports as Executor, handler_d_exports as Handler, history_d_exports as History, migration_d_exports as Migration, package_d_exports as Package, plan_d_exports as Plan, rule_d_exports as Rule, shortcut_d_exports as Shortcut, version_d_exports as Version };
|
|
1094
|
+
declare const runPromise: <A extends Any$3, C extends Coverage, H extends Any$2 = never, I extends Any$1 = never, LE = never, O extends Any = never>(plan: Plan<A, C>, options: PromiseOptions<H, I, O> & ServicesOption<Requirements<H, I, O>, LE> & CoverageCheck<A, H, C>) => Promise<Report<A, Errors<H, I>>>;
|
|
1095
|
+
export { action_d_exports as Action, change_d_exports as Change, executor_d_exports as Executor, handler_d_exports as Handler, history_d_exports as History, interaction_d_exports as Interaction, migration_d_exports as Migration, observer_d_exports as Observer, package_d_exports as Package, plan_d_exports as Plan, rule_d_exports as Rule, shortcut_d_exports as Shortcut, version_d_exports as Version };
|
|
517
1096
|
//# sourceMappingURL=index.d.ts.map
|