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.
Files changed (50) hide show
  1. package/README.md +96 -1
  2. package/dist/changelog.d.ts +10 -10
  3. package/dist/changelog.js +4 -4
  4. package/dist/changelog.js.map +1 -1
  5. package/dist/{document-BZcZo9nr.js → document-HfPyYxEd.js} +20 -20
  6. package/dist/{document-BZcZo9nr.js.map → document-HfPyYxEd.js.map} +1 -1
  7. package/dist/{document-DWHsgywm.d.ts → document-gtXeGFJR.d.ts} +41 -41
  8. package/dist/{document-DWHsgywm.d.ts.map → document-gtXeGFJR.d.ts.map} +1 -1
  9. package/dist/html.d.ts +2 -2
  10. package/dist/html.js +2 -2
  11. package/dist/html.js.map +1 -1
  12. package/dist/index.d.ts +681 -102
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +908 -235
  15. package/dist/index.js.map +1 -1
  16. package/dist/markdown.d.ts +2 -2
  17. package/dist/markdown.js +2 -2
  18. package/dist/markdown.js.map +1 -1
  19. package/dist/{mdast-DiRsYwPU.js → mdast-Oqkh0Gs1.js} +2 -2
  20. package/dist/{mdast-DiRsYwPU.js.map → mdast-Oqkh0Gs1.js.map} +1 -1
  21. package/dist/{package-BfBYnaCz.d.ts → package-CA5R57IC.d.ts} +117 -112
  22. package/dist/{package-BfBYnaCz.d.ts.map → package-CA5R57IC.d.ts.map} +1 -1
  23. package/package.json +3 -3
  24. package/src/features/documents/changelog.ts +8 -8
  25. package/src/features/documents/document.ts +39 -39
  26. package/src/features/documents/index.ts +2 -2
  27. package/src/features/execution/executor.ts +631 -272
  28. package/src/features/execution/handler.ts +205 -84
  29. package/src/features/execution/interaction.ts +174 -0
  30. package/src/features/execution/observation.ts +489 -0
  31. package/src/features/execution/observer.ts +395 -0
  32. package/src/features/execution/promise-callback.ts +76 -0
  33. package/src/features/package.ts +3 -3
  34. package/src/features/planning/history.ts +10 -10
  35. package/src/features/planning/identifiers.ts +7 -4
  36. package/src/features/planning/resolve-error.ts +13 -13
  37. package/src/features/planning/resolve.ts +11 -4
  38. package/src/features/planning/rewrite.ts +1 -1
  39. package/src/features/planning/validate.ts +1 -1
  40. package/src/foundation/action.ts +17 -17
  41. package/src/foundation/change.ts +10 -10
  42. package/src/foundation/instruction.ts +5 -5
  43. package/src/foundation/migration.ts +12 -12
  44. package/src/foundation/plan.ts +23 -18
  45. package/src/foundation/rule.ts +6 -6
  46. package/src/foundation/shortcut.ts +6 -6
  47. package/src/foundation/version.ts +6 -6
  48. package/src/index.ts +15 -11
  49. package/src/renderers/html.ts +1 -1
  50. 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
+ };
@@ -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 @next */
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 @next
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 @next */
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 @next */
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 @next
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 @next
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 @next
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 @next
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 @next */
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 @next
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 @next
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 @next
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 @next
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