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.
Files changed (48) hide show
  1. package/README.md +33 -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 +437 -105
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +750 -273
  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 +485 -313
  28. package/src/features/execution/handler.ts +30 -30
  29. package/src/features/execution/interaction.ts +11 -11
  30. package/src/features/execution/observation.ts +489 -0
  31. package/src/features/execution/observer.ts +395 -0
  32. package/src/features/package.ts +3 -3
  33. package/src/features/planning/history.ts +10 -10
  34. package/src/features/planning/identifiers.ts +7 -4
  35. package/src/features/planning/resolve-error.ts +13 -13
  36. package/src/features/planning/resolve.ts +11 -4
  37. package/src/features/planning/validate.ts +1 -1
  38. package/src/foundation/action.ts +17 -17
  39. package/src/foundation/change.ts +10 -10
  40. package/src/foundation/instruction.ts +5 -5
  41. package/src/foundation/migration.ts +12 -12
  42. package/src/foundation/plan.ts +23 -18
  43. package/src/foundation/rule.ts +6 -6
  44. package/src/foundation/shortcut.ts +6 -6
  45. package/src/foundation/version.ts +6 -6
  46. package/src/index.ts +14 -12
  47. package/src/renderers/html.ts +1 -1
  48. package/src/renderers/markdown.ts +1 -1
@@ -13,7 +13,7 @@ type GuardedError<G> = Callback.GuardedError<G>;
13
13
  * apply phase that changes state. A manual handler has neither: the executor waits for a
14
14
  * person in `confirmation`, then runs the handler's optional check in `verification`.
15
15
  *
16
- * @since @next
16
+ * @since 0.0.1
17
17
  */
18
18
  export type Phase = "prepare" | "apply" | "confirmation" | "verification";
19
19
 
@@ -21,14 +21,14 @@ export type Phase = "prepare" | "apply" | "confirmation" | "verification";
21
21
  * Who performs an action: a handler's apply phase, or a person whose confirmation the
22
22
  * executor waits for.
23
23
  *
24
- * @since @next
24
+ * @since 0.2.0
25
25
  */
26
26
  export type Performer = "automated" | "manual";
27
27
 
28
28
  /**
29
29
  * A person confirmed manual work, and the handler's `verify` check returned `false`.
30
30
  *
31
- * @since @next
31
+ * @since 0.2.0
32
32
  */
33
33
  export class VerificationFailed extends Data.TaggedError("VerificationFailed")<{
34
34
  readonly actionId: string;
@@ -44,7 +44,7 @@ export class VerificationFailed extends Data.TaggedError("VerificationFailed")<{
44
44
  * recognized, or its prepare phase returned something other than `Handler.prepared` or
45
45
  * `Handler.skip`.
46
46
  *
47
- * @since @next
47
+ * @since 0.0.1
48
48
  */
49
49
  export class UnexpectedHandlerError extends Data.TaggedError("UnexpectedHandlerError")<{
50
50
  readonly actionId: string;
@@ -63,7 +63,7 @@ const PreparationTypeId = "~deltafold/Preparation";
63
63
  * A prepare phase decided to apply. The apply phase receives `value` unchanged; the
64
64
  * executor never reads, validates, or serializes it.
65
65
  *
66
- * @since @next
66
+ * @since 0.1.0
67
67
  */
68
68
  export type Prepared<out P> = {
69
69
  readonly [PreparationTypeId]: typeof PreparationTypeId;
@@ -75,7 +75,7 @@ export type Prepared<out P> = {
75
75
  * A prepare phase decided that the action does not apply. The occurrence is skipped
76
76
  * with `reason`.
77
77
  *
78
- * @since @next
78
+ * @since 0.1.0
79
79
  */
80
80
  export type Skip = {
81
81
  readonly [PreparationTypeId]: typeof PreparationTypeId;
@@ -86,7 +86,7 @@ export type Skip = {
86
86
  /**
87
87
  * What a prepare phase returns: `Handler.prepared(value)` or `Handler.skip(reason)`.
88
88
  *
89
- * @since @next
89
+ * @since 0.1.0
90
90
  */
91
91
  export type Preparation<P> = Prepared<P> | Skip;
92
92
 
@@ -97,7 +97,7 @@ type PreparedValue<T> = T extends Prepared<infer P> ? P : never;
97
97
  * Ends a prepare phase with the value its apply phase receives. Wrapping the value keeps
98
98
  * it apart from a skip, whatever its shape.
99
99
  *
100
- * @since @next
100
+ * @since 0.1.0
101
101
  */
102
102
  export function prepared(): Prepared<void>;
103
103
  export function prepared<P>(value: P): Prepared<P>;
@@ -108,7 +108,7 @@ export function prepared(value?: unknown): Prepared<unknown> {
108
108
  /**
109
109
  * Ends a prepare phase by skipping the occurrence. The apply phase does not run.
110
110
  *
111
- * @since @next
111
+ * @since 0.1.0
112
112
  */
113
113
  export const skip = (reason: string): Skip => ({
114
114
  [PreparationTypeId]: PreparationTypeId,
@@ -127,7 +127,7 @@ const notAPreparation = () =>
127
127
  * that already holds the prepared value, or confirmed by a person. `verify` checks
128
128
  * confirmed work and fails when the check does not pass.
129
129
  *
130
- * @since @next
130
+ * @since 0.1.0
131
131
  */
132
132
  export type Step<E, R> =
133
133
  | Skip
@@ -146,7 +146,7 @@ const TypeId = "~deltafold/Handler";
146
146
  * phases together. A prepared value stays inside the handler, so handlers with
147
147
  * different prepared values share this type.
148
148
  *
149
- * @since @next
149
+ * @since 0.0.1
150
150
  */
151
151
  export type Handler<out A extends Action.Any, out E = never, out R = never> = {
152
152
  readonly [TypeId]: typeof TypeId;
@@ -166,32 +166,32 @@ export type Handler<out A extends Action.Any, out E = never, out R = never> = {
166
166
  /**
167
167
  * Any handler.
168
168
  *
169
- * @since @next
169
+ * @since 0.0.1
170
170
  */
171
171
  export type Any = Handler<Action.Any, any, any>;
172
172
 
173
173
  /**
174
174
  * The errors of a handler or a union of handlers.
175
175
  *
176
- * @since @next
176
+ * @since 0.0.1
177
177
  */
178
178
  export type Error<H> = H extends Handler<any, infer E, any> ? E : never;
179
179
 
180
180
  /**
181
181
  * The Effect services of a handler or a union of handlers.
182
182
  *
183
- * @since @next
183
+ * @since 0.0.1
184
184
  */
185
185
  export type Services<H> = H extends Handler<any, any, infer R> ? R : never;
186
186
 
187
187
  /**
188
188
  * The action identifiers implemented by a handler or a union of handlers.
189
189
  *
190
- * @since @next
190
+ * @since 0.0.1
191
191
  */
192
192
  export type ActionId<H> = H extends Handler<infer A, any, any> ? A["id"] : never;
193
193
 
194
- /** @since @next */
194
+ /** @since 0.0.1 */
195
195
  export const isHandler = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
196
196
 
197
197
  const make = <A extends Action.Any, E, R>(
@@ -203,7 +203,7 @@ const make = <A extends Action.Any, E, R>(
203
203
  /**
204
204
  * Named Effect services that a Promise handler declares.
205
205
  *
206
- * @since @next
206
+ * @since 0.0.1
207
207
  */
208
208
  export type ServiceMap = Callback.ServiceMap;
209
209
 
@@ -211,7 +211,7 @@ export type ServiceMap = Callback.ServiceMap;
211
211
  * The second argument of Promise handler callbacks: the `AbortSignal` that
212
212
  * `Effect.tryPromise` aborts on interruption, and the declared services, resolved.
213
213
  *
214
- * @since @next
214
+ * @since 0.0.1
215
215
  */
216
216
  export type PromiseContext<S extends ServiceMap = NoServices> = Callback.PromiseContext<S>;
217
217
 
@@ -219,7 +219,7 @@ export type PromiseContext<S extends ServiceMap = NoServices> = Callback.Promise
219
219
  * The second argument of a Promise apply phase: the Promise context and the action
220
220
  * payload.
221
221
  *
222
- * @since @next
222
+ * @since 0.1.0
223
223
  */
224
224
  export type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = PromiseContext<S> & {
225
225
  readonly payload: Payload;
@@ -230,7 +230,7 @@ export type PromiseApplyContext<Payload, S extends ServiceMap = NoServices> = Pr
230
230
  * `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value. Each
231
231
  * phase gets its own signal.
232
232
  *
233
- * @since @next
233
+ * @since 0.1.0
234
234
  */
235
235
  export type PromisePhases<Payload, T extends Preparation<unknown>, S extends ServiceMap> = {
236
236
  readonly prepare: (payload: Payload, context: PromiseContext<S>) => PromiseLike<T> | T;
@@ -245,11 +245,11 @@ export type PromisePhases<Payload, T extends Preparation<unknown>, S extends Ser
245
245
  * check. Guards must declare their parameter type, for example
246
246
  * `(cause: unknown): cause is NotFound => cause instanceof NotFound`.
247
247
  *
248
- * @since @next
248
+ * @since 0.0.1
249
249
  */
250
250
  export type ErrorGuard = Callback.ErrorGuard;
251
251
 
252
- /** @since @next */
252
+ /** @since 0.0.1 */
253
253
  export type PromiseOptions<S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
254
254
  /** Effect services resolved for the callbacks and added to the handler requirements. */
255
255
  readonly services?: S;
@@ -299,7 +299,7 @@ type PromiseHandler<A extends Action.Any, S extends ServiceMap, G> = Handler<
299
299
  * });
300
300
  * ```
301
301
  *
302
- * @since @next
302
+ * @since 0.0.1
303
303
  */
304
304
  export function promise<
305
305
  A extends Action.Any,
@@ -373,7 +373,7 @@ export function promise<
373
373
  /**
374
374
  * The second argument of an Effect apply phase.
375
375
  *
376
- * @since @next
376
+ * @since 0.1.0
377
377
  */
378
378
  export type EffectApplyContext<Payload> = { readonly payload: Payload };
379
379
 
@@ -381,7 +381,7 @@ export type EffectApplyContext<Payload> = { readonly payload: Payload };
381
381
  * An Effect handler with a prepare phase. `prepare` reads state and succeeds with
382
382
  * `Handler.prepared(value)` or `Handler.skip(reason)`; `apply` receives the value.
383
383
  *
384
- * @since @next
384
+ * @since 0.1.0
385
385
  */
386
386
  export type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2> = {
387
387
  readonly prepare: (payload: Payload) => Effect.Effect<T, E1, R1>;
@@ -414,7 +414,7 @@ export type EffectPhases<Payload, T extends Preparation<unknown>, E1, R1, E2, R2
414
414
  * });
415
415
  * ```
416
416
  *
417
- * @since @next
417
+ * @since 0.0.1
418
418
  */
419
419
  export function effect<A extends Action.Any, E = never, R = never>(
420
420
  action: A,
@@ -488,7 +488,7 @@ const makeManual = <A extends Action.Any, E, R>(
488
488
  prepare: (scope) => Effect.succeed({ _tag: "Confirm", verify: verify?.(scope) }),
489
489
  });
490
490
 
491
- /** @since @next */
491
+ /** @since 0.2.0 */
492
492
  export type ManualOptions<Payload, S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>> = {
493
493
  /** Effect services resolved for `verify` and added to the handler requirements. */
494
494
  readonly services?: S;
@@ -523,7 +523,7 @@ export type ManualOptions<Payload, S extends ServiceMap, G extends ReadonlyArray
523
523
  * });
524
524
  * ```
525
525
  *
526
- * @since @next
526
+ * @since 0.2.0
527
527
  */
528
528
  export function manual<A extends Action.Any>(action: A): Handler<A>;
529
529
  export function manual<
@@ -567,7 +567,7 @@ export function manual<
567
567
  return makeManual(action, () => check);
568
568
  }
569
569
 
570
- /** @since @next */
570
+ /** @since 0.2.0 */
571
571
  export type ManualEffectOptions<Payload, E, R> = {
572
572
  /**
573
573
  * Read-only check that runs after the person confirms. Succeeding with `false` fails
@@ -580,7 +580,7 @@ export type ManualEffectOptions<Payload, E, R> = {
580
580
  * `Handler.manual` with an Effect `verify` check, which keeps its own errors and
581
581
  * services.
582
582
  *
583
- * @since @next
583
+ * @since 0.2.0
584
584
  */
585
585
  export function manualEffect<A extends Action.Any>(action: A): Handler<A>;
586
586
  export function manualEffect<A extends Action.Any, E = never, R = never>(
@@ -9,7 +9,7 @@ import { adaptPromise } from "./promise-callback.ts";
9
9
  * What a person says about manual work. There is no other answer: free-form input never
10
10
  * reaches a report.
11
11
  *
12
- * @since @next
12
+ * @since 0.2.0
13
13
  */
14
14
  export type Answer = "confirmed" | "declined";
15
15
 
@@ -17,7 +17,7 @@ export type Answer = "confirmed" | "declined";
17
17
  * A request to confirm manual work. The occurrence carries the action, its description,
18
18
  * and the migration instruction that declared it, which is what to show the person.
19
19
  *
20
- * @since @next
20
+ * @since 0.2.0
21
21
  */
22
22
  export type Request<A extends Action.Any = Action.Any> = {
23
23
  readonly occurrence: Occurrence<A>;
@@ -29,7 +29,7 @@ export type Request<A extends Action.Any = Action.Any> = {
29
29
  * `"confirmed"` or `"declined"` (`invalid-answer`). An invalid answer is never kept: it
30
30
  * may be text that the person typed.
31
31
  *
32
- * @since @next
32
+ * @since 0.2.0
33
33
  */
34
34
  export class UnexpectedInteractionError extends Data.TaggedError("UnexpectedInteractionError")<{
35
35
  readonly occurrenceId: string;
@@ -67,7 +67,7 @@ const TypeId = "~deltafold/Interaction";
67
67
  * serializes its own prompts. A failure or a decline elsewhere stops new actions but
68
68
  * does not withdraw a request that was already made; only cancellation does.
69
69
  *
70
- * @since @next
70
+ * @since 0.2.0
71
71
  */
72
72
  export type Interaction<out E = never, out R = never> = {
73
73
  readonly [TypeId]: typeof TypeId;
@@ -77,28 +77,28 @@ export type Interaction<out E = never, out R = never> = {
77
77
  /**
78
78
  * Any interaction.
79
79
  *
80
- * @since @next
80
+ * @since 0.2.0
81
81
  */
82
82
  export type Any = Interaction<any, any>;
83
83
 
84
84
  /**
85
85
  * The errors of an interaction.
86
86
  *
87
- * @since @next
87
+ * @since 0.2.0
88
88
  */
89
89
  export type Error<I> = I extends Interaction<infer E, any> ? E : never;
90
90
 
91
91
  /**
92
92
  * The Effect services of an interaction.
93
93
  *
94
- * @since @next
94
+ * @since 0.2.0
95
95
  */
96
96
  export type Services<I> = I extends Interaction<any, infer R> ? R : never;
97
97
 
98
- /** @since @next */
98
+ /** @since 0.2.0 */
99
99
  export const isInteraction = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
100
100
 
101
- /** @since @next */
101
+ /** @since 0.2.0 */
102
102
  export type PromiseOptions<
103
103
  S extends Callback.ServiceMap,
104
104
  G extends ReadonlyArray<Callback.ErrorGuard>,
@@ -127,7 +127,7 @@ export type PromiseOptions<
127
127
  * );
128
128
  * ```
129
129
  *
130
- * @since @next
130
+ * @since 0.2.0
131
131
  */
132
132
  export const promise = <
133
133
  const S extends Callback.ServiceMap = Callback.NoServices,
@@ -160,7 +160,7 @@ export const promise = <
160
160
  * Confirms manual work with an Effect, which keeps its own errors and services and
161
161
  * stops through Effect interruption when the run is cancelled.
162
162
  *
163
- * @since @next
163
+ * @since 0.2.0
164
164
  */
165
165
  export const effect = <E = never, R = never>(
166
166
  confirm: (request: Request) => Effect.Effect<Answer, E, R>,