@barnum/barnum 0.2.3 → 0.4.0

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,263 @@
+import { fileURLToPath } from "node:url";
+import type { JSONSchema7 } from "json-schema";
+import type { z } from "zod";
+import { type TypedAction, toAction, typedAction } from "./ast.js";
+import { chain } from "./chain.js";
+import { all } from "./all.js";
+import { constant, identity } from "./builtins/index.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 → void (null at runtime)
+// ---------------------------------------------------------------------------
+
+/**
+ * Handlers that return `Promise<void>` produce `void` output (null at
+ * runtime). This is honest — the handler completes and returns nothing
+ * useful, but execution continues.
+ */
+type HandlerOutput<TOutput> = [TOutput] extends [void] ? void : TOutput;
+
+// ---------------------------------------------------------------------------
+// createHandler — single overload, validators optional
+// ---------------------------------------------------------------------------
+
+export function createHandler<TValue = void, 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 = void,
+  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 =>
+    chain(toAction(all(identity(), constant(config))), toAction(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,37 @@
+import type { TaggedUnion, OptionDef, ResultDef, IteratorDef } from "./ast.js";
+
+export * from "./ast.js";
+export {
+  allObject,
+  asOption,
+  constant,
+  drop,
+  flatten,
+  getField,
+  getIndex,
+  identity,
+  panic,
+  pick,
+  range,
+  splitFirst,
+  splitLast,
+  tag,
+  taggedUnionSchema,
+  withResource,
+  wrapInField,
+} from "./builtins/index.js";
+export { Option, first, last } from "./option.js";
+export { Result } from "./result.js";
+export { Iterator } from "./iterator.js";
+export { runPipeline, type RunPipelineOptions, type LogLevel } 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<"Option", OptionDef<T>>;
+export type Result<TValue, TError> = TaggedUnion<
+  "Result",
+  ResultDef<TValue, TError>
+>;
+export type Iterator<TElement> = TaggedUnion<"Iterator", IteratorDef<TElement>>;

package/src/iterator.ts

@@ -0,0 +1,243 @@
+import {
+  type Iterator as IteratorT,
+  type IteratorDef,
+  type Option as OptionT,
+  type Pipeable,
+  type Result as ResultT,
+  type TypedAction,
+  toAction,
+  typedAction,
+  branch,
+  branchFamily,
+  forEach,
+  loop,
+} from "./ast.js";
+import { chain } from "./chain.js";
+import {
+  constant,
+  drop,
+  flatten,
+  getField,
+  getIndex,
+  identity,
+  slice,
+  splitFirst,
+  splitLast,
+  tag,
+} from "./builtins/index.js";
+import { all } from "./all.js";
+import { Option } from "./option.js";
+import { bindInput } from "./bind.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a single value in an array. `T → T[]`
+ * Implemented as `all(identity())`. May warrant a dedicated builtin later.
+ */
+function wrapInArray<TElement>(): TypedAction<TElement, TElement[]> {
+  return all(identity()) as TypedAction<TElement, TElement[]>;
+}
+
+/**
+ * Normalize any IntoIterator return type to a plain array.
+ * Used inside `.flatMap()` to handle Iterator, Option, Result, and Array returns.
+ */
+const intoIteratorNormalize = branchFamily({
+  Iterator: branch({ Iterator: identity() }),
+  Option: branch({ Some: wrapInArray(), None: constant([]) }),
+  Result: branch({ Ok: wrapInArray(), Err: constant([]) }),
+  Array: identity(),
+});
+
+// ---------------------------------------------------------------------------
+// Iterator namespace
+// ---------------------------------------------------------------------------
+
+export const Iterator = {
+  /** Wrap an array as Iterator. `T[] → Iterator<T>` */
+  fromArray<TElement>(): TypedAction<TElement[], IteratorT<TElement>> {
+    return tag<"Iterator", IteratorDef<TElement>, "Iterator">(
+      "Iterator",
+      "Iterator",
+    );
+  },
+
+  /** Wrap an Option as Iterator. `Option<T> → Iterator<T>` */
+  fromOption<TElement>(): TypedAction<OptionT<TElement>, IteratorT<TElement>> {
+    return branch({
+      Some: chain(wrapInArray<TElement>(), Iterator.fromArray<TElement>()),
+      None: chain(constant<TElement[]>([]), Iterator.fromArray<TElement>()),
+    }) as TypedAction<OptionT<TElement>, IteratorT<TElement>>;
+  },
+
+  /** Wrap a Result as Iterator (Ok kept, Err dropped). `Result<T, E> → Iterator<T>` */
+  fromResult<TElement, TError>(): TypedAction<
+    ResultT<TElement, TError>,
+    IteratorT<TElement>
+  > {
+    return branch({
+      Ok: chain(wrapInArray<TElement>(), Iterator.fromArray<TElement>()),
+      Err: chain(constant<TElement[]>([]), Iterator.fromArray<TElement>()),
+    }) as TypedAction<ResultT<TElement, TError>, IteratorT<TElement>>;
+  },
+
+  /** Unwrap Iterator to array. `Iterator<T> → T[]` */
+  collect<TElement>(): TypedAction<IteratorT<TElement>, TElement[]> {
+    return getField("value") as TypedAction<IteratorT<TElement>, TElement[]>;
+  },
+
+  /** Transform each element. `Iterator<T> → Iterator<U>` */
+  map<TIn, TOut>(
+    action: Pipeable<TIn, TOut>,
+  ): TypedAction<IteratorT<TIn>, IteratorT<TOut>> {
+    return chain(
+      toAction(getField("value")),
+      chain(toAction(forEach(action)), Iterator.fromArray<TOut>()),
+    ) as TypedAction<IteratorT<TIn>, IteratorT<TOut>>;
+  },
+
+  /** Flat-map each element. `f` returns any IntoIterator type. `Iterator<T> → Iterator<U>` */
+  flatMap<TIn, TOut>(
+    action: Pipeable<TIn, unknown>,
+  ): TypedAction<IteratorT<TIn>, IteratorT<TOut>> {
+    return chain(
+      toAction(getField("value")),
+      chain(
+        toAction(forEach(chain(action, intoIteratorNormalize))),
+        chain(toAction(flatten()), Iterator.fromArray<TOut>()),
+      ),
+    ) as TypedAction<IteratorT<TIn>, IteratorT<TOut>>;
+  },
+
+  /** Keep elements where predicate returns true. `Iterator<T> → Iterator<T>` */
+  filter<TElement>(
+    predicate: Pipeable<TElement, boolean>,
+  ): TypedAction<IteratorT<TElement>, IteratorT<TElement>> {
+    return Iterator.flatMap<TElement, TElement>(
+      bindInput<TElement>((element) =>
+        element
+          .then(predicate)
+          .asOption()
+          .branch({
+            Some: element.some(),
+            None: chain(drop, Option.none<TElement>()),
+          }),
+      ),
+    );
+  },
+
+  /** Head/tail decomposition. `Iterator<T> → Option<[T, Iterator<T>]>` */
+  splitFirst<TElement>(): TypedAction<
+    IteratorT<TElement>,
+    OptionT<[TElement, IteratorT<TElement>]>
+  > {
+    return Iterator.collect<TElement>()
+      .then(splitFirst<TElement>())
+      .then(
+        Option.map(
+          all(
+            getIndex<[TElement, TElement[]], 0>(0).unwrap(),
+            getIndex<[TElement, TElement[]], 1>(1).unwrap().iterate(),
+          ),
+        ),
+      );
+  },
+
+  /** Init/last decomposition. `Iterator<T> → Option<[Iterator<T>, T]>` */
+  splitLast<TElement>(): TypedAction<
+    IteratorT<TElement>,
+    OptionT<[IteratorT<TElement>, TElement]>
+  > {
+    return Iterator.collect<TElement>()
+      .then(splitLast<TElement>())
+      .then(
+        Option.map(
+          all(
+            getIndex<[TElement[], TElement], 0>(0).unwrap().iterate(),
+            getIndex<[TElement[], TElement], 1>(1).unwrap(),
+          ),
+        ),
+      );
+  },
+
+  /** Fold elements with accumulator. `Iterator<T> → TAcc` */
+  fold<TElement, TAcc>(
+    init: Pipeable<void, TAcc>,
+    body: Pipeable<[TAcc, TElement], TAcc>,
+  ): TypedAction<IteratorT<TElement>, TAcc> {
+    return Iterator.collect<TElement>().then(
+      bindInput<TElement[]>((elements) =>
+        all(init, elements).then(
+          loop<TAcc, [TAcc, TElement[]]>((recur, done) => {
+            // Re-wrap done to bridge VoidToNull<TAcc> → TAcc (TypeScript
+            // can't simplify the conditional type for generic TAcc).
+            const doneTAcc = typedAction<TAcc, never>(toAction(done));
+
+            // Wrap return with typedAction — branch output inference fails
+            // for generic types inside loop bodies.
+            return typedAction<[TAcc, TElement[]], never>(
+              toAction(
+                bindInput<[TAcc, TElement[]]>((state) => {
+                  const acc = state.getIndex(0).unwrap();
+                  const remaining = state.getIndex(1).unwrap();
+
+                  return remaining.splitFirst().branch({
+                    None: acc.then(doneTAcc),
+                    Some: bindInput<[TElement, TElement[]]>((headTail) => {
+                      const head = headTail.getIndex(0).unwrap();
+                      const tail = headTail.getIndex(1).unwrap();
+
+                      return all(acc, head)
+                        .then(body)
+                        .then(
+                          bindInput<TAcc>((newAcc) =>
+                            all(newAcc, tail).then(recur),
+                          ),
+                        );
+                    }),
+                  });
+                }),
+              ),
+            );
+          }),
+        ),
+      ),
+    );
+  },
+
+  /** Slice elements from start to end. `Iterator<T> → Iterator<T>` */
+  slice<TElement>(
+    start: number,
+    end?: number,
+  ): TypedAction<IteratorT<TElement>, IteratorT<TElement>> {
+    return chain(
+      Iterator.collect<TElement>(),
+      chain(
+        toAction(slice<TElement>(start, end)),
+        Iterator.fromArray<TElement>(),
+      ),
+    );
+  },
+
+  /** First n elements. `Iterator<T> → Iterator<T>` */
+  take<TElement>(
+    n: number,
+  ): TypedAction<IteratorT<TElement>, IteratorT<TElement>> {
+    return Iterator.slice(0, n);
+  },
+
+  /** Drop first n elements. `Iterator<T> → Iterator<T>` */
+  skip<TElement>(
+    n: number,
+  ): TypedAction<IteratorT<TElement>, IteratorT<TElement>> {
+    return Iterator.slice(n);
+  },
+
+  /** Check if iterator is empty. `Iterator<T> → boolean` */
+  isEmpty<TElement>(): TypedAction<IteratorT<TElement>, boolean> {
+    return Iterator.collect<TElement>().splitFirst().isNone();
+  },
+} as const;