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 +84 -17
- package/dist/index.d.ts +475 -89
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +474 -210
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/features/execution/executor.ts +515 -186
- package/src/features/execution/handler.ts +464 -115
- package/src/features/execution/interaction.ts +174 -0
- package/src/features/execution/promise-callback.ts +76 -0
- package/src/features/execution/settlement.ts +13 -10
- 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
|
|
|
@@ -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
|
|
131
|
-
|
|
132
|
-
|
|
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
|
-
|
|
140
|
-
|
|
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`
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
- `signal` cancels and `timeout` limits each
|
|
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.
|
|
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.
|