simple-circuit-engine 0.0.10 → 0.0.12

package/dist/core/simulation/states/basic/BatteryState.d.ts

@@ -0,0 +1,16 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for Battery components.
+ * Batteries are stateless always-on pinSources.
+ *
+ * @public
+ */
+export declare class BatteryState extends ComponentState {
+    /**
+     * Create a new battery state.
+     *
+     * @param componentId - UUID of the battery component
+     */
+    constructor(componentId: UUID);
+}

package/dist/core/simulation/states/basic/ClockState.d.ts

@@ -0,0 +1,16 @@
+import { UUID } from '../../../utils';
+import { ComponentState } from '../ComponentState';
+/**
+ * Simulation state for Clock components.
+ * Clock output either voltage (LOGIC HIGH) or LOGIC LOW switching periodically
+ *
+ * @public
+ */
+export declare class ClockState extends ComponentState {
+    /**
+     * Create a new Clock state, either gnd or vcc
+     *
+     * @param componentId - UUID of the Clock component
+     */
+    constructor(componentId: UUID);
+}

package/dist/core/simulation/states/basic/DoubleThrowSwitchState.d.ts

@@ -0,0 +1,21 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for DoubleSwitch (SPDT - Single-Pole Double-Throw - switch) components.
+ * These switches can be "input1", "1to2", "input2" or "2to1"
+ *
+ * @public
+ */
+export declare class DoubleThrowSwitchState extends ComponentState {
+    /**
+     * Create a new double Switch state.
+     *
+     * @param componentId - UUID of the double Switch component
+     * @param initialState - Initial operational state (default: "input1")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if switch is in 1to2 or 2to1 state
+     */
+    get isInTransition(): boolean;
+}

package/dist/core/simulation/states/basic/LightbulbState.d.ts

@@ -0,0 +1,21 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for Lightbulb components.
+ * Lightbulbs can be "on" (emitting light) or "off".
+ *
+ * @public
+ */
+export declare class LightbulbState extends ComponentState {
+    /**
+     * Create a new Lightbulb state.
+     *
+     * @param componentId - UUID of the Lightbulb component
+     * @param initialState - Initial operational state (default: "off")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if Lightbulb is in lit state (on or going_on)
+     */
+    get isLit(): boolean;
+}

package/dist/core/simulation/states/basic/RectangleLEDState.d.ts

@@ -0,0 +1,9 @@
+import { SmallLEDState } from './SmallLEDState';
+/**
+ * Simulation state for RectangleLED components. Same as SmallLEDState.
+ * LEDs can be "on" (emitting light) or "off".
+ *
+ * @public
+ */
+export declare class RectangleLEDState extends SmallLEDState {
+}

package/dist/core/simulation/states/basic/RelayState.d.ts

@@ -0,0 +1,25 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for mechanical Relay components.
+ * Relays can be "open", "closing", "closed", or "opening".
+ *
+ * @public
+ */
+export declare class RelayState extends ComponentState {
+    /**
+     * Create a new Relay state.
+     *
+     * @param componentId - UUID of the Relay component
+     * @param initialState - Initial operational state (default: "open")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if relay is in opening or closing state
+     */
+    get isInTransition(): boolean;
+    /**
+     * Check if relay is in closed or closing state
+     */
+    get isClosed(): boolean;
+}

package/dist/core/simulation/states/basic/SmallLEDState.d.ts

@@ -0,0 +1,21 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for SmallLED components.
+ * LEDs can be "on" (emitting light) or "off".
+ *
+ * @public
+ */
+export declare class SmallLEDState extends ComponentState {
+    /**
+     * Create a new SmallLED state.
+     *
+     * @param componentId - UUID of the LED component
+     * @param initialState - Initial operational state (default: "off")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if LED is in lit state (on or going_on)
+     */
+    get isLit(): boolean;
+}

package/dist/core/simulation/states/basic/SwitchState.d.ts

@@ -0,0 +1,25 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for Switch components.
+ * Switches can be "open", "closing", "closed", or "opening".
+ *
+ * @public
+ */
+export declare class SwitchState extends ComponentState {
+    /**
+     * Create a new Switch state.
+     *
+     * @param componentId - UUID of the Switch component
+     * @param initialState - Initial operational state (default: "open")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if switch is in opening or closing state
+     */
+    get isInTransition(): boolean;
+    /**
+     * Check if switch is in closed or closing state
+     */
+    get isClosed(): boolean;
+}

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

@@ -0,0 +1,17 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for Inverter components
+ * Inverters can be "low", "rising", "high", or "falling".
+ *
+ * @public
+ */
+export declare class InverterState extends LogicGateState {
+    /**
+     * Create a new Inverter state.
+     *
+     * @param componentId - UUID of the Inverter component
+     * @param initialState - Initial operational state (default: "low")
+     */
+    constructor(componentId: UUID, initialState?: string);
+}

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

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NAND4 Gate components (4 inputs).
+ *
+ * @public
+ */
+export declare class Nand4GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

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

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NAND8 Gate components (8 inputs).
+ *
+ * @public
+ */
+export declare class Nand8GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

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

@@ -0,0 +1,16 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NAND Gate components.
+ *
+ * @public
+ */
+export declare class NandGateState extends LogicGateState {
+    /**
+     * Create a new NAND Gate state.
+     *
+     * @param componentId - UUID of the NAND Gate component
+     * @param initialState - Initial operational state (default: "low")
+     */
+    constructor(componentId: UUID, initialState?: string);
+}

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

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NOR4 Gate components (4 inputs).
+ *
+ * @public
+ */
+export declare class Nor4GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

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

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NOR8 Gate components (8 inputs).
+ *
+ * @public
+ */
+export declare class Nor8GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

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

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NOR Gate components.
+ *
+ * @public
+ */
+export declare class NorGateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

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

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for XOR4 Gate components (4 inputs).
+ *
+ * @public
+ */
+export declare class Xor4GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

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

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for XOR8 Gate components (8 inputs).
+ *
+ * @public
+ */
+export declare class Xor8GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

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

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for XOR Gate components.
+ *
+ * @public
+ */
+export declare class XorGateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

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,26 @@
+/**
+ * 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';

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: 50;
+    /**
+     * 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>;
+}