circuitjson-toolkit 1.0.16 → 1.1.0

package/src/core/ParserOptions.mjs

@@ -0,0 +1,333 @@
+import { ToolkitAsset } from './contracts/ToolkitAsset.mjs'
+import { AttachedValueLimits } from './AttachedValueLimits.mjs'
+
+const ASSET_MODES = new Set(['none', 'metadata', 'full'])
+const EXTENSION_MODES = new Set(['none', 'metadata', 'canonical', 'full'])
+const RETAIN_SOURCE_MODES = new Set(['none', 'reference'])
+const WORKER_MODES = new Set(['auto', true, false])
+
+/**
+ * Normalizes the common standalone parser input and option contract.
+ */
+export class ParserOptions {
+    /**
+     * Normalizes one parser request without decoding its CircuitJSON payload.
+     * @param {unknown} input Parser input candidate.
+     * @param {unknown} [options] Common parser options candidate.
+     * @returns {{ input: { fileName: string, data: string | ArrayBuffer | Uint8Array, assets: object[] }, sourceReference: object, options: { preserveRaw: boolean, decodeAssets: string, extensions: string | string[], reports: string[], retainSource: string, worker: 'auto' | boolean, transferInput: boolean, signal: any, onProgress: Function | undefined } }} Normalized request.
+     */
+    static normalize(input, options = {}) {
+        const inputFields = ParserOptions.#plainDescriptors(
+            input,
+            'CircuitJSON parser input must be an object.'
+        )
+        const optionFields = ParserOptions.#plainDescriptors(
+            options,
+            'CircuitJSON parser options must be an object.'
+        )
+        const data = ParserOptions.#dataValue(inputFields.data)
+        const inputAssets = ParserOptions.#dataValue(inputFields.assets)
+        if (!ParserOptions.#isData(data)) {
+            throw new TypeError(
+                'CircuitJSON parser data must be a string, ArrayBuffer, or Uint8Array.'
+            )
+        }
+        if (inputAssets !== undefined && !Array.isArray(inputAssets)) {
+            throw new TypeError('CircuitJSON parser assets must be an array.')
+        }
+        if (inputAssets !== undefined) AttachedValueLimits.add(inputAssets)
+
+        const decodeAssetsValue = ParserOptions.#dataValue(
+            optionFields.decodeAssets
+        )
+        const decodeAssets = String(
+            decodeAssetsValue === undefined ? 'metadata' : decodeAssetsValue
+        )
+        if (!ASSET_MODES.has(decodeAssets)) {
+            throw new TypeError(
+                `Unsupported CircuitJSON asset decode mode: ${decodeAssets}.`
+            )
+        }
+        const extensions = ParserOptions.#extensions(
+            ParserOptions.#dataValue(optionFields.extensions)
+        )
+        const reports = ParserOptions.#stringList(
+            ParserOptions.#dataValue(optionFields.reports),
+            'report'
+        )
+        const retainSourceValue = ParserOptions.#dataValue(
+            optionFields.retainSource
+        )
+        const retainSource = String(
+            retainSourceValue === undefined ? 'none' : retainSourceValue
+        )
+        if (!RETAIN_SOURCE_MODES.has(retainSource)) {
+            throw new TypeError(
+                `Unsupported CircuitJSON source retention mode: ${retainSource}.`
+            )
+        }
+        const workerValue = ParserOptions.#dataValue(optionFields.worker)
+        const worker = workerValue === undefined ? 'auto' : workerValue
+        if (!WORKER_MODES.has(worker)) {
+            throw new TypeError(
+                'CircuitJSON worker must be auto, true, or false.'
+            )
+        }
+        if (
+            ParserOptions.#dataValue(optionFields.onProgress) !== undefined &&
+            typeof ParserOptions.#dataValue(optionFields.onProgress) !==
+                'function'
+        ) {
+            throw new TypeError('CircuitJSON onProgress must be a function.')
+        }
+
+        return {
+            input: {
+                fileName: ParserOptions.fileName(input),
+                data,
+                assets: inputAssets || []
+            },
+            sourceReference: input,
+            options: {
+                preserveRaw:
+                    ParserOptions.#dataValue(optionFields.preserveRaw) === true,
+                decodeAssets,
+                extensions,
+                reports,
+                retainSource,
+                worker,
+                transferInput:
+                    ParserOptions.#dataValue(optionFields.transferInput) ===
+                    true,
+                signal: ParserOptions.#dataValue(optionFields.signal),
+                onProgress: ParserOptions.#dataValue(optionFields.onProgress)
+            }
+        }
+    }
+
+    /**
+     * Decodes supported parser data into JSON text.
+     * @param {string | ArrayBuffer | Uint8Array} data Parser payload.
+     * @returns {string} Decoded text.
+     */
+    static text(data) {
+        if (typeof data === 'string') return data
+        if (data instanceof ArrayBuffer) {
+            return new TextDecoder().decode(new Uint8Array(data))
+        }
+        if (data instanceof Uint8Array) return new TextDecoder().decode(data)
+        throw new TypeError(
+            'CircuitJSON parser data must be a string, ArrayBuffer, or Uint8Array.'
+        )
+    }
+
+    /**
+     * Selects supplied assets for one canonicalization by DocumentResult.
+     * @param {object[]} assets Supplied asset records.
+     * @param {string} mode Asset decode mode.
+     * @returns {object[]} Selected canonical assets.
+     */
+    static assets(assets, mode) {
+        return ToolkitAsset.prepareAll(assets, { mode })
+    }
+
+    /**
+     * Performs bounded CircuitJSON array detection without full JSON parsing.
+     * @param {unknown} input Parser input candidate.
+     * @returns {boolean} Whether the input has a CircuitJSON array prefix.
+     */
+    static supports(input) {
+        try {
+            const descriptors = ParserOptions.#plainDescriptors(
+                input,
+                'CircuitJSON parser input must be an object.'
+            )
+            const data = ParserOptions.#dataValue(descriptors.data)
+            if (!ParserOptions.#isData(data)) return false
+            return ParserOptions.#prefix(data).trimStart().startsWith('[')
+        } catch {
+            return false
+        }
+    }
+
+    /**
+     * Normalizes a source file name for errors and result identity.
+     * @param {unknown} input Parser input candidate.
+     * @returns {string} Normalized file name.
+     */
+    static fileName(input) {
+        try {
+            const descriptors = ParserOptions.#plainDescriptors(
+                input,
+                'CircuitJSON parser input must be an object.'
+            )
+            const fileName = ParserOptions.#dataValue(descriptors.fileName)
+            if (
+                fileName !== undefined &&
+                !['string', 'number', 'boolean', 'bigint'].includes(
+                    typeof fileName
+                )
+            ) {
+                return ''
+            }
+            return String(fileName || '')
+                .replaceAll('\\', '/')
+                .replace(/^\.\//u, '')
+        } catch {
+            return ''
+        }
+    }
+
+    /**
+     * Normalizes the extensions mode or selected feature ids.
+     * @param {unknown} value Extensions option candidate.
+     * @returns {string | string[]} Normalized extensions option.
+     */
+    static #extensions(value) {
+        if (value === undefined) return 'canonical'
+        if (Array.isArray(value)) {
+            return ParserOptions.#stringList(value, 'extension feature')
+        }
+        const mode = String(value)
+        if (!EXTENSION_MODES.has(mode)) {
+            throw new TypeError(
+                `Unsupported CircuitJSON extensions mode: ${mode}.`
+            )
+        }
+        return mode
+    }
+
+    /**
+     * Normalizes one option list into unique non-empty strings.
+     * @param {unknown} value List candidate.
+     * @param {string} label Item label.
+     * @returns {string[]} Normalized list.
+     */
+    static #stringList(value, label) {
+        if (value === undefined) return []
+        const descriptors = ParserOptions.#arrayDescriptors(value, label)
+        const items = []
+        for (let index = 0; index < descriptors.length.value; index += 1) {
+            const item = descriptors[String(index)].value
+            if (typeof item !== 'string' || !item.trim()) {
+                throw new TypeError(
+                    `CircuitJSON ${label} ids must be non-empty strings.`
+                )
+            }
+            items.push(item.trim())
+        }
+        return [...new Set(items)]
+    }
+
+    /**
+     * Returns true for the canonical parser payload types.
+     * @param {unknown} data Payload candidate.
+     * @returns {boolean} Whether the payload type is supported.
+     */
+    static #isData(data) {
+        return (
+            typeof data === 'string' ||
+            data instanceof ArrayBuffer ||
+            data instanceof Uint8Array
+        )
+    }
+
+    /**
+     * Decodes only a bounded prefix for format detection.
+     * @param {string | ArrayBuffer | Uint8Array} data Parser payload.
+     * @returns {string} Bounded text prefix.
+     */
+    static #prefix(data) {
+        const limit = 512
+        if (typeof data === 'string') return data.slice(0, limit)
+        const bytes =
+            data instanceof Uint8Array
+                ? data.subarray(0, limit)
+                : new Uint8Array(data, 0, Math.min(data.byteLength, limit))
+        return new TextDecoder().decode(bytes)
+    }
+
+    /**
+     * Returns own data descriptors for a plain request record.
+     * @param {unknown} value Record candidate.
+     * @param {string} message Failure message.
+     * @returns {Record<string, PropertyDescriptor>} Data descriptors.
+     */
+    static #plainDescriptors(value, message) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new TypeError(message)
+        }
+        let prototype
+        let descriptors
+        try {
+            prototype = Object.getPrototypeOf(value)
+            descriptors = Object.getOwnPropertyDescriptors(value)
+        } catch {
+            throw new TypeError(message)
+        }
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(message)
+        }
+        for (const descriptor of Object.values(descriptors)) {
+            if (!Object.hasOwn(descriptor, 'value')) {
+                throw new TypeError(
+                    'CircuitJSON parser fields must be data properties.'
+                )
+            }
+        }
+        return descriptors
+    }
+
+    /**
+     * Returns exact dense-array descriptors without caller iteration.
+     * @param {unknown} value Array candidate.
+     * @param {string} label Item label.
+     * @returns {Record<string, PropertyDescriptor>} Array descriptors.
+     */
+    static #arrayDescriptors(value, label) {
+        if (!Array.isArray(value)) {
+            throw new TypeError(`CircuitJSON ${label}s must be an array.`)
+        }
+        let prototype
+        let descriptors
+        try {
+            prototype = Object.getPrototypeOf(value)
+            descriptors = Object.getOwnPropertyDescriptors(value)
+        } catch {
+            throw new TypeError(`CircuitJSON ${label}s must be a dense array.`)
+        }
+        const length = ParserOptions.#dataValue(descriptors.length)
+        if (
+            prototype !== Array.prototype ||
+            !Number.isSafeInteger(length) ||
+            length < 0 ||
+            Reflect.ownKeys(descriptors).length !== length + 1
+        ) {
+            throw new TypeError(`CircuitJSON ${label}s must be a dense array.`)
+        }
+        for (let index = 0; index < length; index += 1) {
+            const descriptor = descriptors[String(index)]
+            if (
+                !descriptor ||
+                !Object.hasOwn(descriptor, 'value') ||
+                descriptor.enumerable !== true
+            ) {
+                throw new TypeError(
+                    `CircuitJSON ${label}s must contain data properties.`
+                )
+            }
+        }
+        return descriptors
+    }
+
+    /**
+     * Reads one data descriptor value.
+     * @param {PropertyDescriptor | undefined} descriptor Descriptor.
+     * @returns {unknown} Data value.
+     */
+    static #dataValue(descriptor) {
+        return descriptor && Object.hasOwn(descriptor, 'value')
+            ? descriptor.value
+            : undefined
+    }
+}

package/src/core/PcbBoundsSelectionModel.mjs

@@ -13,13 +13,29 @@ export class PcbBoundsSelectionModel {
      * @returns {{ bounds: object | null, point: object | null, candidates: object[], selectedCandidate: object | null, componentKeys: string[], netNames: string[] }}
      */
     static resolve(documentModel, bounds, options = {}) {
+        return PcbBoundsSelectionModel.resolvePrimitives(
+            PcbInteractionPrimitiveModel.build(documentModel).primitives,
+            bounds,
+            options
+        )
+    }
+
+    /**
+     * Resolves area selection from an already prepared primitive list.
+     * @param {object[]} primitives Prepared PCB primitives.
+     * @param {{ minX?: unknown, minY?: unknown, maxX?: unknown, maxY?: unknown }} bounds Board-space bounds.
+     * @param {{ side?: string, hiddenLayers?: string[], hiddenObjects?: string[] }} [options] Selection options.
+     * @returns {{ bounds: object | null, point: object | null, candidates: object[], selectedCandidate: object | null, componentKeys: string[], netNames: string[] }}
+     */
+    static resolvePrimitives(primitives, bounds, options = {}) {
         const normalizedBounds = PcbBoundsSelectionModel.normalizeBounds(bounds)
         if (!normalizedBounds) return PcbBoundsSelectionModel.#empty()
 
+        const visibility = PcbBoundsSelectionModel.#visibilityOptions(options)
         const candidates = PcbBoundsSelectionModel.#containedPrimitives(
-            documentModel,
+            primitives,
             normalizedBounds,
-            options
+            visibility
         ).map((primitive) =>
             PcbCandidateSelectionModel.fromPrimitive(primitive)
         )
@@ -90,15 +106,13 @@ export class PcbBoundsSelectionModel {
 
     /**
      * Returns primitives that are visible and touch the measured bounds.
-     * @param {object | object[]} documentModel Parsed PCB document model.
+     * @param {object[]} primitives Prepared primitives.
      * @param {object} bounds Normalized bounds.
      * @param {object} options Selection options.
      * @returns {object[]}
      */
-    static #containedPrimitives(documentModel, bounds, options) {
-        return PcbInteractionPrimitiveModel.build(
-            documentModel
-        ).primitives.filter(
+    static #containedPrimitives(primitives, bounds, options) {
+        return (primitives || []).filter(
             (primitive) =>
                 PcbBoundsSelectionModel.#isVisible(primitive, options) &&
                 PcbBoundsSelectionModel.#touchesBounds(primitive, bounds)
@@ -112,24 +126,46 @@ export class PcbBoundsSelectionModel {
      * @returns {boolean}
      */
     static #isVisible(primitive, options) {
-        const side = String(options?.side || '')
+        const side = options.side
         if (side && primitive.side && primitive.side !== side) return false
 
-        const hiddenLayers = new Set(
-            (Array.isArray(options?.hiddenLayers) ? options.hiddenLayers : [])
-                .map(String)
-                .filter(Boolean)
-        )
-        if (primitive.layer && hiddenLayers.has(String(primitive.layer))) {
+        if (
+            primitive.layer &&
+            options.hiddenLayers.has(String(primitive.layer))
+        ) {
             return false
         }
 
-        const hiddenObjects = new Set(
-            (Array.isArray(options?.hiddenObjects) ? options.hiddenObjects : [])
-                .map(String)
-                .filter(Boolean)
+        return !options.hiddenObjects.has(
+            PcbBoundsSelectionModel.#objectKey(primitive)
         )
-        return !hiddenObjects.has(PcbBoundsSelectionModel.#objectKey(primitive))
+    }
+
+    /**
+     * Builds visibility lookup sets once for one area-selection operation.
+     * @param {{ side?: string, hiddenLayers?: string[], hiddenObjects?: string[] }} options Raw options.
+     * @returns {{ side: string, hiddenLayers: Set<string>, hiddenObjects: Set<string> }} Prepared visibility.
+     */
+    static #visibilityOptions(options) {
+        return {
+            side: String(options?.side || ''),
+            hiddenLayers: new Set(
+                (Array.isArray(options?.hiddenLayers)
+                    ? options.hiddenLayers
+                    : []
+                )
+                    .map(String)
+                    .filter(Boolean)
+            ),
+            hiddenObjects: new Set(
+                (Array.isArray(options?.hiddenObjects)
+                    ? options.hiddenObjects
+                    : []
+                )
+                    .map(String)
+                    .filter(Boolean)
+            )
+        }
     }
 
     /**

package/src/core/PcbDiagnosticFocusModel.mjs

@@ -1,6 +1,7 @@
 import { CircuitJsonIndexer } from './CircuitJsonIndexer.mjs'
 import { CircuitJsonUnits } from './CircuitJsonUnits.mjs'
 import { PcbInteractionPrimitiveModel } from './PcbInteractionPrimitiveModel.mjs'
+import { CircuitJsonDocumentContext } from './context/CircuitJsonDocumentContext.mjs'
 
 /**
  * Resolves viewport focus targets for PCB diagnostic rows.
@@ -12,7 +13,23 @@ export class PcbDiagnosticFocusModel {
      * @returns {Map<string, object>}
      */
     static build(documentModel) {
-        const model = PcbInteractionPrimitiveModel.build(documentModel)
+        let context
+        try {
+            context = CircuitJsonDocumentContext.prepare(documentModel)
+        } catch {
+            return new Map()
+        }
+        const model = PcbInteractionPrimitiveModel.build(context)
+        return PcbDiagnosticFocusModel.buildPrepared(context, model)
+    }
+
+    /**
+     * Builds focus rows from one already prepared complete primitive model.
+     * @param {object | object[]} documentModel Parsed PCB document.
+     * @param {object} model Complete primitive model.
+     * @returns {Map<string, object>} Diagnostic focus rows.
+     */
+    static buildPrepared(documentModel, model) {
         const context = PcbDiagnosticFocusModel.#context(documentModel, model)
         const rows = new Map()
 
@@ -178,7 +195,12 @@ export class PcbDiagnosticFocusModel {
             ['pcb_trace_id', [element?.pcb_trace_id, element?.pcb_trace_ids]],
             [
                 'pcb_smtpad_id',
-                [element?.pcb_smtpad_id, element?.pcb_smtpad_ids]
+                [
+                    element?.pcb_smtpad_id,
+                    element?.pcb_smtpad_ids,
+                    element?.pcb_pad_id,
+                    element?.pcb_pad_ids
+                ]
             ],
             ['pcb_via_id', [element?.pcb_via_id, element?.pcb_via_ids]],
             [
@@ -280,6 +302,11 @@ export class PcbDiagnosticFocusModel {
      * @returns {object[]}
      */
     static #elements(documentModel) {
+        try {
+            return CircuitJsonDocumentContext.prepare(documentModel).model
+        } catch {
+            // Preserve the tolerant legacy wrapper fallbacks below.
+        }
         if (Array.isArray(documentModel)) return documentModel
         if (Array.isArray(documentModel?.elements))
             return documentModel.elements
@@ -355,15 +382,19 @@ export class PcbDiagnosticFocusModel {
      * @returns {object | null}
      */
     static #mergeBounds(boundsRows) {
-        const rows = boundsRows
-            .map((bounds) => PcbDiagnosticFocusModel.#normalizeBounds(bounds))
-            .filter(Boolean)
-        if (!rows.length) return null
-
-        const minX = Math.min(...rows.map((bounds) => bounds.minX))
-        const minY = Math.min(...rows.map((bounds) => bounds.minY))
-        const maxX = Math.max(...rows.map((bounds) => bounds.maxX))
-        const maxY = Math.max(...rows.map((bounds) => bounds.maxY))
+        let minX = Infinity
+        let minY = Infinity
+        let maxX = -Infinity
+        let maxY = -Infinity
+        for (const candidate of boundsRows) {
+            const bounds = PcbDiagnosticFocusModel.#normalizeBounds(candidate)
+            if (!bounds) continue
+            minX = Math.min(minX, bounds.minX)
+            minY = Math.min(minY, bounds.minY)
+            maxX = Math.max(maxX, bounds.maxX)
+            maxY = Math.max(maxY, bounds.maxY)
+        }
+        if (!Number.isFinite(minX)) return null
         return {
             minX,
             minY,