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 +64 -1
- package/dist/index.d.ts +307 -60
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +232 -36
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/features/execution/executor.ts +232 -45
- package/src/features/execution/handler.ts +181 -60
- package/src/features/execution/interaction.ts +174 -0
- package/src/features/execution/promise-callback.ts +76 -0
- package/src/features/planning/rewrite.ts +1 -1
- package/src/index.ts +2 -0
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.
|