deltafold 0.2.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 +33 -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 +437 -105
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +750 -273
- 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 +485 -313
- package/src/features/execution/handler.ts +30 -30
- package/src/features/execution/interaction.ts +11 -11
- package/src/features/execution/observation.ts +489 -0
- package/src/features/execution/observer.ts +395 -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/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 +14 -12
- 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
|
+
});
|
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
|
|
@@ -6,7 +6,7 @@ import type { Issue } from "./validate.ts";
|
|
|
6
6
|
/**
|
|
7
7
|
* A candidate route, summarized for diagnostics and explicit selection.
|
|
8
8
|
*
|
|
9
|
-
* @since
|
|
9
|
+
* @since 0.0.1
|
|
10
10
|
*/
|
|
11
11
|
export type RouteSummary = {
|
|
12
12
|
/** Pass this as the `route` option to select the route. */
|
|
@@ -23,7 +23,7 @@ export type RouteSummary = {
|
|
|
23
23
|
/**
|
|
24
24
|
* An ancestry hop with no declared route in the requested direction.
|
|
25
25
|
*
|
|
26
|
-
* @since
|
|
26
|
+
* @since 0.0.1
|
|
27
27
|
*/
|
|
28
28
|
export type Blocker = {
|
|
29
29
|
readonly from: string;
|
|
@@ -34,7 +34,7 @@ export type Blocker = {
|
|
|
34
34
|
/**
|
|
35
35
|
* The history's declarations are invalid. Resolution needs a valid history.
|
|
36
36
|
*
|
|
37
|
-
* @since
|
|
37
|
+
* @since 0.0.1
|
|
38
38
|
*/
|
|
39
39
|
export class InvalidHistory extends Data.TaggedError("InvalidHistory")<{
|
|
40
40
|
readonly issues: ReadonlyArray<Issue>;
|
|
@@ -46,7 +46,7 @@ export class InvalidHistory extends Data.TaggedError("InvalidHistory")<{
|
|
|
46
46
|
}
|
|
47
47
|
}
|
|
48
48
|
|
|
49
|
-
/** @since
|
|
49
|
+
/** @since 0.0.1 */
|
|
50
50
|
export class UnknownVersion extends Data.TaggedError("UnknownVersion")<{
|
|
51
51
|
readonly version: string;
|
|
52
52
|
readonly known: ReadonlyArray<string>;
|
|
@@ -60,7 +60,7 @@ export class UnknownVersion extends Data.TaggedError("UnknownVersion")<{
|
|
|
60
60
|
* No declared route connects the versions. This never means that no work is needed:
|
|
61
61
|
* declare `Migration.noop` for a supported zero-work transition.
|
|
62
62
|
*
|
|
63
|
-
* @since
|
|
63
|
+
* @since 0.0.1
|
|
64
64
|
*/
|
|
65
65
|
export class UnsupportedRoute extends Data.TaggedError("UnsupportedRoute")<{
|
|
66
66
|
readonly from: string;
|
|
@@ -83,7 +83,7 @@ export class UnsupportedRoute extends Data.TaggedError("UnsupportedRoute")<{
|
|
|
83
83
|
/**
|
|
84
84
|
* Several routes connect the versions and no selection or policy chose one.
|
|
85
85
|
*
|
|
86
|
-
* @since
|
|
86
|
+
* @since 0.0.1
|
|
87
87
|
*/
|
|
88
88
|
export class AmbiguousRoute extends Data.TaggedError("AmbiguousRoute")<{
|
|
89
89
|
readonly from: string;
|
|
@@ -103,7 +103,7 @@ export class AmbiguousRoute extends Data.TaggedError("AmbiguousRoute")<{
|
|
|
103
103
|
/**
|
|
104
104
|
* The `route` option names no candidate route.
|
|
105
105
|
*
|
|
106
|
-
* @since
|
|
106
|
+
* @since 0.0.1
|
|
107
107
|
*/
|
|
108
108
|
export class UnknownRoute extends Data.TaggedError("UnknownRoute")<{
|
|
109
109
|
readonly route: string;
|
|
@@ -119,7 +119,7 @@ export class UnknownRoute extends Data.TaggedError("UnknownRoute")<{
|
|
|
119
119
|
/**
|
|
120
120
|
* Rules rewrite a sequence back into itself.
|
|
121
121
|
*
|
|
122
|
-
* @since
|
|
122
|
+
* @since 0.0.1
|
|
123
123
|
*/
|
|
124
124
|
export class RewriteCycle extends Data.TaggedError("RewriteCycle")<{
|
|
125
125
|
readonly route: string;
|
|
@@ -134,7 +134,7 @@ export class RewriteCycle extends Data.TaggedError("RewriteCycle")<{
|
|
|
134
134
|
/**
|
|
135
135
|
* Rules can produce different results depending on which applies first.
|
|
136
136
|
*
|
|
137
|
-
* @since
|
|
137
|
+
* @since 0.0.1
|
|
138
138
|
*/
|
|
139
139
|
export class ConflictingRewrites extends Data.TaggedError("ConflictingRewrites")<{
|
|
140
140
|
readonly route: string;
|
|
@@ -152,7 +152,7 @@ export class ConflictingRewrites extends Data.TaggedError("ConflictingRewrites")
|
|
|
152
152
|
* Optimization explored too many states or chained too many rule applications, for
|
|
153
153
|
* example because a rule keeps growing the sequence.
|
|
154
154
|
*
|
|
155
|
-
* @since
|
|
155
|
+
* @since 0.0.1
|
|
156
156
|
*/
|
|
157
157
|
export class RewriteLimitExceeded extends Data.TaggedError("RewriteLimitExceeded")<{
|
|
158
158
|
readonly route: string;
|
|
@@ -169,7 +169,7 @@ export class RewriteLimitExceeded extends Data.TaggedError("RewriteLimitExceeded
|
|
|
169
169
|
/**
|
|
170
170
|
* More candidate routes exist than the resolver enumerates.
|
|
171
171
|
*
|
|
172
|
-
* @since
|
|
172
|
+
* @since 0.0.1
|
|
173
173
|
*/
|
|
174
174
|
export class TooManyRoutes extends Data.TaggedError("TooManyRoutes")<{
|
|
175
175
|
readonly from: string;
|
|
@@ -181,7 +181,7 @@ export class TooManyRoutes extends Data.TaggedError("TooManyRoutes")<{
|
|
|
181
181
|
}
|
|
182
182
|
}
|
|
183
183
|
|
|
184
|
-
/** @since
|
|
184
|
+
/** @since 0.0.1 */
|
|
185
185
|
export type RewriteError = RewriteCycle | ConflictingRewrites | RewriteLimitExceeded;
|
|
186
186
|
|
|
187
187
|
/**
|
|
@@ -189,7 +189,7 @@ export type RewriteError = RewriteCycle | ConflictingRewrites | RewriteLimitExce
|
|
|
189
189
|
* closest ones by release ancestry, and blockers. `AmbiguousRoute` lists the candidate
|
|
190
190
|
* routes: pass one as `route`, or choose a `policy`.
|
|
191
191
|
*
|
|
192
|
-
* @since
|
|
192
|
+
* @since 0.0.1
|
|
193
193
|
*/
|
|
194
194
|
export type ResolveError =
|
|
195
195
|
| InvalidHistory
|
|
@@ -15,7 +15,13 @@ import type {
|
|
|
15
15
|
import type * as Shortcut from "../../foundation/shortcut.ts";
|
|
16
16
|
import type { Version } from "../../foundation/version.ts";
|
|
17
17
|
import { resolveGuide } from "./guide.ts";
|
|
18
|
-
import {
|
|
18
|
+
import {
|
|
19
|
+
declaredOccurrenceId,
|
|
20
|
+
routeHop,
|
|
21
|
+
routeShortcut,
|
|
22
|
+
routeStart,
|
|
23
|
+
stepId,
|
|
24
|
+
} from "./identifiers.ts";
|
|
19
25
|
import {
|
|
20
26
|
AmbiguousRoute,
|
|
21
27
|
ConflictingRewrites,
|
|
@@ -43,7 +49,7 @@ import { actionsOfSteps, hasProse, stepsOf, type Declarations } from "./validate
|
|
|
43
49
|
* `cost`; a shortcut costs its declared `cost` or the total of its migrations.
|
|
44
50
|
* - `prefer-shortcuts`: a route through a shortcut over the route the shortcut replaces.
|
|
45
51
|
*
|
|
46
|
-
* @since
|
|
52
|
+
* @since 0.0.1
|
|
47
53
|
*/
|
|
48
54
|
export type RoutePolicy =
|
|
49
55
|
| "fewest-actions"
|
|
@@ -344,6 +350,7 @@ const buildPlan = (
|
|
|
344
350
|
|
|
345
351
|
return {
|
|
346
352
|
_tag: "Step",
|
|
353
|
+
id: stepId(member.migration, member.direction),
|
|
347
354
|
migration: member.migration,
|
|
348
355
|
direction: member.direction,
|
|
349
356
|
from: stepFrom,
|
|
@@ -570,7 +577,7 @@ const unsupported = (context: Context, from: string, to: string, direction: Requ
|
|
|
570
577
|
});
|
|
571
578
|
};
|
|
572
579
|
|
|
573
|
-
/** @since
|
|
580
|
+
/** @since 0.0.1 */
|
|
574
581
|
export type ResolveOptions = {
|
|
575
582
|
readonly from: Version | string;
|
|
576
583
|
readonly to: Version | string;
|
|
@@ -658,7 +665,7 @@ export const resolve = (
|
|
|
658
665
|
/**
|
|
659
666
|
* A reachable destination and the identifiers of its candidate routes.
|
|
660
667
|
*
|
|
661
|
-
* @since
|
|
668
|
+
* @since 0.0.1
|
|
662
669
|
*/
|
|
663
670
|
export type Destination = {
|
|
664
671
|
readonly version: Version;
|