@codemation/core 0.2.3 → 0.3.0

package/src/authoring/defineNode.types.ts

@@ -4,10 +4,11 @@ import type {
   CredentialRequirement,
   CredentialTypeId,
 } from "../contracts/credentialTypes";
-import type { Node, NodeExecutionContext } from "../contracts/runtimeTypes";
-import type { Items, NodeOutputs, RunnableNodeConfig } from "../contracts/workflowTypes";
+import type { ItemNode, Node, NodeExecutionContext } from "../contracts/runtimeTypes";
+import type { Item, ItemInputMapper, Items, NodeOutputs, RunnableNodeConfig } from "../contracts/workflowTypes";
 import type { TypeToken } from "../di";
 import { node as persistedNode } from "../runtime-types/runtimeTypeDecorators.types";
+import type { ZodType } from "zod";
 import { z } from "zod";
 import { DefinedNodeRegistry } from "./DefinedNodeRegistry";
 
@@ -54,27 +55,46 @@ export interface DefinedNodeRunContext<
   readonly execution: NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>;
 }
 
+/**
+ * Arguments for {@link defineNode} `executeOne` (engine `ctx` matches {@link ItemNode.executeOne};
+ * the second callback parameter adds {@link DefinedNodeRunContext} for credential accessors).
+ */
+export type DefineNodeExecuteOneArgs<TConfig extends CredentialJsonRecord, TInputJson, TWireJson> = Readonly<{
+  input: TInputJson;
+  item: Item;
+  itemIndex: number;
+  items: Items;
+  ctx: NodeExecutionContext<RunnableNodeConfig<TInputJson, unknown, TWireJson> & Readonly<{ config: TConfig }>>;
+}>;
+
 export interface DefinedNode<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
   TInputJson,
   TOutputJson,
   _TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+  TWireJson = TInputJson,
 > {
   readonly kind: "defined-node";
   readonly key: TKey;
   readonly title: string;
   readonly description?: string;
-  create(config: TConfig, name?: string, id?: string): RunnableNodeConfig<TInputJson, TOutputJson>;
+  create(config: TConfig, name?: string, id?: string): RunnableNodeConfig<TInputJson, TOutputJson, TWireJson>;
   register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
 }
 
+/**
+ * Plugin / DSL-friendly node: **one item in, one item out** per engine activation step.
+ * The engine applies {@link RunnableNodeConfig.mapInput} (if any) + {@link RunnableNodeConfig.inputSchema}
+ * before `executeOne`. Use {@link defineBatchNode} for legacy batch `run(items, …)` semantics.
+ */
 export interface DefineNodeOptions<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
   TInputJson,
   TOutputJson,
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+  TWireJson = TInputJson,
 > {
   readonly key: TKey;
   readonly title: string;
@@ -84,6 +104,38 @@ export interface DefineNodeOptions<
    * The Next host resolves Lucide (`lucide:…`), built-in SVGs (`builtin:…`), Simple Icons (`si:…`), and image URLs (`https:`, `data:`, `/…`).
    */
   readonly icon?: string;
+  /** Default values / form hints for **static** node configuration (credentials, retry, IDs), not per-item payload. */
+  readonly input?: Readonly<Record<keyof TConfig & string, unknown>>;
+  readonly configSchema?: z.ZodType<TConfig>;
+  readonly credentials?: TBindings;
+  /**
+   * Validates **`input`** after optional {@link mapInput} (engine also accepts `inputSchema` on the node class).
+   */
+  readonly inputSchema?: ZodType<TInputJson>;
+  /**
+   * Maps wire JSON (`item.json` from upstream) to execute input before validation.
+   */
+  readonly mapInput?: ItemInputMapper<TWireJson, TInputJson>;
+  executeOne(
+    args: DefineNodeExecuteOneArgs<TConfig, TInputJson, TWireJson>,
+    context: DefinedNodeRunContext<TConfig, TBindings>,
+  ): MaybePromise<TOutputJson>;
+}
+
+/**
+ * Batch-oriented defined node (legacy): receives all items at once via `run`.
+ */
+export interface DefineBatchNodeOptions<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson,
+  TOutputJson,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+> {
+  readonly key: TKey;
+  readonly title: string;
+  readonly description?: string;
+  readonly icon?: string;
   readonly input?: Readonly<Record<keyof TConfig & string, unknown>>;
   readonly configSchema?: z.ZodType<TConfig>;
   readonly credentials?: TBindings;
@@ -161,11 +213,100 @@ export function defineNode<
   TInputJson,
   TOutputJson,
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+  TWireJson = TInputJson,
+>(
+  options: DefineNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings, TWireJson>,
+): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TWireJson> {
+  const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
+  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson, TWireJson> &
+    Readonly<{ config: TConfig }>;
+
+  const DefinedNodeRuntime = class implements ItemNode<DefinedRunnableNodeConfigShape, TInputJson, TOutputJson> {
+    readonly kind = "node" as const;
+    readonly outputPorts = ["main"] as const;
+    readonly inputSchema = options.inputSchema;
+
+    async executeOne(
+      args: Readonly<{
+        input: TInputJson;
+        item: Item;
+        itemIndex: number;
+        items: Items;
+        ctx: NodeExecutionContext<DefinedRunnableNodeConfigShape>;
+      }>,
+    ): Promise<TOutputJson> {
+      const ctx = args.ctx;
+      const context: DefinedNodeRunContext<TConfig, TBindings> = {
+        config: ctx.config.config,
+        credentials: definedNodeCredentialAccessorFactory.create(
+          options.credentials,
+          ctx,
+        ) as DefinedNodeCredentialAccessors<TBindings>,
+        execution: ctx as unknown as NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>,
+      };
+      const payload: DefineNodeExecuteOneArgs<TConfig, TInputJson, TWireJson> = {
+        input: args.input,
+        item: args.item,
+        itemIndex: args.itemIndex,
+        items: args.items,
+        ctx,
+      };
+      return await options.executeOne(payload, context);
+    }
+  };
+
+  persistedNode({ name: options.key })(DefinedNodeRuntime);
+
+  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson, TWireJson> {
+    readonly kind = "node" as const;
+    readonly type: TypeToken<unknown> = DefinedNodeRuntime;
+    readonly icon = options.icon;
+    readonly inputSchema = options.inputSchema;
+    readonly mapInput = options.mapInput;
+
+    constructor(
+      public readonly name: string,
+      public readonly config: TConfig,
+      public readonly id?: string,
+    ) {}
+
+    getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
+      return credentialRequirements;
+    }
+  };
+
+  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TWireJson> = {
+    kind: "defined-node",
+    key: options.key,
+    title: options.title,
+    description: options.description,
+    create(config, name = options.title, id) {
+      return new DefinedRunnableNodeConfig(name, config, id);
+    },
+    register(context) {
+      context.registerNode(DefinedNodeRuntime);
+    },
+  };
+
+  DefinedNodeRegistry.register(
+    definition as DefinedNode<string, Record<string, unknown>, unknown, unknown, undefined, unknown>,
+  );
+
+  return definition;
+}
+
+export function defineBatchNode<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson,
+  TOutputJson,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
 >(
-  options: DefineNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings>,
-): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> {
+  options: DefineBatchNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings>,
+): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TInputJson> {
   const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
-  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson> & Readonly<{ config: TConfig }>;
+  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson, TInputJson> &
+    Readonly<{ config: TConfig }>;
 
   const DefinedNodeRuntime = class implements Node<DefinedRunnableNodeConfigShape> {
     readonly kind = "node" as const;
@@ -198,7 +339,7 @@ export function defineNode<
 
   persistedNode({ name: options.key })(DefinedNodeRuntime);
 
-  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson> {
+  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson, TInputJson> {
     readonly kind = "node" as const;
     readonly type: TypeToken<unknown> = DefinedNodeRuntime;
     readonly icon = options.icon;
@@ -214,7 +355,7 @@ export function defineNode<
     }
   };
 
-  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> = {
+  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings, TInputJson> = {
     kind: "defined-node",
     key: options.key,
     title: options.title,
@@ -227,7 +368,9 @@ export function defineNode<
     },
   };
 
-  DefinedNodeRegistry.register(definition as DefinedNode<string, Record<string, unknown>, unknown, unknown>);
+  DefinedNodeRegistry.register(
+    definition as DefinedNode<string, Record<string, unknown>, unknown, unknown, undefined, unknown>,
+  );
 
   return definition;
 }

package/src/authoring/index.ts

@@ -5,8 +5,10 @@ export type {
   DefinedNodeCredentialBinding,
   DefinedNodeCredentialBindings,
   DefinedNodeRunContext,
+  DefineBatchNodeOptions,
+  DefineNodeExecuteOneArgs,
   DefineNodeOptions,
 } from "./defineNode.types";
-export { defineNode } from "./defineNode.types";
+export { defineBatchNode, defineNode } from "./defineNode.types";
 export type { DefineCredentialOptions } from "./defineCredential.types";
 export { defineCredential } from "./defineCredential.types";