simple-circuit-engine 0.0.11 → 0.0.12

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