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
|
@@ -0,0 +1,395 @@
|
|
|
1
|
+
import { type Cause, Effect, Exit, Predicate } from "effect";
|
|
2
|
+
|
|
3
|
+
import type * as Plan from "../../foundation/plan.ts";
|
|
4
|
+
import type { InterruptReason, Outcome, Report } from "./executor.ts";
|
|
5
|
+
import type { Performer, Phase } from "./handler.ts";
|
|
6
|
+
|
|
7
|
+
const TypeId = "~deltafold/Observer";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* The run that emitted an event.
|
|
11
|
+
*
|
|
12
|
+
* @since 0.2.1
|
|
13
|
+
*/
|
|
14
|
+
export type Run = {
|
|
15
|
+
/** The `runId` passed to the executor, if any. Shared observers use it to tell runs apart. */
|
|
16
|
+
readonly id: string | undefined;
|
|
17
|
+
readonly mode: Report["mode"];
|
|
18
|
+
readonly from: string;
|
|
19
|
+
readonly to: string;
|
|
20
|
+
readonly route: string;
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Counters at the moment an event was emitted. Counters never decrease during a run.
|
|
25
|
+
*
|
|
26
|
+
* @since 0.2.1
|
|
27
|
+
*/
|
|
28
|
+
export type Progress = {
|
|
29
|
+
/** Steps with actions and prose-only steps. Omitted steps are not counted. */
|
|
30
|
+
readonly steps: { readonly total: number; readonly finished: number };
|
|
31
|
+
readonly actions: {
|
|
32
|
+
readonly total: number;
|
|
33
|
+
/** Occurrences whose prepare or apply phase has started and that have not settled. */
|
|
34
|
+
readonly running: number;
|
|
35
|
+
readonly finished: number;
|
|
36
|
+
};
|
|
37
|
+
};
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* One step of the route, as observers see it.
|
|
41
|
+
*
|
|
42
|
+
* - `execute`: the step has actions after optimization.
|
|
43
|
+
* - `prose`: the step has instruction prose but no actions. The executor runs nothing
|
|
44
|
+
* for it and does not wait at it.
|
|
45
|
+
* - `omitted`: a noop, or a step whose actions rules removed or moved into another step.
|
|
46
|
+
*
|
|
47
|
+
* @since 0.2.1
|
|
48
|
+
*/
|
|
49
|
+
export type StepInfo = {
|
|
50
|
+
/** The plan step's `id`. */
|
|
51
|
+
readonly id: string;
|
|
52
|
+
/** Position in `plan.steps`, including omitted steps. */
|
|
53
|
+
readonly index: number;
|
|
54
|
+
readonly migration: string;
|
|
55
|
+
readonly direction: Plan.Direction;
|
|
56
|
+
readonly from: string;
|
|
57
|
+
readonly to: string;
|
|
58
|
+
/** Occurrence identifiers of the step, in plan order. */
|
|
59
|
+
readonly occurrences: ReadonlyArray<string>;
|
|
60
|
+
/**
|
|
61
|
+
* Other steps whose declared actions this step's replacements stand for. Running this
|
|
62
|
+
* step performs work that those steps declared.
|
|
63
|
+
*/
|
|
64
|
+
readonly absorbs: ReadonlyArray<string>;
|
|
65
|
+
} & (
|
|
66
|
+
| { readonly kind: "execute" | "prose" }
|
|
67
|
+
| { readonly kind: "omitted"; readonly reason: "noop" | "all-actions-removed" }
|
|
68
|
+
);
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* One occurrence of the plan, as observers see it.
|
|
72
|
+
*
|
|
73
|
+
* @since 0.2.1
|
|
74
|
+
*/
|
|
75
|
+
export type ActionInfo = {
|
|
76
|
+
readonly occurrence: string;
|
|
77
|
+
readonly action: string;
|
|
78
|
+
readonly kind: string;
|
|
79
|
+
readonly description: string;
|
|
80
|
+
readonly migration: string;
|
|
81
|
+
readonly direction: Plan.Direction;
|
|
82
|
+
/** The step that runs the occurrence. */
|
|
83
|
+
readonly step: string;
|
|
84
|
+
readonly origin:
|
|
85
|
+
| { readonly _tag: "Declared" }
|
|
86
|
+
| {
|
|
87
|
+
readonly _tag: "Replacement";
|
|
88
|
+
readonly rule: string;
|
|
89
|
+
/** Identifiers of the replaced occurrences, in order. */
|
|
90
|
+
readonly replaces: ReadonlyArray<string>;
|
|
91
|
+
};
|
|
92
|
+
/** Steps that declared the actions behind this occurrence, in plan order. */
|
|
93
|
+
readonly sources: ReadonlyArray<string>;
|
|
94
|
+
};
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* An outcome as observers see it. Each variant lists its fields explicitly, so a field
|
|
98
|
+
* added to the report's outcome never reaches observers unreviewed. A failure keeps only
|
|
99
|
+
* the error's string `_tag`; the full error is in the execution's report.
|
|
100
|
+
*
|
|
101
|
+
* @since 0.2.1
|
|
102
|
+
*/
|
|
103
|
+
export type OutcomeSummary =
|
|
104
|
+
| { readonly _tag: "Completed"; readonly performer: "automated" }
|
|
105
|
+
| {
|
|
106
|
+
readonly _tag: "Completed";
|
|
107
|
+
readonly performer: "manual";
|
|
108
|
+
readonly confirmation: "asserted" | "verified";
|
|
109
|
+
}
|
|
110
|
+
| { readonly _tag: "Skipped"; readonly reason: string }
|
|
111
|
+
| { readonly _tag: "Declined" }
|
|
112
|
+
| {
|
|
113
|
+
readonly _tag: "Failed";
|
|
114
|
+
readonly phase: Phase;
|
|
115
|
+
readonly errorTag: string | undefined;
|
|
116
|
+
}
|
|
117
|
+
| {
|
|
118
|
+
readonly _tag: "Interrupted";
|
|
119
|
+
readonly phase: Phase;
|
|
120
|
+
readonly reason: InterruptReason;
|
|
121
|
+
readonly settled: boolean;
|
|
122
|
+
}
|
|
123
|
+
| { readonly _tag: "Unattempted" }
|
|
124
|
+
| {
|
|
125
|
+
readonly _tag: "WouldExecute";
|
|
126
|
+
readonly evaluated: boolean;
|
|
127
|
+
readonly performer: Performer;
|
|
128
|
+
}
|
|
129
|
+
| { readonly _tag: "WouldSkip"; readonly reason: string }
|
|
130
|
+
| {
|
|
131
|
+
readonly _tag: "Undetermined";
|
|
132
|
+
readonly reason: string;
|
|
133
|
+
readonly performer: Performer;
|
|
134
|
+
}
|
|
135
|
+
| { readonly _tag: "PreparationFailed"; readonly errorTag: string | undefined };
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Occurrences by outcome tag. `unsettled` counts interrupted occurrences that may still be
|
|
139
|
+
* running.
|
|
140
|
+
*
|
|
141
|
+
* @since 0.2.1
|
|
142
|
+
*/
|
|
143
|
+
export type Counts = { readonly [K in Outcome["_tag"]]: number } & {
|
|
144
|
+
readonly unsettled: number;
|
|
145
|
+
};
|
|
146
|
+
|
|
147
|
+
type Base = {
|
|
148
|
+
readonly run: Run;
|
|
149
|
+
/** Position of the event in its run, starting at 0. */
|
|
150
|
+
readonly seq: number;
|
|
151
|
+
/** Milliseconds since the Unix epoch, from Effect's `Clock`. */
|
|
152
|
+
readonly timestamp: number;
|
|
153
|
+
readonly progress: Progress;
|
|
154
|
+
};
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* The run is starting: every action has a handler, and manual work has an interaction to
|
|
158
|
+
* ask with. A run that fails either check emits no events. Lists every step of the route,
|
|
159
|
+
* including omitted ones.
|
|
160
|
+
*
|
|
161
|
+
* @since 0.2.1
|
|
162
|
+
*/
|
|
163
|
+
export type RunStarted = Base & {
|
|
164
|
+
readonly _tag: "RunStarted";
|
|
165
|
+
readonly steps: ReadonlyArray<StepInfo>;
|
|
166
|
+
};
|
|
167
|
+
|
|
168
|
+
/** @since 0.2.1 */
|
|
169
|
+
export type StepStarted = Base & { readonly _tag: "StepStarted"; readonly step: StepInfo };
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* A phase of an occurrence started: its prepare or apply phase, the confirmation of
|
|
173
|
+
* manual work, or its verification. `prepare` appears only for handlers that have a
|
|
174
|
+
* prepare phase. `confirmation` means the run is waiting for a person. An occurrence
|
|
175
|
+
* emits this once per phase that starts.
|
|
176
|
+
*
|
|
177
|
+
* @since 0.2.1
|
|
178
|
+
*/
|
|
179
|
+
export type ActionPhaseStarted = Base & {
|
|
180
|
+
readonly _tag: "ActionPhaseStarted";
|
|
181
|
+
readonly action: ActionInfo;
|
|
182
|
+
readonly phase: Phase;
|
|
183
|
+
};
|
|
184
|
+
|
|
185
|
+
/**
|
|
186
|
+
* An occurrence has its final outcome. Emitted once for each occurrence whose outcome is
|
|
187
|
+
* known, and as `Unattempted` for an occurrence that started but stopped before applying
|
|
188
|
+
* or asking. It arrives after the occurrence's scope has closed, except when an
|
|
189
|
+
* interrupted Promise has not settled: then the scope stays open until it does, the
|
|
190
|
+
* reported outcome is already final, and a later cleanup failure is only logged. Dry-run
|
|
191
|
+
* outcomes that need no prepare phase arrive without a start.
|
|
192
|
+
*
|
|
193
|
+
* @since 0.2.1
|
|
194
|
+
*/
|
|
195
|
+
export type ActionSettled = Base & {
|
|
196
|
+
readonly _tag: "ActionSettled";
|
|
197
|
+
readonly action: ActionInfo;
|
|
198
|
+
readonly outcome: OutcomeSummary;
|
|
199
|
+
};
|
|
200
|
+
|
|
201
|
+
/**
|
|
202
|
+
* A started step ended. `counts` covers the step's occurrences.
|
|
203
|
+
*
|
|
204
|
+
* @since 0.2.1
|
|
205
|
+
*/
|
|
206
|
+
export type StepSettled = Base & {
|
|
207
|
+
readonly _tag: "StepSettled";
|
|
208
|
+
readonly step: StepInfo;
|
|
209
|
+
readonly counts: Counts;
|
|
210
|
+
};
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* The run ended. `status` and `counts` match the execution's report. When the fiber of
|
|
214
|
+
* `Executor.effect` is interrupted, there is no report: `report` is `false`, the status is
|
|
215
|
+
* `"interrupted"`, and running occurrences count as unsettled interruptions. If the
|
|
216
|
+
* interruption cuts short the delivery of `RunFinished`, the observers that had not yet
|
|
217
|
+
* received it get the report-less one with the same `seq`, so each observer receives
|
|
218
|
+
* exactly one.
|
|
219
|
+
*
|
|
220
|
+
* @since 0.2.1
|
|
221
|
+
*/
|
|
222
|
+
export type RunFinished = Base & {
|
|
223
|
+
readonly _tag: "RunFinished";
|
|
224
|
+
readonly status: Report["status"];
|
|
225
|
+
readonly counts: Counts;
|
|
226
|
+
readonly report: boolean;
|
|
227
|
+
};
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* What an observer receives. A run emits `RunStarted`; then, for each step that is not
|
|
231
|
+
* omitted, `StepStarted`, an `ActionPhaseStarted` for each phase that starts, an
|
|
232
|
+
* `ActionSettled` for each occurrence, and `StepSettled`; and finally `RunFinished`. Action
|
|
233
|
+
* events of parallel branches interleave.
|
|
234
|
+
*
|
|
235
|
+
* Events carry identifiers and plain data, never payloads, errors, or causes. Action
|
|
236
|
+
* descriptions are included, so they must not contain secrets.
|
|
237
|
+
*
|
|
238
|
+
* @since 0.2.1
|
|
239
|
+
*/
|
|
240
|
+
export type Event =
|
|
241
|
+
| RunStarted
|
|
242
|
+
| StepStarted
|
|
243
|
+
| ActionPhaseStarted
|
|
244
|
+
| ActionSettled
|
|
245
|
+
| StepSettled
|
|
246
|
+
| RunFinished;
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* An observer that failed, or that was abandoned after cancellation or a timeout because
|
|
250
|
+
* it did not finish within the settlement grace period. An abandoned callback is
|
|
251
|
+
* interrupted but not awaited, so one that cannot be interrupted may keep running. The
|
|
252
|
+
* cause can hold arbitrary values, so do not serialize it as a whole.
|
|
253
|
+
*
|
|
254
|
+
* @since 0.2.1
|
|
255
|
+
*/
|
|
256
|
+
export type ObservationFailure = {
|
|
257
|
+
/** Position of the observer in the `observers` array. */
|
|
258
|
+
readonly observer: number;
|
|
259
|
+
readonly event: Event["_tag"];
|
|
260
|
+
readonly seq: number;
|
|
261
|
+
readonly reason: "failed" | "abandoned";
|
|
262
|
+
readonly cause: Cause.Cause<unknown>;
|
|
263
|
+
};
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* Receives the events of a run. Pass observers to the executor's `observers` option. `R`
|
|
267
|
+
* is the Effect services an observer requires, which become requirements of the execution.
|
|
268
|
+
*
|
|
269
|
+
* The executor delivers one event at a time, to each observer in array order, and waits
|
|
270
|
+
* for each delivery before it continues, so every observer sees the same order. After
|
|
271
|
+
* cancellation or a timeout, each delivery waits at most `settleTimeout` and is then
|
|
272
|
+
* abandoned. A failed or abandoned delivery is listed in the report's `observation` and
|
|
273
|
+
* never changes an outcome. Observers only receive events: they cannot answer a manual
|
|
274
|
+
* confirmation.
|
|
275
|
+
*
|
|
276
|
+
* @since 0.2.1
|
|
277
|
+
*/
|
|
278
|
+
export type Observer<out R = never> = {
|
|
279
|
+
readonly [TypeId]: typeof TypeId;
|
|
280
|
+
/** Delivers one event and captures how the delivery ended. It never fails. */
|
|
281
|
+
readonly notify: (event: Event) => Effect.Effect<Exit.Exit<unknown, unknown>, never, R>;
|
|
282
|
+
};
|
|
283
|
+
|
|
284
|
+
/**
|
|
285
|
+
* Any observer.
|
|
286
|
+
*
|
|
287
|
+
* @since 0.2.1
|
|
288
|
+
*/
|
|
289
|
+
export type Any = Observer<any>;
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* The Effect services of an observer or a union of observers.
|
|
293
|
+
*
|
|
294
|
+
* @since 0.2.1
|
|
295
|
+
*/
|
|
296
|
+
export type Services<O> = O extends Observer<infer R> ? R : never;
|
|
297
|
+
|
|
298
|
+
/** @since 0.2.1 */
|
|
299
|
+
export const isObserver = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
|
|
300
|
+
|
|
301
|
+
class AsyncSyncObserver extends Error {
|
|
302
|
+
override readonly name = "AsyncSyncObserver";
|
|
303
|
+
override readonly message =
|
|
304
|
+
"An Observer.sync callback returned a Promise. Use Observer.promise for asynchronous callbacks.";
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Observes with a synchronous callback. A thrown value is recorded as an observation
|
|
309
|
+
* failure.
|
|
310
|
+
*
|
|
311
|
+
* @example
|
|
312
|
+
* ```ts
|
|
313
|
+
* Observer.sync((event) => {
|
|
314
|
+
* if (event._tag === "ActionSettled") console.error(event.action.occurrence, event.outcome._tag);
|
|
315
|
+
* });
|
|
316
|
+
* ```
|
|
317
|
+
*
|
|
318
|
+
* @since 0.2.1
|
|
319
|
+
*/
|
|
320
|
+
export const sync = (callback: (event: Event) => void): Observer => ({
|
|
321
|
+
[TypeId]: TypeId,
|
|
322
|
+
notify: (event) =>
|
|
323
|
+
Effect.sync((): Exit.Exit<void, unknown> => {
|
|
324
|
+
try {
|
|
325
|
+
const result: unknown = callback(event);
|
|
326
|
+
if (!Predicate.isPromiseLike(result)) return Exit.void;
|
|
327
|
+
// Keep a rejection from going unhandled; the misuse is reported instead.
|
|
328
|
+
Promise.resolve(result).catch(() => undefined);
|
|
329
|
+
|
|
330
|
+
return Exit.fail(new AsyncSyncObserver());
|
|
331
|
+
} catch (cause) {
|
|
332
|
+
// The thrown value is the failure, exactly as the observer threw it.
|
|
333
|
+
return Exit.fail(cause);
|
|
334
|
+
}
|
|
335
|
+
}),
|
|
336
|
+
});
|
|
337
|
+
|
|
338
|
+
/**
|
|
339
|
+
* Observes with a Promise callback. The executor waits for the Promise. The `signal`
|
|
340
|
+
* aborts when the executor stops waiting: after cancellation or a timeout, once the
|
|
341
|
+
* settlement grace period has passed, or when the execution is interrupted. A services
|
|
342
|
+
* layer that `Executor.runPromise` built stays open until an abandoned Promise settles.
|
|
343
|
+
*
|
|
344
|
+
* @since 0.2.1
|
|
345
|
+
*/
|
|
346
|
+
export const promise = (
|
|
347
|
+
callback: (event: Event, context: { readonly signal: AbortSignal }) => PromiseLike<unknown>,
|
|
348
|
+
): Observer => ({
|
|
349
|
+
[TypeId]: TypeId,
|
|
350
|
+
notify: (event) =>
|
|
351
|
+
Effect.suspend(() => {
|
|
352
|
+
let pending: Promise<unknown> | undefined;
|
|
353
|
+
|
|
354
|
+
// Declaring `signal` makes Effect.promise allocate an AbortController. The rejection
|
|
355
|
+
// is the failure, exactly as the observer rejected.
|
|
356
|
+
return Effect.promise((signal): Promise<Exit.Exit<unknown, unknown>> => {
|
|
357
|
+
const settles = new Promise<unknown>((resolve) =>
|
|
358
|
+
resolve(callback(event, { signal })),
|
|
359
|
+
).then(
|
|
360
|
+
() => Exit.void,
|
|
361
|
+
(cause: unknown) => Exit.fail(cause),
|
|
362
|
+
);
|
|
363
|
+
pending = settles;
|
|
364
|
+
|
|
365
|
+
return settles;
|
|
366
|
+
}).pipe(
|
|
367
|
+
// The executor abandons a delivery by interrupting it without waiting, and keeps
|
|
368
|
+
// the run's services open until the interruption ends. Ending it only once the
|
|
369
|
+
// Promise settles keeps them open for the callback's remaining work.
|
|
370
|
+
Effect.onInterrupt(() =>
|
|
371
|
+
pending === undefined
|
|
372
|
+
? Effect.void
|
|
373
|
+
: Effect.promise(() => pending ?? Promise.resolve()),
|
|
374
|
+
),
|
|
375
|
+
);
|
|
376
|
+
}),
|
|
377
|
+
});
|
|
378
|
+
|
|
379
|
+
/**
|
|
380
|
+
* Observes with an Effect. Its services become requirements of the execution. Its
|
|
381
|
+
* failures are recorded as observation failures and never fail the execution.
|
|
382
|
+
*
|
|
383
|
+
* @example
|
|
384
|
+
* ```ts
|
|
385
|
+
* Observer.effect((event) => Effect.logDebug(event._tag));
|
|
386
|
+
* ```
|
|
387
|
+
*
|
|
388
|
+
* @since 0.2.1
|
|
389
|
+
*/
|
|
390
|
+
export const effect = <E = never, R = never>(
|
|
391
|
+
callback: (event: Event) => Effect.Effect<unknown, E, R>,
|
|
392
|
+
): Observer<R> => ({
|
|
393
|
+
[TypeId]: TypeId,
|
|
394
|
+
notify: (event) => Effect.exit(Effect.suspend(() => callback(event))),
|
|
395
|
+
});
|
|
@@ -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
|
+
};
|
package/src/features/package.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { Predicate } from "effect";
|
|
|
3
3
|
import type * as Action from "../foundation/action.ts";
|
|
4
4
|
import type { History } from "./planning/history.ts";
|
|
5
5
|
|
|
6
|
-
/** @since
|
|
6
|
+
/** @since 0.0.1 */
|
|
7
7
|
export type Package<A extends Action.Any = Action.Any> = {
|
|
8
8
|
readonly _tag: "Package";
|
|
9
9
|
/** The name of the modeled package, for example `@acme/widgets`. */
|
|
@@ -20,13 +20,13 @@ export type Package<A extends Action.Any = Action.Any> = {
|
|
|
20
20
|
* export const widgets = Package.make("@acme/widgets", { history });
|
|
21
21
|
* ```
|
|
22
22
|
*
|
|
23
|
-
* @since
|
|
23
|
+
* @since 0.0.1
|
|
24
24
|
*/
|
|
25
25
|
export const make = <A extends Action.Any>(
|
|
26
26
|
name: string,
|
|
27
27
|
options: { readonly history: History<A> },
|
|
28
28
|
): Package<A> => ({ _tag: "Package", name, history: options.history });
|
|
29
29
|
|
|
30
|
-
/** @since
|
|
30
|
+
/** @since 0.0.1 */
|
|
31
31
|
export const isPackage = (value: unknown): value is Package<any> =>
|
|
32
32
|
Predicate.isTagged(value, "Package");
|
|
@@ -23,7 +23,7 @@ import { validate as validateDeclarations, type Issue } from "./validate.ts";
|
|
|
23
23
|
export * from "./resolve-error.ts";
|
|
24
24
|
export type { Destination, Issue, ResolveOptions, RoutePolicy };
|
|
25
25
|
|
|
26
|
-
/** @since
|
|
26
|
+
/** @since 0.0.1 */
|
|
27
27
|
export type History<A extends Action.Any = Action.Any, C extends Change.Any = Change.Any> = {
|
|
28
28
|
readonly _tag: "History";
|
|
29
29
|
readonly versions: ReadonlyArray<Version>;
|
|
@@ -39,21 +39,21 @@ export type History<A extends Action.Any = Action.Any, C extends Change.Any = Ch
|
|
|
39
39
|
/**
|
|
40
40
|
* Any history.
|
|
41
41
|
*
|
|
42
|
-
* @since
|
|
42
|
+
* @since 0.0.1
|
|
43
43
|
*/
|
|
44
44
|
export type Any = History<any>;
|
|
45
45
|
|
|
46
46
|
/**
|
|
47
47
|
* Every action instance that a plan resolved from the history can contain.
|
|
48
48
|
*
|
|
49
|
-
* @since
|
|
49
|
+
* @since 0.0.1
|
|
50
50
|
*/
|
|
51
51
|
export type ActionsOf<H> = H extends History<infer A> ? A : never;
|
|
52
52
|
|
|
53
53
|
/**
|
|
54
54
|
* Every change that a plan resolved from the history can list in `changes`.
|
|
55
55
|
*
|
|
56
|
-
* @since
|
|
56
|
+
* @since 0.0.1
|
|
57
57
|
*/
|
|
58
58
|
export type ChangesOf<H> = H extends History<any, infer C> ? C : never;
|
|
59
59
|
|
|
@@ -64,7 +64,7 @@ export type ChangesOf<H> = H extends History<any, infer C> ? C : never;
|
|
|
64
64
|
* `make` does not throw. Use `History.validate` to list declaration issues;
|
|
65
65
|
* resolution fails with `InvalidHistory` when there are any.
|
|
66
66
|
*
|
|
67
|
-
* @since
|
|
67
|
+
* @since 0.0.1
|
|
68
68
|
*/
|
|
69
69
|
export const make = <
|
|
70
70
|
const M extends ReadonlyArray<Migration.Any>,
|
|
@@ -86,7 +86,7 @@ export const make = <
|
|
|
86
86
|
shortcuts: declarations.shortcuts ?? [],
|
|
87
87
|
});
|
|
88
88
|
|
|
89
|
-
/** @since
|
|
89
|
+
/** @since 0.0.1 */
|
|
90
90
|
export const isHistory = (value: unknown): value is Any => Predicate.isTagged(value, "History");
|
|
91
91
|
|
|
92
92
|
const contexts = new WeakMap<
|
|
@@ -107,7 +107,7 @@ const prepare = (history: Any) => {
|
|
|
107
107
|
/**
|
|
108
108
|
* Lists declaration issues in a deterministic order. An empty list means valid.
|
|
109
109
|
*
|
|
110
|
-
* @since
|
|
110
|
+
* @since 0.0.1
|
|
111
111
|
*/
|
|
112
112
|
export const validate = (history: Any): ReadonlyArray<Issue> => prepare(history).issues;
|
|
113
113
|
|
|
@@ -132,7 +132,7 @@ const valid = (history: Any): Result.Result<Context, InvalidHistory> => {
|
|
|
132
132
|
* if (Result.isSuccess(result)) console.log(result.success.route.id);
|
|
133
133
|
* ```
|
|
134
134
|
*
|
|
135
|
-
* @since
|
|
135
|
+
* @since 0.0.1
|
|
136
136
|
*/
|
|
137
137
|
export const resolve = <A extends Action.Any, C extends Change.Any>(
|
|
138
138
|
history: History<A, C>,
|
|
@@ -149,7 +149,7 @@ export const resolve = <A extends Action.Any, C extends Change.Any>(
|
|
|
149
149
|
/**
|
|
150
150
|
* Destinations reachable by upgrade from a version, with their candidate routes.
|
|
151
151
|
*
|
|
152
|
-
* @since
|
|
152
|
+
* @since 0.0.1
|
|
153
153
|
*/
|
|
154
154
|
export const upgrades = (
|
|
155
155
|
history: Any,
|
|
@@ -160,7 +160,7 @@ export const upgrades = (
|
|
|
160
160
|
/**
|
|
161
161
|
* Destinations reachable by downgrade from a version, with their candidate routes.
|
|
162
162
|
*
|
|
163
|
-
* @since
|
|
163
|
+
* @since 0.0.1
|
|
164
164
|
*/
|
|
165
165
|
export const downgrades = (
|
|
166
166
|
history: Any,
|
|
@@ -11,15 +11,18 @@ const occurrencePart = (id: string) => escape(id, /[\\/()+]/g);
|
|
|
11
11
|
|
|
12
12
|
const routePart = (id: string) => escape(id, /[\\>[\]]/g);
|
|
13
13
|
|
|
14
|
+
/** A plan step: `<migration>` forward, `<migration>/revert` in reverse. */
|
|
15
|
+
export const stepId = (migration: Migration.Any, direction: Direction): string =>
|
|
16
|
+
direction === "forward"
|
|
17
|
+
? occurrencePart(migration.id)
|
|
18
|
+
: `${occurrencePart(migration.id)}/revert`;
|
|
19
|
+
|
|
14
20
|
/** `<migration>/<action>` forward, `<migration>/revert/<action>` in reverse. */
|
|
15
21
|
export const declaredOccurrenceId = (
|
|
16
22
|
migration: Migration.Any,
|
|
17
23
|
direction: Direction,
|
|
18
24
|
action: Action.Any,
|
|
19
|
-
): string =>
|
|
20
|
-
direction === "forward"
|
|
21
|
-
? `${occurrencePart(migration.id)}/${occurrencePart(action.id)}`
|
|
22
|
-
: `${occurrencePart(migration.id)}/revert/${occurrencePart(action.id)}`;
|
|
25
|
+
): string => `${stepId(migration, direction)}/${occurrencePart(action.id)}`;
|
|
23
26
|
|
|
24
27
|
/**
|
|
25
28
|
* `<rule>(<replaced>+<replaced>)/<action>`. Replaced identifiers are complete occurrence
|