simple-circuit-engine 0.0.11 → 0.0.12

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';

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

@@ -0,0 +1,175 @@
+import { ICameraOptions, IPosition, UUID } from '../utils';
+/**
+ * canonic version for circuit files produced
+ */
+export declare const CIRCUIT_FILE_VERSION = "0.0.11";
+/**
+ * Type of electrical pinSources in the circuit.
+ *
+ * ENodes have a sourceType which can be undefined or one of the following:
+ * - **Voltage**: ENode that provides a voltage source to the circuit. All Enodes of this type are considered at the same positive potential.
+ * - **Current**: Ground/neutral ENodes that provides a current source to the circuit. All Enodes of this type are considered as points at
+ * the same 0V-GROUND potential and are points from where electrons enters the circuit.
+ */
+export declare enum ENodeSourceType {
+    Voltage = "Voltage",
+    Current = "Current"
+}
+/**
+ * Type of electrical node (ENode) in the circuit.
+ *
+ * ENodes represent atomic electrical connection points and come in two variants (immutable after node creation)
+ *
+ * - **Pin**: Connection point belonging to a Component. Position is derived
+ *   from the parent component's position, rotation, and pin index. Automatically
+ *   created when a component is added, deleted when component is removed.
+ *
+ * - **BranchingPoint**: Junction point where wires split. Has an independent
+ *   position on the grid. Automatically created when wires are split, deleted
+ *   when no wires remain connected (orphaned).
+ */
+export declare enum ENodeType {
+    /**
+     * Component pin connection point.
+     *
+     * Properties:
+     * - Has parent component reference
+     * - Has pin label within component
+     * - Position derived from component
+     * - Lifecycle tied to component (cascade deletion)
+     */
+    Pin = "Pin",
+    /**
+     * Wire branching point (junction).
+     *
+     * Properties:
+     * - Independent position on grid
+     * - Created when wire is split
+     * - Deleted when last wire is removed (orphaned cleanup)
+     * - No parent component
+     */
+    BranchingPoint = "BranchingPoint"
+}
+/**
+ * Metadata describing a component pin's source type and subtype.
+ *
+ * @property sourceType - Voltage/Current source or undefined for passive pins
+ * @property subtype - Pin role classification: 'free', 'vcc', 'logicInput', 'logicOutput'
+ */
+export interface IPinMetadata {
+    readonly subtype: string;
+    readonly sourceType: ENodeSourceType | undefined;
+}
+/**
+ * Metadata for a component type.
+ *
+ * @property id - Unique string identifier matching the enum value
+ * @property name - Human-readable display name
+ * @property pins - Array of pin labels (order-significant)
+ * @property config - Default configuration parameters (depends on the component, e.g., initialState, activationLogic, color...)
+ */
+export interface IComponentTypeMetadata {
+    readonly id: string;
+    readonly name: string;
+    readonly pins: Map<string, IPinMetadata>;
+    readonly config: Map<string, string>;
+}
+/**
+ * Available logic families
+ *
+ * - `CMOS1`: CMOS technology, base unit 1 inverter = 1 tick
+ * - `TTL1`: TTL technology, base unit 1 NAND2 = 1 tick
+ * - `Sandbox`: User-defined delays, no technology constraints
+ */
+export type LogicFamily = 'CMOS1' | 'TTL1' | 'Sandbox';
+/** All supported logic families */
+export declare const ALL_LOGIC_FAMILIES: LogicFamily[];
+/** Default logic family applied when none is specified */
+export declare const DEFAULT_LOGIC_FAMILY: LogicFamily;
+/** Interface defining an ElectricalNode **/
+export interface IENode {
+    id: UUID;
+    type: ENodeType;
+    component?: UUID | null;
+    pinLabel?: string | null;
+    position?: IPosition | null;
+    source?: ENodeSourceType | null;
+    subtype: string;
+}
+/** Interface defining a Wire (link between 2 ENodes supporting intermediate position to tune its path) **/
+export interface IWire {
+    id: UUID;
+    node1: UUID;
+    node2: UUID;
+    intermediatePositions: IPosition[];
+}
+/** Interface defining a Component **/
+export interface IComponent {
+    id: UUID;
+    type: ComponentType;
+    position: IPosition;
+    rotation: number;
+    pins: UUID[];
+    config: {
+        [key: string]: string;
+    };
+    editable: boolean;
+}
+/**
+ * User editable options for a Circuit
+ */
+export type ICircuitOptions = {
+    name: string;
+    defaultLogicFamily: LogicFamily;
+};
+/** circuit metadata type — combines user writable options and managed metadata */
+export type ICircuitMetadata = {
+    version: string;
+    options: ICircuitOptions;
+    cameraOptions: ICameraOptions;
+    size: number;
+    divisions: number;
+};
+/** circuit type */
+export type ICircuit = {
+    metadata: ICircuitMetadata;
+    components: Iterable<IComponent>;
+    enodes: Iterable<IENode>;
+    wires: Iterable<IWire>;
+};
+/**
+ * Enumeration of ALL available component types.
+ *
+ * Each component type represents a specific electrical element that can be
+ * placed in a circuit (battery, LED, transistor, etc.).
+ */
+export declare enum ComponentType {
+    Cube = "cube",// no pins component for testing purposes mainly
+    Label = "label",// decorative text label with no pins
+    Battery = "battery",
+    Switch = "switch",
+    DoubleThrowSwitch = "doubleThrowSwitch",
+    Lightbulb = "lightbulb",
+    Relay = "relay",
+    SmallLED = "smallLED",
+    RectangleLED = "rectangleLED",
+    Clock = "clock",
+    Inverter = "inverter",
+    NandGate = "nandGate",
+    Nand4Gate = "nand4Gate",
+    Nand8Gate = "nand8Gate",
+    NorGate = "norGate",
+    Nor4Gate = "nor4Gate",
+    Nor8Gate = "nor8Gate",
+    XorGate = "xorGate",
+    Xor4Gate = "xor4Gate",
+    Xor8Gate = "xor8Gate"
+}
+/**
+ * Component type metadata lookup table.
+ *
+ * Maps each ComponentType enum value to its associated metadata
+ * (id, display name, pins, and default configuration arguments).
+ *
+ */
+export declare const COMPONENT_TYPE_METADATA: Readonly<Record<ComponentType, IComponentTypeMetadata>>;

package/dist/core/utils/CameraOptions.d.ts

@@ -0,0 +1,83 @@
+import { ICameraOptions } from './types';
+import { Position3D } from './Position3D';
+/**
+ * Camera configuration options.
+ *
+ * @example
+ * ```typescript
+ * // Create with defaults
+ * const defaultOpts = new CameraOptions();
+ *
+ * // Create with custom values
+ * const customOpts = new CameraOptions(
+ *   new Position3D(0, 20, 10),
+ *   new Position3D(5, 0, 0),
+ *   60,
+ *   0.5,
+ *   2000
+ * );
+ * ```
+ */
+export declare class CameraOptions {
+    readonly position: Position3D;
+    readonly lookAtPosition: Position3D;
+    readonly fov: number;
+    readonly near: number;
+    readonly far: number;
+    /**
+     * Create new camera options.
+     *
+     * @param position - Camera position (default: 0, 15, 15)
+     * @param lookAtPosition - Camera look-at target position (default: 0, 0, 0)
+     * @param fov - Field of view in degrees (default: 75)
+     * @param near - Near clipping plane distance (default: 0.1)
+     * @param far - Far clipping plane distance (default: 1000)
+     */
+    constructor(position?: Position3D, lookAtPosition?: Position3D, fov?: number, near?: number, far?: number);
+    /**
+     * Serialize camera options to JSON.
+     *
+     * @returns Plain object with camera configuration
+     *
+     * @example
+     * ```typescript
+     * const opts = new CameraOptions();
+     * const json = opts.toJSON();
+     * console.log(json);
+     * // {
+     * //   position: { x: 0, y: 15, z: 0 },
+     * //   lookAtPosition: { x: 0, y: 0, z: 0 },
+     * //   fov: 75,
+     * //   near: 0.1,
+     * //   far: 1000
+     * // }
+     * ```
+     */
+    toJSON(): ICameraOptions;
+    /**
+     * Deserialize camera options from JSON.
+     *
+     * @param json - Plain object with camera configuration
+     * @returns CameraOptions instance
+     *
+     * @example
+     * ```typescript
+     * const json = {
+     *   position: { x: 0, y: 20, z: 10 },
+     *   lookAtPosition: { x: 5, y: 0, z: 0 },
+     *   fov: 60,
+     *   near: 0.5,
+     *   far: 2000
+     * };
+     * const opts = CameraOptions.fromJSON(json);
+     * console.log(opts.position.y); // 20
+     * ```
+     */
+    static fromJSON(json: ICameraOptions): CameraOptions;
+    /**
+     * String representation for debugging.
+     *
+     * @returns String with camera configuration details
+     */
+    toString(): string;
+}

package/dist/core/utils/MemoizeDecorator.d.ts

@@ -0,0 +1,9 @@
+interface MemoizeArgs {
+    expiring?: number;
+    hashFunction?: boolean | ((...args: any[]) => any);
+    tags?: string[];
+}
+export declare function Memoize(args?: MemoizeArgs | MemoizeArgs['hashFunction']): (_target: Object, _propertyKey: string, descriptor: TypedPropertyDescriptor<any>) => void;
+export declare function MemoizeExpiring(expiring: number, hashFunction?: MemoizeArgs['hashFunction']): (_target: Object, _propertyKey: string, descriptor: TypedPropertyDescriptor<any>) => void;
+export declare function clear(tags: string[]): number;
+export {};