@codemation/core-nodes 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -21,9 +21,9 @@ type PortsEmission = Readonly<{
   readonly ports: Readonly<Partial<Record<OutputPortKey, Items | ReadonlyArray<JsonNonArray>>>>;
 }>;
 //#endregion
-//#region ../core/src/contracts/itemValue.d.ts
-declare const ITEM_VALUE_BRAND: unique symbol;
-type ItemValueResolvedContext = Readonly<{
+//#region ../core/src/contracts/itemExpr.d.ts
+declare const ITEM_EXPR_BRAND: unique symbol;
+type ItemExprResolvedContext = Readonly<{
   runId: RunId;
   workflowId: WorkflowId;
   nodeId: NodeId;
@@ -33,19 +33,23 @@ type ItemValueResolvedContext = Readonly<{
 /**
  * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
  */
-type ItemValueContext = ItemValueResolvedContext;
-type ItemValueArgs<TItemJson = unknown> = Readonly<{
+type ItemExprContext = ItemExprResolvedContext;
+type ItemExprArgs<TItemJson = unknown> = Readonly<{
   item: Item<TItemJson>;
   itemIndex: number;
   items: Items<TItemJson>;
-  ctx: ItemValueContext;
+  ctx: ItemExprContext;
 }>;
-type ItemValueCallback<T, TItemJson = unknown> = (args: ItemValueArgs<TItemJson>) => T | Promise<T>;
-type ItemValue<T, TItemJson = unknown> = Readonly<{
-  readonly [ITEM_VALUE_BRAND]: true;
-  readonly fn: ItemValueCallback<T, TItemJson>;
+type ItemExprCallback<T, TItemJson = unknown> = (args: ItemExprArgs<TItemJson>) => T | Promise<T>;
+type ItemExpr<T, TItemJson = unknown> = Readonly<{
+  readonly [ITEM_EXPR_BRAND]: true;
+  readonly fn: ItemExprCallback<T, TItemJson>;
 }>;
 //#endregion
+//#region ../core/src/contracts/params.d.ts
+type Expr<T, TItemJson = unknown> = ItemExpr<T, TItemJson>;
+type ParamDeep<T, TItemJson = unknown> = Expr<T, TItemJson> | (T extends readonly (infer U)[] ? ReadonlyArray<ParamDeep<U, TItemJson>> : never) | (T extends object ? { [K in keyof T]: ParamDeep<T[K], TItemJson> } : T);
+//#endregion
 //#region ../core/src/contracts/retryPolicySpec.types.d.ts
 /**
  * In-process retry policy for runnable nodes. Serialized configs use the same
@@ -362,6 +366,9 @@ type ExecutableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = Trigger
 //#region ../core/src/contracts/workflowTypes.d.ts
 type WorkflowId = string;
 type NodeId = string;
+type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
+  __codemationNodeJson?: TJson;
+}>;
 type OutputPortKey = string;
 type InputPortKey = string;
 type NodeKind = "trigger" | "node";
@@ -531,8 +538,8 @@ interface ParentExecutionRef {
 }
 interface RunDataSnapshot {
   getOutputs(nodeId: NodeId): NodeOutputs | undefined;
-  getOutputItems(nodeId: NodeId, output?: OutputPortKey): Items;
-  getOutputItem(nodeId: NodeId, itemIndex: number, output?: OutputPortKey): Item | undefined;
+  getOutputItems<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, output?: OutputPortKey): Items<TJson>;
+  getOutputItem<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, itemIndex: number, output?: OutputPortKey): Item<TJson> | undefined;
 }
 type UpstreamRefPlaceholder = `$${number}`;
 /** Whether to persist run execution data after the workflow finishes. */
@@ -738,12 +745,13 @@ type DefinedNodeCredentialBinding = ResolvableCredentialType | Readonly<{
   readonly helpUrl?: string;
 }>;
 type DefinedNodeCredentialBindings = Readonly<Record<string, DefinedNodeCredentialBinding>>;
+type DefinedNodeConfigInput<TConfigResolved extends CredentialJsonRecord, TItemJson> = ParamDeep<TConfigResolved, TItemJson>;
 interface DefinedNode<TKey$1 extends string, TConfig extends CredentialJsonRecord, TInputJson$1, TOutputJson$1, _TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
   readonly kind: "defined-node";
   readonly key: TKey$1;
   readonly title: string;
   readonly description?: string;
-  create(config: TConfig, name?: string, id?: string): RunnableNodeConfig<TInputJson$1, TOutputJson$1>;
+  create<TConfigItemJson = TInputJson$1>(config: DefinedNodeConfigInput<TConfig, TConfigItemJson>, name?: string, id?: string): RunnableNodeConfig<TInputJson$1, TOutputJson$1>;
   register(context: {
     registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void;
   }): void;
@@ -814,7 +822,7 @@ type AgentMessageLine<TInputJson$1 = unknown> = AgentMessageDto | AgentMessageTe
  * Message list for an agent. Prefer a **plain array** of `{ role, content }` (optionally with function `content` for templates).
  * Use the object form only when you need `buildMessages` to append messages after optional `prompt` lines.
  */
-type AgentMessageConfig<TInputJson$1 = unknown> = ItemValue<ReadonlyArray<AgentMessageLine<TInputJson$1>>, TInputJson$1> | ReadonlyArray<AgentMessageLine<TInputJson$1>> | {
+type AgentMessageConfig<TInputJson$1 = unknown> = Expr<ReadonlyArray<AgentMessageLine<TInputJson$1>>, TInputJson$1> | ReadonlyArray<AgentMessageLine<TInputJson$1>> | {
   readonly prompt?: ReadonlyArray<AgentMessageLine<TInputJson$1>>;
   readonly buildMessages?: (args: AgentMessageBuildArgs<TInputJson$1>) => ReadonlyArray<AgentMessageDto>;
 };
@@ -894,11 +902,11 @@ interface AgentNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> exten
   readonly outputSchema?: ZodType<TOutputJson$1>;
 }
 //#endregion
-//#region ../core/src/execution/ItemValueResolver.d.ts
+//#region ../core/src/execution/ItemExprResolver.d.ts
 /**
- * Resolves {@link import("../contracts/itemValue").ItemValue} leaves on runnable config before {@link RunnableNode.execute}.
+ * Resolves {@link import("../contracts/itemExpr").ItemExpr} leaves on runnable config before {@link RunnableNode.execute}.
  */
-declare class ItemValueResolver {
+declare class ItemExprResolver {
   resolveConfigForItem<TConfig extends RunnableNodeConfig<any, any>>(ctx: NodeExecutionContext<TConfig>, item: Item, itemIndex: number, items: ReadonlyArray<Item>): Promise<NodeExecutionContext<TConfig>>;
 }
 //#endregion
@@ -1155,10 +1163,10 @@ declare class AIAgent<TInputJson$1 = unknown, TOutputJson$1 = unknown> implement
 //#region src/nodes/NodeBackedToolRuntime.d.ts
 declare class NodeBackedToolRuntime {
   private readonly nodeResolver;
-  private readonly itemValueResolver;
+  private readonly itemExprResolver;
   private readonly outputNormalizer;
   private readonly outputBehaviorResolver;
-  constructor(nodeResolver: NodeResolver, itemValueResolver: ItemValueResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver);
+  constructor(nodeResolver: NodeResolver, itemExprResolver: ItemExprResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver);
   execute(config: NodeBackedToolConfig<any, ZodSchemaAny, ZodSchemaAny>, args: ToolExecuteArgs): Promise<unknown>;
   private executeResolvedNode;
   private isRunnableNode;
@@ -1175,7 +1183,7 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   outputPorts: readonly ["main"];
   /**
    * Engine validates {@link RunnableNodeConfig.inputSchema} (Zod) on {@code item.json} before enqueue, then resolves
-   * per-item **`itemValue`** leaves on config before {@link #execute}. Prefer modeling prompts as
+   * per-item **`itemExpr`** leaves on config before {@link #execute}. Prefer modeling prompts as
    * {@code { messages: [{ role, content }, ...] }} (on input or config) so persisted inputs are visible in the UI.
    */
   readonly inputSchema: z.ZodUnknown;
@@ -1695,12 +1703,13 @@ interface WorkflowAgentOptions<TCurrentJson, TOutputSchema extends z.ZodTypeAny
 }
 //#endregion
 //#region src/workflowAuthoring/WorkflowBranchBuilder.types.d.ts
+type WorkflowMapCallback$1<TCurrentJson, TNextJson$1> = (item: Item<TCurrentJson>, ctx: NodeExecutionContext<MapData<TCurrentJson, TNextJson$1>>) => TNextJson$1;
 declare class WorkflowBranchBuilder<TCurrentJson> {
   private readonly steps;
   constructor(steps?: ReadonlyArray<AnyRunnableNodeConfig>);
   then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): WorkflowBranchBuilder<RunnableNodeOutputJson<TConfig>>;
-  map<TNextJson$1>(mapper: (item: TCurrentJson) => TNextJson$1): WorkflowBranchBuilder<TNextJson$1>;
-  map<TNextJson$1>(name: string, mapper: (item: TCurrentJson) => TNextJson$1, options?: MapDataOptions): WorkflowBranchBuilder<TNextJson$1>;
+  map<TNextJson$1>(mapper: WorkflowMapCallback$1<TCurrentJson, TNextJson$1>): WorkflowBranchBuilder<TNextJson$1>;
+  map<TNextJson$1>(name: string, mapper: WorkflowMapCallback$1<TCurrentJson, TNextJson$1>, options?: MapDataOptions): WorkflowBranchBuilder<TNextJson$1>;
   wait(duration: number | string): WorkflowBranchBuilder<TCurrentJson>;
   wait(name: string, duration: number | string, id?: string): WorkflowBranchBuilder<TCurrentJson>;
   split<TElem>(getElements: (item: Item<TCurrentJson>, ctx: NodeExecutionContext<Split<TCurrentJson, TElem>>) => readonly TElem[]): WorkflowBranchBuilder<TElem>;
@@ -1712,19 +1721,22 @@ declare class WorkflowBranchBuilder<TCurrentJson> {
   agent<TOutputSchema extends z.ZodTypeAny>(options: WorkflowAgentOptions<TCurrentJson, TOutputSchema>): WorkflowBranchBuilder<z.output<TOutputSchema>>;
   agent(options: WorkflowAgentOptions<TCurrentJson, undefined>): WorkflowBranchBuilder<Record<string, unknown>>;
   agent<TOutputSchema extends z.ZodTypeAny>(name: string, options: WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>): WorkflowBranchBuilder<TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>>;
-  node<TConfig extends Record<string, unknown>, TOutputJson$1>(definitionOrKey: DefinedNode<string, TConfig, TCurrentJson, TOutputJson$1> | string, config: TConfig, name?: string, id?: string): WorkflowBranchBuilder<TOutputJson$1>;
+  node<TConfig extends CredentialJsonRecord, TInputJson$1, TOutputJson$1>(definitionOrKey: DefinedNode<string, TConfig, TInputJson$1, TOutputJson$1> | string, config: DefinedNodeConfigInput<TConfig, TCurrentJson>, name?: string, id?: string): TCurrentJson extends TInputJson$1 ? WorkflowBranchBuilder<TOutputJson$1> : never;
   getSteps(): ReadonlyArray<AnyRunnableNodeConfig>;
 }
 //#endregion
 //#region src/workflowAuthoring/WorkflowChain.types.d.ts
 type BranchCallback<TCurrentJson, TNextJson$1> = (branch: WorkflowBranchBuilder<TCurrentJson>) => WorkflowBranchBuilder<TNextJson$1>;
 type RouteBranchCallback<TCurrentJson, TNextJson$1> = (branch: WorkflowChain<TCurrentJson>) => WorkflowChain<TNextJson$1>;
+type WorkflowMapCallback<TCurrentJson, TNextJson$1> = (item: Item<TCurrentJson>, ctx: NodeExecutionContext<MapData<TCurrentJson, TNextJson$1>>) => TNextJson$1;
+type WorkflowIfPredicate<TCurrentJson> = (item: Item<TCurrentJson>, ctx: NodeExecutionContext<If<TCurrentJson>>) => boolean;
+type WorkflowSwitchCaseKeyResolver<TCurrentJson> = (item: Item<TCurrentJson>, ctx: NodeExecutionContext<Switch<TCurrentJson>>) => string | Promise<string>;
 declare class WorkflowChain<TCurrentJson> {
   private readonly chain;
   constructor(chain: ChainCursor<TCurrentJson>);
   then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): WorkflowChain<RunnableNodeOutputJson<TConfig>>;
-  map<TNextJson$1>(mapper: (item: TCurrentJson) => TNextJson$1): WorkflowChain<TNextJson$1>;
-  map<TNextJson$1>(name: string, mapper: (item: TCurrentJson) => TNextJson$1, options?: MapDataOptions): WorkflowChain<TNextJson$1>;
+  map<TNextJson$1>(mapper: WorkflowMapCallback<TCurrentJson, TNextJson$1>): WorkflowChain<TNextJson$1>;
+  map<TNextJson$1>(name: string, mapper: WorkflowMapCallback<TCurrentJson, TNextJson$1>, options?: MapDataOptions): WorkflowChain<TNextJson$1>;
   wait(duration: number | string): WorkflowChain<TCurrentJson>;
   wait(name: string, duration: number | string, id?: string): WorkflowChain<TCurrentJson>;
   split<TElem>(getElements: (item: Item<TCurrentJson>, ctx: NodeExecutionContext<Split<TCurrentJson, TElem>>) => readonly TElem[]): WorkflowChain<TElem>;
@@ -1742,11 +1754,11 @@ declare class WorkflowChain<TCurrentJson> {
     mode: MergeMode;
     prefer?: ReadonlyArray<string>;
   }>, id?: string): WorkflowChain<TCurrentJson>;
-  if<TBranchJson>(predicate: (item: TCurrentJson) => boolean, branches: Readonly<{
+  if<TBranchJson>(predicate: WorkflowIfPredicate<TCurrentJson>, branches: Readonly<{
     true?: BranchCallback<TCurrentJson, TBranchJson>;
     false?: BranchCallback<TCurrentJson, TBranchJson>;
   }>): WorkflowChain<TBranchJson>;
-  if<TBranchJson>(name: string, predicate: (item: TCurrentJson) => boolean, branches: Readonly<{
+  if<TBranchJson>(name: string, predicate: WorkflowIfPredicate<TCurrentJson>, branches: Readonly<{
     true?: BranchCallback<TCurrentJson, TBranchJson>;
     false?: BranchCallback<TCurrentJson, TBranchJson>;
   }>): WorkflowChain<TBranchJson>;
@@ -1754,19 +1766,19 @@ declare class WorkflowChain<TCurrentJson> {
   switch<TBranchJson>(cfg: Readonly<{
     cases: readonly string[];
     defaultCase: string;
-    resolveCaseKey: (item: TCurrentJson) => string | Promise<string>;
+    resolveCaseKey: WorkflowSwitchCaseKeyResolver<TCurrentJson>;
     branches: Readonly<Record<string, RouteBranchCallback<TCurrentJson, TBranchJson> | undefined>>;
   }>): WorkflowChain<TBranchJson>;
   switch<TBranchJson>(name: string, cfg: Readonly<{
     cases: readonly string[];
     defaultCase: string;
-    resolveCaseKey: (item: TCurrentJson) => string | Promise<string>;
+    resolveCaseKey: WorkflowSwitchCaseKeyResolver<TCurrentJson>;
     branches: Readonly<Record<string, RouteBranchCallback<TCurrentJson, TBranchJson> | undefined>>;
   }>, id?: string): WorkflowChain<TBranchJson>;
   agent<TOutputSchema extends z.ZodTypeAny>(options: WorkflowAgentOptions<TCurrentJson, TOutputSchema>): WorkflowChain<z.output<TOutputSchema>>;
   agent(options: WorkflowAgentOptions<TCurrentJson, undefined>): WorkflowChain<Record<string, unknown>>;
   agent<TOutputSchema extends z.ZodTypeAny>(name: string, options: WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>): WorkflowChain<TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>>;
-  node<TConfig extends Record<string, unknown>, TOutputJson$1>(definitionOrKey: DefinedNode<string, TConfig, TCurrentJson, TOutputJson$1> | string, config: TConfig, name?: string, id?: string): WorkflowChain<TOutputJson$1>;
+  node<TConfig extends CredentialJsonRecord, TInputJson$1, TOutputJson$1>(definitionOrKey: DefinedNode<string, TConfig, TInputJson$1, TOutputJson$1> | string, config: DefinedNodeConfigInput<TConfig, TCurrentJson>, name?: string, id?: string): TCurrentJson extends TInputJson$1 ? WorkflowChain<TOutputJson$1> : never;
   build(): WorkflowDefinition;
 }
 //#endregion

package/dist/index.d.ts

@@ -21,9 +21,9 @@ type PortsEmission = Readonly<{
   readonly ports: Readonly<Partial<Record<OutputPortKey, Items | ReadonlyArray<JsonNonArray>>>>;
 }>;
 //#endregion
-//#region ../core/src/contracts/itemValue.d.ts
-declare const ITEM_VALUE_BRAND: unique symbol;
-type ItemValueResolvedContext = Readonly<{
+//#region ../core/src/contracts/itemExpr.d.ts
+declare const ITEM_EXPR_BRAND: unique symbol;
+type ItemExprResolvedContext = Readonly<{
   runId: RunId;
   workflowId: WorkflowId;
   nodeId: NodeId;
@@ -33,19 +33,23 @@ type ItemValueResolvedContext = Readonly<{
 /**
  * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
  */
-type ItemValueContext = ItemValueResolvedContext;
-type ItemValueArgs<TItemJson = unknown> = Readonly<{
+type ItemExprContext = ItemExprResolvedContext;
+type ItemExprArgs<TItemJson = unknown> = Readonly<{
   item: Item<TItemJson>;
   itemIndex: number;
   items: Items<TItemJson>;
-  ctx: ItemValueContext;
+  ctx: ItemExprContext;
 }>;
-type ItemValueCallback<T, TItemJson = unknown> = (args: ItemValueArgs<TItemJson>) => T | Promise<T>;
-type ItemValue<T, TItemJson = unknown> = Readonly<{
-  readonly [ITEM_VALUE_BRAND]: true;
-  readonly fn: ItemValueCallback<T, TItemJson>;
+type ItemExprCallback<T, TItemJson = unknown> = (args: ItemExprArgs<TItemJson>) => T | Promise<T>;
+type ItemExpr<T, TItemJson = unknown> = Readonly<{
+  readonly [ITEM_EXPR_BRAND]: true;
+  readonly fn: ItemExprCallback<T, TItemJson>;
 }>;
 //#endregion
+//#region ../core/src/contracts/params.d.ts
+type Expr<T, TItemJson = unknown> = ItemExpr<T, TItemJson>;
+type ParamDeep<T, TItemJson = unknown> = Expr<T, TItemJson> | (T extends readonly (infer U)[] ? ReadonlyArray<ParamDeep<U, TItemJson>> : never) | (T extends object ? { [K in keyof T]: ParamDeep<T[K], TItemJson> } : T);
+//#endregion
 //#region ../core/src/contracts/retryPolicySpec.types.d.ts
 /**
  * In-process retry policy for runnable nodes. Serialized configs use the same
@@ -362,6 +366,9 @@ type ExecutableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = Trigger
 //#region ../core/src/contracts/workflowTypes.d.ts
 type WorkflowId = string;
 type NodeId = string;
+type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
+  __codemationNodeJson?: TJson;
+}>;
 type OutputPortKey = string;
 type InputPortKey = string;
 type NodeKind = "trigger" | "node";
@@ -531,8 +538,8 @@ interface ParentExecutionRef {
 }
 interface RunDataSnapshot {
   getOutputs(nodeId: NodeId): NodeOutputs | undefined;
-  getOutputItems(nodeId: NodeId, output?: OutputPortKey): Items;
-  getOutputItem(nodeId: NodeId, itemIndex: number, output?: OutputPortKey): Item | undefined;
+  getOutputItems<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, output?: OutputPortKey): Items<TJson>;
+  getOutputItem<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, itemIndex: number, output?: OutputPortKey): Item<TJson> | undefined;
 }
 type UpstreamRefPlaceholder = `$${number}`;
 /** Whether to persist run execution data after the workflow finishes. */
@@ -738,12 +745,13 @@ type DefinedNodeCredentialBinding = ResolvableCredentialType | Readonly<{
   readonly helpUrl?: string;
 }>;
 type DefinedNodeCredentialBindings = Readonly<Record<string, DefinedNodeCredentialBinding>>;
+type DefinedNodeConfigInput<TConfigResolved extends CredentialJsonRecord, TItemJson> = ParamDeep<TConfigResolved, TItemJson>;
 interface DefinedNode<TKey$1 extends string, TConfig extends CredentialJsonRecord, TInputJson$1, TOutputJson$1, _TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
   readonly kind: "defined-node";
   readonly key: TKey$1;
   readonly title: string;
   readonly description?: string;
-  create(config: TConfig, name?: string, id?: string): RunnableNodeConfig<TInputJson$1, TOutputJson$1>;
+  create<TConfigItemJson = TInputJson$1>(config: DefinedNodeConfigInput<TConfig, TConfigItemJson>, name?: string, id?: string): RunnableNodeConfig<TInputJson$1, TOutputJson$1>;
   register(context: {
     registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void;
   }): void;
@@ -814,7 +822,7 @@ type AgentMessageLine<TInputJson$1 = unknown> = AgentMessageDto | AgentMessageTe
  * Message list for an agent. Prefer a **plain array** of `{ role, content }` (optionally with function `content` for templates).
  * Use the object form only when you need `buildMessages` to append messages after optional `prompt` lines.
  */
-type AgentMessageConfig<TInputJson$1 = unknown> = ItemValue<ReadonlyArray<AgentMessageLine<TInputJson$1>>, TInputJson$1> | ReadonlyArray<AgentMessageLine<TInputJson$1>> | {
+type AgentMessageConfig<TInputJson$1 = unknown> = Expr<ReadonlyArray<AgentMessageLine<TInputJson$1>>, TInputJson$1> | ReadonlyArray<AgentMessageLine<TInputJson$1>> | {
   readonly prompt?: ReadonlyArray<AgentMessageLine<TInputJson$1>>;
   readonly buildMessages?: (args: AgentMessageBuildArgs<TInputJson$1>) => ReadonlyArray<AgentMessageDto>;
 };
@@ -894,11 +902,11 @@ interface AgentNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> exten
   readonly outputSchema?: ZodType<TOutputJson$1>;
 }
 //#endregion
-//#region ../core/src/execution/ItemValueResolver.d.ts
+//#region ../core/src/execution/ItemExprResolver.d.ts
 /**
- * Resolves {@link import("../contracts/itemValue").ItemValue} leaves on runnable config before {@link RunnableNode.execute}.
+ * Resolves {@link import("../contracts/itemExpr").ItemExpr} leaves on runnable config before {@link RunnableNode.execute}.
  */
-declare class ItemValueResolver {
+declare class ItemExprResolver {
   resolveConfigForItem<TConfig extends RunnableNodeConfig<any, any>>(ctx: NodeExecutionContext<TConfig>, item: Item, itemIndex: number, items: ReadonlyArray<Item>): Promise<NodeExecutionContext<TConfig>>;
 }
 //#endregion
@@ -1155,10 +1163,10 @@ declare class AIAgent<TInputJson$1 = unknown, TOutputJson$1 = unknown> implement
 //#region src/nodes/NodeBackedToolRuntime.d.ts
 declare class NodeBackedToolRuntime {
   private readonly nodeResolver;
-  private readonly itemValueResolver;
+  private readonly itemExprResolver;
   private readonly outputNormalizer;
   private readonly outputBehaviorResolver;
-  constructor(nodeResolver: NodeResolver, itemValueResolver: ItemValueResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver);
+  constructor(nodeResolver: NodeResolver, itemExprResolver: ItemExprResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver);
   execute(config: NodeBackedToolConfig<any, ZodSchemaAny, ZodSchemaAny>, args: ToolExecuteArgs): Promise<unknown>;
   private executeResolvedNode;
   private isRunnableNode;
@@ -1175,7 +1183,7 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   outputPorts: readonly ["main"];
   /**
    * Engine validates {@link RunnableNodeConfig.inputSchema} (Zod) on {@code item.json} before enqueue, then resolves
-   * per-item **`itemValue`** leaves on config before {@link #execute}. Prefer modeling prompts as
+   * per-item **`itemExpr`** leaves on config before {@link #execute}. Prefer modeling prompts as
    * {@code { messages: [{ role, content }, ...] }} (on input or config) so persisted inputs are visible in the UI.
    */
   readonly inputSchema: z.ZodUnknown;
@@ -1695,12 +1703,13 @@ interface WorkflowAgentOptions<TCurrentJson, TOutputSchema extends z.ZodTypeAny
 }
 //#endregion
 //#region src/workflowAuthoring/WorkflowBranchBuilder.types.d.ts
+type WorkflowMapCallback$1<TCurrentJson, TNextJson$1> = (item: Item<TCurrentJson>, ctx: NodeExecutionContext<MapData<TCurrentJson, TNextJson$1>>) => TNextJson$1;
 declare class WorkflowBranchBuilder<TCurrentJson> {
   private readonly steps;
   constructor(steps?: ReadonlyArray<AnyRunnableNodeConfig>);
   then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): WorkflowBranchBuilder<RunnableNodeOutputJson<TConfig>>;
-  map<TNextJson$1>(mapper: (item: TCurrentJson) => TNextJson$1): WorkflowBranchBuilder<TNextJson$1>;
-  map<TNextJson$1>(name: string, mapper: (item: TCurrentJson) => TNextJson$1, options?: MapDataOptions): WorkflowBranchBuilder<TNextJson$1>;
+  map<TNextJson$1>(mapper: WorkflowMapCallback$1<TCurrentJson, TNextJson$1>): WorkflowBranchBuilder<TNextJson$1>;
+  map<TNextJson$1>(name: string, mapper: WorkflowMapCallback$1<TCurrentJson, TNextJson$1>, options?: MapDataOptions): WorkflowBranchBuilder<TNextJson$1>;
   wait(duration: number | string): WorkflowBranchBuilder<TCurrentJson>;
   wait(name: string, duration: number | string, id?: string): WorkflowBranchBuilder<TCurrentJson>;
   split<TElem>(getElements: (item: Item<TCurrentJson>, ctx: NodeExecutionContext<Split<TCurrentJson, TElem>>) => readonly TElem[]): WorkflowBranchBuilder<TElem>;
@@ -1712,19 +1721,22 @@ declare class WorkflowBranchBuilder<TCurrentJson> {
   agent<TOutputSchema extends z.ZodTypeAny>(options: WorkflowAgentOptions<TCurrentJson, TOutputSchema>): WorkflowBranchBuilder<z.output<TOutputSchema>>;
   agent(options: WorkflowAgentOptions<TCurrentJson, undefined>): WorkflowBranchBuilder<Record<string, unknown>>;
   agent<TOutputSchema extends z.ZodTypeAny>(name: string, options: WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>): WorkflowBranchBuilder<TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>>;
-  node<TConfig extends Record<string, unknown>, TOutputJson$1>(definitionOrKey: DefinedNode<string, TConfig, TCurrentJson, TOutputJson$1> | string, config: TConfig, name?: string, id?: string): WorkflowBranchBuilder<TOutputJson$1>;
+  node<TConfig extends CredentialJsonRecord, TInputJson$1, TOutputJson$1>(definitionOrKey: DefinedNode<string, TConfig, TInputJson$1, TOutputJson$1> | string, config: DefinedNodeConfigInput<TConfig, TCurrentJson>, name?: string, id?: string): TCurrentJson extends TInputJson$1 ? WorkflowBranchBuilder<TOutputJson$1> : never;
   getSteps(): ReadonlyArray<AnyRunnableNodeConfig>;
 }
 //#endregion
 //#region src/workflowAuthoring/WorkflowChain.types.d.ts
 type BranchCallback<TCurrentJson, TNextJson$1> = (branch: WorkflowBranchBuilder<TCurrentJson>) => WorkflowBranchBuilder<TNextJson$1>;
 type RouteBranchCallback<TCurrentJson, TNextJson$1> = (branch: WorkflowChain<TCurrentJson>) => WorkflowChain<TNextJson$1>;
+type WorkflowMapCallback<TCurrentJson, TNextJson$1> = (item: Item<TCurrentJson>, ctx: NodeExecutionContext<MapData<TCurrentJson, TNextJson$1>>) => TNextJson$1;
+type WorkflowIfPredicate<TCurrentJson> = (item: Item<TCurrentJson>, ctx: NodeExecutionContext<If<TCurrentJson>>) => boolean;
+type WorkflowSwitchCaseKeyResolver<TCurrentJson> = (item: Item<TCurrentJson>, ctx: NodeExecutionContext<Switch<TCurrentJson>>) => string | Promise<string>;
 declare class WorkflowChain<TCurrentJson> {
   private readonly chain;
   constructor(chain: ChainCursor<TCurrentJson>);
   then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): WorkflowChain<RunnableNodeOutputJson<TConfig>>;
-  map<TNextJson$1>(mapper: (item: TCurrentJson) => TNextJson$1): WorkflowChain<TNextJson$1>;
-  map<TNextJson$1>(name: string, mapper: (item: TCurrentJson) => TNextJson$1, options?: MapDataOptions): WorkflowChain<TNextJson$1>;
+  map<TNextJson$1>(mapper: WorkflowMapCallback<TCurrentJson, TNextJson$1>): WorkflowChain<TNextJson$1>;
+  map<TNextJson$1>(name: string, mapper: WorkflowMapCallback<TCurrentJson, TNextJson$1>, options?: MapDataOptions): WorkflowChain<TNextJson$1>;
   wait(duration: number | string): WorkflowChain<TCurrentJson>;
   wait(name: string, duration: number | string, id?: string): WorkflowChain<TCurrentJson>;
   split<TElem>(getElements: (item: Item<TCurrentJson>, ctx: NodeExecutionContext<Split<TCurrentJson, TElem>>) => readonly TElem[]): WorkflowChain<TElem>;
@@ -1742,11 +1754,11 @@ declare class WorkflowChain<TCurrentJson> {
     mode: MergeMode;
     prefer?: ReadonlyArray<string>;
   }>, id?: string): WorkflowChain<TCurrentJson>;
-  if<TBranchJson>(predicate: (item: TCurrentJson) => boolean, branches: Readonly<{
+  if<TBranchJson>(predicate: WorkflowIfPredicate<TCurrentJson>, branches: Readonly<{
     true?: BranchCallback<TCurrentJson, TBranchJson>;
     false?: BranchCallback<TCurrentJson, TBranchJson>;
   }>): WorkflowChain<TBranchJson>;
-  if<TBranchJson>(name: string, predicate: (item: TCurrentJson) => boolean, branches: Readonly<{
+  if<TBranchJson>(name: string, predicate: WorkflowIfPredicate<TCurrentJson>, branches: Readonly<{
     true?: BranchCallback<TCurrentJson, TBranchJson>;
     false?: BranchCallback<TCurrentJson, TBranchJson>;
   }>): WorkflowChain<TBranchJson>;
@@ -1754,19 +1766,19 @@ declare class WorkflowChain<TCurrentJson> {
   switch<TBranchJson>(cfg: Readonly<{
     cases: readonly string[];
     defaultCase: string;
-    resolveCaseKey: (item: TCurrentJson) => string | Promise<string>;
+    resolveCaseKey: WorkflowSwitchCaseKeyResolver<TCurrentJson>;
     branches: Readonly<Record<string, RouteBranchCallback<TCurrentJson, TBranchJson> | undefined>>;
   }>): WorkflowChain<TBranchJson>;
   switch<TBranchJson>(name: string, cfg: Readonly<{
     cases: readonly string[];
     defaultCase: string;
-    resolveCaseKey: (item: TCurrentJson) => string | Promise<string>;
+    resolveCaseKey: WorkflowSwitchCaseKeyResolver<TCurrentJson>;
     branches: Readonly<Record<string, RouteBranchCallback<TCurrentJson, TBranchJson> | undefined>>;
   }>, id?: string): WorkflowChain<TBranchJson>;
   agent<TOutputSchema extends z.ZodTypeAny>(options: WorkflowAgentOptions<TCurrentJson, TOutputSchema>): WorkflowChain<z.output<TOutputSchema>>;
   agent(options: WorkflowAgentOptions<TCurrentJson, undefined>): WorkflowChain<Record<string, unknown>>;
   agent<TOutputSchema extends z.ZodTypeAny>(name: string, options: WorkflowAgentOptions<TCurrentJson, TOutputSchema | undefined>): WorkflowChain<TOutputSchema extends z.ZodTypeAny ? z.output<TOutputSchema> : Record<string, unknown>>;
-  node<TConfig extends Record<string, unknown>, TOutputJson$1>(definitionOrKey: DefinedNode<string, TConfig, TCurrentJson, TOutputJson$1> | string, config: TConfig, name?: string, id?: string): WorkflowChain<TOutputJson$1>;
+  node<TConfig extends CredentialJsonRecord, TInputJson$1, TOutputJson$1>(definitionOrKey: DefinedNode<string, TConfig, TInputJson$1, TOutputJson$1> | string, config: DefinedNodeConfigInput<TConfig, TCurrentJson>, name?: string, id?: string): TCurrentJson extends TInputJson$1 ? WorkflowChain<TOutputJson$1> : never;
   build(): WorkflowDefinition;
 }
 //#endregion

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AgentConfigInspector, AgentConnectionNodeCollector, AgentGuardrailDefaults, AgentMessageConfigNormalizer, CallableToolConfig, ConnectionInvocationIdFactory, ConnectionNodeIdFactory, CoreTokens, DefinedNodeRegistry, ItemValueResolver, ItemsInputNormalizer, NodeBackedToolConfig, NodeOutputNormalizer, RetryPolicy, RunnableOutputBehaviorResolver, WorkflowBuilder, chatModel, emitPorts, getOriginIndexFromItem, inject, injectable, isPortsEmission, node } from "@codemation/core";
+import { AgentConfigInspector, AgentConnectionNodeCollector, AgentGuardrailDefaults, AgentMessageConfigNormalizer, CallableToolConfig, ConnectionInvocationIdFactory, ConnectionNodeIdFactory, CoreTokens, DefinedNodeRegistry, ItemExprResolver, ItemsInputNormalizer, NodeBackedToolConfig, NodeOutputNormalizer, RetryPolicy, RunnableOutputBehaviorResolver, WorkflowBuilder, chatModel, emitPorts, getOriginIndexFromItem, inject, injectable, isPortsEmission, node } from "@codemation/core";
 import { ChatOpenAI } from "@langchain/openai";
 import { AIMessage, HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
 import { isInteropZodSchema } from "@langchain/core/utils/types";
@@ -2690,9 +2690,9 @@ var AgentToolCallPortMap = class {
 //#region src/nodes/NodeBackedToolRuntime.ts
 var _ref$1, _ref2$1, _ref3$1;
 let NodeBackedToolRuntime = class NodeBackedToolRuntime$1 {
-	constructor(nodeResolver, itemValueResolver, outputNormalizer, outputBehaviorResolver) {
+	constructor(nodeResolver, itemExprResolver, outputNormalizer, outputBehaviorResolver) {
 		this.nodeResolver = nodeResolver;
-		this.itemValueResolver = itemValueResolver;
+		this.itemExprResolver = itemExprResolver;
 		this.outputNormalizer = outputNormalizer;
 		this.outputBehaviorResolver = outputBehaviorResolver;
 	}
@@ -2734,7 +2734,7 @@ let NodeBackedToolRuntime = class NodeBackedToolRuntime$1 {
 				item: nodeInput,
 				itemIndex: 0,
 				items,
-				ctx: await this.itemValueResolver.resolveConfigForItem(ctx, nodeInput, 0, items)
+				ctx: await this.itemExprResolver.resolveConfigForItem(ctx, nodeInput, 0, items)
 			};
 			const raw = await Promise.resolve(runnable.execute(execArgs));
 			return this.outputNormalizer.normalizeExecuteResult({
@@ -2755,12 +2755,12 @@ let NodeBackedToolRuntime = class NodeBackedToolRuntime$1 {
 NodeBackedToolRuntime = __decorate([
 	injectable(),
 	__decorateParam(0, inject(CoreTokens.NodeResolver)),
-	__decorateParam(1, inject(ItemValueResolver)),
+	__decorateParam(1, inject(ItemExprResolver)),
 	__decorateParam(2, inject(NodeOutputNormalizer)),
 	__decorateParam(3, inject(RunnableOutputBehaviorResolver)),
 	__decorateMetadata("design:paramtypes", [
 		Object,
-		typeof (_ref$1 = typeof ItemValueResolver !== "undefined" && ItemValueResolver) === "function" ? _ref$1 : Object,
+		typeof (_ref$1 = typeof ItemExprResolver !== "undefined" && ItemExprResolver) === "function" ? _ref$1 : Object,
 		typeof (_ref2$1 = typeof NodeOutputNormalizer !== "undefined" && NodeOutputNormalizer) === "function" ? _ref2$1 : Object,
 		typeof (_ref3$1 = typeof RunnableOutputBehaviorResolver !== "undefined" && RunnableOutputBehaviorResolver) === "function" ? _ref3$1 : Object
 	])
@@ -2782,7 +2782,7 @@ let AIAgentNode = class AIAgentNode$1 {
 	outputPorts = ["main"];
 	/**
 	* Engine validates {@link RunnableNodeConfig.inputSchema} (Zod) on {@code item.json} before enqueue, then resolves
-	* per-item **`itemValue`** leaves on config before {@link #execute}. Prefer modeling prompts as
+	* per-item **`itemExpr`** leaves on config before {@link #execute}. Prefer modeling prompts as
 	* {@code { messages: [{ role, content }, ...] }} (on input or config) so persisted inputs are visible in the UI.
 	*/
 	inputSchema = unknown();
@@ -4028,7 +4028,7 @@ var WorkflowBranchBuilder = class WorkflowBranchBuilder {
 	map(nameOrMapper, mapperOrUndefined, options) {
 		const name = typeof nameOrMapper === "string" ? nameOrMapper : "Map data";
 		const mapper = typeof nameOrMapper === "string" ? mapperOrUndefined : nameOrMapper;
-		return this.then(new MapData(name, (item) => mapper(item.json), options));
+		return this.then(new MapData(name, mapper, options));
 	}
 	wait(nameOrDuration, durationOrUndefined, id) {
 		const name = typeof nameOrDuration === "string" && durationOrUndefined !== void 0 ? nameOrDuration : "Wait";
@@ -4074,7 +4074,7 @@ var WorkflowChain = class WorkflowChain {
 	map(nameOrMapper, mapperOrUndefined, options) {
 		const name = typeof nameOrMapper === "string" ? nameOrMapper : "Map data";
 		const mapper = typeof nameOrMapper === "string" ? mapperOrUndefined : nameOrMapper;
-		return this.then(new MapData(name, (item) => mapper(item.json), options));
+		return this.then(new MapData(name, mapper, options));
 	}
 	wait(nameOrDuration, durationOrUndefined, id) {
 		const name = typeof nameOrDuration === "string" && durationOrUndefined !== void 0 ? nameOrDuration : "Wait";
@@ -4106,7 +4106,7 @@ var WorkflowChain = class WorkflowChain {
 		const name = typeof nameOrPredicate === "string" ? nameOrPredicate : "If";
 		const predicate = typeof nameOrPredicate === "string" ? predicateOrBranches : nameOrPredicate;
 		const branches = typeof nameOrPredicate === "string" ? branchesOrUndefined : predicateOrBranches;
-		const cursor = this.chain.then(new If(name, (item) => predicate(item.json)));
+		const cursor = this.chain.then(new If(name, (item, _index, _items, ctx) => predicate(item, ctx)));
 		const trueSteps = branches.true?.(new WorkflowBranchBuilder()).getSteps();
 		const falseSteps = branches.false?.(new WorkflowBranchBuilder()).getSteps();
 		return new WorkflowChain(cursor.when({
@@ -4124,7 +4124,7 @@ var WorkflowChain = class WorkflowChain {
 		return this.then(new Switch(name, {
 			cases: cfg.cases,
 			defaultCase: cfg.defaultCase,
-			resolveCaseKey: (item) => cfg.resolveCaseKey(item.json)
+			resolveCaseKey: (item, _index, _items, ctx) => cfg.resolveCaseKey(item, ctx)
 		}, id)).route(cfg.branches);
 	}
 	agent(nameOrOptions, optionsOrUndefined) {