@codemation/node-example 0.0.21 → 0.0.24

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @codemation/node-example
 
+## 0.0.24
+
+### Patch Changes
+
+- Updated dependencies [[`d3a4321`](https://github.com/MadeRelevant/codemation/commit/d3a4321dc178df51dfd61cc6eb872ccca36bbcdb)]:
+  - @codemation/core@0.2.3
+
+## 0.0.23
+
+### Patch Changes
+
+- Updated dependencies [[`74dc571`](https://github.com/MadeRelevant/codemation/commit/74dc571afb592bd7c05297b25f9f1fb06a46815f), [`74dc571`](https://github.com/MadeRelevant/codemation/commit/74dc571afb592bd7c05297b25f9f1fb06a46815f)]:
+  - @codemation/core@0.2.2
+
+## 0.0.22
+
+### Patch Changes
+
+- Updated dependencies [[`4989e9c`](https://github.com/MadeRelevant/codemation/commit/4989e9c7d97513c05904d47d2f85794ba716a4d3)]:
+  - @codemation/core@0.2.1
+
 ## 0.0.21
 
 ### Patch Changes

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { ReadableStream } from "node:stream/web";
 import { InjectionToken as TypeToken } from "tsyringe";
+import { ZodType } from "zod";
 
 //#region ../core/src/contracts/retryPolicySpec.types.d.ts
 
@@ -169,10 +170,60 @@ interface NodeConfigBase {
 }
 declare const runnableNodeInputType: unique symbol;
 declare const runnableNodeOutputType: unique symbol;
-interface RunnableNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> extends NodeConfigBase {
+/** Phantom: JSON shape on the wire from upstream before {@link RunnableNodeConfig.mapInput}. */
+declare const runnableNodeWireType: unique symbol;
+/**
+ * Read-only execution slice passed to {@link RunnableNodeConfig.mapInput} (aligned with the engine’s
+ * node execution context for `runId`, `data`, etc.). Use **`ctx.data`** to read **any completed** upstream
+ * node’s outputs in this run (e.g. `ctx.data.getOutputItems(nodeIdA, "main")` while mapping at D), not only
+ * the immediate predecessor’s {@link ItemInputMapperArgs.item}.
+ */
+interface ItemInputMapperContext {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  /** Node whose activation is being prepared (the consumer of `mapInput`). */
+  readonly nodeId: NodeId;
+  readonly activationId: NodeActivationId;
+  readonly parent?: ParentExecutionRef;
+  readonly data: RunDataSnapshot;
+}
+/**
+ * Arguments for optional per-item input mapping applied by the engine before Zod validation.
+ */
+interface ItemInputMapperArgs<TWireJson$1 = unknown> {
+  readonly item: Item<TWireJson$1>;
+  readonly itemIndex: number;
+  readonly items: Items<TWireJson$1>;
+  readonly ctx: ItemInputMapperContext;
+}
+/**
+ * Per-item mapper before Zod validation. Uses a **bivariant** method signature so concrete
+ * `ItemInputMapper<SpecificWire, TIn>` remains assignable to `RunnableNodeConfig` fields typed as
+ * `ItemInputMapper<unknown, unknown>` (same pattern as React-style callbacks).
+ */
+type ItemInputMapper<TWireJson$1 = unknown, TInputJson$1 = unknown> = {
+  bivarianceHack(args: ItemInputMapperArgs<TWireJson$1>): TInputJson$1 | Promise<TInputJson$1>;
+}["bivarianceHack"];
+/**
+ * Runnable node: **`TInputJson`** is the payload after `mapInput` (if any) + Zod validation — what {@link ItemNode}
+ * `executeOne` receives. **`TOutputJson`** is emitted `item.json` on outputs. **`TWireJson`** is `item.json` from
+ * upstream **before** `mapInput`; it defaults to **`TInputJson`** when there is no mapper or wire differs from execute input.
+ */
+interface RunnableNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown, TWireJson$1 = TInputJson$1> extends NodeConfigBase {
   readonly kind: "node";
   readonly [runnableNodeInputType]?: TInputJson$1;
   readonly [runnableNodeOutputType]?: TOutputJson$1;
+  readonly [runnableNodeWireType]?: TWireJson$1;
+  /**
+   * Optional Zod input contract for {@link ItemNode} when not set on the node class.
+   * Resolution order: node instance `inputSchema`, then config `inputSchema`, then `z.unknown()`.
+   */
+  readonly inputSchema?: ZodType<TInputJson$1>;
+  /**
+   * Optional per-item mapper: engine applies it before validating against the node’s `inputSchema`.
+   * When omitted, the engine validates `item.json` directly.
+   */
+  readonly mapInput?: ItemInputMapper<TWireJson$1, TInputJson$1>;
 }
 type PairedItemRef = Readonly<{
   nodeId: NodeId;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ReadableStream } from "node:stream/web";
 import { InjectionToken as TypeToken } from "tsyringe";
+import { ZodType } from "zod";
 
 //#region ../core/src/contracts/retryPolicySpec.types.d.ts
 
@@ -169,10 +170,60 @@ interface NodeConfigBase {
 }
 declare const runnableNodeInputType: unique symbol;
 declare const runnableNodeOutputType: unique symbol;
-interface RunnableNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> extends NodeConfigBase {
+/** Phantom: JSON shape on the wire from upstream before {@link RunnableNodeConfig.mapInput}. */
+declare const runnableNodeWireType: unique symbol;
+/**
+ * Read-only execution slice passed to {@link RunnableNodeConfig.mapInput} (aligned with the engine’s
+ * node execution context for `runId`, `data`, etc.). Use **`ctx.data`** to read **any completed** upstream
+ * node’s outputs in this run (e.g. `ctx.data.getOutputItems(nodeIdA, "main")` while mapping at D), not only
+ * the immediate predecessor’s {@link ItemInputMapperArgs.item}.
+ */
+interface ItemInputMapperContext {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  /** Node whose activation is being prepared (the consumer of `mapInput`). */
+  readonly nodeId: NodeId;
+  readonly activationId: NodeActivationId;
+  readonly parent?: ParentExecutionRef;
+  readonly data: RunDataSnapshot;
+}
+/**
+ * Arguments for optional per-item input mapping applied by the engine before Zod validation.
+ */
+interface ItemInputMapperArgs<TWireJson$1 = unknown> {
+  readonly item: Item<TWireJson$1>;
+  readonly itemIndex: number;
+  readonly items: Items<TWireJson$1>;
+  readonly ctx: ItemInputMapperContext;
+}
+/**
+ * Per-item mapper before Zod validation. Uses a **bivariant** method signature so concrete
+ * `ItemInputMapper<SpecificWire, TIn>` remains assignable to `RunnableNodeConfig` fields typed as
+ * `ItemInputMapper<unknown, unknown>` (same pattern as React-style callbacks).
+ */
+type ItemInputMapper<TWireJson$1 = unknown, TInputJson$1 = unknown> = {
+  bivarianceHack(args: ItemInputMapperArgs<TWireJson$1>): TInputJson$1 | Promise<TInputJson$1>;
+}["bivarianceHack"];
+/**
+ * Runnable node: **`TInputJson`** is the payload after `mapInput` (if any) + Zod validation — what {@link ItemNode}
+ * `executeOne` receives. **`TOutputJson`** is emitted `item.json` on outputs. **`TWireJson`** is `item.json` from
+ * upstream **before** `mapInput`; it defaults to **`TInputJson`** when there is no mapper or wire differs from execute input.
+ */
+interface RunnableNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown, TWireJson$1 = TInputJson$1> extends NodeConfigBase {
   readonly kind: "node";
   readonly [runnableNodeInputType]?: TInputJson$1;
   readonly [runnableNodeOutputType]?: TOutputJson$1;
+  readonly [runnableNodeWireType]?: TWireJson$1;
+  /**
+   * Optional Zod input contract for {@link ItemNode} when not set on the node class.
+   * Resolution order: node instance `inputSchema`, then config `inputSchema`, then `z.unknown()`.
+   */
+  readonly inputSchema?: ZodType<TInputJson$1>;
+  /**
+   * Optional per-item mapper: engine applies it before validating against the node’s `inputSchema`.
+   * When omitted, the engine validates `item.json` directly.
+   */
+  readonly mapInput?: ItemInputMapper<TWireJson$1, TInputJson$1>;
 }
 type PairedItemRef = Readonly<{
   nodeId: NodeId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/node-example",
-  "version": "0.0.21",
+  "version": "0.0.24",
   "publishConfig": {
     "access": "public"
   },
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@codemation/core": "0.2.0"
+    "@codemation/core": "0.2.3"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",