deltafold 0.0.1 → 0.2.0

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 CHANGED
@@ -17,6 +17,7 @@ the repository's
17
17
  - [Resolve a plan](#resolve-a-plan)
18
18
  - [Run a plan with Promise handlers](#run-a-plan-with-promise-handlers)
19
19
  - [Run a plan with Effect handlers](#run-a-plan-with-effect-handlers)
20
+ - [Leave an action to a person](#leave-an-action-to-a-person)
20
21
  - [Simplify routes with rules and shortcuts](#simplify-routes-with-rules-and-shortcuts)
21
22
  - [Render changelogs and guides](#render-changelogs-and-guides)
22
23
 
@@ -30,7 +31,7 @@ deltafold requires `effect` 4 as a peer dependency and a runtime with a global
30
31
  `AbortSignal`, such as Node.js 22.18 or later, Deno, Bun, or a browser. Type
31
32
  checking needs DOM or Node.js types for `AbortSignal`.
32
33
 
33
- - `deltafold`: declarations, planning, handlers, and executors.
34
+ - `deltafold`: declarations, planning, handlers, interactions, and executors.
34
35
  - `deltafold/changelog`: changelog and document builders.
35
36
  - `deltafold/markdown` and `deltafold/html`: renderers for those documents.
36
37
 
@@ -127,24 +128,25 @@ ancestor, because its author asserts that it is equivalent.
127
128
 
128
129
  ## Run a plan with Promise handlers
129
130
 
130
- Handlers bind to action instances. A precondition that returns `false` skips the
131
- action and reports the reason. In this example, `renameKey` and `fileExists`
132
- stand for your own file access.
131
+ Handlers bind to action instances. A handler either applies its action
132
+ directly, or first runs a read-only `prepare` phase. `prepare` returns
133
+ `Handler.prepared(value)`, and `apply` then receives that value, or
134
+ `Handler.skip(reason)`, which skips the action and reports the reason. In this
135
+ example, `renameKey` and `fileExists` stand for your own file access.
133
136
 
134
137
  ```ts
135
138
  import { Executor, Handler } from "deltafold";
136
139
 
137
140
  const handlers = [
138
- Handler.promise(
139
- renameTimeout,
140
- async ({ file, from, to }, { signal }) => {
141
+ Handler.promise(renameTimeout, {
142
+ prepare: async ({ file }) =>
143
+ (await fileExists(file))
144
+ ? Handler.prepared()
145
+ : Handler.skip("This project has no app.json"),
146
+ apply: async (_prepared, { payload: { file, from, to }, signal }) => {
141
147
  await renameKey(file, from, to, { signal });
142
148
  },
143
- {
144
- when: ({ file }) => fileExists(file),
145
- skipReason: "This project has no app.json",
146
- },
147
- ),
149
+ }),
148
150
  ];
149
151
 
150
152
  try {
@@ -166,10 +168,10 @@ try {
166
168
  the partial report.
167
169
  - Nothing is rolled back and progress is not saved: running the plan again
168
170
  repeats completed actions.
169
- - `dryRun: true` evaluates preconditions without running any action body. A
170
- precondition that may depend on an earlier action is reported `Undetermined`,
171
- because the dry run does not apply that action.
172
- - `signal` cancels and `timeout` limits each action; both reject with
171
+ - `dryRun: true` runs `prepare` phases and never runs `apply`. A prepare phase
172
+ that may depend on an earlier action is reported `Undetermined`, because the
173
+ dry run does not apply that action.
174
+ - `signal` cancels and `timeout` limits each phase; both reject with
173
175
  `ExecutionInterrupted`. Cancellation is cooperative: a callback that ignores
174
176
  its signal can keep running after the run ends, and the report marks it as
175
177
  possibly still running.
@@ -204,7 +206,10 @@ const report = await Effect.runPromise(
204
206
  );
205
207
  ```
206
208
 
207
- Here `configFiles` is your implementation of the service. To cancel an Effect
209
+ Here `configFiles` is your implementation of the service. `Handler.effect`
210
+ also accepts `{ prepare, apply }`. Both phases run in the action's own scope,
211
+ so a resource acquired in `prepare`, such as a lock, stays open until the
212
+ action ends. To cancel an Effect
208
213
  execution, interrupt its fiber; it ends as interrupted, without a report.
209
214
 
210
215
  The handler array must cover every action of the history: a missing handler is
@@ -213,6 +218,68 @@ check coverage only at run time, before any action starts. `Handler.promise` can
213
218
  declare services too, and `Executor.runPromise` then needs a `services` context
214
219
  or layer that covers them.
215
220
 
221
+ ## Leave an action to a person
222
+
223
+ An action is work that a migration requires. The handler decides who performs
224
+ it, so the same action can be manual in one environment and automated in
225
+ another. `Handler.manual` declares that a person does the work. It has no
226
+ prepare or apply phase and no text of its own: the person sees the instruction
227
+ or description that the migration already declares.
228
+
229
+ ```ts
230
+ import { Executor, Handler, Interaction, type Plan } from "deltafold";
231
+
232
+ const handlers = [
233
+ Handler.manual(renameTimeout, {
234
+ verify: ({ file, to }) => hasKey(file, to),
235
+ }),
236
+ ];
237
+
238
+ // The migration's instruction for this action, or the action's description.
239
+ const textOf = ({ action, instruction }: Plan.Occurrence) =>
240
+ instruction?.content
241
+ .map((part) => (part._tag === "Text" ? part.text : part.action.description))
242
+ .join("") ?? action.description;
243
+
244
+ const interaction = Interaction.promise(async ({ occurrence }, { signal }) =>
245
+ (await ask(textOf(occurrence), { signal })) ? "confirmed" : "declined",
246
+ );
247
+
248
+ const report = await Executor.runPromise(plan, { handlers, interaction });
249
+ ```
250
+
251
+ deltafold has no prompt of its own. The `interaction` asks the person, with
252
+ whatever terminal or interface the caller has, and answers `"confirmed"` or
253
+ `"declined"`. `ask` and `hasKey` stand for your own code.
254
+
255
+ - A confirmed occurrence is `Completed` with `performer: "manual"`. Its
256
+ `confirmation` is `"asserted"` when the person said so and nothing checked it,
257
+ or `"verified"` when the handler's optional `verify` check also passed.
258
+ `verify` runs only after the confirmation. A check that returns `false` fails
259
+ the occurrence with `VerificationFailed`. A passing check is evidence that the
260
+ work is in place, not proof of how it was done.
261
+ - A declined occurrence is `Declined`. The run stops as it does after a failure
262
+ and rejects with `ExecutionFailed`, which lists it under `declined`.
263
+ - A run whose plan has manual handlers and no `interaction` rejects with
264
+ `InteractionUnavailable` before any action starts. This is checked at run
265
+ time. An action without a handler is still a coverage error and never becomes
266
+ manual work.
267
+ - `timeout` does not limit the wait for a person. To end the wait, abort the
268
+ `signal` option of `runPromise`. The occurrence is then `Interrupted` in its
269
+ `confirmation` phase, and the `signal` that the interaction receives aborts
270
+ so it can stop asking.
271
+ - A dry run never asks, never runs `verify`, and needs no interaction. It
272
+ reports `performer: "manual"` on the `WouldExecute` and `Undetermined`
273
+ outcomes of manual occurrences.
274
+ - Parallel branches can ask at the same time. An interaction that owns one
275
+ terminal queues its own prompts. A failure or a decline in one branch stops
276
+ new actions, but a person who was already asked can still answer.
277
+ - Progress is not saved. Running the plan again asks again for manual work that
278
+ was already confirmed.
279
+
280
+ `Handler.manualEffect` and `Interaction.effect` take an Effect check and an
281
+ Effect interaction, and keep their errors and services.
282
+
216
283
  ## Simplify routes with rules and shortcuts
217
284
 
218
285
  Rules replace consecutive actions when you assert that they are equivalent.