@boboddy/sdk 0.2.15-alpha → 0.4.0

package/dist/definitions/pipelines/fan-out-builder.d.ts

@@ -0,0 +1,66 @@
+import type { ZodType } from "zod";
+import { type AdvanceAllCtx, type AdvanceAllResult, type AdvanceEachCtx, type AdvanceEachResult } from "../advancement-policies/cohort-fluent-rules";
+import { type AnyTypedStep, type FanOutInputCtx, type IsAny, type LastSignalKeys, type PipelineMeta, type RequiredInputKeys } from "./builder-helpers";
+import type { AnyBinding, PipelineNodeConfig } from "./define-pipeline";
+import { PipelineStepBuilder } from "./builder";
+/**
+ * `.fanOutStep()` (issue #167) split out of `builder.ts` (which would
+ * otherwise exceed this repo's `max-lines` limit) — genuinely mutually
+ * referential with `PipelineStepBuilder` (`beginFanOut` both is called from
+ * `PipelineStepBuilder.fanOutStep()` and returns a new one), so the import
+ * cycle is structural, not accidental.
+ */
+export type FanOutInputMapping<S extends AnyTypedStep> = Partial<Record<string, AnyBinding>> & (IsAny<S["__inputType"]> extends true ? unknown : S["__inputType"] extends object ? {
+    [K in RequiredInputKeys<S["__inputType"]>]: AnyBinding;
+} : unknown);
+/**
+ * `.fanOutStep(step, config)`'s sole config argument — `step` itself is a
+ * separate positional argument (mirroring `.step(step, options)`), not a
+ * field on this object. `K` is inferred from the literal value of
+ * `config.over` in the same pass TypeScript type-checks `config.input`,
+ * the same mechanism `builder.ts`'s `StepOptions` already relies on for
+ * `.step()` — see that type's doc comment for why overloads are avoided
+ * here too.
+ */
+export type FanOutStepConfig<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep>, S extends AnyTypedStep, K extends LastSignalKeys<TSteps> = LastSignalKeys<TSteps>> = {
+    /**
+     * The signal to resolve each branch from — constrained to the most
+     * recent ordinary step's declared signal keys (`TSteps`'s last element).
+     * Note this is the last *step*, not necessarily the fan-out's immediate
+     * graph predecessor: chaining a second `.fanOutStep()` right after
+     * `.advanceAll()` (with no intervening `.step()`) still only offers this
+     * same step's signals, since a `cohortGate` node produces no signals of
+     * its own to resolve from.
+     *
+     * A number-typed signal resolves a fixed branch count with no `item` on
+     * the input ctx (count-only mode); an array-typed signal resolves branch
+     * count from the array's length and adds a typed `item` to the input
+     * ctx for each branch.
+     */
+    over: K;
+    input?: (ctx: FanOutInputCtx<TInput, TSteps, TFanOuts, K>) => FanOutInputMapping<S>;
+    /**
+     * Every branch's own continue/block decision (even the default "always
+     * continue" must be declared explicitly) — evaluated once per branch
+     * against that branch's own signals.
+     */
+    advance: (ctx: AdvanceEachCtx<S["__signalKeys"], S["__signalTypeMap"]>) => AdvanceEachResult;
+    /**
+     * The whole-cohort decision, evaluated once the fan-out's branches have
+     * settled — a pure gate, not a step: nothing besides the fan-out+gate
+     * pair itself is appended to the pipeline's node sequence.
+     */
+    advanceAll: (ctx: AdvanceAllCtx) => AdvanceAllResult;
+    timeout?: number | null;
+};
+/**
+ * Builds and pushes the `fanOut`+`cohortGate` node pair, resolves both the
+ * per-branch (`advance`) and whole-cohort (`advanceAll`) policies from
+ * `config`, and returns straight into a `PipelineStepBuilder` — mirroring
+ * how `pushStep` in `builder.ts` resolves a step's `advance` policy inline
+ * rather than through a chained `.advance()` call on an intermediate
+ * builder. Called from `PipelineStepBuilder.fanOutStep()` — factored out
+ * here (rather than inlined there) purely to keep the node-construction
+ * logic next to the types it feeds.
+ */
+export declare function beginFanOut<TInput extends ZodType, TSteps extends ReadonlyArray<AnyTypedStep>, TFanOuts extends ReadonlyArray<AnyTypedStep>, S extends AnyTypedStep, K extends LastSignalKeys<TSteps> = LastSignalKeys<TSteps>>(inputSchema: TInput, meta: Omit<PipelineMeta<TInput>, "additionalPipelineInput" | "additionalStepInput">, nodes: PipelineNodeConfig[], pipelineInputBindings: Record<string, AnyBinding>, pipelineStepInputBindings: Record<string, AnyBinding>, step: S, config: FanOutStepConfig<TInput, TSteps, TFanOuts, S, K>): PipelineStepBuilder<TInput, TSteps, [...TFanOuts, S]>;