@lifi/composer-sdk 0.8.1 → 0.9.0

package/dist/authoring/FlowBuilderCore.d.ts

@@ -1,17 +1,17 @@
-import { Ref, Resource, SolType, BindValue, AppliedGuard, Flow } from '@lifi/compose-spec';
-import { TypedRef, TypedLiteral, InputSchema, InputDecl, TypedGuard, OutputKind } from '../types.js';
-import { InputHandle, OutputHandle, ResourceInputHandle } from './handles.js';
-
+import { InputDecl, InputSchema, OutputKind, TypedGuard, TypedLiteral, TypedRef } from "../types.js";
+import { InputHandle, OutputHandle, ResourceInputHandle } from "./handles.js";
+import { AppliedGuard, BindValue, Flow, Ref, Resource, SolType } from "@lifi/compose-spec";
+//#region src/authoring/FlowBuilderCore.d.ts
 /**
  * Arguments for calling an operation node in a flow.
  */
-interface CallArgs {
-    /** Maps parameter names to input/output handles or raw `$ref` pointers. */
-    readonly bind: Record<string, AnyBindable>;
-    /** Optional operation-specific configuration. */
-    readonly config?: object;
-    /** Optional guards (e.g. slippage checks) applied to this operation's outputs. */
-    readonly guards?: readonly TypedGuard[];
+export interface CallArgs {
+  /** Maps parameter names to input/output handles or raw `$ref` pointers. */
+  readonly bind: Record<string, AnyBindable>;
+  /** Optional operation-specific configuration. */
+  readonly config?: object;
+  /** Optional guards (e.g. slippage checks) applied to this operation's outputs. */
+  readonly guards?: readonly TypedGuard[];
 }
 /**
  * Any value that can be bound to an operation parameter: an input handle, an
@@ -28,16 +28,16 @@ interface CallArgs {
  * Use `raw.ref<T>()` to create a typed ref from a raw path string, and
  * `raw.literal<T>()` to bake in a constant.
  */
-type AnyBindable = InputHandle | OutputHandle | TypedRef | TypedLiteral | Ref;
+export type AnyBindable = InputHandle | OutputHandle | TypedRef | TypedLiteral | Ref;
 /**
  * Provides references to runtime context values available inside a flow.
  * Access via `builder.context`.
  */
-interface ContextAccessor {
-    /** A `$ref` pointing to the transaction sender (signer) address. */
-    readonly sender: TypedRef<'address'>;
-    /** A `$ref` pointing to the on-chain execution (proxy) address. */
-    readonly executionAddress: TypedRef<'address'>;
+export interface ContextAccessor {
+  /** A `$ref` pointing to the transaction sender (signer) address. */
+  readonly sender: TypedRef<"address">;
+  /** A `$ref` pointing to the on-chain execution (proxy) address. */
+  readonly executionAddress: TypedRef<"address">;
 }
 type InputHandleOf<D extends InputDecl> = D extends Resource ? ResourceInputHandle : D extends SolType ? InputHandle<D> : InputHandle;
 /**
@@ -46,19 +46,17 @@ type InputHandleOf<D extends InputDecl> = D extends Resource ? ResourceInputHand
  *
  * @typeParam T - The flow's input schema.
  */
-type InputHandles<T extends InputSchema> = {
-    readonly [K in keyof T]: InputHandleOf<T[K]>;
-};
+export type InputHandles<T extends InputSchema> = { readonly [K in keyof T]: InputHandleOf<T[K]>; };
 /**
  * Options for creating a new flow builder.
  *
  * @typeParam T - The flow's input schema.
  */
-interface FlowOptions<T extends InputSchema> {
-    /** Optional human-readable name for the flow. Defaults to a random UUID. */
-    readonly name?: string;
-    /** Input declarations mapping names to resource or scalar types. */
-    readonly inputs: T;
+export interface FlowOptions<T extends InputSchema> {
+  /** Optional human-readable name for the flow. Defaults to a random UUID. */
+  readonly name?: string;
+  /** Input declarations mapping names to resource or scalar types. */
+  readonly inputs: T;
 }
 /**
  * A Flow document branded with its input schema for type-safe request building.
@@ -66,8 +64,8 @@ interface FlowOptions<T extends InputSchema> {
  * The `__inputs` field is a phantom type — it exists only at compile time for
  * TypeScript inference and is never present at runtime.
  */
-type TypedFlow<T extends InputSchema = InputSchema> = Flow & {
-    readonly __inputs?: T;
+export type TypedFlow<T extends InputSchema = InputSchema> = Flow & {
+  readonly __inputs?: T;
 };
 /**
  * Core flow builder interface providing low-level access to flow construction.
@@ -77,46 +75,44 @@ type TypedFlow<T extends InputSchema = InputSchema> = Flow & {
  *
  * @typeParam T - The flow's input schema.
  */
-interface FlowBuilderCore<T extends InputSchema = InputSchema> {
-    /** Runtime context references (sender address, execution address). */
-    readonly context: ContextAccessor;
-    /** Typed handles for each declared flow input, used to bind inputs to operations. */
-    readonly inputs: InputHandles<T>;
-    /**
-     * Appends an untyped operation node to the flow. This is an escape hatch
-     * for operations not yet covered by the generated methods.
-     *
-     * Use `raw.ref<T>()` to reference this node's outputs in subsequent typed
-     * operations.
-     *
-     * @param id - Unique node identifier within the flow.
-     * @param op - The operation name (e.g. `"custom.vaultQuery"`).
-     * @param args - Bind map, config, and optional guards for the node.
-     * @throws Error if a node with the same `id` already exists in the flow.
-     */
-    readonly untypedOp: (id: string, op: string, args: {
-        readonly bind: Record<string, BindValue>;
-        readonly config: Record<string, unknown>;
-        readonly guards?: readonly AppliedGuard[];
-    }) => void;
-    /** Serialises the builder state into a {@link TypedFlow} document. */
-    readonly build: () => TypedFlow<T>;
+export interface FlowBuilderCore<T extends InputSchema = InputSchema> {
+  /** Runtime context references (sender address, execution address). */
+  readonly context: ContextAccessor;
+  /** Typed handles for each declared flow input, used to bind inputs to operations. */
+  readonly inputs: InputHandles<T>;
+  /**
+   * Appends an untyped operation node to the flow. This is an escape hatch
+   * for operations not yet covered by the generated methods.
+   *
+   * Use `raw.ref<T>()` to reference this node's outputs in subsequent typed
+   * operations.
+   *
+   * @param id - Unique node identifier within the flow.
+   * @param op - The operation name (e.g. `"custom.vaultQuery"`).
+   * @param args - Bind map, config, and optional guards for the node.
+   * @throws Error if a node with the same `id` already exists in the flow.
+   */
+  readonly untypedOp: (id: string, op: string, args: {
+    readonly bind: Record<string, BindValue>;
+    readonly config: Record<string, unknown>;
+    readonly guards?: readonly AppliedGuard[];
+  }) => void;
+  /** Serialises the builder state into a {@link TypedFlow} document. */
+  readonly build: () => TypedFlow<T>;
 }
 /** Maps output port names to their output kind for compile-time and runtime validation. */
-type OutputSpec = Record<string, OutputKind>;
+export type OutputSpec = Record<string, OutputKind>;
 /**
  * Maps each output family's port name to the config key that sizes it: an
  * array (one instance per element) or a non-negative integer count.
  * A family port is also listed in the {@link OutputSpec}, as `'resource'`.
  */
-type FamilySpec = Readonly<Record<string, string>>;
+export type FamilySpec = Readonly<Record<string, string>>;
 /** The handles `call` returns for an {@link OutputSpec} and its families. */
-type OutputHandles<O extends OutputSpec, F extends FamilySpec> = {
-    readonly [K in keyof O & string]: K extends keyof F ? readonly OutputHandle<'resource'>[] : OutputHandle<O[K]>;
-};
+export type OutputHandles<O extends OutputSpec, F extends FamilySpec> = { readonly [K in keyof O & string]: K extends keyof F ? readonly OutputHandle<"resource">[] : OutputHandle<O[K]>; };
 /** Internal interface exposed to bindGeneratedOps — not part of the public API. */
-interface FlowBuilderInternal<T extends InputSchema = InputSchema> extends FlowBuilderCore<T> {
-    readonly call: <O extends OutputSpec, F extends FamilySpec = Record<never, string>>(nodeId: string, op: string, args: CallArgs, outputs: O, families?: F) => OutputHandles<O, F>;
+export interface FlowBuilderInternal<T extends InputSchema = InputSchema> extends FlowBuilderCore<T> {
+  readonly call: <O extends OutputSpec, F extends FamilySpec = Record<never, string>>(nodeId: string, op: string, args: CallArgs, outputs: O, families?: F) => OutputHandles<O, F>;
 }
 /**
  * Creates a new flow builder targeting the given chain.
@@ -126,6 +122,7 @@ interface FlowBuilderInternal<T extends InputSchema = InputSchema> extends FlowB
  * @returns A {@link FlowBuilderInternal} instance.
  * @internal
  */
-declare const createFlowBuilderCore: <T extends InputSchema>(chainId: number, options: FlowOptions<T>) => FlowBuilderInternal<T>;
-
-export { type AnyBindable, type CallArgs, type ContextAccessor, type FamilySpec, type FlowBuilderCore, type FlowBuilderInternal, type FlowOptions, type InputHandles, type OutputHandles, type OutputSpec, type TypedFlow, createFlowBuilderCore };
+export declare const createFlowBuilderCore: <T extends InputSchema>(chainId: number, options: FlowOptions<T>) => FlowBuilderInternal<T>;
+//#endregion
+export {};
+//# sourceMappingURL=FlowBuilderCore.d.ts.map

package/dist/authoring/FlowBuilderCore.js

@@ -1,103 +1,105 @@
-import {
-  familySize,
-  instancePortName
-} from "@lifi/compose-spec";
 import { toBindValue } from "./handles.js";
 import { ref } from "./raw.js";
+import { familySize, instancePortName } from "@lifi/compose-spec";
+//#region src/authoring/FlowBuilderCore.ts
 const isResource = (decl) => typeof decl === "object" && decl !== null && "kind" in decl;
+/**
+* Creates a new flow builder targeting the given chain.
+*
+* @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).
+* @param options - Flow configuration including input declarations.
+* @returns A {@link FlowBuilderInternal} instance.
+* @internal
+*/
 const createFlowBuilderCore = (chainId, options) => {
-  const id = options.name ?? crypto.randomUUID();
-  const flowInputs = [];
-  const nodes = [];
-  const nodeIds = /* @__PURE__ */ new Set();
-  const inputHandles = {};
-  for (const [name, decl] of Object.entries(options.inputs)) {
-    if (isResource(decl)) {
-      if (decl.chainId !== chainId) {
-        throw new Error(
-          `Input "${name}" has chainId ${decl.chainId} but flow targets chain ${chainId}`
-        );
-      }
-      flowInputs.push({ name, resource: decl });
-      inputHandles[name] = { _tag: "input", inputName: name, resource: decl };
-    } else {
-      flowInputs.push({ name, type: decl });
-      inputHandles[name] = { _tag: "input", inputName: name };
-    }
-  }
-  const call = (nodeId, op, args, outputs, families) => {
-    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
-    nodeIds.add(nodeId);
-    const bind = {};
-    for (const [key, val] of Object.entries(args.bind)) {
-      bind[key] = toBindValue(val);
-    }
-    const config = args.config ?? {};
-    const node = {
-      id: nodeId,
-      op,
-      bind,
-      config,
-      ...args.guards && args.guards.length > 0 && { guards: args.guards }
-    };
-    nodes.push(node);
-    const outputHandle = (portName) => ({
-      _tag: "output",
-      nodeId,
-      portName
-    });
-    return new Proxy({}, {
-      get: (_target, prop) => {
-        if (typeof prop !== "string" || prop === "then") return void 0;
-        if (!Object.hasOwn(outputs, prop)) {
-          throw new Error(
-            `Op "${op}" has no output port "${prop}". Valid ports: ${Object.keys(
-              outputs
-            ).join(", ")}`
-          );
-        }
-        const countFrom = families?.[prop];
-        if (countFrom === void 0) return outputHandle(prop);
-        const size = familySize({ name: prop, countFrom }, config);
-        return Array.from(
-          { length: size },
-          (_, index) => outputHandle(instancePortName(prop, index))
-        );
-      }
-    });
-  };
-  const untypedOp = (nodeId, op, args) => {
-    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
-    nodeIds.add(nodeId);
-    const node = {
-      id: nodeId,
-      op,
-      bind: args.bind,
-      config: args.config,
-      ...args.guards && args.guards.length > 0 && { guards: args.guards }
-    };
-    nodes.push(node);
-  };
-  const build = () => ({
-    version: 1,
-    id,
-    chainId,
-    inputs: [...flowInputs],
-    nodes: [...nodes]
-  });
-  const context = {
-    sender: ref("context.sender"),
-    executionAddress: ref("context.executionAddress")
-  };
-  return {
-    context,
-    inputs: inputHandles,
-    call,
-    untypedOp,
-    build
-  };
-};
-export {
-  createFlowBuilderCore
+	const id = options.name ?? crypto.randomUUID();
+	const flowInputs = [];
+	const nodes = [];
+	const nodeIds = /* @__PURE__ */ new Set();
+	const inputHandles = {};
+	for (const [name, decl] of Object.entries(options.inputs)) if (isResource(decl)) {
+		if (decl.chainId !== chainId) throw new Error(`Input "${name}" has chainId ${decl.chainId} but flow targets chain ${chainId}`);
+		flowInputs.push({
+			name,
+			resource: decl
+		});
+		inputHandles[name] = {
+			_tag: "input",
+			inputName: name,
+			resource: decl
+		};
+	} else {
+		flowInputs.push({
+			name,
+			type: decl
+		});
+		inputHandles[name] = {
+			_tag: "input",
+			inputName: name
+		};
+	}
+	const call = (nodeId, op, args, outputs, families) => {
+		if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
+		nodeIds.add(nodeId);
+		const bind = {};
+		for (const [key, val] of Object.entries(args.bind)) bind[key] = toBindValue(val);
+		const config = args.config ?? {};
+		const node = {
+			id: nodeId,
+			op,
+			bind,
+			config,
+			...args.guards && args.guards.length > 0 && { guards: args.guards }
+		};
+		nodes.push(node);
+		const outputHandle = (portName) => ({
+			_tag: "output",
+			nodeId,
+			portName
+		});
+		return new Proxy({}, { get: (_target, prop) => {
+			if (typeof prop !== "string" || prop === "then") return void 0;
+			if (!Object.hasOwn(outputs, prop)) throw new Error(`Op "${op}" has no output port "${prop}". Valid ports: ${Object.keys(outputs).join(", ")}`);
+			const countFrom = families?.[prop];
+			if (countFrom === void 0) return outputHandle(prop);
+			const size = familySize({
+				name: prop,
+				countFrom
+			}, config);
+			return Array.from({ length: size }, (_, index) => outputHandle(instancePortName(prop, index)));
+		} });
+	};
+	const untypedOp = (nodeId, op, args) => {
+		if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
+		nodeIds.add(nodeId);
+		const node = {
+			id: nodeId,
+			op,
+			bind: args.bind,
+			config: args.config,
+			...args.guards && args.guards.length > 0 && { guards: args.guards }
+		};
+		nodes.push(node);
+	};
+	const build = () => ({
+		version: 1,
+		id,
+		chainId,
+		inputs: [...flowInputs],
+		nodes: [...nodes]
+	});
+	return {
+		context: {
+			sender: ref("context.sender"),
+			executionAddress: ref("context.executionAddress")
+		},
+		inputs: inputHandles,
+		call,
+		untypedOp,
+		build
+	};
 };
+//#endregion
+export { createFlowBuilderCore };
+
 //# sourceMappingURL=FlowBuilderCore.js.map

package/dist/authoring/FlowBuilderCore.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/authoring/FlowBuilderCore.ts"],"sourcesContent":["import {\n  type AppliedGuard,\n  type BindValue,\n  type Call,\n  familySize,\n  type Flow,\n  type FlowInput,\n  instancePortName,\n  type Ref,\n  type Resource,\n  type SolType,\n} from '@lifi/compose-spec';\n\nimport type {\n  InputDecl,\n  InputSchema,\n  OutputKind,\n  TypedGuard,\n  TypedLiteral,\n  TypedRef,\n} from '../types.js';\n\nimport type {\n  InputHandle,\n  OutputHandle,\n  ResourceInputHandle,\n} from './handles.js';\nimport { toBindValue } from './handles.js';\nimport { ref } from './raw.js';\n\n/**\n * Arguments for calling an operation node in a flow.\n */\nexport interface CallArgs {\n  /** Maps parameter names to input/output handles or raw `$ref` pointers. */\n  readonly bind: Record<string, AnyBindable>;\n  /** Optional operation-specific configuration. */\n  readonly config?: object;\n  /** Optional guards (e.g. slippage checks) applied to this operation's outputs. */\n  readonly guards?: readonly TypedGuard[];\n}\n\n/**\n * Any value that can be bound to an operation parameter: an input handle, an\n * output handle from a previous operation, a typed `$ref` pointer, a typed\n * literal, or a bare `{ $ref }` pointer.\n *\n * This is the bind type of {@link FlowBuilderInternal.call}, the entry point\n * every generated operation lowers into — not a public authoring surface. A\n * bare `Ref` belongs here because a generated op resolves its own typed binds\n * to wire refs (`toBindRef` in `./signatureArgs.js`) before calling it. Typed\n * operation slots use `Bindable<T>`, which rejects a bare `Ref`; see\n * `RefBindable` in `./handles.js`.\n *\n * Use `raw.ref<T>()` to create a typed ref from a raw path string, and\n * `raw.literal<T>()` to bake in a constant.\n */\nexport type AnyBindable =\n  InputHandle | OutputHandle | TypedRef | TypedLiteral | Ref;\n\n/**\n * Provides references to runtime context values available inside a flow.\n * Access via `builder.context`.\n */\nexport interface ContextAccessor {\n  /** A `$ref` pointing to the transaction sender (signer) address. */\n  readonly sender: TypedRef<'address'>;\n  /** A `$ref` pointing to the on-chain execution (proxy) address. */\n  readonly executionAddress: TypedRef<'address'>;\n}\n\ntype InputHandleOf<D extends InputDecl> = D extends Resource\n  ? ResourceInputHandle\n  : D extends SolType\n    ? InputHandle<D>\n    : InputHandle;\n\n/**\n * A mapped type that converts an input schema into typed handles.\n * Resource inputs produce {@link ResourceInputHandle}; scalar inputs produce {@link InputHandle}.\n *\n * @typeParam T - The flow's input schema.\n */\nexport type InputHandles<T extends InputSchema> = {\n  readonly [K in keyof T]: InputHandleOf<T[K]>;\n};\n\n/**\n * Options for creating a new flow builder.\n *\n * @typeParam T - The flow's input schema.\n */\nexport interface FlowOptions<T extends InputSchema> {\n  /** Optional human-readable name for the flow. Defaults to a random UUID. */\n  readonly name?: string;\n  /** Input declarations mapping names to resource or scalar types. */\n  readonly inputs: T;\n}\n\n/**\n * A Flow document branded with its input schema for type-safe request building.\n *\n * The `__inputs` field is a phantom type — it exists only at compile time for\n * TypeScript inference and is never present at runtime.\n */\nexport type TypedFlow<T extends InputSchema = InputSchema> = Flow & {\n  readonly __inputs?: T;\n};\n\n/**\n * Core flow builder interface providing low-level access to flow construction.\n *\n * For most use cases, prefer the {@link FlowBuilder} type returned by `sdk.flow()`\n * which adds generated operation methods and a `compile` method.\n *\n * @typeParam T - The flow's input schema.\n */\nexport interface FlowBuilderCore<T extends InputSchema = InputSchema> {\n  /** Runtime context references (sender address, execution address). */\n  readonly context: ContextAccessor;\n  /** Typed handles for each declared flow input, used to bind inputs to operations. */\n  readonly inputs: InputHandles<T>;\n  /**\n   * Appends an untyped operation node to the flow. This is an escape hatch\n   * for operations not yet covered by the generated methods.\n   *\n   * Use `raw.ref<T>()` to reference this node's outputs in subsequent typed\n   * operations.\n   *\n   * @param id - Unique node identifier within the flow.\n   * @param op - The operation name (e.g. `\"custom.vaultQuery\"`).\n   * @param args - Bind map, config, and optional guards for the node.\n   * @throws Error if a node with the same `id` already exists in the flow.\n   */\n  readonly untypedOp: (\n    id: string,\n    op: string,\n    args: {\n      readonly bind: Record<string, BindValue>;\n      readonly config: Record<string, unknown>;\n      readonly guards?: readonly AppliedGuard[];\n    },\n  ) => void;\n  /** Serialises the builder state into a {@link TypedFlow} document. */\n  readonly build: () => TypedFlow<T>;\n}\n\n/** Maps output port names to their output kind for compile-time and runtime validation. */\nexport type OutputSpec = Record<string, OutputKind>;\n\n/**\n * Maps each output family's port name to the config key that sizes it: an\n * array (one instance per element) or a non-negative integer count.\n * A family port is also listed in the {@link OutputSpec}, as `'resource'`.\n */\nexport type FamilySpec = Readonly<Record<string, string>>;\n\n/** The handles `call` returns for an {@link OutputSpec} and its families. */\nexport type OutputHandles<O extends OutputSpec, F extends FamilySpec> = {\n  readonly [K in keyof O & string]: K extends keyof F\n    ? readonly OutputHandle<'resource'>[]\n    : OutputHandle<O[K]>;\n};\n\n/** Internal interface exposed to bindGeneratedOps — not part of the public API. */\nexport interface FlowBuilderInternal<\n  T extends InputSchema = InputSchema,\n> extends FlowBuilderCore<T> {\n  readonly call: <\n    O extends OutputSpec,\n    F extends FamilySpec = Record<never, string>,\n  >(\n    nodeId: string,\n    op: string,\n    args: CallArgs,\n    outputs: O,\n    families?: F,\n  ) => OutputHandles<O, F>;\n}\n\nconst isResource = (decl: InputDecl): decl is Resource =>\n  typeof decl === 'object' && decl !== null && 'kind' in decl;\n\n/**\n * Creates a new flow builder targeting the given chain.\n *\n * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).\n * @param options - Flow configuration including input declarations.\n * @returns A {@link FlowBuilderInternal} instance.\n * @internal\n */\nexport const createFlowBuilderCore = <T extends InputSchema>(\n  chainId: number,\n  options: FlowOptions<T>,\n): FlowBuilderInternal<T> => {\n  const id = options.name ?? crypto.randomUUID();\n  const flowInputs: FlowInput[] = [];\n  const nodes: Call[] = [];\n  const nodeIds = new Set<string>();\n\n  const inputHandles = {} as Record<string, InputHandle | ResourceInputHandle>;\n  for (const [name, decl] of Object.entries(options.inputs)) {\n    if (isResource(decl)) {\n      if (decl.chainId !== chainId) {\n        throw new Error(\n          `Input \"${name}\" has chainId ${decl.chainId} but flow targets chain ${chainId}`,\n        );\n      }\n      flowInputs.push({ name, resource: decl });\n      inputHandles[name] = { _tag: 'input', inputName: name, resource: decl };\n    } else {\n      flowInputs.push({ name, type: decl });\n      inputHandles[name] = { _tag: 'input', inputName: name };\n    }\n  }\n\n  const call = <\n    O extends OutputSpec,\n    F extends FamilySpec = Record<never, string>,\n  >(\n    nodeId: string,\n    op: string,\n    args: CallArgs,\n    outputs: O,\n    families?: F,\n  ): OutputHandles<O, F> => {\n    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: \"${nodeId}\"`);\n    nodeIds.add(nodeId);\n\n    const bind: Record<string, BindValue> = {};\n    for (const [key, val] of Object.entries(args.bind)) {\n      bind[key] = toBindValue(val);\n    }\n\n    const config = (args.config ?? {}) as Record<string, unknown>;\n    const node: Call = {\n      id: nodeId,\n      op,\n      bind,\n      config,\n      ...(args.guards && args.guards.length > 0 && { guards: args.guards }),\n    };\n    nodes.push(node);\n\n    const outputHandle = (portName: string): OutputHandle => ({\n      _tag: 'output',\n      nodeId,\n      portName,\n    });\n    return new Proxy({} as OutputHandles<O, F>, {\n      get: (\n        _target,\n        prop,\n      ): OutputHandle | readonly OutputHandle[] | undefined => {\n        if (typeof prop !== 'string' || prop === 'then') return undefined;\n        // Own-key only: the trap sees every property a consumer reads, so `in`\n        // would answer a handle for `toString` or `constructor` instead of the\n        // unknown-port error.\n        if (!Object.hasOwn(outputs, prop)) {\n          throw new Error(\n            `Op \"${op}\" has no output port \"${prop}\". Valid ports: ${Object.keys(\n              outputs,\n            ).join(', ')}`,\n          );\n        }\n        const countFrom = families?.[prop];\n        if (countFrom === undefined) return outputHandle(prop);\n        const size = familySize({ name: prop, countFrom }, config);\n        return Array.from({ length: size }, (_, index) =>\n          outputHandle(instancePortName(prop, index)),\n        );\n      },\n    });\n  };\n\n  const untypedOp = (\n    nodeId: string,\n    op: string,\n    args: {\n      readonly bind: Record<string, BindValue>;\n      readonly config: Record<string, unknown>;\n      readonly guards?: readonly AppliedGuard[];\n    },\n  ): void => {\n    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: \"${nodeId}\"`);\n    nodeIds.add(nodeId);\n    const node: Call = {\n      id: nodeId,\n      op,\n      bind: args.bind,\n      config: args.config,\n      ...(args.guards && args.guards.length > 0 && { guards: args.guards }),\n    };\n    nodes.push(node);\n  };\n\n  const build = (): TypedFlow<T> => ({\n    version: 1,\n    id,\n    chainId,\n    inputs: [...flowInputs],\n    nodes: [...nodes],\n  });\n\n  const context: ContextAccessor = {\n    sender: ref<'address'>('context.sender'),\n    executionAddress: ref<'address'>('context.executionAddress'),\n  };\n\n  return {\n    context,\n    inputs: inputHandles as InputHandles<T>,\n    call,\n    untypedOp,\n    build,\n  };\n};\n"],"mappings":"AAAA;AAAA,EAIE;AAAA,EAGA;AAAA,OAIK;AAgBP,SAAS,mBAAmB;AAC5B,SAAS,WAAW;AAwJpB,MAAM,aAAa,CAAC,SAClB,OAAO,SAAS,YAAY,SAAS,QAAQ,UAAU;AAUlD,MAAM,wBAAwB,CACnC,SACA,YAC2B;AAC3B,QAAM,KAAK,QAAQ,QAAQ,OAAO,WAAW;AAC7C,QAAM,aAA0B,CAAC;AACjC,QAAM,QAAgB,CAAC;AACvB,QAAM,UAAU,oBAAI,IAAY;AAEhC,QAAM,eAAe,CAAC;AACtB,aAAW,CAAC,MAAM,IAAI,KAAK,OAAO,QAAQ,QAAQ,MAAM,GAAG;AACzD,QAAI,WAAW,IAAI,GAAG;AACpB,UAAI,KAAK,YAAY,SAAS;AAC5B,cAAM,IAAI;AAAA,UACR,UAAU,IAAI,iBAAiB,KAAK,OAAO,2BAA2B,OAAO;AAAA,QAC/E;AAAA,MACF;AACA,iBAAW,KAAK,EAAE,MAAM,UAAU,KAAK,CAAC;AACxC,mBAAa,IAAI,IAAI,EAAE,MAAM,SAAS,WAAW,MAAM,UAAU,KAAK;AAAA,IACxE,OAAO;AACL,iBAAW,KAAK,EAAE,MAAM,MAAM,KAAK,CAAC;AACpC,mBAAa,IAAI,IAAI,EAAE,MAAM,SAAS,WAAW,KAAK;AAAA,IACxD;AAAA,EACF;AAEA,QAAM,OAAO,CAIX,QACA,IACA,MACA,SACA,aACwB;AACxB,QAAI,QAAQ,IAAI,MAAM,EAAG,OAAM,IAAI,MAAM,uBAAuB,MAAM,GAAG;AACzE,YAAQ,IAAI,MAAM;AAElB,UAAM,OAAkC,CAAC;AACzC,eAAW,CAAC,KAAK,GAAG,KAAK,OAAO,QAAQ,KAAK,IAAI,GAAG;AAClD,WAAK,GAAG,IAAI,YAAY,GAAG;AAAA,IAC7B;AAEA,UAAM,SAAU,KAAK,UAAU,CAAC;AAChC,UAAM,OAAa;AAAA,MACjB,IAAI;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAI,KAAK,UAAU,KAAK,OAAO,SAAS,KAAK,EAAE,QAAQ,KAAK,OAAO;AAAA,IACrE;AACA,UAAM,KAAK,IAAI;AAEf,UAAM,eAAe,CAAC,cAAoC;AAAA,MACxD,MAAM;AAAA,MACN;AAAA,MACA;AAAA,IACF;AACA,WAAO,IAAI,MAAM,CAAC,GAA0B;AAAA,MAC1C,KAAK,CACH,SACA,SACuD;AACvD,YAAI,OAAO,SAAS,YAAY,SAAS,OAAQ,QAAO;AAIxD,YAAI,CAAC,OAAO,OAAO,SAAS,IAAI,GAAG;AACjC,gBAAM,IAAI;AAAA,YACR,OAAO,EAAE,yBAAyB,IAAI,mBAAmB,OAAO;AAAA,cAC9D;AAAA,YACF,EAAE,KAAK,IAAI,CAAC;AAAA,UACd;AAAA,QACF;AACA,cAAM,YAAY,WAAW,IAAI;AACjC,YAAI,cAAc,OAAW,QAAO,aAAa,IAAI;AACrD,cAAM,OAAO,WAAW,EAAE,MAAM,MAAM,UAAU,GAAG,MAAM;AACzD,eAAO,MAAM;AAAA,UAAK,EAAE,QAAQ,KAAK;AAAA,UAAG,CAAC,GAAG,UACtC,aAAa,iBAAiB,MAAM,KAAK,CAAC;AAAA,QAC5C;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH;AAEA,QAAM,YAAY,CAChB,QACA,IACA,SAKS;AACT,QAAI,QAAQ,IAAI,MAAM,EAAG,OAAM,IAAI,MAAM,uBAAuB,MAAM,GAAG;AACzE,YAAQ,IAAI,MAAM;AAClB,UAAM,OAAa;AAAA,MACjB,IAAI;AAAA,MACJ;AAAA,MACA,MAAM,KAAK;AAAA,MACX,QAAQ,KAAK;AAAA,MACb,GAAI,KAAK,UAAU,KAAK,OAAO,SAAS,KAAK,EAAE,QAAQ,KAAK,OAAO;AAAA,IACrE;AACA,UAAM,KAAK,IAAI;AAAA,EACjB;AAEA,QAAM,QAAQ,OAAqB;AAAA,IACjC,SAAS;AAAA,IACT;AAAA,IACA;AAAA,IACA,QAAQ,CAAC,GAAG,UAAU;AAAA,IACtB,OAAO,CAAC,GAAG,KAAK;AAAA,EAClB;AAEA,QAAM,UAA2B;AAAA,IAC/B,QAAQ,IAAe,gBAAgB;AAAA,IACvC,kBAAkB,IAAe,0BAA0B;AAAA,EAC7D;AAEA,SAAO;AAAA,IACL;AAAA,IACA,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}
+{"version":3,"file":"FlowBuilderCore.js","names":[],"sources":["../../src/authoring/FlowBuilderCore.ts"],"sourcesContent":["import {\n  type AppliedGuard,\n  type BindValue,\n  type Call,\n  familySize,\n  type Flow,\n  type FlowInput,\n  instancePortName,\n  type Ref,\n  type Resource,\n  type SolType,\n} from '@lifi/compose-spec';\n\nimport type {\n  InputDecl,\n  InputSchema,\n  OutputKind,\n  TypedGuard,\n  TypedLiteral,\n  TypedRef,\n} from '../types.js';\n\nimport type {\n  InputHandle,\n  OutputHandle,\n  ResourceInputHandle,\n} from './handles.js';\nimport { toBindValue } from './handles.js';\nimport { ref } from './raw.js';\n\n/**\n * Arguments for calling an operation node in a flow.\n */\nexport interface CallArgs {\n  /** Maps parameter names to input/output handles or raw `$ref` pointers. */\n  readonly bind: Record<string, AnyBindable>;\n  /** Optional operation-specific configuration. */\n  readonly config?: object;\n  /** Optional guards (e.g. slippage checks) applied to this operation's outputs. */\n  readonly guards?: readonly TypedGuard[];\n}\n\n/**\n * Any value that can be bound to an operation parameter: an input handle, an\n * output handle from a previous operation, a typed `$ref` pointer, a typed\n * literal, or a bare `{ $ref }` pointer.\n *\n * This is the bind type of {@link FlowBuilderInternal.call}, the entry point\n * every generated operation lowers into — not a public authoring surface. A\n * bare `Ref` belongs here because a generated op resolves its own typed binds\n * to wire refs (`toBindRef` in `./signatureArgs.js`) before calling it. Typed\n * operation slots use `Bindable<T>`, which rejects a bare `Ref`; see\n * `RefBindable` in `./handles.js`.\n *\n * Use `raw.ref<T>()` to create a typed ref from a raw path string, and\n * `raw.literal<T>()` to bake in a constant.\n */\nexport type AnyBindable =\n  InputHandle | OutputHandle | TypedRef | TypedLiteral | Ref;\n\n/**\n * Provides references to runtime context values available inside a flow.\n * Access via `builder.context`.\n */\nexport interface ContextAccessor {\n  /** A `$ref` pointing to the transaction sender (signer) address. */\n  readonly sender: TypedRef<'address'>;\n  /** A `$ref` pointing to the on-chain execution (proxy) address. */\n  readonly executionAddress: TypedRef<'address'>;\n}\n\ntype InputHandleOf<D extends InputDecl> = D extends Resource\n  ? ResourceInputHandle\n  : D extends SolType\n    ? InputHandle<D>\n    : InputHandle;\n\n/**\n * A mapped type that converts an input schema into typed handles.\n * Resource inputs produce {@link ResourceInputHandle}; scalar inputs produce {@link InputHandle}.\n *\n * @typeParam T - The flow's input schema.\n */\nexport type InputHandles<T extends InputSchema> = {\n  readonly [K in keyof T]: InputHandleOf<T[K]>;\n};\n\n/**\n * Options for creating a new flow builder.\n *\n * @typeParam T - The flow's input schema.\n */\nexport interface FlowOptions<T extends InputSchema> {\n  /** Optional human-readable name for the flow. Defaults to a random UUID. */\n  readonly name?: string;\n  /** Input declarations mapping names to resource or scalar types. */\n  readonly inputs: T;\n}\n\n/**\n * A Flow document branded with its input schema for type-safe request building.\n *\n * The `__inputs` field is a phantom type — it exists only at compile time for\n * TypeScript inference and is never present at runtime.\n */\nexport type TypedFlow<T extends InputSchema = InputSchema> = Flow & {\n  readonly __inputs?: T;\n};\n\n/**\n * Core flow builder interface providing low-level access to flow construction.\n *\n * For most use cases, prefer the {@link FlowBuilder} type returned by `sdk.flow()`\n * which adds generated operation methods and a `compile` method.\n *\n * @typeParam T - The flow's input schema.\n */\nexport interface FlowBuilderCore<T extends InputSchema = InputSchema> {\n  /** Runtime context references (sender address, execution address). */\n  readonly context: ContextAccessor;\n  /** Typed handles for each declared flow input, used to bind inputs to operations. */\n  readonly inputs: InputHandles<T>;\n  /**\n   * Appends an untyped operation node to the flow. This is an escape hatch\n   * for operations not yet covered by the generated methods.\n   *\n   * Use `raw.ref<T>()` to reference this node's outputs in subsequent typed\n   * operations.\n   *\n   * @param id - Unique node identifier within the flow.\n   * @param op - The operation name (e.g. `\"custom.vaultQuery\"`).\n   * @param args - Bind map, config, and optional guards for the node.\n   * @throws Error if a node with the same `id` already exists in the flow.\n   */\n  readonly untypedOp: (\n    id: string,\n    op: string,\n    args: {\n      readonly bind: Record<string, BindValue>;\n      readonly config: Record<string, unknown>;\n      readonly guards?: readonly AppliedGuard[];\n    },\n  ) => void;\n  /** Serialises the builder state into a {@link TypedFlow} document. */\n  readonly build: () => TypedFlow<T>;\n}\n\n/** Maps output port names to their output kind for compile-time and runtime validation. */\nexport type OutputSpec = Record<string, OutputKind>;\n\n/**\n * Maps each output family's port name to the config key that sizes it: an\n * array (one instance per element) or a non-negative integer count.\n * A family port is also listed in the {@link OutputSpec}, as `'resource'`.\n */\nexport type FamilySpec = Readonly<Record<string, string>>;\n\n/** The handles `call` returns for an {@link OutputSpec} and its families. */\nexport type OutputHandles<O extends OutputSpec, F extends FamilySpec> = {\n  readonly [K in keyof O & string]: K extends keyof F\n    ? readonly OutputHandle<'resource'>[]\n    : OutputHandle<O[K]>;\n};\n\n/** Internal interface exposed to bindGeneratedOps — not part of the public API. */\nexport interface FlowBuilderInternal<\n  T extends InputSchema = InputSchema,\n> extends FlowBuilderCore<T> {\n  readonly call: <\n    O extends OutputSpec,\n    F extends FamilySpec = Record<never, string>,\n  >(\n    nodeId: string,\n    op: string,\n    args: CallArgs,\n    outputs: O,\n    families?: F,\n  ) => OutputHandles<O, F>;\n}\n\nconst isResource = (decl: InputDecl): decl is Resource =>\n  typeof decl === 'object' && decl !== null && 'kind' in decl;\n\n/**\n * Creates a new flow builder targeting the given chain.\n *\n * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).\n * @param options - Flow configuration including input declarations.\n * @returns A {@link FlowBuilderInternal} instance.\n * @internal\n */\nexport const createFlowBuilderCore = <T extends InputSchema>(\n  chainId: number,\n  options: FlowOptions<T>,\n): FlowBuilderInternal<T> => {\n  const id = options.name ?? crypto.randomUUID();\n  const flowInputs: FlowInput[] = [];\n  const nodes: Call[] = [];\n  const nodeIds = new Set<string>();\n\n  const inputHandles = {} as Record<string, InputHandle | ResourceInputHandle>;\n  for (const [name, decl] of Object.entries(options.inputs)) {\n    if (isResource(decl)) {\n      if (decl.chainId !== chainId) {\n        throw new Error(\n          `Input \"${name}\" has chainId ${decl.chainId} but flow targets chain ${chainId}`,\n        );\n      }\n      flowInputs.push({ name, resource: decl });\n      inputHandles[name] = { _tag: 'input', inputName: name, resource: decl };\n    } else {\n      flowInputs.push({ name, type: decl });\n      inputHandles[name] = { _tag: 'input', inputName: name };\n    }\n  }\n\n  const call = <\n    O extends OutputSpec,\n    F extends FamilySpec = Record<never, string>,\n  >(\n    nodeId: string,\n    op: string,\n    args: CallArgs,\n    outputs: O,\n    families?: F,\n  ): OutputHandles<O, F> => {\n    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: \"${nodeId}\"`);\n    nodeIds.add(nodeId);\n\n    const bind: Record<string, BindValue> = {};\n    for (const [key, val] of Object.entries(args.bind)) {\n      bind[key] = toBindValue(val);\n    }\n\n    const config = (args.config ?? {}) as Record<string, unknown>;\n    const node: Call = {\n      id: nodeId,\n      op,\n      bind,\n      config,\n      ...(args.guards && args.guards.length > 0 && { guards: args.guards }),\n    };\n    nodes.push(node);\n\n    const outputHandle = (portName: string): OutputHandle => ({\n      _tag: 'output',\n      nodeId,\n      portName,\n    });\n    return new Proxy({} as OutputHandles<O, F>, {\n      get: (\n        _target,\n        prop,\n      ): OutputHandle | readonly OutputHandle[] | undefined => {\n        if (typeof prop !== 'string' || prop === 'then') return undefined;\n        // Own-key only: the trap sees every property a consumer reads, so `in`\n        // would answer a handle for `toString` or `constructor` instead of the\n        // unknown-port error.\n        if (!Object.hasOwn(outputs, prop)) {\n          throw new Error(\n            `Op \"${op}\" has no output port \"${prop}\". Valid ports: ${Object.keys(\n              outputs,\n            ).join(', ')}`,\n          );\n        }\n        const countFrom = families?.[prop];\n        if (countFrom === undefined) return outputHandle(prop);\n        const size = familySize({ name: prop, countFrom }, config);\n        return Array.from({ length: size }, (_, index) =>\n          outputHandle(instancePortName(prop, index)),\n        );\n      },\n    });\n  };\n\n  const untypedOp = (\n    nodeId: string,\n    op: string,\n    args: {\n      readonly bind: Record<string, BindValue>;\n      readonly config: Record<string, unknown>;\n      readonly guards?: readonly AppliedGuard[];\n    },\n  ): void => {\n    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: \"${nodeId}\"`);\n    nodeIds.add(nodeId);\n    const node: Call = {\n      id: nodeId,\n      op,\n      bind: args.bind,\n      config: args.config,\n      ...(args.guards && args.guards.length > 0 && { guards: args.guards }),\n    };\n    nodes.push(node);\n  };\n\n  const build = (): TypedFlow<T> => ({\n    version: 1,\n    id,\n    chainId,\n    inputs: [...flowInputs],\n    nodes: [...nodes],\n  });\n\n  const context: ContextAccessor = {\n    sender: ref<'address'>('context.sender'),\n    executionAddress: ref<'address'>('context.executionAddress'),\n  };\n\n  return {\n    context,\n    inputs: inputHandles as InputHandles<T>,\n    call,\n    untypedOp,\n    build,\n  };\n};\n"],"mappings":";;;;AAoLA,MAAM,cAAc,SAClB,OAAO,SAAS,YAAY,SAAS,QAAQ,UAAU;;;;;;;;;AAUzD,MAAa,yBACX,SACA,YAC2B;CAC3B,MAAM,KAAK,QAAQ,QAAQ,OAAO,WAAW;CAC7C,MAAM,aAA0B,CAAC;CACjC,MAAM,QAAgB,CAAC;CACvB,MAAM,0BAAU,IAAI,IAAY;CAEhC,MAAM,eAAe,CAAC;CACtB,KAAK,MAAM,CAAC,MAAM,SAAS,OAAO,QAAQ,QAAQ,MAAM,GACtD,IAAI,WAAW,IAAI,GAAG;EACpB,IAAI,KAAK,YAAY,SACnB,MAAM,IAAI,MACR,UAAU,KAAK,gBAAgB,KAAK,QAAQ,0BAA0B,SACxE;EAEF,WAAW,KAAK;GAAE;GAAM,UAAU;EAAK,CAAC;EACxC,aAAa,QAAQ;GAAE,MAAM;GAAS,WAAW;GAAM,UAAU;EAAK;CACxE,OAAO;EACL,WAAW,KAAK;GAAE;GAAM,MAAM;EAAK,CAAC;EACpC,aAAa,QAAQ;GAAE,MAAM;GAAS,WAAW;EAAK;CACxD;CAGF,MAAM,QAIJ,QACA,IACA,MACA,SACA,aACwB;EACxB,IAAI,QAAQ,IAAI,MAAM,GAAG,MAAM,IAAI,MAAM,uBAAuB,OAAO,EAAE;EACzE,QAAQ,IAAI,MAAM;EAElB,MAAM,OAAkC,CAAC;EACzC,KAAK,MAAM,CAAC,KAAK,QAAQ,OAAO,QAAQ,KAAK,IAAI,GAC/C,KAAK,OAAO,YAAY,GAAG;EAG7B,MAAM,SAAU,KAAK,UAAU,CAAC;EAChC,MAAM,OAAa;GACjB,IAAI;GACJ;GACA;GACA;GACA,GAAI,KAAK,UAAU,KAAK,OAAO,SAAS,KAAK,EAAE,QAAQ,KAAK,OAAO;EACrE;EACA,MAAM,KAAK,IAAI;EAEf,MAAM,gBAAgB,cAAoC;GACxD,MAAM;GACN;GACA;EACF;EACA,OAAO,IAAI,MAAM,CAAC,GAA0B,EAC1C,MACE,SACA,SACuD;GACvD,IAAI,OAAO,SAAS,YAAY,SAAS,QAAQ,OAAO,KAAA;GAIxD,IAAI,CAAC,OAAO,OAAO,SAAS,IAAI,GAC9B,MAAM,IAAI,MACR,OAAO,GAAG,wBAAwB,KAAK,kBAAkB,OAAO,KAC9D,OACF,CAAC,CAAC,KAAK,IAAI,GACb;GAEF,MAAM,YAAY,WAAW;GAC7B,IAAI,cAAc,KAAA,GAAW,OAAO,aAAa,IAAI;GACrD,MAAM,OAAO,WAAW;IAAE,MAAM;IAAM;GAAU,GAAG,MAAM;GACzD,OAAO,MAAM,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,UACtC,aAAa,iBAAiB,MAAM,KAAK,CAAC,CAC5C;EACF,EACF,CAAC;CACH;CAEA,MAAM,aACJ,QACA,IACA,SAKS;EACT,IAAI,QAAQ,IAAI,MAAM,GAAG,MAAM,IAAI,MAAM,uBAAuB,OAAO,EAAE;EACzE,QAAQ,IAAI,MAAM;EAClB,MAAM,OAAa;GACjB,IAAI;GACJ;GACA,MAAM,KAAK;GACX,QAAQ,KAAK;GACb,GAAI,KAAK,UAAU,KAAK,OAAO,SAAS,KAAK,EAAE,QAAQ,KAAK,OAAO;EACrE;EACA,MAAM,KAAK,IAAI;CACjB;CAEA,MAAM,eAA6B;EACjC,SAAS;EACT;EACA;EACA,QAAQ,CAAC,GAAG,UAAU;EACtB,OAAO,CAAC,GAAG,KAAK;CAClB;CAOA,OAAO;EACL,SAAA;GALA,QAAQ,IAAe,gBAAgB;GACvC,kBAAkB,IAAe,0BAA0B;EAIrD;EACN,QAAQ;EACR;EACA;EACA;CACF;AACF"}

package/dist/authoring/handles.cjs

@@ -1,46 +1,31 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var handles_exports = {};
-__export(handles_exports, {
-  handleToRef: () => handleToRef,
-  isInputHandle: () => isInputHandle,
-  isOutputHandle: () => isOutputHandle,
-  toBindValue: () => toBindValue
-});
-module.exports = __toCommonJS(handles_exports);
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/authoring/handles.ts
+/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */
 const isInputHandle = (h) => h._tag === "input";
+/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */
 const isOutputHandle = (h) => h._tag === "output";
+/**
+* Converts a handle to a JSON `$ref` pointer used in the flow document.
+* Input handles become `"input.<name>"`; output handles become `"<nodeId>.<port>"`.
+*/
 const handleToRef = (h) => {
-  if (h._tag === "input") {
-    if (!h.inputName) throw new Error("InputHandle has empty inputName");
-    return { $ref: `input.${h.inputName}` };
-  }
-  if (!h.nodeId) throw new Error("OutputHandle has empty nodeId");
-  if (!h.portName) throw new Error("OutputHandle has empty portName");
-  return { $ref: `${h.nodeId}.${h.portName}` };
+	if (h._tag === "input") {
+		if (!h.inputName) throw new Error("InputHandle has empty inputName");
+		return { $ref: `input.${h.inputName}` };
+	}
+	if (!h.nodeId) throw new Error("OutputHandle has empty nodeId");
+	if (!h.portName) throw new Error("OutputHandle has empty portName");
+	return { $ref: `${h.nodeId}.${h.portName}` };
 };
+/**
+* Converts a bindable to the wire `bind` value it denotes: handles become
+* `$ref` pointers, refs and literals pass through as-is.
+*/
 const toBindValue = (bindable) => "_tag" in bindable ? handleToRef(bindable) : bindable;
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  handleToRef,
-  isInputHandle,
-  isOutputHandle,
-  toBindValue
-});
+//#endregion
+exports.handleToRef = handleToRef;
+exports.isInputHandle = isInputHandle;
+exports.isOutputHandle = isOutputHandle;
+exports.toBindValue = toBindValue;
+
 //# sourceMappingURL=handles.cjs.map

package/dist/authoring/handles.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/authoring/handles.ts"],"sourcesContent":["import type {\n  BindValue,\n  Ref,\n  Resource,\n  SolType,\n  StaticSolType,\n} from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedLiteral, TypedRef } from '../types.js';\n\n/**\n * A handle referencing a flow input declared in the flow's input schema.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface InputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'input';\n  readonly inputName: string;\n  readonly __outputKind?: T;\n}\n\n/**\n * An input handle for a resource (token) input, carrying the resource\n * declaration alongside the reference.\n */\nexport interface ResourceInputHandle extends InputHandle<'resource'> {\n  readonly resource: Resource;\n}\n\n/**\n * A handle referencing an output port of a previously declared operation node.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface OutputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'output';\n  readonly nodeId: string;\n  readonly portName: string;\n  readonly __outputKind?: T;\n}\n\n/**\n * What an output family's sizing parameter accepts, given the config field the\n * family counts from: an array of that field's elements, or a number.\n */\nexport type FamilySource<Field> = Field extends readonly (infer E)[]\n  ? readonly E[]\n  : number;\n\n/** Whether a number literal is a valid family count: a non-negative integer. */\ntype IsCountLiteral<N extends number> = `${N}` extends\n  `-${string}` | `${string}.${string}` | `${string}e${string}`\n  ? false\n  : true;\n\n/**\n * `N` resource handles as a tuple. A non-literal `number`, or a literal that is\n * not a valid count, gives an open array; {@link FamilyCount} rejects the\n * invalid literal at the call site.\n */\ntype HandleTuple<\n  N extends number,\n  Acc extends readonly OutputHandle<'resource'>[] = readonly [],\n> = number extends N\n  ? readonly OutputHandle<'resource'>[]\n  : IsCountLiteral<N> extends false\n    ? readonly OutputHandle<'resource'>[]\n    : Acc['length'] extends N\n      ? Acc\n      : HandleTuple<N, readonly [...Acc, OutputHandle<'resource'>]>;\n\n/**\n * The handles of an output family: one resource {@link OutputHandle} per\n * element of the config array the family counts from, or as many as the config\n * count. A literal array or count yields a tuple of that length, so indexing\n * past the last instance is a type error.\n */\nexport type OutputFamilyHandles<TCount extends readonly unknown[] | number> =\n  TCount extends readonly unknown[]\n    ? { readonly [I in keyof TCount]: OutputHandle<'resource'> }\n    : TCount extends number\n      ? HandleTuple<TCount>\n      : never;\n\n/**\n * Holds the config value an output family counts from to the op's own type. A\n * runtime-sized array or count passes as is. A literal tuple must also satisfy\n * `Shape`, so a tuple shorter than the op's `minItems` fails at the call site\n * instead of at the server's bind step. A literal count must be a non-negative\n * integer.\n */\nexport type FamilyCount<\n  TCount extends readonly unknown[] | number,\n  Shape,\n> = TCount extends readonly unknown[]\n  ? number extends TCount['length']\n    ? unknown\n    : TCount extends Shape\n      ? unknown\n      : { readonly 'output family config array has too few entries': never }\n  : TCount extends number\n    ? IsCountLiteral<TCount> extends true\n      ? unknown\n      : {\n          readonly 'output family count must be a non-negative integer': never;\n        }\n    : unknown;\n\n/** Discriminated union of all handle types that can be bound to operation arguments. */\nexport type AnyHandle = InputHandle | OutputHandle;\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */\nexport const isInputHandle = (h: AnyHandle): h is InputHandle =>\n  h._tag === 'input';\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */\nexport const isOutputHandle = (h: AnyHandle): h is OutputHandle =>\n  h._tag === 'output';\n\n/**\n * Converts a handle to a JSON `$ref` pointer used in the flow document.\n * Input handles become `\"input.<name>\"`; output handles become `\"<nodeId>.<port>\"`.\n */\nexport const handleToRef = (h: AnyHandle): { $ref: string } => {\n  if (h._tag === 'input') {\n    if (!h.inputName) throw new Error('InputHandle has empty inputName');\n    return { $ref: `input.${h.inputName}` };\n  }\n  if (!h.nodeId) throw new Error('OutputHandle has empty nodeId');\n  if (!h.portName) throw new Error('OutputHandle has empty portName');\n  return { $ref: `${h.nodeId}.${h.portName}` };\n};\n\n/**\n * For a bind slot expecting type T, widen the set of accepted handle types:\n * - `'bytes32'` is the raw 32-byte word type: accept any static-32-byte handle\n *   (`uint256`/`uintN`/`address`/`bool`/`bytes32`) plus `'resource'` (a uint256\n *   amount). At the IR1 boundary every value is a type-erased word, so any\n *   static-32-byte handle is a sound bind for a `bytes32` payload port.\n * - `'uint256'` keeps its existing widening to also accept `'resource'`-tagged\n *   handles (resources are uint256 amounts).\n * - every other type keeps exact-SolType matching.\n */\ntype SlotAssignable<T extends OutputKind> = T extends 'bytes32'\n  ? StaticSolType | 'resource'\n  : T extends 'uint256'\n    ? T | 'resource'\n    : T;\n\n/**\n * The values accepted by a typed slot that must resolve to a `$ref`:\n * - `OutputHandle<T>` / `InputHandle<T>` (same type)\n * - For `'uint256'` slots, also `'resource'`-tagged handles\n * - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)\n * - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)\n *\n * Plain `{ $ref: '...' }` objects are **not** accepted - use `raw.ref<T>()`\n * to create a typed ref when you need to reference a raw path.\n */\nexport type RefBindable<T extends OutputKind> =\n  | OutputHandle<SlotAssignable<T>>\n  | InputHandle<SlotAssignable<T>>\n  | TypedRef<SlotAssignable<T>>;\n\n/**\n * Any ref-resolving bindable, with no per-slot type constraint.\n */\nexport type AnyRefBindable = InputHandle | OutputHandle | TypedRef;\n\n/**\n * The set of values accepted by a typed operation bind slot: everything\n * {@link RefBindable} accepts, plus a {@link TypedLiteral} constant baked\n * into the flow document. A `'resource'` slot rejects a literal: a token\n * resource is not a scalar constant.\n *\n * Use `raw.literal<T>()` to create one.\n */\nexport type Bindable<T extends OutputKind> =\n  RefBindable<T> | LiteralBindable<SlotAssignable<T>>;\n\n// Distributes over the slot's assignable kinds and keeps the scalar ones: a\n// `'resource'` slot has no scalar arm, so its literal arm collapses to\n// `never` and a literal is rejected outright.\ntype LiteralBindable<K extends OutputKind> = K extends SolType\n  ? TypedLiteral<K>\n  : never;\n\n/**\n * Converts a bindable to the wire `bind` value it denotes: handles become\n * `$ref` pointers, refs and literals pass through as-is.\n */\nexport const toBindValue = (\n  bindable: InputHandle | OutputHandle | TypedRef | TypedLiteral | Ref,\n): BindValue => ('_tag' in bindable ? handleToRef(bindable) : bindable);\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgHO,MAAM,gBAAgB,CAAC,MAC5B,EAAE,SAAS;AAGN,MAAM,iBAAiB,CAAC,MAC7B,EAAE,SAAS;AAMN,MAAM,cAAc,CAAC,MAAmC;AAC7D,MAAI,EAAE,SAAS,SAAS;AACtB,QAAI,CAAC,EAAE,UAAW,OAAM,IAAI,MAAM,iCAAiC;AACnE,WAAO,EAAE,MAAM,SAAS,EAAE,SAAS,GAAG;AAAA,EACxC;AACA,MAAI,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,+BAA+B;AAC9D,MAAI,CAAC,EAAE,SAAU,OAAM,IAAI,MAAM,iCAAiC;AAClE,SAAO,EAAE,MAAM,GAAG,EAAE,MAAM,IAAI,EAAE,QAAQ,GAAG;AAC7C;AA4DO,MAAM,cAAc,CACzB,aACe,UAAU,WAAW,YAAY,QAAQ,IAAI;","names":[]}
+{"version":3,"file":"handles.cjs","names":[],"sources":["../../src/authoring/handles.ts"],"sourcesContent":["import type {\n  BindValue,\n  Ref,\n  Resource,\n  SolType,\n  StaticSolType,\n} from '@lifi/compose-spec';\n\nimport type { OutputKind, TypedLiteral, TypedRef } from '../types.js';\n\n/**\n * A handle referencing a flow input declared in the flow's input schema.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface InputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'input';\n  readonly inputName: string;\n  readonly __outputKind?: T;\n}\n\n/**\n * An input handle for a resource (token) input, carrying the resource\n * declaration alongside the reference.\n */\nexport interface ResourceInputHandle extends InputHandle<'resource'> {\n  readonly resource: Resource;\n}\n\n/**\n * A handle referencing an output port of a previously declared operation node.\n * The phantom `__outputKind` field carries the type parameter through\n * TypeScript's structural type system without affecting runtime shape.\n */\nexport interface OutputHandle<T extends OutputKind = OutputKind> {\n  readonly _tag: 'output';\n  readonly nodeId: string;\n  readonly portName: string;\n  readonly __outputKind?: T;\n}\n\n/**\n * What an output family's sizing parameter accepts, given the config field the\n * family counts from: an array of that field's elements, or a number.\n */\nexport type FamilySource<Field> = Field extends readonly (infer E)[]\n  ? readonly E[]\n  : number;\n\n/** Whether a number literal is a valid family count: a non-negative integer. */\ntype IsCountLiteral<N extends number> = `${N}` extends\n  `-${string}` | `${string}.${string}` | `${string}e${string}`\n  ? false\n  : true;\n\n/**\n * `N` resource handles as a tuple. A non-literal `number`, or a literal that is\n * not a valid count, gives an open array; {@link FamilyCount} rejects the\n * invalid literal at the call site.\n */\ntype HandleTuple<\n  N extends number,\n  Acc extends readonly OutputHandle<'resource'>[] = readonly [],\n> = number extends N\n  ? readonly OutputHandle<'resource'>[]\n  : IsCountLiteral<N> extends false\n    ? readonly OutputHandle<'resource'>[]\n    : Acc['length'] extends N\n      ? Acc\n      : HandleTuple<N, readonly [...Acc, OutputHandle<'resource'>]>;\n\n/**\n * The handles of an output family: one resource {@link OutputHandle} per\n * element of the config array the family counts from, or as many as the config\n * count. A literal array or count yields a tuple of that length, so indexing\n * past the last instance is a type error.\n */\nexport type OutputFamilyHandles<TCount extends readonly unknown[] | number> =\n  TCount extends readonly unknown[]\n    ? { readonly [I in keyof TCount]: OutputHandle<'resource'> }\n    : TCount extends number\n      ? HandleTuple<TCount>\n      : never;\n\n/**\n * Holds the config value an output family counts from to the op's own type. A\n * runtime-sized array or count passes as is. A literal tuple must also satisfy\n * `Shape`, so a tuple shorter than the op's `minItems` fails at the call site\n * instead of at the server's bind step. A literal count must be a non-negative\n * integer.\n */\nexport type FamilyCount<\n  TCount extends readonly unknown[] | number,\n  Shape,\n> = TCount extends readonly unknown[]\n  ? number extends TCount['length']\n    ? unknown\n    : TCount extends Shape\n      ? unknown\n      : { readonly 'output family config array has too few entries': never }\n  : TCount extends number\n    ? IsCountLiteral<TCount> extends true\n      ? unknown\n      : {\n          readonly 'output family count must be a non-negative integer': never;\n        }\n    : unknown;\n\n/** Discriminated union of all handle types that can be bound to operation arguments. */\nexport type AnyHandle = InputHandle | OutputHandle;\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */\nexport const isInputHandle = (h: AnyHandle): h is InputHandle =>\n  h._tag === 'input';\n\n/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */\nexport const isOutputHandle = (h: AnyHandle): h is OutputHandle =>\n  h._tag === 'output';\n\n/**\n * Converts a handle to a JSON `$ref` pointer used in the flow document.\n * Input handles become `\"input.<name>\"`; output handles become `\"<nodeId>.<port>\"`.\n */\nexport const handleToRef = (h: AnyHandle): { $ref: string } => {\n  if (h._tag === 'input') {\n    if (!h.inputName) throw new Error('InputHandle has empty inputName');\n    return { $ref: `input.${h.inputName}` };\n  }\n  if (!h.nodeId) throw new Error('OutputHandle has empty nodeId');\n  if (!h.portName) throw new Error('OutputHandle has empty portName');\n  return { $ref: `${h.nodeId}.${h.portName}` };\n};\n\n/**\n * For a bind slot expecting type T, widen the set of accepted handle types:\n * - `'bytes32'` is the raw 32-byte word type: accept any static-32-byte handle\n *   (`uint256`/`uintN`/`address`/`bool`/`bytes32`) plus `'resource'` (a uint256\n *   amount). At the IR1 boundary every value is a type-erased word, so any\n *   static-32-byte handle is a sound bind for a `bytes32` payload port.\n * - `'uint256'` keeps its existing widening to also accept `'resource'`-tagged\n *   handles (resources are uint256 amounts).\n * - every other type keeps exact-SolType matching.\n */\ntype SlotAssignable<T extends OutputKind> = T extends 'bytes32'\n  ? StaticSolType | 'resource'\n  : T extends 'uint256'\n    ? T | 'resource'\n    : T;\n\n/**\n * The values accepted by a typed slot that must resolve to a `$ref`:\n * - `OutputHandle<T>` / `InputHandle<T>` (same type)\n * - For `'uint256'` slots, also `'resource'`-tagged handles\n * - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)\n * - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)\n *\n * Plain `{ $ref: '...' }` objects are **not** accepted - use `raw.ref<T>()`\n * to create a typed ref when you need to reference a raw path.\n */\nexport type RefBindable<T extends OutputKind> =\n  | OutputHandle<SlotAssignable<T>>\n  | InputHandle<SlotAssignable<T>>\n  | TypedRef<SlotAssignable<T>>;\n\n/**\n * Any ref-resolving bindable, with no per-slot type constraint.\n */\nexport type AnyRefBindable = InputHandle | OutputHandle | TypedRef;\n\n/**\n * The set of values accepted by a typed operation bind slot: everything\n * {@link RefBindable} accepts, plus a {@link TypedLiteral} constant baked\n * into the flow document. A `'resource'` slot rejects a literal: a token\n * resource is not a scalar constant.\n *\n * Use `raw.literal<T>()` to create one.\n */\nexport type Bindable<T extends OutputKind> =\n  RefBindable<T> | LiteralBindable<SlotAssignable<T>>;\n\n// Distributes over the slot's assignable kinds and keeps the scalar ones: a\n// `'resource'` slot has no scalar arm, so its literal arm collapses to\n// `never` and a literal is rejected outright.\ntype LiteralBindable<K extends OutputKind> = K extends SolType\n  ? TypedLiteral<K>\n  : never;\n\n/**\n * Converts a bindable to the wire `bind` value it denotes: handles become\n * `$ref` pointers, refs and literals pass through as-is.\n */\nexport const toBindValue = (\n  bindable: InputHandle | OutputHandle | TypedRef | TypedLiteral | Ref,\n): BindValue => ('_tag' in bindable ? handleToRef(bindable) : bindable);\n"],"mappings":";;;AAgHA,MAAa,iBAAiB,MAC5B,EAAE,SAAS;;AAGb,MAAa,kBAAkB,MAC7B,EAAE,SAAS;;;;;AAMb,MAAa,eAAe,MAAmC;CAC7D,IAAI,EAAE,SAAS,SAAS;EACtB,IAAI,CAAC,EAAE,WAAW,MAAM,IAAI,MAAM,iCAAiC;EACnE,OAAO,EAAE,MAAM,SAAS,EAAE,YAAY;CACxC;CACA,IAAI,CAAC,EAAE,QAAQ,MAAM,IAAI,MAAM,+BAA+B;CAC9D,IAAI,CAAC,EAAE,UAAU,MAAM,IAAI,MAAM,iCAAiC;CAClE,OAAO,EAAE,MAAM,GAAG,EAAE,OAAO,GAAG,EAAE,WAAW;AAC7C;;;;;AA4DA,MAAa,eACX,aACe,UAAU,WAAW,YAAY,QAAQ,IAAI"}