simple-circuit-engine 0.0.11 → 0.0.12

package/dist/core/topology/Circuit.d.ts

@@ -0,0 +1,420 @@
+import { UUID, Rotation, Position } from '../utils';
+import { ComponentType, ENodeSourceType, ICircuit } from './types';
+import { CircuitOptions } from './CircuitOptions';
+import { CircuitMetadata } from './CircuitMetadata';
+import { Component } from './Component';
+import { ENode } from './ENode';
+import { Wire } from './Wire';
+/**
+ * Circuit container managing components, ENodes, and wires.
+ *
+ * The Circuit class provides:
+ * - Component management (add/remove with automatic pin ENode creation)
+ * - Topology queries (get by ID, enumerate all)
+ * - Automatic lifecycle management (cascade deletion, orphan cleanup)
+ * - JSON serialization for persistence
+ *
+ * **Key Principles**:
+ * - Users manage Components and Wires; ENodes are managed automatically
+ * - Removing a Component cascades to remove its pins and connected wires
+ * - Orphaned branching ENodes (no wires) are automatically removed
+ * - All operations maintain bidirectional consistency
+ *
+ * @example
+ * ```typescript
+ * const circuit = new Circuit();
+ *
+ * // Add a component at position (10, 20) with 2 pins
+ * const lightbulb = circuit.addComponent(
+ *   new Position(10, 20),
+ *   new Rotation(90),
+ *   2
+ * );
+ *
+ * console.log(lightbulb.id);    // UUID
+ * console.log(lightbulb.pins);  // [pin-uuid-1, pin-uuid-2]
+ *
+ * // Query components
+ * const comp = circuit.getComponent(lightbulb.id);
+ * const all = circuit.getAllComponents();
+ *
+ * // Remove component (cascade deletes pins and wires)
+ * circuit.removeComponent(lightbulb.id);
+ * ```
+ */
+export declare class Circuit {
+    /**
+     * Circuit metadata holding general information.
+     * @private
+     */
+    metadata: CircuitMetadata;
+    /**
+     * Map of all components in the circuit (UUID → Component).
+     * @private
+     */
+    private components;
+    /**
+     * Map of all electrical nodes in the circuit (UUID → ENode).
+     * Includes both pin nodes and branching point nodes.
+     * @private
+     */
+    private enodes;
+    /**
+     * Map of all wires in the circuit (UUID → Wire).
+     * @private
+     */
+    private wires;
+    /**
+     * Create a new empty circuit.
+     */
+    constructor(options: CircuitOptions);
+    get name(): string;
+    set name(value: string);
+    /**
+     * Add a new component to the circuit.
+     *
+     * Automatically creates pin ENodes for the component and links them
+     * bidirectionally. Pin ENode UUIDs are stored in the component's pins array.
+     * Pin labels are derived from the ComponentType metadata.
+     *
+     * @param type - Component type (Battery, Switch, LED, etc.)
+     * @param position - Grid position (x, y integers)
+     * @param rotation - Orientation angle (integer degrees)
+     * @param config - Optional configuration map for component-specific settings
+     * @returns The created Component
+     * @throws {TypeError} If position/rotation coordinates are not integers
+     *
+     * @example
+     * ```typescript
+     * const lightbulb = circuit.addComponent(
+     *   new Position(10, 20),
+     *   new Rotation(90),
+     *   ComponentType.Lightbulb
+     * );
+     *
+     * console.log(lightbulb.type);        // ComponentType.Lightbulb
+     * console.log(lightbulb.pins.length); // 2
+     * console.log(lightbulb.position.x);  // 10
+     * ```
+     */
+    addComponent(type: ComponentType, position: Position, rotation: Rotation, config?: Map<string, string> | undefined): Component;
+    /**
+     * Resolve and update the transitionSpan config for a component
+     * if automatic resolution returns undefined nothing is done on the component
+     *
+     * @param component - Component to resolve transitionSpan for
+     */
+    resolveTransitionSpan(component: Component): void;
+    /**
+     * Remove a component from the circuit.
+     *
+     * **Cascade deletion** removes:
+     * - All pin ENodes belonging to the component
+     * - All Wires connected to those pins
+     *
+     * @param id - Component UUID
+     * @throws {Error} If component does not exist
+     * @returns Object containing arrays of deleted Wires and ENodes IDs
+     *
+     * @example
+     * ```typescript
+     * circuit.removeComponent(componentId);
+     * // Component, its pins, and connected wires are all removed
+     * ```
+     */
+    removeComponent(id: UUID): {
+        deletedWires: UUID[];
+        deletedENodes: UUID[];
+    };
+    hasComponent(id: UUID): boolean;
+    /**
+     * Get a component by ID.
+     *
+     * @param id - Component UUID
+     * @returns The Component or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const component = circuit.getComponent(componentId);
+     * if (component) {
+     *   console.log(component.position);
+     * }
+     * ```
+     */
+    getComponent(id: UUID): Component | undefined;
+    /**
+     * Get all components in the circuit.
+     *
+     * Returns a new array on each call (defensive copy).
+     *
+     * @returns Array of all Components
+     *
+     * @example
+     * ```typescript
+     * const components = circuit.getAllComponents();
+     * console.log(`Circuit has ${components.length} components`);
+     *
+     * for (const comp of components) {
+     *   console.log(comp.id, comp.position);
+     * }
+     * ```
+     */
+    getAllComponents(): Component[];
+    getAllComponentsByType(type: ComponentType): Component[];
+    getFirstComponentOfType(type: ComponentType): Component | undefined;
+    /**
+     * Get an electrical node by ID.
+     *
+     * Note: ENodes are automatically managed and not directly created
+     * or removed by users.
+     *
+     * @param id - ENode UUID
+     * @returns The ENode or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const component = circuit.addComponent(
+     *   new Position(10, 20),
+     *   new Rotation(0),
+     *   2
+     * );
+     *
+     * const pinId = component.pins[0];
+     * const enode = circuit.getENode(pinId);
+     * console.log(enode.type); // ENodeType.Pin
+     * ```
+     */
+    getENode(id: UUID): ENode | undefined;
+    /**
+     * Get all electrical nodes in the circuit.
+     *
+     * Includes both pin nodes (from components) and branching point nodes
+     * (from wire splits).
+     *
+     * Returns a new array on each call (defensive copy).
+     *
+     * @returns Array of all ENodes
+     *
+     * @example
+     * ```typescript
+     * const enodes = circuit.getAllENodes();
+     * console.log(`Circuit has ${enodes.length} electrical nodes`);
+     *
+     * for (const enode of enodes) {
+     *   console.log(enode.id, enode.type);
+     * }
+     * ```
+     */
+    getAllENodes(): ENode[];
+    /**
+     * Add a branching point electrical node at a specific position.
+     *
+     * Branching points are used to split wires and create junctions.
+     * @param position - Grid position for the branching point
+     * @param sourceType - Optional source type (voltage/current)
+     * @returns The created ENode
+     */
+    addBranchingPoint(position: Position, sourceType?: ENodeSourceType): ENode;
+    /**
+     * Remove a branching point electrical node from the circuit.
+     * Also removes all wires connected to this branching point if there are ony one or more than 2.
+     * In the case there are exactly two wires, they will be merged before removing the branching point.
+     *
+     * @param id - Branching point ENode UUID
+     * @throws {Error} If ENode does not exist or is not a branching point
+     */
+    removeBranchingPoint(id: UUID): {
+        deletedWires?: UUID[] | undefined;
+        mergedWires?: UUID[] | undefined;
+        newWire?: Wire | undefined;
+    };
+    /**
+     * Add a wire connecting two electrical nodes.
+     *
+     * Validates that both nodes exist, not a self-connection, and no duplicate.
+     * Updates bidirectional references (Wire ↔ ENodes).
+     *
+     * @param node1 - First ENode UUID
+     * @param node2 - Second ENode UUID
+     * @param intermediatePositions - Optional path waypoints for rendering
+     * @returns The created Wire, or Error if validation fails
+     *
+     * @example
+     * ```typescript
+     * const comp1 = circuit.addComponent(new Position(0, 0), new Rotation(0), 1);
+     * const comp2 = circuit.addComponent(new Position(10, 10), new Rotation(0), 1);
+     *
+     * const wire = circuit.addWire(comp1.pins[0], comp2.pins[0]);
+     * if (wire instanceof Error) {
+     *   console.error('Failed:', wire.message);
+     * }
+     * ```
+     */
+    addWire(node1: UUID, node2: UUID, intermediatePositions?: Position[]): Wire | Error;
+    /**
+     * Remove a wire from the circuit.
+     *
+     * @param id - Wire UUID
+     * @throws {Error} If wire does not exist
+     *
+     * @example
+     * ```typescript
+     * circuit.removeWire(wireId);
+     * // Wire is removed
+     * ```
+     */
+    removeWire(id: UUID): void;
+    /**
+     * Split a wire in the circuit.
+     *
+     * It creates two new wires connected by either the target enode or a new branching point ENode at the specified position.
+     * Returns 2 UUIDS of the new wires.
+     *
+     * @param id - Wire UUID
+     * @param position
+     * @throws {Error} If wire does not exist
+     *
+     * @example
+     * ```typescript
+     * circuit.splitWire(wireId);
+     * // Wire and any orphaned branching points are removed
+     * ```
+     */
+    /**
+     * Split an existing wire at a position, creating a branching point.
+     * The original wire is removed and replaced with two new wires
+     * connecting through the new branching point.
+     * NB : in the special case where targetEnode belongs to a component where the wire is already connected
+     * only one new wire will be created as this method don't allow a wire directly connecting two pins of the same component.
+     *
+     * @param wireId - Wire to split
+     * @param position - Position for the new branching point : no effect if targetEnodeId provided
+     * @param targetEnodeId - if provided, the existing enode to split the wire at
+     * @returns Object containing the new branching point and an array of the two new wires
+     * @throws Error if wireId not found
+     */
+    splitWire(wireId: UUID, position: Position, targetEnodeId?: UUID | null): {
+        branchingPoint: ENode;
+        wires: Array<Wire>;
+    };
+    getWireBetweenNodes(node1: UUID, node2: UUID): Wire | undefined;
+    /**
+     * Get a wire by ID.
+     *
+     * @param id - Wire UUID
+     * @returns The Wire or undefined if not found
+     */
+    getWire(id: UUID): Wire | undefined;
+    /**
+     * Get all wires in the circuit.
+     *
+     * Returns a new array on each call (defensive copy).
+     *
+     * @returns Array of all Wires
+     */
+    getAllWires(): Wire[];
+    /**
+     * Get all wires connected to a specific ENode.
+     *
+     * @param nodeId - ENode UUID
+     * @returns Array of connected Wires, or empty array if node not found
+     */
+    getWiresByNode(nodeId: UUID): Wire[];
+    /**
+     * Get all wires connected to a component, e.g to any pin enode of the component.
+     *
+     * @param componentId - Component UUID
+     * @returns Array of connected Wires, or empty array if component not found
+     */
+    getWiresByComponent(componentId: UUID): Wire[];
+    /**
+     * Get both ENodes connected by a wire.
+     *
+     * @param wireId - Wire UUID
+     * @returns Tuple [node1, node2] or undefined if wire not found
+     */
+    getNodesByWire(wireId: UUID): [ENode, ENode] | undefined;
+    /**
+     * Check if a wire already exists between two nodes.
+     *
+     * Order-independent: returns true for (A, B) or (B, A).
+     *
+     * @param node1 - First ENode UUID
+     * @param node2 - Second ENode UUID
+     * @returns true if wire exists, false otherwise
+     */
+    hasWireBetween(node1: UUID, node2: UUID): boolean;
+    /**
+     * Find all components with pins among the provided enode IDs set.
+     *
+     * @param pinIds - Set of pins UUIDs
+     * @returns Set of components UUIDs
+     */
+    getComponentsOfPins(pinIds: Set<UUID>): Set<UUID>;
+    /**
+     * Get a component's pin ENode by its label.
+     * @param component
+     * @param pinLabel
+     */
+    getComponentPinByLabel(component: Component, pinLabel: string): ENode | undefined;
+    /**
+     * Update the intermediate positions of a wire.
+     * Update the wire in place.
+     *
+     * @param wireId - Wire to update
+     * @param intermediatePositions - New intermediate positions
+     * @param simplify - Whether to simplify positions by removing collinear points : useful when finalizing wire routing
+     * @returns The updated Wire
+     * @throws Error if wireId not found
+     */
+    updateWireIntermediatePositions(wireId: UUID, intermediatePositions: Position[], simplify?: boolean): Wire;
+    /**
+     * Simplify intermediate positions of a wire.
+     * Update the wire in place.
+     * @param wireId - Wire to simplify
+     * @returns The updated Wire
+     * @throws Error if wireId not found
+     */
+    simplifyWireIntermediatePositions(wireId: UUID): Wire;
+    /**
+     * Update the source type of an ENode (branching point or component pin).
+     * @param enodeId - ENode to update
+     * @param sourceType - New source type (null to clear)
+     * @throws Error if enodeId not found
+     */
+    updateENodeSourceType(enodeId: UUID, sourceType: ENodeSourceType | null): void;
+    /**
+     * iterate through all components, enodes and wires positions to get the size that allows to enclose all elements.
+     * @param margin - optional margin to add to the size
+     * @returns size that allows to enclose all elements plus margin
+     * @todo if calls to this method at each build operation ends causes slowness see to optimize by restricting checked elements
+     */
+    getEnclosingSize(margin?: number): number;
+    /**
+     * Serialize circuit to JSON.
+     *
+     * @returns JSON-serializable object containing all components, enodes, and wires
+     *
+     * @example
+     * ```typescript
+     * const json = circuit.toJSON();
+     * localStorage.setItem('my-circuit', JSON.stringify(json));
+     * ```
+     */
+    toJSON(): ICircuit;
+    /**
+     * Deserialize circuit from JSON.
+     *
+     * @param json - Circuit data
+     * @returns Circuit instance
+     * @throws {Error} If JSON is invalid or violates invariants
+     *
+     * @example
+     * ```typescript
+     * const jsonStr = localStorage.getItem('my-circuit');
+     * const json = JSON.parse(jsonStr);
+     * const circuit = Circuit.fromJSON(json);
+     * ```
+     */
+    static fromJSON(json: ICircuit): Circuit;
+}

package/dist/core/topology/CircuitMetadata.d.ts

@@ -0,0 +1,24 @@
+import { CameraOptions } from '../utils';
+import { CircuitOptions } from './CircuitOptions';
+import { ICircuitMetadata } from './types';
+export declare class CircuitMetadata implements ICircuitMetadata {
+    version: string;
+    options: CircuitOptions;
+    size: number;
+    divisions: number;
+    cameraOptions: CameraOptions;
+    /**
+     * Create a new CircuitMetadata holding general information about the Circuit.
+     *
+     * @param version - Circuit version
+     * @param options - Circuit options
+     * @param size - Size of the circuit grid
+     * @param divisions - Divisions in the circuit grid
+     * @param cameraOptions - Camera Options at startup
+     * @throws {TypeError} If size or divisions are not integers
+     */
+    constructor(version: string, options: CircuitOptions, size: number, divisions: number, cameraOptions: CameraOptions);
+    toJSON(): ICircuitMetadata;
+    static fromJSON(json: ICircuitMetadata): CircuitMetadata;
+    toString(): string;
+}

package/dist/core/topology/CircuitOptions.d.ts

@@ -0,0 +1,14 @@
+import { ICircuitOptions, LogicFamily } from './types';
+export declare class CircuitOptions implements ICircuitOptions {
+    name: string;
+    defaultLogicFamily: LogicFamily;
+    /**
+     * Create new circuit options.
+     *
+     * @param name - Circuit name (default: Untitled Circuit)
+     * @param defaultLogicFamily - Circuit default logic family (default: CMOS1)
+     */
+    constructor(name?: string, defaultLogicFamily?: LogicFamily);
+    toJSON(): ICircuitOptions;
+    static fromJSON(json: ICircuitOptions): CircuitOptions;
+}

package/dist/core/topology/Component.d.ts

@@ -0,0 +1,152 @@
+import { UUID, Position, Rotation } from '../utils';
+import { ComponentType, IComponent } from './types';
+/**
+ * Electrical component placed on the circuit grid.
+ *
+ * Components represent physical circuit elements (lightbulbs, transistors, etc.)
+ * with a specific position, orientation, and set of electrical connection pins.
+ *
+ * **Lifecycle**: Components are created and removed via the Circuit class.
+ * When a component is added to a circuit, pin ENodes are automatically created
+ * for each pin. When removed, pins and connected wires are cascade-deleted.
+ *
+ * @example
+ * ```typescript
+ * const position = new Position(10, 20);
+ * const rotation = new Rotation(90);
+ * const pins = ['pin-uuid-1', 'pin-uuid-2'];
+ *
+ * const component = new Component(position, rotation, pins);
+ *
+ * console.log(component.id);        // "550e8400-..."
+ * console.log(component.position);  // Position { x: 10, y: 20 }
+ * console.log(component.rotation);  // Rotation { angle: 90 }
+ * console.log(component.pins);      // ['pin-uuid-1', 'pin-uuid-2']
+ * ```
+ */
+export declare class Component {
+    /**
+     * Unique identifier for this component.
+     * @readonly
+     */
+    readonly id: UUID;
+    /**
+     * Component type (Battery, Switch, LED, etc.).
+     * @readonly
+     */
+    readonly type: ComponentType;
+    /**
+     * Position on the 2D discrete grid.
+     * @readonly
+     */
+    readonly position: Position;
+    /**
+     * Orientation angle in degrees.
+     * @readonly
+     */
+    readonly rotation: Rotation;
+    /**
+     * Array of pin ENode UUIDs.
+     * Pin order is significant (index 0 is first pin, etc.).
+     * @readonly
+     */
+    readonly pins: ReadonlyArray<UUID>;
+    /**
+     * Configuration parameters for this component instance.
+     *
+     * This map holds key-value pairs representing configurable settings
+     * The available configuration keys depend on the component type see IComponentTypeMetadata for details.
+     *
+     */
+    config: Map<string, string>;
+    /**
+     * allow to flag a component as non editable (feature to implement)
+     */
+    editable: boolean;
+    /**
+     * Create a new component.
+     *
+     * **Note**: Typically components are created via `Circuit.addComponent()`
+     * which handles pin ENode creation automatically. This constructor is used
+     * internally by Circuit.
+     *
+     * @param type - Component type (Battery, Switch, LED, etc.)
+     * @param position - Grid position (integer x, y)
+     * @param rotation - Orientation angle (integer degrees)
+     * @param pins - Array of pin ENode UUIDs
+     *
+     * @param editable
+     * @example
+     * ```typescript
+     * // Usually created via Circuit:
+     * const component = circuit.addComponent(
+     *   new Position(10, 20),
+     *   new Rotation(90),
+     *   ComponentType.Battery
+     * );
+     *
+     * // Direct construction (for deserialization):
+     * const component = new Component(
+     *   ComponentType.Battery,
+     *   new Position(10, 20),
+     *   new Rotation(90),
+     *   ['pin-id-1', 'pin-id-2']
+     * );
+     * ```
+     */
+    constructor(type: ComponentType, position: Position, rotation: Rotation, pins: ReadonlyArray<UUID>, editable?: boolean);
+    getPinLabel(pinId: UUID): string | undefined;
+    setAllParameters(config: Map<string, string>): void;
+    setParameter(key: string, value: string): void;
+    /**
+     * Update the component's position.
+     *
+     * @param newPosition - The new position for the component
+     *
+     * @example
+     * ```typescript
+     * const component = circuit.getComponent(componentId);
+     * component.setPosition(new Position(15, 25));
+     * ```
+     */
+    setPosition(newPosition: Position): void;
+    /**
+     * Update the component's rotation.
+     *
+     * @param newRotation - The new rotation for the component
+     *
+     * @example
+     * ```typescript
+     * const component = circuit.getComponent(componentId);
+     * component.setRotation(new Rotation(90));
+     * ```
+     */
+    setRotation(newRotation: Rotation): void;
+    /**
+     * Serialize component to JSON.
+     *
+     * @returns Plain object representation
+     *
+     * @example
+     * ```typescript
+     * const json = component.toJSON();
+     * console.log(json);
+     * // {
+     * //   id: "550e8400-...",
+     * //   type: "battery",
+     * //   position: { x: 10, y: 20 },
+     * //   rotation: 90,
+     * //   pins: ['pin-uuid-1', 'pin-uuid-2']
+     * // }
+     * ```
+     */
+    toJSON(): IComponent;
+    /**
+     * Deserialize component from JSON.
+     *
+     * @param json - Component data
+     * @returns Component instance
+     *
+     */
+    static fromJSON(json: IComponent): Component;
+}