simple-circuit-engine 0.0.11 → 0.0.13

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,153 @@
+import { UUID, Position, Rotation } from '../utils';
+import { ComponentType, IComponent, IPinMetadata } 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;
+    getPinMetadata(pinId: UUID): IPinMetadata | 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;
+}

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

@@ -0,0 +1,200 @@
+import { UUID, Position } from '../utils';
+import { ENodeSourceType, ENodeType, IENode } from './types';
+import { Circuit } from './Circuit';
+/**
+ * Electrical connection point (component pin or wire branching point).
+ *
+ * ENodes are automatically managed by the Circuit:
+ * - **Pin nodes**: Created when components are added, deleted when components removed
+ * - **Branching nodes**: Created when wires split, deleted when orphaned (no wires)
+ *
+ * **Position Handling**:
+ * - Pin nodes: Position derived from parent component
+ * - Branching nodes: Independent position stored directly
+ *
+ * @example
+ * ```typescript
+ * // Pin node (created automatically by Circuit)
+ * const circuit = new Circuit();
+ * const component = circuit.addComponent(new Position(10, 20), new Rotation(0), 2);
+ * const pinNode = circuit.getENode(component.pins[0]);
+ *
+ * console.log(pinNode.type);       // ENodeType.Pin
+ * console.log(pinNode.component);  // component UUID
+ * console.log(pinNode.pinLabel);   // '0'
+ *
+ * // Branching node (created during wire split)
+ * const branchNode = new ENode(
+ *   ENodeType.BranchingPoint,
+ *   undefined,
+ *   undefined,
+ *   new Position(15, 25)
+ * );
+ * console.log(branchNode.position); // Position { x: 15, y: 25 }
+ * ```
+ */
+export declare class ENode {
+    /**
+     * Unique identifier for this ENode.
+     * @readonly
+     */
+    readonly id: UUID;
+    /**
+     * Type of electrical node (Pin or BranchingPoint).
+     * @readonly
+     */
+    readonly type: ENodeType;
+    /**
+     * Parent component UUID (only for pin nodes).
+     * Undefined for branching point nodes.
+     * @readonly
+     */
+    readonly component: UUID | undefined;
+    /**
+     * Pin label within component (only for pin nodes).
+     * Undefined for branching point nodes.
+     * @readonly
+     */
+    readonly pinLabel: string | undefined;
+    /**
+     * Grid position (only for branching point nodes).
+     * Undefined for pin nodes (position derived from component).
+     * @readonly
+     */
+    readonly position: Position | undefined;
+    /**
+     * Set of wire UUIDs connected to this node.
+     * Mutable to allow wire connections/disconnections.
+     */
+    readonly wires: Set<UUID>;
+    /**
+     * Is the ENode a source of voltage or current?
+     */
+    source: ENodeSourceType | undefined;
+    /**
+     * Pin role classification: free, mainVcc, vcc, mainGnd, gnd, logicInput, logicOutput.
+     * @readonly
+     */
+    readonly subtype: string;
+    /**
+     * Create a new electrical node.
+     *
+     * **Note**: Typically ENodes are created automatically by Circuit.
+     * This constructor is used internally.
+     *
+     * @param type - Node type (Pin or BranchingPoint)
+     * @param component - Parent component UUID (pin nodes only)
+     * @param pinLabel - Pin label (pin nodes only)
+     * @param position - Grid position (branching points only)
+     * @param source - Source type (Voltage/Current) or undefined
+     *
+     * @param subtype
+     * @example
+     * ```typescript
+     * // Pin node (internal to Circuit)
+     * const pinNode = new ENode(
+     *   ENodeType.Pin,
+     *   componentId,
+     *   '0',  // first pin
+     *   undefined,
+     *   undefined
+     * );
+     *
+     * // Branching point node
+     * const branchNode = new ENode(
+     *   ENodeType.BranchingPoint,
+     *   undefined,
+     *   undefined,
+     *   new Position(15, 25),
+     *   undefined
+     * );
+     * ```
+     */
+    constructor(type: ENodeType, component: UUID | undefined, pinLabel: string | undefined, position: Position | undefined, source?: ENodeSourceType | undefined, subtype?: string);
+    /**
+     * Get the position of this electrical node.
+     *
+     * **Pin nodes**: Derives position from parent component.
+     * **Branching nodes**: Returns stored position directly.
+     *
+     * @param circuit - Circuit instance (needed to look up component for pin nodes)
+     * @returns Position on the grid
+     *
+     * @example
+     * ```typescript
+     * const circuit = new Circuit();
+     * const component = circuit.addComponent(
+     *   new Position(10, 20),
+     *   new Rotation(0),
+     *   1
+     * );
+     *
+     * const pinNode = circuit.getENode(component.pins[0]);
+     * const position = pinNode.getPosition(circuit);
+     * console.log(position.x); // 10 (derived from component)
+     * ```
+     */
+    getPosition(circuit: Circuit): Position;
+    /**
+     * Update the enode (branching point only)'s position.
+     *
+     * @param newPosition - The new position for the enode
+     *
+     * @example
+     * ```typescript
+     * const component = circuit.getComponent(componentId);
+     * component.setPosition(new Position(15, 25));
+     * ```
+     */
+    setPosition(newPosition: Position): void;
+    /**
+     * Update the enode's source type.
+     * @param sourceType
+     */
+    setSourceType(sourceType?: ENodeSourceType | undefined): void;
+    /**
+     * Serialize ENode to JSON.
+     *
+     * @returns Plain object representation
+     *
+     * @example
+     * ```typescript
+     * const json = enode.toJSON();
+     * console.log(json);
+     * // Pin node:
+     * // {
+     * //   id: "uuid",
+     * //   type: "Pin",
+     * //   component: "component-uuid",
+     * //   pinLabel: "0"
+     * // }
+     *
+     * // Branching node:
+     * // {
+     * //   id: "uuid",
+     * //   type: "BranchingPoint",
+     * //   position: { x: 15, y: 25 }
+     * // }
+     * ```
+     */
+    toJSON(): IENode;
+    /**
+     * Deserialize ENode from JSON.
+     *
+     * @param json - ENode data
+     * @returns ENode instance
+     *
+     * @example
+     * ```typescript
+     * const json = {
+     *   id: "uuid",
+     *   type: "Pin",
+     *   component: "component-uuid",
+     *   pinLabel: "0"
+     * };
+     *
+     * const enode = ENode.fromJSON(json);
+     * ```
+     */
+    static fromJSON(json: IENode): ENode;
+}

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

@@ -0,0 +1,130 @@
+import { UUID, Position } from '../utils';
+import { IWire } from './types';
+/**
+ * Electrical connection between two ENodes.
+ *
+ * Wires connect exactly two electrical nodes (component pins or branching points).
+ * They support intermediate positions for ad-hoc routing paths in rendering.
+ *
+ * **Lifecycle**: Wires are created and removed via the Circuit class.
+ * - Creating a wire updates bidirectional references (Wire ↔ ENodes)
+ * - Removing a wire triggers orphaned branching point cleanup
+ * - Splitting a wire creates new branching ENode and multiple wires
+ *
+ * @example
+ * ```typescript
+ * const circuit = new Circuit();
+ * const comp1 = circuit.addComponent(new Position(0, 0), new Rotation(0), 1);
+ * const comp2 = circuit.addComponent(new Position(10, 10), new Rotation(0), 1);
+ *
+ * // Straight wire
+ * const wire = circuit.addWire(comp1.pins[0], comp2.pins[0]);
+ *
+ * // Wire with custom path
+ * const curvedWire = circuit.addWire(
+ *   comp1.pins[0],
+ *   comp2.pins[0],
+ *   [new Position(5, 5), new Position(8, 7)]
+ * );
+ * ```
+ */
+export declare class Wire {
+    /**
+     * Unique identifier for this wire.
+     * @readonly
+     */
+    readonly id: UUID;
+    /**
+     * First connected ENode UUID.
+     * @readonly
+     */
+    readonly node1: UUID;
+    /**
+     * Second connected ENode UUID.
+     * @readonly
+     */
+    readonly node2: UUID;
+    /**
+     * Optional intermediate positions for wire routing.
+     * Empty array indicates straight-line connection.
+     * @readonly
+     */
+    intermediatePositions: Array<Position>;
+    /**
+     * Create a new wire.
+     *
+     * **Note**: Typically wires are created via `Circuit.addWire()` which
+     * handles validation and bidirectional reference updates. This constructor
+     * is used internally by Circuit.
+     *
+     * @param node1 - First ENode UUID
+     * @param node2 - Second ENode UUID
+     * @param intermediatePositions - Optional waypoints for rendering
+     *
+     * @example
+     * ```typescript
+     * // Usually created via Circuit:
+     * const wire = circuit.addWire(nodeId1, nodeId2);
+     *
+     * // With intermediate positions:
+     * const wire = circuit.addWire(
+     *   nodeId1,
+     *   nodeId2,
+     *   [new Position(5, 10), new Position(15, 10)]
+     * );
+     * ```
+     */
+    constructor(node1: UUID, node2: UUID, intermediatePositions?: Array<Position>);
+    /**
+     * Check if this is a straight-line wire.
+     *
+     * @returns true if no intermediate positions, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const straightWire = new Wire(node1, node2);
+     * console.log(straightWire.isStraightLine()); // true
+     *
+     * const curvedWire = new Wire(node1, node2, [new Position(5, 5)]);
+     * console.log(curvedWire.isStraightLine()); // false
+     * ```
+     */
+    isStraightLine(): boolean;
+    /**
+     * Serialize wire to JSON.
+     *
+     * @returns Plain object representation
+     *
+     * @example
+     * ```typescript
+     * const json = wire.toJSON();
+     * console.log(json);
+     * // {
+     * //   id: "uuid",
+     * //   node1: "node-uuid-1",
+     * //   node2: "node-uuid-2",
+     * //   intermediatePositions: [{ x: 5, y: 10 }]
+     * // }
+     * ```
+     */
+    toJSON(): IWire;
+    /**
+     * Deserialize wire from JSON.
+     *
+     * @param json - Wire data
+     * @returns Wire instance
+     *
+     * @example
+     * ```typescript
+     * const json = {
+     *   id: "uuid",
+     *   node1: "node-uuid-1",
+     *   node2: "node-uuid-2",
+     *   intermediatePositions: [{ x: 5, y: 10 }]
+     * };
+     *
+     * const wire = Wire.fromJSON(json);
+     * ```
+     */
+    static fromJSON(json: IWire): Wire;
+}

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

@@ -0,0 +1,52 @@
+import { ComponentType, LogicFamily } from './types';
+import { Component } from './Component';
+/**
+ * Gate family classification used for delay table lookup.
+ * Maps to the logical function regardless of physical implementation.
+ */
+type GateFamily = 'NOT' | 'Buffer' | 'NAND' | 'AND' | 'NOR' | 'OR' | 'XOR' | 'XNOR';
+/**
+ * Given a component compute the basis transitionSpan from its logicFamily if applicable
+ * if not applicable / already implemented returns undefined
+ * @param component
+ */
+export declare function computeTransitionSpan(component: Component): number | undefined;
+/**
+ * Classify a ComponentType + activationLogic combination into a GateFamily and input count.
+ *
+ * Returns null for non-gate component types (Battery, Switch, LED, etc.).
+ *
+ * @param componentType - The component type to classify
+ * @param activationLogic - 'positive' or 'negative' from the component config
+ * @returns Object with gateFamily and inputCount, or null if not a gate
+ */
+export declare function classifyGate(componentType: ComponentType, activationLogic: string): {
+    gateFamily: GateFamily;
+    inputCount: number;
+} | null;
+/**
+ * Compute the propagation delay in ticks for a gate given its logic family, gate family, and input count.
+ *
+ * CMOS1 formulas (base unit: 1 inverter = 1 tick):
+ * - NOT: 1 (constant)
+ * - Buffer: 2 (constant)
+ * - NAND/NOR: log2(n)
+ * - AND/OR: log2(n) + 1
+ * - XOR: log2(n) * 2
+ * - XNOR: log2(n) * 2 + 1
+ *
+ * This table assumes inverter, NAND, NAND4, NAND8, NOR, NOR4, NOR8 and XOR(2) are transistor level primitives
+ *
+ * TTL1 uses lookup tables (base unit: NAND2 = 1 tick).
+ * NOT and Buffer: same as CMOS1 (1 and 2 ticks).
+ * XOR/XNOR: same as CMOS1.
+ *
+ * @param logicFamily - The technology family
+ * @param gateFamily - The logical gate function
+ * @param inputCount - Number of data inputs (not counting Vcc)
+ * @returns Propagation delay in ticks (integer >= 1)
+ * @throws {Error} If called with Sandbox family (caller must not invoke for Sandbox)
+ * @throws {Error} If input count is unsupported for the given family
+ */
+export declare function computeGateDelay(logicFamily: LogicFamily, gateFamily: GateFamily, inputCount: number): number;
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * Module defining the core objects modelling electrical/logical topology: circuit, components, enodes and wires
+ *
+ * @module core/topology
+ */
+export { CIRCUIT_FILE_VERSION, ALL_LOGIC_FAMILIES, DEFAULT_LOGIC_FAMILY, ComponentType, COMPONENT_TYPE_METADATA, ENodeSourceType, ENodeType, } from './types.js';
+export type { LogicFamily, IPinMetadata, IComponentTypeMetadata, IENode, IWire, IComponent, ICircuitOptions, ICircuitMetadata, ICircuit, } from './types.js';
+export { ENode } from './ENode.js';
+export { Wire } from './Wire.js';
+export { Component } from './Component.js';
+export { CircuitOptions } from './CircuitOptions.js';
+export { CircuitMetadata } from './CircuitMetadata.js';
+export { Circuit } from './Circuit.js';
+export { computeTransitionSpan, classifyGate, computeGateDelay } from './delays.js';