pure-effect 0.18.0 → 0.20.0

package/index.d.ts

@@ -35,7 +35,7 @@ export type AskState<T, E = unknown, Ctx = unknown> = {
 // Every optional option and hook takes `undefined`, which keeps its default, under `exactOptionalPropertyTypes` too.
 export type RetryOptions = {
     /** Tries after the first, so `2` makes at most 3 calls. A positive integer, 3 by default. */
-    attempts?: number | undefined;
+    retries?: number | undefined;
     /** Milliseconds before the first retry, 100 by default. */
     delay?: number | undefined;
     /** Multiplies the wait before each later retry, so `2` doubles it. 1 by default, the same wait each time. */
@@ -58,8 +58,8 @@ export type RetryState<T, E = unknown, Ctx = unknown, R = T> = {
 export type RetryExhaustedError<Thrown = unknown> = {
     retryExhausted: true;
     lastError: Thrown;
-    /** The `attempts` option: tries after the first, so the retried steps ran one more time than this. */
-    attempts: number;
+    /** The `retries` option, so the retried steps ran one more time than this. */
+    retries: number;
 };
 
 export type ParallelOptions = {
@@ -82,7 +82,7 @@ export type ParallelState<
     effects: { [K in keyof T]: Effect<T[K], BranchError, Ctx> };
     next(values: [...V]): Effect<R, E, Ctx>;
     /** A frozen copy of the options the `Parallel` was built with. */
-    options?: Readonly<ParallelOptions>;
+    options: Readonly<ParallelOptions>;
 };
 
 export type Effect<T, E = unknown, Ctx = unknown> =
@@ -194,6 +194,9 @@ export declare function Command<R, T = R, E = unknown, Ctx = unknown>(
 /** The name a Command is known by in traces, replays and spans: `meta.name`, else `cmd.name`, else `'anonymous'`. */
 export declare function commandName(command: CommandState<any, any, any, any>): string;
 
+/** Reads the context passed to `runEffect`. With no argument it succeeds with the context; name its type as `Ask<AppCtx>()`. */
+export declare function Ask<Ctx = unknown>(): AskState<Ctx, never, Ctx>;
+
 /** Reads the context passed to `runEffect`. Give the value, error and context types, or none. */
 export declare function Ask<T = never, E = never, Ctx = unknown, N extends AnyEffect = Effect<T, E, Ctx>>(
     next: (context: Ctx) => N
@@ -1245,23 +1248,70 @@ export declare function effectPipe<
 >;
 // END effectPipe overloads.
 
+// The symbol and the iterator's yield type exist only in the declarations, never at runtime: together they are how
+// `effectGen` reads each step's Effect type out of the body's yield type.
+declare const stepEffect: unique symbol;
+declare const stepContext: unique symbol;
+
+/** A step for `yield*` inside `effectGen`, which gives back the Effect's value. Using it any other way throws. */
+// The context is also a function parameter, which TypeScript compares the opposite way to the Effect, so of two steps
+// it merges in a generator's yield type it can only drop the one that reads less context.
+export type Step<X extends AnyEffect, C = EffectContext<X>> = {
+    readonly [stepEffect]?: X;
+    readonly [stepContext]?: (context: C) => void;
+    [Symbol.iterator](): Generator<Step<X, C>, EffectValue<X>, unknown>;
+};
+
+/** Wraps an Effect for `yield*` inside `effectGen`: `const user = yield* step(findUser(email))`. */
+export declare function step<X extends AnyEffect>(effect: X): Step<X>;
+
+type StepEffectOf<Y> = Y extends Step<infer X, any> ? X : never;
+// An `any` return would match both branches and turn the error union into `any`, so it counts as a plain value.
+type GenIsAny<R> = 0 extends 1 & R ? true : false;
+type ReturnedEffect<R> = GenIsAny<R> extends true ? never : R extends AnyEffect ? R : never;
+type GenValue<R> = GenIsAny<R> extends true ? any : R extends AnyEffect ? EffectValue<R> : R;
+type GenError<Y, R> = EffectError<StepEffectOf<Y>> | EffectError<ReturnedEffect<R>>;
+// A step that reads no context gives `unknown`, which would erase the others in an intersection, so it is dropped. Each
+// context is boxed, so one that is itself a union is intersected whole rather than member by member.
+type GenNeeds<X> = X extends AnyEffect
+    ? EffectContext<X> extends infer C
+        ? unknown extends C
+            ? never
+            : { context: C }
+        : never
+    : never;
+type GenIntersection<U> = (U extends any ? (u: U) => void : never) extends (i: infer I) => void ? I : never;
+type GenContext<Y, R> = [GenNeeds<StepEffectOf<Y> | ReturnedEffect<R>>] extends [never]
+    ? unknown
+    : GenIntersection<GenNeeds<StepEffectOf<Y> | ReturnedEffect<R>>> extends { context: infer C }
+      ? C
+      : unknown;
+
+/**
+ * Builds a flow function from a generator function, written with `yield* step(effect)` where `async` code writes
+ * `await`. A plain return value is a `Success`; return a `Failure` to stop.
+ */
+export declare function effectGen<I, Y extends Step<any, any>, R>(
+    body: (input: I) => Generator<Y, R, unknown>
+): (input: I) => Effect<GenValue<R>, GenError<Y, R>, GenContext<Y, R>>;
+
 /**
  * Wraps each Command, and each `Parallel`. Call `op` and return its result; a hook that calls another passes `path` on.
  */
 export type StepRunner = (
     name: string,
-    type: string,
+    type: 'Command' | 'Parallel',
     op: (decision?: ParallelDecision) => Promise<unknown>,
     path: string
 ) => Promise<unknown>;
 
 /**
- * Which branch, if any, cancelled a `Parallel`, and how many branches it had; `branch: null` means an enclosing one
- * did. A replay refuses a `Parallel` whose count differs, and a decision without one is not checked.
+ * Which branch, if any, cancelled a `Parallel`, whether it threw, and how many branches it had; `branch: null` means an
+ * enclosing one did. A replay refuses a `Parallel` whose count differs, and a decision without one is not checked.
  */
 export type ParallelDecision =
     | { cancelled: false; branches?: number | undefined }
-    | { cancelled: true; branch: number | null; branches?: number | undefined };
+    | { cancelled: true; branch: number | null; branches?: number | undefined; threw?: true | undefined };
 
 /**
  * `flowName` is `context.flowName`, or `''` when the context has none. `initialInput` is what the flow was called with
@@ -1317,7 +1367,7 @@ export type ReplayStep = {
     /** `meta.name`, `cmd.name`, or 'anonymous'; 'Parallel' for a `Parallel`'s step. */
     name: string;
     /** `'Command'`, or `'Parallel'` for a `Parallel`'s decision. */
-    type: string;
+    type: 'Command' | 'Parallel';
     /** The step's position in the flow, the same in every run; a Resolver should key off it. */
     path: string;
 };
@@ -1392,16 +1442,15 @@ export type RecordOptions<Ctx = unknown> = RecorderOptions & {
 };
 
 /**
- * Runs a flow for real and returns its outcome with a trace, which keeps the input's type for the replay. That type is
- * wrong when `redact` changes the input, or the trace marks it `unrecorded`.
+ * Runs a flow for real and returns its outcome with a trace. The trace holds the flow's input when `effectPipe` or
+ * `effectGen` built it.
  */
-export declare function recordEffect<I, T, E = unknown, Ctx = unknown>(
-    flowFn: (input: I) => Effect<T, E, Ctx>,
-    initialInput: I,
+export declare function recordEffect<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
     ...options: unknown extends Ctx
         ? [options?: RecordOptions<CheckedContext<Ctx>>]
         : [options: RecordOptions<CheckedContext<Ctx>> & { context: RunContext<CheckedContext<Ctx>> }]
-): Promise<{ result: SuccessState<T> | FailureState<E>; trace: TraceLog<I, Ctx> & { initialInput: I } }>;
+): Promise<{ result: SuccessState<T> | FailureState<E>; trace: TraceLog<unknown, Ctx> }>;
 
 export interface ReplayOptions<Ctx = unknown> {
     /** Context for `Ask`; defaults to the one the trace recorded. */
@@ -1448,13 +1497,24 @@ export declare function replayEffect<T, E = unknown, Ctx = unknown>(
         : [options: ReplayOptions<CheckedContext<Ctx>> & { context: RunContext<CheckedContext<Ctx>> }]
 ): Promise<Omit<Replay<T, E>, 'unreached'> & { unreached?: TraceEntry[] }>;
 
-/** Replays a trace and logs each step with its recorded timing, warning about what will not replay as recorded. */
+export interface TimeTravelOptions<Ctx = unknown> {
+    /** Receives each narrated line; `console.log` by default. */
+    log?: ((...args: any[]) => void) | undefined;
+    /** Context for `Ask`; defaults to the one the trace recorded. */
+    context?: RunContext<Ctx> | undefined;
+    /** The build replaying the trace; a trace recorded at another build gets a warning. */
+    version?: string | undefined;
+}
+
+/**
+ * Replays a trace and logs each step with its recorded timing, warning about what will not replay as recorded. Returns
+ * what `replayEffect` returns for a trace.
+ */
 export declare function timeTravel<T, E = unknown, Ctx = unknown>(
     flowFn: (input: any) => Effect<T, E, Ctx>,
     traceLog: TraceLog,
-    options?: {
-        log?: ((...args: any[]) => void) | undefined;
-        context?: RunContext<CheckedContext<Ctx>> | undefined;
-        version?: string | undefined;
-    }
-): Promise<SuccessState<T> | FailureState<E>>;
+    options?: TimeTravelOptions<CheckedContext<Ctx>>
+): Promise<Replay<T, E>>;
+
+// Only the declarations marked `export` are public; without this, a declaration file exports every top-level one.
+export {};