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.
@@ -0,0 +1,174 @@
1
+ import { Data, Effect, Predicate } from "effect";
2
+
3
+ import type * as Action from "../../foundation/action.ts";
4
+ import type { Occurrence } from "../../foundation/plan.ts";
5
+ import type * as Callback from "./promise-callback.ts";
6
+ import { adaptPromise } from "./promise-callback.ts";
7
+
8
+ /**
9
+ * What a person says about manual work. There is no other answer: free-form input never
10
+ * reaches a report.
11
+ *
12
+ * @since @next
13
+ */
14
+ export type Answer = "confirmed" | "declined";
15
+
16
+ /**
17
+ * A request to confirm manual work. The occurrence carries the action, its description,
18
+ * and the migration instruction that declared it, which is what to show the person.
19
+ *
20
+ * @since @next
21
+ */
22
+ export type Request<A extends Action.Any = Action.Any> = {
23
+ readonly occurrence: Occurrence<A>;
24
+ };
25
+
26
+ /**
27
+ * A Promise interaction rejected with a value that none of its declared error guards
28
+ * recognized (`rejected`), or an interaction answered with something other than
29
+ * `"confirmed"` or `"declined"` (`invalid-answer`). An invalid answer is never kept: it
30
+ * may be text that the person typed.
31
+ *
32
+ * @since @next
33
+ */
34
+ export class UnexpectedInteractionError extends Data.TaggedError("UnexpectedInteractionError")<{
35
+ readonly occurrenceId: string;
36
+ readonly reason: "rejected" | "invalid-answer";
37
+ /** The rejection. Always `undefined` for an invalid answer. */
38
+ readonly cause: unknown;
39
+ }> {
40
+ override get message() {
41
+ return this.reason === "rejected"
42
+ ? `The interaction failed unexpectedly while confirming "${this.occurrenceId}"`
43
+ : `The interaction answered neither "confirmed" nor "declined" for "${this.occurrenceId}"`;
44
+ }
45
+ }
46
+
47
+ const isAnswer = (value: unknown): value is Answer => value === "confirmed" || value === "declined";
48
+
49
+ const checkAnswer = (request: Request) => (answer: unknown) =>
50
+ isAnswer(answer)
51
+ ? Effect.succeed(answer)
52
+ : Effect.fail(
53
+ new UnexpectedInteractionError({
54
+ occurrenceId: request.occurrence.id,
55
+ reason: "invalid-answer",
56
+ cause: undefined,
57
+ }),
58
+ );
59
+
60
+ const TypeId = "~deltafold/Interaction";
61
+
62
+ /**
63
+ * Asks a person to confirm the manual work of a plan. The executor has no terminal or
64
+ * user interface of its own: the consumer running the plan supplies one of these.
65
+ *
66
+ * Parallel branches can ask at the same time. An interaction that owns one terminal
67
+ * serializes its own prompts. A failure or a decline elsewhere stops new actions but
68
+ * does not withdraw a request that was already made; only cancellation does.
69
+ *
70
+ * @since @next
71
+ */
72
+ export type Interaction<out E = never, out R = never> = {
73
+ readonly [TypeId]: typeof TypeId;
74
+ readonly confirm: (request: Request) => Effect.Effect<Answer, E, R>;
75
+ };
76
+
77
+ /**
78
+ * Any interaction.
79
+ *
80
+ * @since @next
81
+ */
82
+ export type Any = Interaction<any, any>;
83
+
84
+ /**
85
+ * The errors of an interaction.
86
+ *
87
+ * @since @next
88
+ */
89
+ export type Error<I> = I extends Interaction<infer E, any> ? E : never;
90
+
91
+ /**
92
+ * The Effect services of an interaction.
93
+ *
94
+ * @since @next
95
+ */
96
+ export type Services<I> = I extends Interaction<any, infer R> ? R : never;
97
+
98
+ /** @since @next */
99
+ export const isInteraction = (value: unknown): value is Any => Predicate.hasProperty(value, TypeId);
100
+
101
+ /** @since @next */
102
+ export type PromiseOptions<
103
+ S extends Callback.ServiceMap,
104
+ G extends ReadonlyArray<Callback.ErrorGuard>,
105
+ > = {
106
+ /** Effect services resolved for the callback and added to the run's requirements. */
107
+ readonly services?: S;
108
+ /** Guards for rejections that keep their own type. */
109
+ readonly errors?: G;
110
+ };
111
+
112
+ /**
113
+ * Confirms manual work with a Promise callback. It receives `{ signal, services }`: an
114
+ * `AbortSignal` that aborts when the run is cancelled, so it can stop asking, and the
115
+ * declared services.
116
+ *
117
+ * @example
118
+ * ```ts
119
+ * // The migration's instruction for this action, or the action's description.
120
+ * const textOf = ({ action, instruction }: Plan.Occurrence) =>
121
+ * instruction?.content
122
+ * .map((part) => (part._tag === "Text" ? part.text : part.action.description))
123
+ * .join("") ?? action.description;
124
+ *
125
+ * const interaction = Interaction.promise(async ({ occurrence }, { signal }) =>
126
+ * (await ask(textOf(occurrence), { signal })) ? "confirmed" : "declined",
127
+ * );
128
+ * ```
129
+ *
130
+ * @since @next
131
+ */
132
+ export const promise = <
133
+ const S extends Callback.ServiceMap = Callback.NoServices,
134
+ const G extends ReadonlyArray<Callback.ErrorGuard> = [],
135
+ >(
136
+ confirm: (request: Request, context: Callback.PromiseContext<S>) => PromiseLike<Answer>,
137
+ options?: PromiseOptions<S, G>,
138
+ ): Interaction<
139
+ Callback.GuardedError<G[number]> | UnexpectedInteractionError,
140
+ Callback.ServiceIds<S>
141
+ > => {
142
+ const adapt = adaptPromise(options ?? {});
143
+
144
+ return {
145
+ [TypeId]: TypeId,
146
+ confirm: (request) =>
147
+ adapt<unknown, UnexpectedInteractionError>(
148
+ (context) => confirm(request, context),
149
+ (cause) =>
150
+ new UnexpectedInteractionError({
151
+ occurrenceId: request.occurrence.id,
152
+ reason: "rejected",
153
+ cause,
154
+ }),
155
+ ).pipe(Effect.flatMap(checkAnswer(request))),
156
+ };
157
+ };
158
+
159
+ /**
160
+ * Confirms manual work with an Effect, which keeps its own errors and services and
161
+ * stops through Effect interruption when the run is cancelled.
162
+ *
163
+ * @since @next
164
+ */
165
+ export const effect = <E = never, R = never>(
166
+ confirm: (request: Request) => Effect.Effect<Answer, E, R>,
167
+ ): Interaction<E | UnexpectedInteractionError, R> => ({
168
+ [TypeId]: TypeId,
169
+ confirm: (request) =>
170
+ Effect.flatMap(
171
+ Effect.suspend(() => confirm(request)),
172
+ checkAnswer(request),
173
+ ),
174
+ });
@@ -0,0 +1,76 @@
1
+ import { Context, Effect, Schema } from "effect";
2
+
3
+ import type { ValueOf } from "../../types.ts";
4
+ import { trackPromise } from "./settlement.ts";
5
+
6
+ /** Named Effect services that Promise callbacks declare. */
7
+ export type ServiceMap = { readonly [name: string | symbol]: Context.Key<any, any> };
8
+
9
+ // oxlint-disable-next-line typescript/no-generated-empty-object-type -- Callbacks without services declare an empty service map.
10
+ export type NoServices = Record<never, never>;
11
+
12
+ /** The `AbortSignal` aborted on interruption, and the declared services, resolved. */
13
+ export type PromiseContext<S extends ServiceMap = NoServices> = {
14
+ readonly signal: AbortSignal;
15
+ readonly services: { readonly [K in keyof S]: S[K]["Service"] };
16
+ };
17
+
18
+ export type ServiceIds<S extends ServiceMap> = ValueOf<{
19
+ [K in keyof S]: S[K] extends Context.Key<infer I, any> ? I : never;
20
+ }>;
21
+
22
+ /** Recognizes a declared rejection: a schema, or a type guard. */
23
+ export type ErrorGuard = Schema.Top | ((cause: unknown) => cause is any);
24
+
25
+ export type GuardedError<G> = G extends Schema.Top
26
+ ? G["Type"]
27
+ : G extends ((cause: unknown) => cause is infer E)
28
+ ? E
29
+ : never;
30
+
31
+ const declaredError =
32
+ <G extends ReadonlyArray<ErrorGuard>>(guards: G) =>
33
+ (cause: unknown): cause is GuardedError<G[number]> =>
34
+ guards.some((guard) => (Schema.isSchema(guard) ? Schema.is(guard)(cause) : guard(cause)));
35
+
36
+ /**
37
+ * Turns Promise callbacks into Effects. Declared services are resolved before each
38
+ * call, rejections that a guard recognizes keep their type, and `unexpected` wraps the
39
+ * rest.
40
+ */
41
+ export const adaptPromise = <S extends ServiceMap, G extends ReadonlyArray<ErrorGuard>>(options: {
42
+ readonly services?: S | undefined;
43
+ readonly errors?: G | undefined;
44
+ }) => {
45
+ const isDeclared = declaredError(options.errors ?? []);
46
+ const services: ServiceMap = options.services ?? {};
47
+ // The callbacks require exactly the declared services. Reading them from the context
48
+ // keeps that requirement typed; only the record of resolved services needs a cast,
49
+ // because Object.fromEntries does not track keys.
50
+ const resolve = Effect.map(
51
+ Effect.context<ServiceIds<S>>(),
52
+ (context) =>
53
+ // oxlint-disable-next-line typescript/no-unsafe-type-assertion
54
+ Object.fromEntries(
55
+ Reflect.ownKeys(services).map((name) => [
56
+ name,
57
+ Context.get(context, services[name]!),
58
+ ]),
59
+ ) as { readonly [K in keyof S]: S[K]["Service"] },
60
+ );
61
+
62
+ return <T, U>(
63
+ callback: (context: PromiseContext<S>) => PromiseLike<T> | T,
64
+ unexpected: (cause: unknown) => U,
65
+ ): Effect.Effect<T, GuardedError<G[number]> | U, ServiceIds<S>> =>
66
+ Effect.flatMap(resolve, (resolved) =>
67
+ trackPromise((capture) =>
68
+ Effect.tryPromise({
69
+ // Declaring `signal` makes Effect.tryPromise allocate an AbortController.
70
+ try: (signal) =>
71
+ capture(Promise.resolve(callback({ signal, services: resolved }))),
72
+ catch: (cause) => (isDeclared(cause) ? cause : unexpected(cause)),
73
+ }),
74
+ ),
75
+ );
76
+ };
@@ -7,16 +7,18 @@ import { Context, Duration, Effect, Option } from "effect";
7
7
  export type Settlement = {
8
8
  /** How long to keep waiting for an interrupted Promise before reporting it pending. */
9
9
  readonly grace: Duration.Input;
10
- readonly record: (settled: boolean) => void;
10
+ /** Receives an interrupted Promise that did not settle within the grace period. */
11
+ readonly unsettled: (promise: Promise<void>) => void;
11
12
  };
12
13
 
13
14
  export const SettlementReference = Context.Reference<Settlement>("deltafold/Settlement", {
14
- defaultValue: () => ({ grace: Duration.zero, record: () => {} }),
15
+ defaultValue: () => ({ grace: Duration.zero, unsettled: () => {} }),
15
16
  });
16
17
 
17
18
  /**
18
19
  * Runs a Promise-producing effect. If it is interrupted after the Promise started,
19
- * waits up to the settlement grace period and records whether the Promise settled.
20
+ * waits up to the settlement grace period and hands a still-pending Promise to the
21
+ * settlement, which can hold resources until it settles.
20
22
  */
21
23
  export const trackPromise = <T, E, R>(
22
24
  start: (capture: (promise: Promise<T>) => Promise<T>) => Effect.Effect<T, E, R>,
@@ -35,14 +37,15 @@ export const trackPromise = <T, E, R>(
35
37
  const started = pending;
36
38
  if (started === undefined) return;
37
39
 
40
+ const settles = started.then(
41
+ () => undefined,
42
+ () => undefined,
43
+ );
38
44
  const settlement = yield* SettlementReference;
39
- const settled = yield* Effect.promise(() =>
40
- started.then(
41
- () => undefined,
42
- () => undefined,
43
- ),
44
- ).pipe(Effect.timeoutOption(settlement.grace));
45
- settlement.record(Option.isSome(settled));
45
+ const settled = yield* Effect.promise(() => settles).pipe(
46
+ Effect.timeoutOption(settlement.grace),
47
+ );
48
+ if (Option.isNone(settled)) settlement.unsettled(settles);
46
49
  }),
47
50
  ),
48
51
  );
@@ -18,7 +18,7 @@ export type Item =
18
18
  readonly concurrency: Action.Concurrency;
19
19
  readonly step: number;
20
20
  }
21
- /** A text-only migration: manual work that rules must not match around. */
21
+ /** A text-only migration: prose instructions that rules must not match around. */
22
22
  | { readonly _tag: "Barrier"; readonly step: number };
23
23
 
24
24
  export type Application = {
package/src/index.ts CHANGED
@@ -7,6 +7,8 @@ export * as Executor from "./features/execution/executor.ts";
7
7
  /** @since @next */
8
8
  export * as Handler from "./features/execution/handler.ts";
9
9
  /** @since @next */
10
+ export * as Interaction from "./features/execution/interaction.ts";
11
+ /** @since @next */
10
12
  export * as History from "./features/planning/history.ts";
11
13
  /** @since @next */
12
14
  export * as Migration from "./foundation/migration.ts";