simple-circuit-engine 0.0.11 → 0.0.13

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

@@ -0,0 +1,189 @@
+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 logic pin's interface data.
+ *
+ * @property interface - name of the pin's interface (one interface combine several pins in the case of numeric inputs/outpus)
+ * @property index - index of the pin within the interface (starts at 0 by convention)
+ */
+export interface ILogicPinMetadata {
+    readonly interface: string;
+    readonly index: number;
+}
+/**
+ * Metadata describing a component pin's source type and subtype.
+ *
+ * @property subtype - Pin role classification: 'free', 'vcc', 'logicInput', 'logicOutput'
+ * @property logicPinData - only for pins of subtype 'logicInput' and 'logicOutput' (MANDATORY in these cases): their logic pin metadata (interface/index)
+ * @property sourceType - Voltage/Current source or undefined for passive pins
+ */
+export interface IPinMetadata {
+    readonly subtype: string;
+    readonly logicPinData?: ILogicPinMetadata;
+    readonly sourceType?: ENodeSourceType;
+}
+/**
+ * Metadata for a component type.
+ *
+ * @property id - Unique string identifier matching the enum value
+ * @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 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",
+    HalfAdder = "halfAdder",
+    Adder = "adder",
+    EightBitAdder = "eightBitAdder",
+    EightBitOnesComplement = "eightBitOnesComplement"
+}
+/**
+ * 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 {};

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

@@ -0,0 +1,166 @@
+/**
+ * Position Type for 2D Discrete Grid
+ *
+ * Represents a position on a 2D discrete (integer) grid. Used for:
+ * - Component placement
+ * - Branching point ENode positions
+ * - Wire intermediate waypoints
+ *
+ * @module core/utils
+ */
+/**
+ * Position on a 2D discrete grid with integer coordinates.
+ *
+ * Enforces integer constraint at construction time to ensure all positions
+ * align with the discrete grid model. Positions are immutable once created.
+ *
+ * @example
+ * ```typescript
+ * const pos = new Position(10, 20);
+ * console.log(pos.x); // 10
+ * console.log(pos.y); // 20
+ *
+ * // Invalid: non-integer coordinates
+ * const invalid = new Position(10.5, 20); // TypeError
+ * ```
+ */
+export declare class Position {
+    readonly x: number;
+    readonly y: number;
+    /**
+     * Create a new position on the discrete grid.
+     *
+     * @param x - X coordinate (must be integer)
+     * @param y - Y coordinate (must be integer)
+     * @throws {TypeError} If x or y are not integers
+     */
+    constructor(x: number, y: number);
+    /**
+     * Check if this position equals another position.
+     *
+     * @param other - Position to compare with
+     * @returns true if both x and y coordinates are equal
+     *
+     * @example
+     * ```typescript
+     * const p1 = new Position(10, 20);
+     * const p2 = new Position(10, 20);
+     * const p3 = new Position(15, 20);
+     *
+     * console.log(p1.equals(p2)); // true
+     * console.log(p1.equals(p3)); // false
+     * ```
+     */
+    equals(other: Position): boolean;
+    /**
+     * Serialize position to JSON.
+     *
+     * @returns Plain object with x and y properties
+     *
+     * @example
+     * ```typescript
+     * const pos = new Position(10, 20);
+     * const json = pos.toJSON();
+     * console.log(json); // { x: 10, y: 20 }
+     * ```
+     */
+    toJSON(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Deserialize position from JSON.
+     *
+     * @param json - Plain object with x and y properties
+     * @returns Position instance
+     * @throws {TypeError} If coordinates are not integers
+     *
+     * @example
+     * ```typescript
+     * const json = { x: 10, y: 20 };
+     * const pos = Position.fromJSON(json);
+     * console.log(pos.x); // 10
+     * ```
+     */
+    static fromJSON(json: {
+        x: number;
+        y: number;
+    }): Position;
+    /**
+     * String representation for debugging.
+     *
+     * @returns String in format "Position(x, y)"
+     */
+    toString(): string;
+}
+/**
+ * Given a path defined by an array of 2D positions, find the best index to insert
+ * a target position so that the path shape is preserved as much as possible.
+ *
+ * This is used when splitting a wire at a position: we need to determine which
+ * segment of the path the target falls on, and return the insertion index.
+ *
+ * Algorithm:
+ * 1. For each consecutive pair of positions (segment), calculate the perpendicular
+ *    distance from target to that segment
+ * 2. Return the index after the start of the closest segment
+ *
+ * @param positions - Array of positions defining the path (typically includes
+ *                    start endpoint, intermediate positions, and end endpoint)
+ * @param target - Position to insert
+ * @param minDistance - Optional maximum distance to consider (default: Infinity)
+ * @returns Index where target should be inserted (0 to positions.length)
+ *
+ * @example
+ * ```typescript
+ * // Path: (0,0) -> (10,0) -> (10,10) -> (20,10)
+ * const path = [
+ *   new Position(0, 0),
+ *   new Position(10, 0),
+ *   new Position(10, 10),
+ *   new Position(20, 10)
+ * ];
+ * // Target at (5, 0) - on first segment
+ * findPositionBestIndex(path, new Position(5, 0)); // Returns 1
+ * // Target at (10, 5) - on second segment
+ * findPositionBestIndex(path, new Position(10, 5)); // Returns 2
+ * ```
+ */
+export declare function findPositionBestIndex(positions: Position[], target: Position, minDistance?: number): number;
+/**
+ * Simplify a path by removing collinear intermediate positions.
+ *
+ * Given an ordered array of positions representing a line path, this function
+ * removes positions that lie on the same line as their neighbors (collinear points).
+ * The resulting path is visually identical but with fewer redundant points.
+ *
+ * Three points A, B, C are collinear if B lies on the line from A to C.
+ * When collinear, B is redundant and can be removed without changing the path shape.
+ *
+ * @param positions - Ordered array of positions representing the path
+ * @param tolerance - Optional tolerance for collinearity check (default: 5)
+ * @returns Simplified array with collinear intermediate points removed
+ *
+ * @example
+ * ```typescript
+ * // Horizontal line with redundant middle points
+ * const path = [
+ *   new Position(0, 0),
+ *   new Position(5, 0),   // collinear - will be removed
+ *   new Position(10, 0),  // collinear - will be removed
+ *   new Position(15, 0)
+ * ];
+ * simplifyPositions(path);
+ * // Returns: [Position(0, 0), Position(15, 0)]
+ *
+ * // L-shaped path - corner point is NOT collinear
+ * const lPath = [
+ *   new Position(0, 0),
+ *   new Position(10, 0),  // corner - kept
+ *   new Position(10, 10)
+ * ];
+ * simplifyPositions(lPath);
+ * // Returns: [Position(0, 0), Position(10, 0), Position(10, 10)]
+ * ```
+ */
+export declare function simplifyPositions(positions: Position[], tolerance?: number): Position[];

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

@@ -0,0 +1,77 @@
+import { IPosition3D } from './types';
+/**
+ * 3D position.
+ * Positions are immutable once created.
+ *
+ * @example
+ * ```typescript
+ * const pos3 = new Position3D(10, 20, 40);
+ * console.log(pos.x); // 10
+ * console.log(pos.y); // 20
+ * console.log(pos.y); // 40
+ *
+ * ```
+ */
+export declare class Position3D {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    /**
+     * Create a new 3D position.
+     *
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     * @param z - Z coordinate
+     */
+    constructor(x: number, y: number, z: number);
+    /**
+     * Check if this position equals another position.
+     *
+     * @param other - Position to compare with
+     * @returns true if x,y and z coordinates are equal
+     *
+     * @example
+     * ```typescript
+     * const p1 = new Position(10, 20, 40);
+     * const p2 = new Position(10, 20, 40);
+     * const p3 = new Position(15, 20, 40);
+     *
+     * console.log(p1.equals(p2)); // true
+     * console.log(p1.equals(p3)); // false
+     * ```
+     */
+    equals(other: Position3D): boolean;
+    /**
+     * Serialize position to JSON.
+     *
+     * @returns Plain object with x, y and z properties
+     *
+     * @example
+     * ```typescript
+     * const pos = new Position(10, 20, 40);
+     * const json = pos.toJSON();
+     * console.log(json); // { x: 10, y: 20, z: 40 }
+     * ```
+     */
+    toJSON(): IPosition3D;
+    /**
+     * Deserialize position from JSON.
+     *
+     * @param json - Plain object with x, y and z properties
+     * @returns Position instance
+     *
+     * @example
+     * ```typescript
+     * const json = { x: 10, y: 20, z: 40 };
+     * const pos = Position.fromJSON(json);
+     * console.log(pos.x); // 10
+     * ```
+     */
+    static fromJSON(json: IPosition3D): Position3D;
+    /**
+     * String representation for debugging.
+     *
+     * @returns String in format "Position(x, y, z)"
+     */
+    toString(): string;
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Rotation Type for Component Orientation
+ * Represents orientation angle for components on the 2D grid.
+ * Uses integer degrees for discrete rotation values.
+ * @module core/utils
+ */
+/**
+ * Rotation angle for component orientation.
+ *
+ * Enforces integer constraint at construction time. Typically used with
+ * values like 0, 90, 180, 270 degrees, but any integer is valid.
+ * Rotations are immutable once created.
+ *
+ * @example
+ * ```typescript
+ * const rotation = new Rotation(90);
+ * console.log(rotation.angle); // 90
+ *
+ * // Invalid: non-integer angle
+ * const invalid = new Rotation(45.5); // TypeError
+ * ```
+ */
+export declare class Rotation {
+    readonly angle: number;
+    /**
+     * Create a new rotation with the specified angle.
+     *
+     * @param angle - Rotation angle in degrees (must be integer)
+     * @throws {TypeError} If angle is not an integer
+     */
+    constructor(angle: number);
+    /**
+     * Serialize rotation to JSON.
+     *
+     * @returns The angle value as a number
+     *
+     * @example
+     * ```typescript
+     * const rotation = new Rotation(90);
+     * const json = rotation.toJSON();
+     * console.log(json); // 90
+     * ```
+     */
+    toJSON(): number;
+    /**
+     * Deserialize rotation from JSON.
+     *
+     * @param angle - Angle value
+     * @returns Rotation instance
+     * @throws {TypeError} If angle is not an integer
+     *
+     * @example
+     * ```typescript
+     * const rotation = Rotation.fromJSON(90);
+     * console.log(rotation.angle); // 90
+     * ```
+     */
+    static fromJSON(angle: number): Rotation;
+    /**
+     * Check if this rotation equals another rotation.
+     *
+     * @param other - Rotation to compare with
+     * @returns true if angles are equal
+     *
+     * @example
+     * ```typescript
+     * const r1 = new Rotation(90);
+     * const r2 = new Rotation(90);
+     * const r3 = new Rotation(180);
+     *
+     * console.log(r1.equals(r2)); // true
+     * console.log(r1.equals(r3)); // false
+     * ```
+     */
+    equals(other: Rotation): boolean;
+    /**
+     * String representation for debugging.
+     *
+     * @returns String in format "Rotation(angle°)"
+     */
+    toString(): string;
+}

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

@@ -0,0 +1,24 @@
+import { UUID } from './types';
+export type { UUID, IPosition, IPosition3D, ICameraOptions } from './types';
+/**
+ * Generate a new RFC 4122 UUID v4 identifier.
+ *
+ * Uses the native `crypto.randomUUID()` API when available (ES2022+ browsers,
+ * Node 19+). For older Node.js environments in testing, falls back to a
+ * polyfill implementation.
+ *
+ * @returns A newly generated UUID string
+ *
+ * @example
+ * ```typescript
+ * const componentId = generateUUID();
+ * const wireId = generateUUID();
+ * console.log(componentId !== wireId); // true (collision probability: ~10^-36)
+ * ```
+ */
+export declare function generateUUID(): UUID;
+export { Memoize, MemoizeExpiring } from './MemoizeDecorator.js';
+export { CameraOptions } from './CameraOptions';
+export { Position, simplifyPositions, findPositionBestIndex } from './Position';
+export { Position3D } from './Position3D';
+export { Rotation } from './Rotation';

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

@@ -0,0 +1,35 @@
+/**
+ * core utilities types definitions
+ * @module core/utils
+ */
+/**
+ * Universally Unique Identifier (RFC 4122 UUID v4).
+ */
+export type UUID = string;
+/**
+ * 2D Position Type
+ * Represents a 2D position on the circuit grid
+ */
+export type IPosition = {
+    x: number;
+    y: number;
+};
+/**
+ * 3D Position Type
+ * Represents a 3D position. Used for Camera placement
+ */
+export type IPosition3D = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Circuit camera options (used to position camera at startup)
+ */
+export type ICameraOptions = {
+    position: IPosition3D;
+    lookAtPosition: IPosition3D;
+    fov: number;
+    near: number;
+    far: number;
+};