circuitjson-toolkit 1.0.0

package/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS
+
+## Project Overview
+
+- Repository: `CircuitJSON Toolkit` JavaScript library.
+- Source is in `src/`.
+- Tests are in `tests/`.
+- Specifications are in `spec/`.
+- Documentation is in `docs/`.
+- The package contains dependency-free CircuitJSON validation, indexing, and
+  utility helpers for browser and Node consumers.
+
+## Build, Run, Test
+
+- Install: `npm install`
+- Test: `npm test`
+- Format: `npm run format`
+- Check formatting: `npm run check:format`
+
+## Coding Style & Naming Conventions
+
+- Prettier settings are in `.prettierrc.json`: 4-space indent, single quotes,
+  no semicolons, no trailing commas.
+- Keep files under 1000 lines; split modules/classes when they grow.
+- Add JSDoc for every function/method, including private helpers.
+- Add inline comments only where non-obvious behavior needs context.
+- Utility modules should use class-based organization with static methods when
+  appropriate.
+- For single-class modules, name the `.mjs` file in CamelCase to match the
+  class name.
+- For private internals, use ECMAScript private elements.
+- Prefer `async/await` for naturally asynchronous operations.
+
+## Library Scope
+
+- Include CircuitJSON element-array validation, parsing, indexing, unit helpers,
+  and small summary helpers.
+- Do not include renderer code, Three.js code, ECAD parser logic, UI wiring, or
+  source-format-specific compatibility adapters.
+
+## Testing Guidelines
+
+- Use repo scripts only: `npm test`.
+- For every feature/fix/behavior change, add or update tests in `tests/`.
+- Keep tests focused on observable CircuitJSON utility behavior.
+- Tests must use small fake CircuitJSON samples only.
+
+## Security & Configuration Tips
+
+- Treat CircuitJSON files as untrusted input.
+- Keep helpers local-first and dependency-free by default.

package/README.md

@@ -0,0 +1,24 @@
+# CircuitJSON Toolkit
+
+Dependency-free utilities for working with serialized CircuitJSON element
+arrays.
+
+## Usage
+
+```js
+import {
+    CircuitJsonDocument,
+    CircuitJsonIndexer,
+    CircuitJsonParser
+} from 'circuitjson-toolkit'
+
+const circuitJson = CircuitJsonParser.parseText(fileText)
+CircuitJsonDocument.assertModel(circuitJson)
+
+const index = CircuitJsonIndexer.index(circuitJson)
+console.log(index.elementsByType.get('pcb_board'))
+```
+
+## License
+
+AGPL-3.0-or-later.

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "circuitjson-toolkit",
+    "version": "1.0.0",
+    "description": "Dependency-free CircuitJSON validation and indexing utilities",
+    "keywords": [
+        "circuitjson",
+        "circuit-json",
+        "pcb",
+        "eda",
+        "ecad"
+    ],
+    "license": "AGPL-3.0-or-later",
+    "type": "module",
+    "main": "./src/index.mjs",
+    "exports": {
+        ".": "./src/index.mjs"
+    },
+    "files": [
+        "src",
+        "docs",
+        "spec",
+        "README.md",
+        "AGENTS.md"
+    ],
+    "scripts": {
+        "test": "node --test",
+        "format": "prettier --write .",
+        "check:format": "prettier --check ."
+    },
+    "devDependencies": {
+        "prettier": "^3.4.2"
+    },
+    "engines": {
+        "node": ">=20"
+    }
+}

package/src/core/CircuitJsonDocument.mjs

@@ -0,0 +1,80 @@
+/**
+ * Validates serialized CircuitJSON element arrays.
+ */
+export class CircuitJsonDocument {
+    /**
+     * Returns true when a value is a CircuitJSON element.
+     * @param {unknown} value Candidate value.
+     * @returns {boolean}
+     */
+    static isElement(value) {
+        return (
+            Boolean(value) &&
+            typeof value === 'object' &&
+            typeof value.type === 'string' &&
+            value.type.trim().length > 0
+        )
+    }
+
+    /**
+     * Returns true when a value is a CircuitJSON element array.
+     * @param {unknown} value Candidate model.
+     * @returns {boolean}
+     */
+    static isModel(value) {
+        return (
+            Array.isArray(value) &&
+            value.every((element) => CircuitJsonDocument.isElement(element))
+        )
+    }
+
+    /**
+     * Throws when a value is not a CircuitJSON element array.
+     * @param {unknown} value Candidate model.
+     * @returns {void}
+     */
+    static assertModel(value) {
+        if (!CircuitJsonDocument.isModel(value)) {
+            throw new TypeError('Expected a CircuitJSON element array.')
+        }
+    }
+
+    /**
+     * Attaches non-serialized metadata to a CircuitJSON array.
+     * @template {object[]} T
+     * @param {T} circuitJson CircuitJSON model.
+     * @param {{ fileName?: string, fileType?: string, kind?: string }} [metadata]
+     * @returns {T}
+     */
+    static attachMetadata(circuitJson, metadata = {}) {
+        CircuitJsonDocument.assertModel(circuitJson)
+        Object.defineProperties(circuitJson, {
+            fileName: {
+                configurable: true,
+                enumerable: true,
+                value: String(metadata.fileName || ''),
+                writable: true
+            },
+            fileType: {
+                configurable: true,
+                enumerable: true,
+                value: String(metadata.fileType || 'circuitjson'),
+                writable: true
+            },
+            kind: {
+                configurable: true,
+                enumerable: true,
+                value: String(metadata.kind || 'pcb'),
+                writable: true
+            },
+            sourceFormat: {
+                configurable: true,
+                enumerable: true,
+                value: 'circuitjson',
+                writable: true
+            }
+        })
+
+        return circuitJson
+    }
+}

package/src/core/CircuitJsonIndexer.mjs

@@ -0,0 +1,62 @@
+import { CircuitJsonDocument } from './CircuitJsonDocument.mjs'
+
+const ID_FIELDS_BY_TYPE = {
+    pcb_board: 'pcb_board_id',
+    pcb_component: 'pcb_component_id',
+    pcb_hole: 'pcb_hole_id',
+    pcb_plated_hole: 'pcb_plated_hole_id',
+    pcb_port: 'pcb_port_id',
+    pcb_smtpad: 'pcb_smtpad_id',
+    pcb_trace: 'pcb_trace_id',
+    pcb_via: 'pcb_via_id',
+    source_component: 'source_component_id',
+    source_net: 'source_net_id',
+    source_port: 'source_port_id',
+    source_trace: 'source_trace_id'
+}
+
+/**
+ * Builds lookup maps for CircuitJSON element arrays.
+ */
+export class CircuitJsonIndexer {
+    /**
+     * Indexes a CircuitJSON model.
+     * @param {object[]} circuitJson CircuitJSON model.
+     * @returns {{ elements: object[], elementsByType: Map<string, object[]>, elementsById: Map<string, object>, sourceComponentById: Map<string, object>, pcbComponentById: Map<string, object> }}
+     */
+    static index(circuitJson) {
+        CircuitJsonDocument.assertModel(circuitJson)
+        const elementsByType = new Map()
+        const elementsById = new Map()
+        const sourceComponentById = new Map()
+        const pcbComponentById = new Map()
+
+        circuitJson.forEach((element) => {
+            const type = String(element?.type || '')
+            if (!elementsByType.has(type)) {
+                elementsByType.set(type, [])
+            }
+            elementsByType.get(type).push(element)
+
+            const idField = ID_FIELDS_BY_TYPE[type]
+            const id = idField ? String(element?.[idField] || '') : ''
+            if (id) {
+                elementsById.set(`${type}:${id}`, element)
+            }
+            if (type === 'source_component' && id) {
+                sourceComponentById.set(id, element)
+            }
+            if (type === 'pcb_component' && id) {
+                pcbComponentById.set(id, element)
+            }
+        })
+
+        return {
+            elements: circuitJson,
+            elementsByType,
+            elementsById,
+            sourceComponentById,
+            pcbComponentById
+        }
+    }
+}

package/src/core/CircuitJsonParser.mjs

@@ -0,0 +1,55 @@
+import { CircuitJsonDocument } from './CircuitJsonDocument.mjs'
+
+/**
+ * Parses standalone CircuitJSON files.
+ */
+export class CircuitJsonParser {
+    /**
+     * Parses standalone CircuitJSON text.
+     * @param {string} text JSON text.
+     * @param {{ fileName?: string }} [options] Parse metadata.
+     * @returns {object[]}
+     */
+    static parseText(text, options = {}) {
+        let parsed
+        try {
+            parsed = JSON.parse(String(text || ''))
+        } catch (error) {
+            throw new SyntaxError(
+                'CircuitJSON file is not valid JSON: ' +
+                    String(error?.message || error || 'Unknown error.')
+            )
+        }
+
+        CircuitJsonDocument.assertModel(parsed)
+        return CircuitJsonDocument.attachMetadata(parsed, {
+            fileName: options.fileName || '',
+            fileType: 'circuitjson',
+            kind: CircuitJsonParser.#resolveKind(parsed)
+        })
+    }
+
+    /**
+     * Parses standalone CircuitJSON bytes.
+     * @param {ArrayBuffer | Uint8Array} bytes File bytes.
+     * @param {{ fileName?: string }} [options] Parse metadata.
+     * @returns {object[]}
+     */
+    static parseBytes(bytes, options = {}) {
+        const view =
+            bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes || [])
+        const text = new TextDecoder().decode(view)
+        return CircuitJsonParser.parseText(text, options)
+    }
+
+    /**
+     * Resolves a broad document kind from available elements.
+     * @param {object[]} model CircuitJSON model.
+     * @returns {string}
+     */
+    static #resolveKind(model) {
+        return model.some((element) => String(element?.type) === 'pcb_board')
+            ? 'pcb'
+            : 'circuitjson'
+    }
+}

package/src/core/CircuitJsonUnits.mjs

@@ -0,0 +1,50 @@
+const MILS_PER_MM = 39.37007874015748
+
+/**
+ * Unit helpers for CircuitJSON's millimeter-based PCB dimensions.
+ */
+export class CircuitJsonUnits {
+    /**
+     * Converts millimeters to mils.
+     * @param {unknown} value Millimeter value.
+     * @param {number} [fallback] Fallback millimeter value.
+     * @returns {number}
+     */
+    static mmToMil(value, fallback = 0) {
+        return CircuitJsonUnits.#round(
+            CircuitJsonUnits.#number(value, fallback) * MILS_PER_MM
+        )
+    }
+
+    /**
+     * Converts a CircuitJSON point from millimeters to mils.
+     * @param {{ x?: unknown, y?: unknown } | null | undefined} point Point.
+     * @returns {{ x: number, y: number }}
+     */
+    static pointMmToMil(point) {
+        return {
+            x: CircuitJsonUnits.mmToMil(point?.x, 0),
+            y: CircuitJsonUnits.mmToMil(point?.y, 0)
+        }
+    }
+
+    /**
+     * Converts a value to a finite number.
+     * @param {unknown} value Candidate number.
+     * @param {number} fallback Fallback number.
+     * @returns {number}
+     */
+    static #number(value, fallback) {
+        const numeric = Number(value)
+        return Number.isFinite(numeric) ? numeric : fallback
+    }
+
+    /**
+     * Rounds render-unit conversions to stable precision.
+     * @param {number} value Numeric value.
+     * @returns {number}
+     */
+    static #round(value) {
+        return Math.round(value * 1_000_000) / 1_000_000
+    }
+}

package/src/index.mjs

@@ -0,0 +1,4 @@
+export { CircuitJsonDocument } from './core/CircuitJsonDocument.mjs'
+export { CircuitJsonIndexer } from './core/CircuitJsonIndexer.mjs'
+export { CircuitJsonParser } from './core/CircuitJsonParser.mjs'
+export { CircuitJsonUnits } from './core/CircuitJsonUnits.mjs'