simple-circuit-engine 0.0.11 → 0.0.13

package/dist/core/simulation/states/gates/index.d.ts

@@ -0,0 +1,25 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for Logic gates components
+ * Gates can be "low", "rising", "high", "falling" or "indeterminate" (if their input is not well-defined)
+ *
+ * @public
+ */
+export declare abstract class LogicGateState extends ComponentState {
+    /**
+     * Create a new Inverter state.
+     *
+     * @param componentId - UUID of the Inverter component
+     * @param initialState - Initial operational state (default: "low")
+     */
+    protected constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if output is in a rising or falling transition
+     */
+    get isInTransition(): boolean;
+    /**
+     * Check if output is high
+     */
+    get isHigh(): boolean;
+}

package/dist/core/simulation/states/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Simulation state definitions
+ * @module core/simulation/states
+ */
+export type { INodeElectricalState } from './types';
+export { unionElectricalStates } from './types';
+export { SimulationState } from './SimulationState.js';
+export { ComponentState } from './ComponentState.js';
+export { BatteryState } from './basic/BatteryState';
+export { LightbulbState } from './basic/LightbulbState';
+export { RectangleLEDState } from './basic/RectangleLEDState';
+export { RelayState } from './basic/RelayState';
+export { SmallLEDState } from './basic/SmallLEDState';
+export { SwitchState } from './basic/SwitchState';
+export { DoubleThrowSwitchState } from './basic/DoubleThrowSwitchState';
+export { ClockState } from './basic/ClockState';
+export { InverterState } from './gates/InverterState';
+export { NandGateState } from './gates/NandGateState';
+export { Nand4GateState } from './gates/Nand4GateState';
+export { Nand8GateState } from './gates/Nand8GateState';
+export { NorGateState } from './gates/NorGateState';
+export { Nor4GateState } from './gates/Nor4GateState';
+export { Nor8GateState } from './gates/Nor8GateState';
+export { XorGateState } from './gates/XorGateState';
+export { Xor4GateState } from './gates/Xor4GateState';
+export { Xor8GateState } from './gates/Xor8GateState';
+export { ArithmeticState } from './arithmetic/ArithmeticState';
+export { HalfAdderState } from './arithmetic/HalfAdderState';
+export { AdderState } from './arithmetic/AdderState';
+export { EightBitAdderState } from './arithmetic/EightBitAdderState';
+export { EightBitOnesComplementState } from './arithmetic/EightBitOnesComplementState';

package/dist/core/simulation/states/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Binary electrical state for wires and enodes (connection points)
+ * @module core/simulation/states
+ * @public
+ */
+export interface INodeElectricalState {
+    /**
+     * True if voltage is present at this node (potential > 0V).
+     * False if node is at ground potential or floating.
+     */
+    hasVoltage: boolean;
+    /**
+     * True if current is actively flowing through this node.
+     * False if no current flow (open circuit or equilibrium).
+     */
+    hasCurrent: boolean;
+    /**
+     * True only if the node is locked from state changes at circuit build time (ex: battery pins or other fixed-voltage/current pinSources).
+     * Important: Those nodes should never have their electrical state modified by the simulation controller!
+     * Always false for wires
+     */
+    locked: boolean;
+}
+/**
+ * Compute the union of multiple electrical states.
+ * Useful to derive a combined pin state from two or more pins
+ * (e.g. cmd_in + cmd_out → coil state).
+ *
+ * @param states - Two or more electrical states to combine
+ * @returns A new state where hasVoltage/hasCurrent are OR'd across inputs, locked is always false
+ */
+export declare function unionElectricalStates(...states: INodeElectricalState[]): INodeElectricalState;

package/dist/core/simulation/types.d.ts

@@ -0,0 +1,155 @@
+import { UUID } from '../utils';
+/**
+ * Simulation speed bounds and defaults for ticks per second (TPS).
+ * @public
+ */
+export declare const SIMULATION_SPEED: {
+    /**
+     * Minimum simulation speed in ticks per second
+     */
+    readonly MIN_TPS: 1;
+    /**
+     * Maximum simulation speed in ticks per second
+     */
+    readonly MAX_TPS: 100;
+    /**
+     * Default simulation speed in ticks per second
+     */
+    readonly DEFAULT_TPS: 3;
+    /**
+     * Default tick interval in milliseconds (1000 / DEFAULT_TPS)
+     */
+    readonly DEFAULT_INTERVAL_MS: 500;
+};
+/**
+ * Default transition timing values for components.
+ * @public
+ */
+export declare const TRANSITION_DEFAULTS: {
+    /**
+     * Default transitionSpan for relays and transistors in ticks (instant transition)
+     */
+    readonly TRANSITION_SPAN_TICKS: 1;
+    /**
+     * Default transitionUserSpan for switches in milliseconds
+     */
+    readonly TRANSITION_USER_SPAN_MS: 200;
+};
+/**
+ * User command to be executed during simulation.
+ * Commands can be queued for future ticks or executed immediately.
+ *
+ * @public
+ */
+export interface IUserCommand {
+    /**
+     * Type of command.
+     */
+    readonly type: 'toggle_switch';
+    /**
+     * UUID of target component.
+     */
+    readonly targetId: UUID;
+    /**
+     * tick when this command was scheduled.
+     */
+    scheduledAtTick: number;
+    /**
+     * Extra parameters associated with this command.
+     *
+     * For `toggle_switch` commands:
+     * - `tickCount`: Number of ticks for the switch transition. Computed at toggle time
+     *   using the formula: `ceil(transitionUserSpan × simulationSpeed / 1000)` with minimum of 1.
+     *   If not provided, behavior uses default transition timing.
+     */
+    readonly parameters?: Map<string, string> | null;
+}
+/**
+ * all reachable nodes and wires from a seed
+ */
+export type IReachabilityResult = {
+    nodes: Set<UUID>;
+    wires: Set<UUID>;
+};
+/**
+ * Configuration options for CircuitRunner
+ */
+export interface IRunnerOptions {
+    /**
+     * Enable historical state tracking.
+     * When true, past simulation states are preserved up to historyLimit.
+     * When false (default), only current state is retained for better performance.
+     * @default false
+     */
+    enableHistory?: boolean;
+    /**
+     * Maximum number of historical states to retain when enableHistory is true.
+     * Uses circular buffer—oldest states are overwritten when limit is reached.
+     * Must be a positive integer.
+     * @default 1000
+     */
+    historyLimit?: number;
+}
+/**
+ * Result statistics of one simulation tick run
+ */
+export interface IRunnerResult {
+    startTick: number;
+    endTick: number;
+    componentUpdateCount: number;
+    nodeUpdateCount: number;
+    wireUpdateCount: number;
+    processedCommandCount: number;
+    scheduledEventCount: number;
+    firedEventCount: number;
+}
+/**
+ * Scheduled event for delayed component transitions.
+ * Events are ordered by readyAtTick in a min-heap priority queue.
+ * Events with same readyAtTick are processed in FIFO order (by scheduledAtTick).
+ *
+ * @public
+ */
+export interface IScheduledEvent {
+    /**
+     * UUID of target component.
+     */
+    readonly targetId: UUID;
+    /**
+     * Tick when this event was scheduled (for FIFO ordering).
+     * @readonly
+     */
+    readonly scheduledAtTick: number;
+    /**
+     * Tick when this event should be processed.
+     * @readonly
+     */
+    readonly readyAtTick: number;
+    /**
+     * Indicates the type of this event, eg 'ClosingEnd', 'OpeningEnd', etc.
+     */
+    readonly type: string;
+    /**
+     * extra parameters associated with this event.
+     */
+    readonly parameters?: Map<string, string> | undefined;
+}
+/**
+ * Dirty elements collected during a tick, returned by getDirtyElements().
+ *
+ * @public
+ */
+export interface IDirtyElements {
+    /**
+     * Components that changed state.
+     */
+    readonly components: ReadonlySet<UUID>;
+    /**
+     * Wires that changed electrical state.
+     */
+    readonly wires: ReadonlySet<UUID>;
+    /**
+     * ENodes that changed electrical state.
+     */
+    readonly enodes: ReadonlySet<UUID>;
+}

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;
+}