deltafold 0.1.0 → 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
 
@@ -217,6 +218,68 @@ check coverage only at run time, before any action starts. `Handler.promise` can
217
218
  declare services too, and `Executor.runPromise` then needs a `services` context
218
219
  or layer that covers them.
219
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
+
220
283
  ## Simplify routes with rules and shortcuts
221
284
 
222
285
  Rules replace consecutive actions when you assert that they are equivalent.