@barnum/barnum 0.2.2 → 0.3.0

package/src/chain.ts

@@ -0,0 +1,17 @@
+import {
+  type Action,
+  type Pipeable,
+  type TypedAction,
+  typedAction,
+} from "./ast.js";
+
+export function chain<T1, T2, T3>(
+  first: Pipeable<T1, T2>,
+  rest: Pipeable<T2, T3>,
+): TypedAction<T1, T3> {
+  return typedAction({
+    kind: "Chain",
+    first: first as Action,
+    rest: rest as Action,
+  });
+}

package/src/effect-id.ts

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// Shared effect ID counter for gensym'd effect identifiers
+// ---------------------------------------------------------------------------
+
+/** Branded ID for resume-style effect handlers. */
+export type ResumeHandlerId = number & {
+  readonly __resumeHandlerBrand: unique symbol;
+};
+
+/** Branded ID for restart-style effect handlers. */
+export type RestartHandlerId = number & {
+  readonly __restartHandlerBrand: unique symbol;
+};
+
+let nextId = 0;
+
+/** Allocate a fresh, unique resume handler ID. */
+export function allocateResumeHandlerId(): ResumeHandlerId {
+  return nextId++ as ResumeHandlerId;
+}
+
+/** Allocate a fresh, unique restart handler ID. */
+export function allocateRestartHandlerId(): RestartHandlerId {
+  return nextId++ as RestartHandlerId;
+}
+
+/** Reset the ID counter. For test isolation only. */
+export function resetEffectIdCounter(): void {
+  nextId = 0;
+}

package/src/handler.ts

@@ -0,0 +1,279 @@
+import { fileURLToPath } from "node:url";
+import type { JSONSchema7 } from "json-schema";
+import type { z } from "zod";
+import { type TypedAction, typedAction } from "./ast.js";
+import { zodToCheckedJsonSchema } from "./schema.js";
+
+// ---------------------------------------------------------------------------
+// HandlerDefinition — the user's handle function + optional validators
+// ---------------------------------------------------------------------------
+
+export interface HandlerDefinition<
+  TValue = unknown,
+  TOutput = unknown,
+  TStepConfig = unknown,
+> {
+  inputValidator?: z.ZodType<TValue>;
+  outputValidator?: z.ZodType<TOutput>;
+  stepConfigValidator?: z.ZodType<TStepConfig>;
+  handle: (context: {
+    value: TValue;
+    stepConfig: TStepConfig;
+  }) => Promise<TOutput>;
+}
+
+/** Runtime-only handler definition shape — erases generic type info. */
+interface UntypedHandlerDefinition {
+  inputValidator?: z.ZodType;
+  outputValidator?: z.ZodType;
+  stepConfigValidator?: z.ZodType;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  handle: (...args: any[]) => Promise<unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Handler — opaque typed handler reference
+// ---------------------------------------------------------------------------
+
+const HANDLER_BRAND = Symbol.for("barnum:handler");
+
+/**
+ * Opaque handler reference with typed metadata. The `__definition` property
+ * is non-enumerable — invisible to `JSON.stringify`, visible to the worker.
+ */
+export type Handler<TValue = unknown, TOutput = unknown> = TypedAction<
+  TValue,
+  TOutput
+> & {
+  readonly [HANDLER_BRAND]: true;
+  readonly __definition: UntypedHandlerDefinition;
+};
+
+// ---------------------------------------------------------------------------
+// getCallerFilePath
+// ---------------------------------------------------------------------------
+
+/**
+ * Deduces the caller's file path from the V8 stack trace API.
+ * Frame 0 = getCallerFilePath, Frame 1 = createHandler, Frame 2 = the caller.
+ */
+function getCallerFilePath(): string {
+  const original = Error.prepareStackTrace;
+  let callerFile: string | undefined;
+
+  Error.prepareStackTrace = (_err, stack): string => {
+    const frame = stack[2];
+    callerFile = frame?.getFileName() ?? undefined;
+    return "";
+  };
+
+  const err = new Error("stack trace capture");
+  void err.stack;
+  Error.prepareStackTrace = original;
+
+  if (!callerFile) {
+    throw new Error(
+      "createHandler: could not determine caller file path from stack trace.",
+    );
+  }
+
+  if (callerFile.startsWith("file://")) {
+    return fileURLToPath(callerFile);
+  }
+  return callerFile;
+}
+
+// ---------------------------------------------------------------------------
+// HandlerOutput — maps void → never so fire-and-forget handlers compose
+// ---------------------------------------------------------------------------
+
+/**
+ * Handlers that return `Promise<void>` produce `never` output. This means
+ * they naturally compose in pipes without needing `.drop()` — a handler
+ * that returns nothing produces a value no one can observe.
+ */
+type HandlerOutput<TOutput> = [TOutput] extends [void] ? never : TOutput;
+
+// ---------------------------------------------------------------------------
+// createHandler — single overload, validators optional
+// ---------------------------------------------------------------------------
+
+export function createHandler<TValue = never, TOutput = unknown>(
+  definition: {
+    inputValidator?: z.ZodType<TValue>;
+    outputValidator?: z.ZodType<NoInfer<TOutput>>;
+    handle: (context: { value: TValue }) => Promise<TOutput>;
+  },
+  exportName?: string,
+): Handler<TValue, HandlerOutput<TOutput>>;
+
+// Implementation
+export function createHandler(
+  definition: UntypedHandlerDefinition,
+  exportName?: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any {
+  const filePath = getCallerFilePath();
+  const funcName = exportName ?? "default";
+
+  const inputSchema = definition.inputValidator
+    ? zodToCheckedJsonSchema(
+        definition.inputValidator,
+        `${filePath}:${funcName} input`,
+      )
+    : undefined;
+  const outputSchema = definition.outputValidator
+    ? zodToCheckedJsonSchema(
+        definition.outputValidator,
+        `${filePath}:${funcName} output`,
+      )
+    : undefined;
+
+  const action = typedAction({
+    kind: "Invoke",
+    handler: {
+      kind: "TypeScript",
+      module: filePath,
+      func: funcName,
+      ...(inputSchema && { input_schema: inputSchema }),
+      ...(outputSchema && { output_schema: outputSchema }),
+    },
+  });
+
+  // Non-enumerable: invisible to JSON.stringify, visible to the worker
+  Object.defineProperty(action, HANDLER_BRAND, {
+    value: true,
+    enumerable: false,
+  });
+  Object.defineProperty(action, "__definition", {
+    value: definition,
+    enumerable: false,
+  });
+
+  return action;
+}
+
+// ---------------------------------------------------------------------------
+// createHandlerWithConfig — single overload, validators optional
+// ---------------------------------------------------------------------------
+
+export function createHandlerWithConfig<
+  TValue = never,
+  TOutput = unknown,
+  TStepConfig = unknown,
+>(
+  definition: {
+    inputValidator?: z.ZodType<TValue>;
+    outputValidator?: z.ZodType<NoInfer<TOutput>>;
+    stepConfigValidator?: z.ZodType<TStepConfig>;
+    handle: (context: {
+      value: TValue;
+      stepConfig: TStepConfig;
+    }) => Promise<TOutput>;
+  },
+  exportName?: string,
+): (config: TStepConfig) => TypedAction<TValue, HandlerOutput<TOutput>>;
+
+// Implementation
+export function createHandlerWithConfig(
+  definition: UntypedHandlerDefinition,
+  exportName?: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any {
+  const filePath = getCallerFilePath();
+  const funcName = exportName ?? "default";
+
+  // The invoke receives [value, config] from All(Identity, Constant(config)).
+  // Build a tuple schema manually — the Rust engine doesn't support draft-07
+  // array-form `items` for tuples, so use `prefixItems` (2020-12 style).
+  const valueSchema = definition.inputValidator
+    ? zodToCheckedJsonSchema(
+        definition.inputValidator,
+        `${filePath}:${funcName} input`,
+      )
+    : {};
+  const configSchema = definition.stepConfigValidator
+    ? zodToCheckedJsonSchema(
+        definition.stepConfigValidator,
+        `${filePath}:${funcName} stepConfig`,
+      )
+    : {};
+  const inputSchema: JSONSchema7 = {
+    type: "array",
+    prefixItems: [valueSchema, configSchema],
+    items: false,
+    minItems: 2,
+    maxItems: 2,
+  } as JSONSchema7;
+  const outputSchema = definition.outputValidator
+    ? zodToCheckedJsonSchema(
+        definition.outputValidator,
+        `${filePath}:${funcName} output`,
+      )
+    : undefined;
+
+  // Internal handle that unpacks the [value, config] tuple from All
+  const internalDefinition: UntypedHandlerDefinition = {
+    handle: ({ value }: { value: unknown }) => {
+      const [pipelineValue, config] = value as [unknown, unknown];
+      return definition.handle({ value: pipelineValue, stepConfig: config });
+    },
+  };
+
+  const invokeAction = typedAction({
+    kind: "Invoke",
+    handler: {
+      kind: "TypeScript",
+      module: filePath,
+      func: funcName,
+      input_schema: inputSchema,
+      ...(outputSchema && { output_schema: outputSchema }),
+    },
+  });
+
+  // Non-enumerable: invisible to JSON.stringify, visible to the worker
+  Object.defineProperty(invokeAction, HANDLER_BRAND, {
+    value: true,
+    enumerable: false,
+  });
+  Object.defineProperty(invokeAction, "__definition", {
+    value: internalDefinition,
+    enumerable: false,
+  });
+
+  // The factory function is the module export, so it must also carry
+  // __definition for the worker to find (the worker imports the module
+  // and accesses the named export, which is this function).
+  const factory = (config: unknown): TypedAction =>
+    typedAction({
+      kind: "Chain",
+      first: {
+        kind: "All",
+        actions: [
+          {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "Identity" } },
+          },
+          {
+            kind: "Invoke",
+            handler: {
+              kind: "Builtin",
+              builtin: { kind: "Constant", value: config },
+            },
+          },
+        ],
+      },
+      rest: invokeAction,
+    });
+
+  Object.defineProperty(factory, HANDLER_BRAND, {
+    value: true,
+    enumerable: false,
+  });
+  Object.defineProperty(factory, "__definition", {
+    value: internalDefinition,
+    enumerable: false,
+  });
+
+  return factory;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+import type { TaggedUnion, OptionDef, ResultDef } from "./ast.js";
+
+export * from "./ast.js";
+export {
+  constant,
+  identity,
+  drop,
+  tag,
+  merge,
+  flatten,
+  extractField,
+  extractIndex,
+  pick,
+  dropResult,
+  withResource,
+  augment,
+  tap,
+  range,
+  Option,
+  Result,
+} from "./builtins.js";
+export * from "./handler.js";
+export { runPipeline } from "./run.js";
+export { zodToCheckedJsonSchema } from "./schema.js";
+
+// Declaration merge: the explicit value exports of Option/Result from builtins
+// shadow the type-only exports from ast's `export *`. Re-declare the generic
+// type aliases here so consumers get both the type and value under one name.
+export type Option<T> = TaggedUnion<OptionDef<T>>;
+export type Result<TValue, TError> = TaggedUnion<ResultDef<TValue, TError>>;

package/src/pipe.ts

@@ -0,0 +1,93 @@
+import {
+  type Action,
+  type PipeIn,
+  type Pipeable,
+  type TypedAction,
+  typedAction,
+} from "./ast.js";
+import { identity } from "./builtins.js";
+
+export function pipe<T1, T2>(a1: Pipeable<T1, T2>): TypedAction<PipeIn<T1>, T2>;
+export function pipe<T1, T2, T3>(
+  a1: Pipeable<T1, T2>,
+  a2: Pipeable<T2, T3>,
+): TypedAction<PipeIn<T1>, T3>;
+export function pipe<T1, T2, T3, T4>(
+  a1: Pipeable<T1, T2>,
+  a2: Pipeable<T2, T3>,
+  a3: Pipeable<T3, T4>,
+): TypedAction<PipeIn<T1>, T4>;
+export function pipe<T1, T2, T3, T4, T5>(
+  a1: Pipeable<T1, T2>,
+  a2: Pipeable<T2, T3>,
+  a3: Pipeable<T3, T4>,
+  a4: Pipeable<T4, T5>,
+): TypedAction<PipeIn<T1>, T5>;
+export function pipe<T1, T2, T3, T4, T5, T6>(
+  a1: Pipeable<T1, T2>,
+  a2: Pipeable<T2, T3>,
+  a3: Pipeable<T3, T4>,
+  a4: Pipeable<T4, T5>,
+  a5: Pipeable<T5, T6>,
+): TypedAction<PipeIn<T1>, T6>;
+export function pipe<T1, T2, T3, T4, T5, T6, T7>(
+  a1: Pipeable<T1, T2>,
+  a2: Pipeable<T2, T3>,
+  a3: Pipeable<T3, T4>,
+  a4: Pipeable<T4, T5>,
+  a5: Pipeable<T5, T6>,
+  a6: Pipeable<T6, T7>,
+): TypedAction<PipeIn<T1>, T7>;
+export function pipe<T1, T2, T3, T4, T5, T6, T7, T8>(
+  a1: Pipeable<T1, T2>,
+  a2: Pipeable<T2, T3>,
+  a3: Pipeable<T3, T4>,
+  a4: Pipeable<T4, T5>,
+  a5: Pipeable<T5, T6>,
+  a6: Pipeable<T6, T7>,
+  a7: Pipeable<T7, T8>,
+): TypedAction<PipeIn<T1>, T8>;
+export function pipe<T1, T2, T3, T4, T5, T6, T7, T8, T9>(
+  a1: Pipeable<T1, T2>,
+  a2: Pipeable<T2, T3>,
+  a3: Pipeable<T3, T4>,
+  a4: Pipeable<T4, T5>,
+  a5: Pipeable<T5, T6>,
+  a6: Pipeable<T6, T7>,
+  a7: Pipeable<T7, T8>,
+  a8: Pipeable<T8, T9>,
+): TypedAction<PipeIn<T1>, T9>;
+export function pipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10>(
+  a1: Pipeable<T1, T2>,
+  a2: Pipeable<T2, T3>,
+  a3: Pipeable<T3, T4>,
+  a4: Pipeable<T4, T5>,
+  a5: Pipeable<T5, T6>,
+  a6: Pipeable<T6, T7>,
+  a7: Pipeable<T7, T8>,
+  a8: Pipeable<T8, T9>,
+  a9: Pipeable<T9, T10>,
+): TypedAction<PipeIn<T1>, T10>;
+export function pipe<T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11>(
+  a1: Pipeable<T1, T2>,
+  a2: Pipeable<T2, T3>,
+  a3: Pipeable<T3, T4>,
+  a4: Pipeable<T4, T5>,
+  a5: Pipeable<T5, T6>,
+  a6: Pipeable<T6, T7>,
+  a7: Pipeable<T7, T8>,
+  a8: Pipeable<T8, T9>,
+  a9: Pipeable<T9, T10>,
+  a10: Pipeable<T10, T11>,
+): TypedAction<PipeIn<T1>, T11>;
+export function pipe(...actions: Action[]): Action {
+  if (actions.length === 0) {
+    return identity;
+  }
+  if (actions.length === 1) {
+    return actions[0];
+  }
+  return actions.reduceRight(
+    (rest, first) => typedAction({ kind: "Chain", first, rest }) as Action,
+  );
+}

package/src/race.ts

@@ -0,0 +1,183 @@
+import {
+  type Action,
+  type Pipeable,
+  type Result,
+  type TypedAction,
+  typedAction,
+  buildRestartBranchAction,
+  TAG_BREAK,
+  IDENTITY,
+} from "./ast.js";
+import {
+  allocateRestartHandlerId,
+  type RestartHandlerId,
+} from "./effect-id.js";
+
+// ---------------------------------------------------------------------------
+// Shared AST fragments
+// ---------------------------------------------------------------------------
+
+const TAG_OK: Action = {
+  kind: "Invoke",
+  handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Ok" } },
+};
+
+const TAG_ERR: Action = {
+  kind: "Invoke",
+  handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Err" } },
+};
+
+/**
+ * `Chain(Tag("Break"), RestartPerform(id))` — shared by race branches.
+ * The winning branch tags its result as Break, then performs. The handler
+ * restarts the body; Branch takes the Break arm (identity), `RestartHandle` exits.
+ */
+function breakPerform(restartHandlerId: RestartHandlerId): Action {
+  return {
+    kind: "Chain",
+    first: TAG_BREAK,
+    rest: { kind: "RestartPerform", restart_handler_id: restartHandlerId },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// race — first branch to complete wins, losers cancelled
+// ---------------------------------------------------------------------------
+
+/**
+ * Run multiple actions concurrently. The first to complete wins; losers
+ * are cancelled during `RestartHandle` frame teardown.
+ *
+ * All branches must have the same input and output type (since either
+ * could win).
+ *
+ * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
+ *   `Chain(Tag("Continue"),`
+ *     `RestartHandle(id, ExtractIndex(0),`
+ *       `Branch({`
+ *         `Continue: All(Chain(a, breakPerform), Chain(b, breakPerform), ...),`
+ *         `Break: identity,`
+ *       `})))`
+ *
+ * First branch to complete tags Break → `RestartPerform` → handler restarts →
+ * Branch takes Break arm → identity → `RestartHandle` exits with winner's value.
+ */
+export function race<TIn, TOut>(
+  ...actions: Pipeable<TIn, TOut>[]
+): TypedAction<TIn, TOut> {
+  const restartHandlerId = allocateRestartHandlerId();
+  const perform = breakPerform(restartHandlerId);
+
+  const branches = actions.map((action) => ({
+    kind: "Chain" as const,
+    first: action as Action,
+    rest: perform,
+  }));
+
+  const allAction: Action = { kind: "All", actions: branches };
+
+  return typedAction(
+    buildRestartBranchAction(restartHandlerId, allAction, IDENTITY),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// sleep — Rust builtin that delays for a fixed duration (passthrough)
+// ---------------------------------------------------------------------------
+
+/**
+ * Sleep for a fixed duration, ignoring input and returning void.
+ *
+ * `ms` is baked into the AST at construction time. Executed by the Rust
+ * scheduler via `tokio::time::sleep` — no subprocess spawned.
+ *
+ * To preserve data across a sleep, use `bindInput`.
+ */
+export function sleep(ms: number): TypedAction<any, never> {
+  return typedAction<any, never>({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Sleep", value: ms } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// dynamicSleep — TypeScript handler for withTimeout (takes ms as input)
+// ---------------------------------------------------------------------------
+
+/** The raw Invoke node for the dynamic sleep handler. */
+const DYNAMIC_SLEEP_INVOKE: Action = {
+  kind: "Invoke",
+  handler: {
+    kind: "TypeScript",
+    module: import.meta.url,
+    func: "dynamicSleep",
+  },
+};
+
+/**
+ * @internal TypeScript handler that takes ms as pipeline input and returns
+ * void after the timer fires. Used by `withTimeout` where the duration
+ * comes from a runtime pipeline, not a build-time constant.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+export function dynamicSleep(): void {}
+Object.defineProperty(dynamicSleep, "__definition", {
+  value: {
+    handle: ({ value }: { value: number }) =>
+      new Promise<void>((resolve) => setTimeout(resolve, value)),
+  },
+  enumerable: false,
+});
+
+// ---------------------------------------------------------------------------
+// withTimeout — race body against sleep, return Result
+// ---------------------------------------------------------------------------
+
+/**
+ * Race the body against a sleep timer. Returns `Result<TOut, void>`:
+ * - Ok(value) if the body completed first
+ * - Err(void) if the timeout fired first
+ *
+ * The `ms` parameter is an AST node that evaluates to the timeout duration
+ * in milliseconds. Use `constant(5000)` for a fixed timeout, or any action
+ * that computes a duration from the pipeline input.
+ *
+ * Built as raw AST rather than through `race()` because each branch wraps
+ * its result differently (Ok vs Err) before the Break+Perform. `race()`
+ * requires homogeneous output types, but withTimeout needs heterogeneous
+ * tagging.
+ *
+ * Same restart+Branch substrate as race: each branch tags Break after
+ * wrapping its result as Ok or Err.
+ */
+export function withTimeout<TIn, TOut>(
+  ms: Pipeable<TIn, number>,
+  body: Pipeable<TIn, TOut>,
+): TypedAction<TIn, Result<TOut, void>> {
+  const restartHandlerId = allocateRestartHandlerId();
+  const perform = breakPerform(restartHandlerId);
+
+  // Branch 1: body → Tag("Ok") → Tag("Break") → RestartPerform
+  const bodyBranch: Action = {
+    kind: "Chain",
+    first: { kind: "Chain", first: body as Action, rest: TAG_OK },
+    rest: perform,
+  };
+
+  // Branch 2: ms → sleep() → Tag("Err") → Tag("Break") → RestartPerform
+  const sleepBranch: Action = {
+    kind: "Chain",
+    first: {
+      kind: "Chain",
+      first: { kind: "Chain", first: ms as Action, rest: DYNAMIC_SLEEP_INVOKE },
+      rest: TAG_ERR,
+    },
+    rest: perform,
+  };
+
+  const allAction: Action = { kind: "All", actions: [bodyBranch, sleepBranch] };
+
+  return typedAction(
+    buildRestartBranchAction(restartHandlerId, allAction, IDENTITY),
+  );
+}