@theclearsky/react-blender-nodes 0.0.4 → 0.0.6

package/README.md

@@ -21,7 +21,10 @@ a flexible and customizable node-based graph editor for web applications.
 React Blender Nodes recreates the iconic Blender node editor experience on the
 web. Built with modern React patterns and TypeScript, it offers a complete
 solution for creating interactive node-based interfaces with support for custom
-nodes, connections, and real-time manipulation.
+nodes, connections, and real-time manipulation. Features an intelligent type
+system with automatic inference, complex data validation, and comprehensive
+connection validation to ensure your node graphs are always type-safe and
+error-free.
 
 ## Quick Start
 
@@ -38,7 +41,6 @@ import {
   FullGraph,
   useFullGraph,
   makeStateWithAutoInfer,
-  makeNodeIdToNodeTypeWithAutoInfer,
   makeTypeOfNodeWithAutoInfer,
   makeDataTypeWithAutoInfer,
 } from 'react-blender-nodes';
@@ -72,14 +74,10 @@ function MyNodeEditor() {
     }),
   };
 
-  // Define node ID to type mapping with auto-infer
-  const nodeIdToNodeType = makeNodeIdToNodeTypeWithAutoInfer({});
-
   // Create state with auto-infer for complete type safety
   const initialState = makeStateWithAutoInfer({
     dataTypes,
     typeOfNodes,
-    nodeIdToNodeType,
     nodes: [],
     edges: [],
   });
@@ -103,7 +101,6 @@ throughout your graph system:
 - **`makeDataTypeWithAutoInfer`**: Validates data type definitions
 - **`makeTypeOfNodeWithAutoInfer`**: Validates node type definitions and
   dataType references
-- **`makeNodeIdToNodeTypeWithAutoInfer`**: Validates node ID to type mappings
 - **`makeStateWithAutoInfer`**: Provides complete type inference for the entire
   state
 
@@ -164,19 +161,91 @@ const dataTypes = {
 - Context menu for adding new nodes
 - Real-time node manipulation
 
-### 🎯 Advanced Features
-
-![Advanced Features](./docs/screenshots/advanced-features.png)
-
-- **Handle Shapes**: 13+ custom handle shapes including geometric and artistic
-  designs
-- **Input Components**: Built-in text and number inputs with validation
-- **Panel System**: Collapsible panels for organizing complex node inputs
+### 🧠 Smart Type System & Validation + Advanced Features
+
+https://github.com/user-attachments/assets/72d9384a-e9ca-4223-906a-dc422fb66f49
+
+- **Intelligent Type Inference**: Automatically infer node types from
+  connections
+  - Dynamic type resolution as you build your graph
+  - Real-time type updates when connections change
+  - Support for `inferFromConnection` data types
+- **Advanced Type Validation**: Comprehensive type checking system
+  - **Complex Type Checking**: Zod schema validation for complex data structures
+  - **Type Conversion Control**: Fine-grained control over allowed type
+    conversions
+  - **Cycle Detection**: Prevent infinite loops in your node graphs
+- **Multiple Data Types**: Support for diverse data structures
+  - Basic types: `string`, `number`
+  - Complex types: Custom objects with Zod schemas
+  - Special types: `inferFromConnection`, `noEquivalent`
+- **Runtime Safety**: Catch type errors before they break your application
+  - Connection validation with detailed error messages
+  - Automatic type propagation across connected nodes
+  - Schema compatibility checking for complex types
 - **State Management**: Integrated reducer for managing graph state
 - **TypeScript Support**: Full type safety with comprehensive definitions
 
 ## Usage Examples
 
+### Smart Type System with Validation
+
+```tsx
+import { z } from 'zod';
+
+// Define complex data types with Zod schemas
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+const dataTypes = {
+  stringType: makeDataTypeWithAutoInfer({
+    name: 'String',
+    underlyingType: 'string',
+    color: '#4A90E2',
+  }),
+  userType: makeDataTypeWithAutoInfer({
+    name: 'User',
+    underlyingType: 'complex',
+    complexSchema: userSchema,
+    color: '#7ED321',
+  }),
+  inferredType: makeDataTypeWithAutoInfer({
+    name: 'Inferred',
+    underlyingType: 'inferFromConnection',
+    color: '#FF6B6B',
+  }),
+};
+
+// Enable advanced validation features
+const initialState = makeStateWithAutoInfer({
+  dataTypes,
+  typeOfNodes: {
+    userInput: makeTypeOfNodeWithAutoInfer({
+      name: 'User Input',
+      inputs: [{ name: 'User Data', dataType: 'userType' }],
+      outputs: [{ name: 'Output', dataType: 'inferredType' }],
+    }),
+    stringProcessor: makeTypeOfNodeWithAutoInfer({
+      name: 'String Processor',
+      inputs: [{ name: 'Input', dataType: 'inferredType' }],
+      outputs: [{ name: 'Result', dataType: 'stringType' }],
+    }),
+  },
+  nodes: [],
+  edges: [],
+  // Enable smart validation features
+  enableTypeInference: true,
+  enableComplexTypeChecking: true,
+  enableCycleChecking: true,
+  allowedConversionsBetweenDataTypes: {
+    userType: { stringType: true }, // Allow user to string conversion
+  },
+});
+```
+
 ### Custom Node with Panels
 
 ```tsx

package/dist/index.d.ts

@@ -40,7 +40,7 @@ export declare type Action<DataTypeUniqueId extends string = string, NodeTypeUni
     type: typeof actionTypesMap.ADD_NODE;
     payload: {
         /** Type of node to add */
-        type: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['nodeIdToNodeType'][string];
+        type: NodeTypeUniqueId;
         /** Position where to place the node */
         position: XYPosition;
     };
@@ -49,7 +49,7 @@ export declare type Action<DataTypeUniqueId extends string = string, NodeTypeUni
     type: typeof actionTypesMap.ADD_NODE_AND_SELECT;
     payload: {
         /** Type of node to add */
-        type: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['nodeIdToNodeType'][string];
+        type: NodeTypeUniqueId;
         /** Position where to place the node */
         position: XYPosition;
     };
@@ -58,7 +58,7 @@ export declare type Action<DataTypeUniqueId extends string = string, NodeTypeUni
     type: typeof actionTypesMap.UPDATE_NODE_BY_REACT_FLOW;
     payload: {
         /** Array of node changes from ReactFlow */
-        changes: NodeChanges<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
+        changes: NodeChanges<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>;
     };
 } | {
     /** Update edges based on ReactFlow changes */
@@ -121,7 +121,7 @@ export declare const actionTypesMap: {
  * @returns Object containing updated nodes, edges, and validation result
  */
 export declare function addEdgeWithTypeChecking<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(newEdgeSourceNodeId: string, newEdgeSourceHandleId: string, newEdgeTargetNodeId: string, newEdgeTargetHandleId: string, state: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>): {
-    updatedNodes: Nodes<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
+    updatedNodes: Nodes<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>;
     updatedEdges: Edges;
     validation: ConnectionValidationResult;
 };
@@ -375,6 +375,8 @@ outputs?: ConfigurableNodeOutput<"string" | "number" | "complex" | "noEquivalent
 isCurrentlyInsideReactFlow?: boolean;
 /** Props for the node resizer component */
 nodeResizerProps?: NodeResizerWithMoreControlsProps;
+/** Node type unique id */
+nodeTypeUniqueId?: string | undefined;
 } & HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>;
 
 /**
@@ -472,7 +474,7 @@ export declare type ConfigurableNodeOutput<UnderlyingType extends SupportedUnder
  * Defines the complete configuration for a customizable node with inputs, outputs,
  * and optional panels. Supports both standalone usage and ReactFlow integration.
  */
-export declare type ConfigurableNodeProps<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
+export declare type ConfigurableNodeProps<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, NodeTypeUniqueId extends string = string, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = {
     /** Display name of the node */
     name?: string;
     /** Background color of the node header */
@@ -485,6 +487,8 @@ export declare type ConfigurableNodeProps<UnderlyingType extends SupportedUnderl
     isCurrentlyInsideReactFlow?: boolean;
     /** Props for the node resizer component */
     nodeResizerProps?: NodeResizerWithMoreControlsProps;
+    /** Node type unique id */
+    nodeTypeUniqueId?: NodeTypeUniqueId;
 } & HTMLAttributes<HTMLDivElement>;
 
 /**
@@ -530,15 +534,15 @@ export declare type ConfigurableNodeProps<UnderlyingType extends SupportedUnderl
  * />
  * ```
  */
-export declare const ConfigurableNodeReactFlowWrapper: ForwardRefExoticComponent<Omit<ConfigurableNodeReactFlowWrapperProps<"string" | "number" | "complex" | "noEquivalent" | "inferFromConnection", never, string>, "position"> & RefAttributes<HTMLDivElement>>;
+export declare const ConfigurableNodeReactFlowWrapper: ForwardRefExoticComponent<Omit<ConfigurableNodeReactFlowWrapperProps<"string" | "number" | "complex" | "noEquivalent" | "inferFromConnection", string, never, string>, "position"> & RefAttributes<HTMLDivElement>>;
 
 /** Props for the ConfigurableNodeReactFlowWrapper component */
-export declare type ConfigurableNodeReactFlowWrapperProps<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = NodeProps<ConfigurableNodeState<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>> & {
+export declare type ConfigurableNodeReactFlowWrapperProps<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, NodeTypeUniqueId extends string = string, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = NodeProps<ConfigurableNodeState<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>> & {
     position: XYPosition;
 };
 
 /** State type for configurable nodes in ReactFlow */
-export declare type ConfigurableNodeState<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = Node_2<Omit<ConfigurableNodeProps<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>, 'isCurrentlyInsideReactFlow'>, 'configurableNode'>;
+export declare type ConfigurableNodeState<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, NodeTypeUniqueId extends string = string, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = Node_2<Omit<ConfigurableNodeProps<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>, 'isCurrentlyInsideReactFlow'>, 'configurableNode'>;
 
 /**
  * Type for connection validation result
@@ -663,7 +667,6 @@ export declare function constructInputPanelOfType<DataTypeUniqueId extends strin
  * import {
  *   constructNodeOfType,
  *   makeStateWithAutoInfer,
- *   makeNodeIdToNodeTypeWithAutoInfer,
  *   makeTypeOfNodeWithAutoInfer,
  *   makeDataTypeWithAutoInfer
  * } from 'react-blender-nodes';
@@ -1060,7 +1063,6 @@ export declare type Edges = ConfigurableEdgeState[];
  *   FullGraph,
  *   useFullGraph,
  *   makeStateWithAutoInfer,
- *   makeNodeIdToNodeTypeWithAutoInfer,
  *   makeTypeOfNodeWithAutoInfer,
  *   makeDataTypeWithAutoInfer
  * } from 'react-blender-nodes';
@@ -1102,17 +1104,10 @@ export declare type Edges = ConfigurableEdgeState[];
  *     }),
  *   };
  *
- *   // Define node ID to type mapping with auto-infer
- *   const nodeIdToNodeType = makeNodeIdToNodeTypeWithAutoInfer({
- *     'node-1': 'inputNode',
- *     'node-2': 'outputNode',
- *   });
- *
  *   // Create state with auto-infer for complete type safety
  *   const initialState = makeStateWithAutoInfer({
  *     dataTypes,
  *     typeOfNodes,
- *     nodeIdToNodeType,
  *     nodes: [],
  *     edges: [],
  *   });
@@ -1146,6 +1141,11 @@ export declare type FullGraphProps<DataTypeUniqueId extends string = string, Nod
     ]>;
 };
 
+export declare function getResultantDataTypeOfHandleConsideringInferredType<DataTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(handle: ConfigurableNodeInput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId> | ConfigurableNodeOutput<UnderlyingType, ComplexSchemaType, DataTypeUniqueId> | undefined): {
+    dataTypeObject: DataType<UnderlyingType, ComplexSchemaType>;
+    dataTypeUniqueId: DataTypeUniqueId;
+} | undefined;
+
 declare type HandleIndices = {
     type: 'input';
     index1: number;
@@ -1300,11 +1300,6 @@ export declare function isSupportedUnderlyingType(type: string): type is Support
  */
 export declare function isValidDataTypeId<DataTypeUniqueId extends string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(id: string, dataTypes: Record<DataTypeUniqueId, DataType<UnderlyingType, ComplexSchemaType>>): id is DataTypeUniqueId;
 
-/**
- * Type guard to check if a string is a valid NodeTypeUniqueId
- */
-export declare function isValidNodeTypeUniqueId<NodeTypeUniqueId extends string>(id: string, nodeIdToNodeType: Record<string, NodeTypeUniqueId>): id is NodeTypeUniqueId;
-
 /**
  * Main reducer function for managing graph state
  *
@@ -1325,7 +1320,6 @@ export declare function isValidNodeTypeUniqueId<NodeTypeUniqueId extends string>
  * import {
  *   mainReducer,
  *   makeStateWithAutoInfer,
- *   makeNodeIdToNodeTypeWithAutoInfer,
  *   makeTypeOfNodeWithAutoInfer,
  *   makeDataTypeWithAutoInfer
  * } from 'react-blender-nodes';
@@ -1348,14 +1342,9 @@ export declare function isValidNodeTypeUniqueId<NodeTypeUniqueId extends string>
  *   }),
  * };
  *
- * const nodeIdToNodeType = makeNodeIdToNodeTypeWithAutoInfer({
- *   'node-1': 'inputNode',
- * });
- *
  * const state = makeStateWithAutoInfer({
  *   dataTypes,
  *   typeOfNodes,
- *   nodeIdToNodeType,
  *   nodes: [],
  *   edges: [],
  * });
@@ -1443,34 +1432,6 @@ export declare function makeAllowedConversionsBetweenDataTypesWithAutoInfer<Data
  */
 export declare function makeDataTypeWithAutoInfer<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(input: DataType<UnderlyingType, ComplexSchemaType>): DataType<UnderlyingType, ComplexSchemaType>;
 
-/**
- * Helper function to create a node ID to node type mapping with automatic type inference
- *
- * This function is essential for type safety when mapping node IDs to their types.
- * It ensures that TypeScript can validate that all node type references are valid,
- * preventing runtime errors when dispatching actions and providing better IDE support.
- *
- * @template NodeTypeUniqueId - Unique identifier type for node types
- * @param input - The node ID to node type mapping
- * @returns The mapping with proper typing
- *
- * @example
- * ```tsx
- * // ✅ Type-safe - TypeScript will validate node type references
- * const nodeIdToNodeType = makeNodeIdToNodeTypeWithAutoInfer({
- *   'node-1': 'inputNode',
- *   'node-2': 'outputNode',
- * });
- *
- * // ❌ Without auto-infer - TypeScript can't validate node type references
- * const nodeIdToNodeType = {
- *   'node-1': 'inputNode',
- *   'node-2': 'outputNode',
- * };
- * ```
- */
-export declare function makeNodeIdToNodeTypeWithAutoInfer<NodeTypeUniqueId extends string = string>(input: NodeIdToNodeType<NodeTypeUniqueId>): NodeIdToNodeType<NodeTypeUniqueId>;
-
 /**
  * Helper function to create a state with automatic type inference
  *
@@ -1503,7 +1464,6 @@ export declare function makeNodeIdToNodeTypeWithAutoInfer<NodeTypeUniqueId exten
  *       outputs: []
  *     })
  *   },
- *   nodeIdToNodeType: makeNodeIdToNodeTypeWithAutoInfer({}),
  *   nodes: [],
  *   edges: [],
  * });
@@ -1513,7 +1473,6 @@ export declare function makeNodeIdToNodeTypeWithAutoInfer<NodeTypeUniqueId exten
  *   dataTypes: { stringType: { name: 'String', underlyingType: 'string', color: '#4A90E2' } },
  *   typeOfNodes: { inputNode: { name: 'Input', inputs: [], outputs: [] } },
  *   nodes: [],
- *   nodeIdToNodeType: {},
  *   edges: [],
  * };
  * ```
@@ -1555,14 +1514,7 @@ export declare function makeTypeOfNodeWithAutoInfer<DataTypeUniqueId extends str
 /**
  * Array of node changes for ReactFlow
  */
-export declare type NodeChanges<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = NodeChange<Optional<ConfigurableNodeReactFlowWrapperProps<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>, NodeOptionalKeys>>[];
-
-/**
- * Mapping from node IDs to their node types
- *
- * @template NodeTypeUniqueId - Unique identifier type for node types
- */
-export declare type NodeIdToNodeType<NodeTypeUniqueId extends string = string> = Record<string, NodeTypeUniqueId>;
+export declare type NodeChanges<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, NodeTypeUniqueId extends string = string, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = NodeChange<Optional<ConfigurableNodeReactFlowWrapperProps<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>, NodeOptionalKeys>>[];
 
 declare type NodeOptionalKeys = 'draggable' | 'zIndex' | 'selectable' | 'deletable' | 'dragging' | 'selected' | 'isConnectable' | 'positionAbsoluteX' | 'positionAbsoluteY';
 
@@ -1634,7 +1586,7 @@ export declare type NodeResizerWithMoreControlsProps = NodeResizerProps & {
 /**
  * Array of configurable nodes in the graph
  */
-export declare type Nodes<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = Optional<ConfigurableNodeReactFlowWrapperProps<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>, NodeOptionalKeys>[];
+export declare type Nodes<UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, NodeTypeUniqueId extends string = string, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never, DataTypeUniqueId extends string = string> = Optional<ConfigurableNodeReactFlowWrapperProps<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>, NodeOptionalKeys>[];
 
 declare type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
 
@@ -1682,7 +1634,7 @@ export declare type ReactFlowAwareInputProps = {
  * @returns Object containing updated nodes, edges, and validation result
  */
 export declare function removeEdgeWithTypeChecking<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(removedEdge: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>['edges'][number], state: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>, removedEdgeChange: EdgeChange<ConfigurableEdgeState>): {
-    updatedNodes: Nodes<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
+    updatedNodes: Nodes<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>;
     updatedEdges: Edges;
     validation: ConnectionValidationResult;
 };
@@ -1780,17 +1732,57 @@ export declare type State<DataTypeUniqueId extends string = string, NodeTypeUniq
     /** Map of node type definitions */
     typeOfNodes: Record<NodeTypeUniqueId, TypeOfNode<DataTypeUniqueId>>;
     /** Array of nodes in the graph */
-    nodes: Nodes<UnderlyingType, ComplexSchemaType, DataTypeUniqueId>;
-    /** Mapping from node IDs to their types */
-    nodeIdToNodeType: NodeIdToNodeType<NodeTypeUniqueId>;
+    nodes: Nodes<UnderlyingType, NodeTypeUniqueId, ComplexSchemaType, DataTypeUniqueId>;
     /** Array of edges in the graph */
     edges: Edges;
-    /** Optional mapping of allowed conversions between data types */
+    /**
+     * Optional mapping of allowed conversions between data types
+     * - When not provided, all conversions are allowed
+     * - If provided, only the conversions that are explicitly allowed will be allowed (happens even with empty object)
+     * - By default, it will not allow conversion between complex types unless explicitly allowed here (even if complex type checking is enabled)
+     * - If you want to allow conversion between complex types unless disallowed by complex type checking, you can set `allowConversionBetweenComplexTypesUnlessDisallowedByComplexTypeChecking` to true
+     *
+     * @default undefined
+     */
     allowedConversionsBetweenDataTypes?: AllowedConversionsBetweenDataTypes<DataTypeUniqueId>;
-    /** Whether to enable type inference */
+    /**
+     * Whether to allow conversion between complex types unless disallowed by complex type checking
+     * - If not provided, is considered disabled
+     * - Only takes effect if complex type checking is enabled (`allowedConversionsBetweenDataTypes` is provided)
+     * - If enabled, it will allow conversion between complex types unless disallowed by complex type checking
+     * - If disabled, it will not allow conversion between complex types unless explicitly allowed by `allowedConversionsBetweenDataTypes`, even if complex type checking is enabled
+     *
+     * @default undefined
+     */
+    allowConversionBetweenComplexTypesUnlessDisallowedByComplexTypeChecking?: boolean;
+    /**
+     * Whether to enable type inference
+     * - If not provided, is considered disabled
+     * - When disabled, the types of the nodes are not inferred from the connections
+     * - When enabled, the types of the nodes are inferred from the connections and reset when edges are removed
+     *
+     * @default undefined
+     */
     enableTypeInference?: boolean;
-    /** Whether to enable complex type checking */
+    /**
+     * Whether to enable complex type checking
+     * - If not provided, is considered disabled
+     * - When disabled, the complex types are not checked for compatibility, all connections are allowed
+     * - When enabled, the complex types are checked for compatibility, and connections are not allowed if the complex types are not compatible
+     * - Complex types are compatible if they are the same type or if they have exactly the same schema
+     *
+     * @default undefined
+     */
     enableComplexTypeChecking?: boolean;
+    /**
+     * Whether to enable cycle checking
+     * - If not provided, is considered disabled
+     * - When disabled, the cycles are not checked, all connections are allowed
+     * - When enabled, the cycles are checked, and connections are not allowed if they create a cycle
+     *
+     * @default undefined
+     */
+    enableCycleChecking?: boolean;
 };
 
 /**
@@ -1854,6 +1846,7 @@ export declare type TypeOfNode<DataTypeUniqueId extends string = string> = {
     inputs: (TypeOfInput<DataTypeUniqueId> | TypeOfInputPanel<DataTypeUniqueId>)[];
     /** Array of outputs */
     outputs: TypeOfInput<DataTypeUniqueId>[];
+    subtree?: {};
 };
 
 /**
@@ -1973,7 +1966,6 @@ export declare type UseDragReturn = {
  * import {
  *   useFullGraph,
  *   makeStateWithAutoInfer,
- *   makeNodeIdToNodeTypeWithAutoInfer,
  *   makeTypeOfNodeWithAutoInfer,
  *   makeDataTypeWithAutoInfer
  * } from 'react-blender-nodes';
@@ -2006,16 +1998,10 @@ export declare type UseDragReturn = {
  *   }),
  * };
  *
- * // Define node ID to type mapping with auto-infer
- * const nodeIdToNodeType = makeNodeIdToNodeTypeWithAutoInfer({
- *   'node-1': 'inputNode',
- * });
- *
  * // Create state with auto-infer for complete type safety
  * const initialState = makeStateWithAutoInfer({
  *   dataTypes,
  *   typeOfNodes,
- *   nodeIdToNodeType,
  *   nodes: [],
  *   edges: [],
  * });
@@ -2034,4 +2020,17 @@ export declare function useFullGraph<DataTypeUniqueId extends string = string, N
     dispatch: ActionDispatch<[action: Action<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>]>;
 };
 
+/**
+ * Checks if adding an edge will create a cycle in the graph
+ *
+ * @template DataTypeUniqueId - Unique identifier type for data types
+ * @template NodeTypeUniqueId - Unique identifier type for node types
+ * @template UnderlyingType - Supported underlying data types
+ * @template ComplexSchemaType - Zod schema type for complex data types
+ * @param state - The current graph state
+ * @param newEdge - The edge to check
+ * @returns Whether the edge will create a cycle
+ */
+export declare function willAddingEdgeCreateCycle<DataTypeUniqueId extends string = string, NodeTypeUniqueId extends string = string, UnderlyingType extends SupportedUnderlyingTypes = SupportedUnderlyingTypes, ComplexSchemaType extends UnderlyingType extends 'complex' ? z.ZodType : never = never>(state: State<DataTypeUniqueId, NodeTypeUniqueId, UnderlyingType, ComplexSchemaType>, sourceNodeId: string, targetNodeId: string): boolean;
+
 export { }