altium-toolkit 0.1.1 → 0.1.17

package/src/core/altium/PcbOutlineRecovery.mjs

@@ -2,6 +2,7 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { PcbGeometryFlipper } from './PcbGeometryFlipper.mjs'
 import { PcbOutlineRasterizer } from './PcbOutlineRasterizer.mjs'
 
 /**
@@ -92,81 +93,11 @@ export class PcbOutlineRecovery {
     /**
      * Mirrors one normalized PCB model vertically so the SVG matches the
      * authored top-view orientation.
-     * @param {{ boardOutline: { minX: number, minY: number, widthMil: number, heightMil: number, segments: Array<Record<string, number | string>> }, polygons?: { layer?: string, segments: Array<Record<string, number | string>> }[], fills?: { x1: number, y1: number, x2: number, y2: number, layerCode?: number, layerId?: number }[], tracks?: { x1: number, y1: number, x2: number, y2: number, width: number, layerCode?: number, layerId?: number }[], arcs?: { x: number, y: number, radius: number, startAngle: number, endAngle: number, width: number, layerCode?: number, layerId?: number }[], vias?: { x: number, y: number, diameter: number, holeDiameter: number }[], pads?: { x: number, y: number, rotation?: number, holeRotation?: number | null }[], components?: { designator: string, x: number, y: number, rotation: number, layer: string, pattern: string }[] }} pcb
-     * @returns {{ boardOutline: { minX: number, minY: number, widthMil: number, heightMil: number, segments: Array<Record<string, number | string>> }, polygons: { layer?: string, segments: Array<Record<string, number | string>> }[], fills: { x1: number, y1: number, x2: number, y2: number, layerCode?: number, layerId?: number }[], tracks: { x1: number, y1: number, x2: number, y2: number, width: number, layerCode?: number, layerId?: number }[], arcs: { x: number, y: number, radius: number, startAngle: number, endAngle: number, width: number, layerCode?: number, layerId?: number }[], vias: { x: number, y: number, diameter: number, holeDiameter: number }[], pads: { x: number, y: number, rotation?: number, holeRotation?: number | null }[], components: { designator: string, x: number, y: number, rotation: number, layer: string, pattern: string }[] }}
+     * @param {{ boardOutline: { minX: number, minY: number, widthMil: number, heightMil: number, segments: Array<Record<string, number | string>> }, polygons?: { layer?: string, segments: Array<Record<string, number | string>> }[], fills?: { x1: number, y1: number, x2: number, y2: number, layerCode?: number, layerId?: number }[], tracks?: { x1: number, y1: number, x2: number, y2: number, width: number, layerCode?: number, layerId?: number }[], arcs?: { x: number, y: number, radius: number, startAngle: number, endAngle: number, width: number, layerCode?: number, layerId?: number }[], vias?: { x: number, y: number, diameter: number, holeDiameter: number }[], pads?: { x: number, y: number, rotation?: number, holeRotation?: number | null }[], texts?: { x: number, y: number, rotation?: number }[], components?: { designator: string, x: number, y: number, rotation: number, layer: string, pattern: string }[] }} pcb
+     * @returns {{ boardOutline: { minX: number, minY: number, widthMil: number, heightMil: number, segments: Array<Record<string, number | string>> }, polygons: { layer?: string, segments: Array<Record<string, number | string>> }[], fills: { x1: number, y1: number, x2: number, y2: number, layerCode?: number, layerId?: number }[], tracks: { x1: number, y1: number, x2: number, y2: number, width: number, layerCode?: number, layerId?: number }[], arcs: { x: number, y: number, radius: number, startAngle: number, endAngle: number, width: number, layerCode?: number, layerId?: number }[], vias: { x: number, y: number, diameter: number, holeDiameter: number }[], pads: { x: number, y: number, rotation?: number, holeRotation?: number | null }[], texts: { x: number, y: number, rotation?: number }[], components: { designator: string, x: number, y: number, rotation: number, layer: string, pattern: string }[] }}
      */
     static flipGeometryVertically(pcb) {
-        const outline = pcb?.boardOutline
-        const maxY =
-            Number(outline?.minY || 0) + Number(outline?.heightMil || 0)
-        const mirrorY = (value) =>
-            Number(outline?.minY || 0) + maxY - Number(value || 0)
-
-        return {
-            ...pcb,
-            boardOutline: {
-                ...outline,
-                segments: (outline?.segments || []).map((segment) =>
-                    PcbOutlineRecovery.#flipSegment(segment, mirrorY)
-                )
-            },
-            polygons: (pcb?.polygons || []).map((polygon) => ({
-                ...polygon,
-                segments: (polygon.segments || []).map((segment) =>
-                    PcbOutlineRecovery.#flipSegment(segment, mirrorY)
-                )
-            })),
-            fills: (pcb?.fills || []).map((fill) => {
-                const y1 = mirrorY(fill.y1)
-                const y2 = mirrorY(fill.y2)
-
-                return {
-                    ...fill,
-                    y1: Math.min(y1, y2),
-                    y2: Math.max(y1, y2)
-                }
-            }),
-            tracks: (pcb?.tracks || []).map((track) => ({
-                ...track,
-                y1: mirrorY(track.y1),
-                y2: mirrorY(track.y2)
-            })),
-            arcs: (pcb?.arcs || []).map((arc) => ({
-                ...arc,
-                y: mirrorY(arc.y),
-                startAngle: PcbOutlineRecovery.#normalizeAngle(
-                    360 - Number(arc.startAngle || 0)
-                ),
-                endAngle: PcbOutlineRecovery.#normalizeAngle(
-                    360 - Number(arc.endAngle || 0)
-                )
-            })),
-            vias: (pcb?.vias || []).map((via) => ({
-                ...via,
-                y: mirrorY(via.y)
-            })),
-            pads: (pcb?.pads || []).map((pad) => ({
-                ...pad,
-                y: mirrorY(pad.y),
-                rotation: PcbOutlineRecovery.#normalizeAngle(
-                    360 - Number(pad.rotation || 0)
-                ),
-                holeRotation:
-                    pad?.holeRotation === null ||
-                    pad?.holeRotation === undefined
-                        ? (pad?.holeRotation ?? null)
-                        : PcbOutlineRecovery.#normalizeAngle(
-                              360 - Number(pad.holeRotation || 0)
-                          )
-            })),
-            components: (pcb?.components || []).map((component) => ({
-                ...component,
-                y: mirrorY(component.y),
-                rotation: PcbOutlineRecovery.#normalizeAngle(
-                    360 - Number(component.rotation || 0)
-                )
-            }))
-        }
+        return PcbGeometryFlipper.flipGeometryVertically(pcb)
     }
 
     /**
@@ -915,43 +846,4 @@ export class PcbOutlineRecovery {
 
         return delta
     }
-
-    /**
-     * Mirrors one outline or polygon segment across the board Y axis.
-     * @param {Record<string, number | string>} segment
-     * @param {(value: number) => number} mirrorY
-     * @returns {Record<string, number | string>}
-     */
-    static #flipSegment(segment, mirrorY) {
-        if (segment.type !== 'arc') {
-            return {
-                ...segment,
-                y1: mirrorY(Number(segment.y1 || 0)),
-                y2: mirrorY(Number(segment.y2 || 0))
-            }
-        }
-
-        const startAngle = Number(segment.startAngle || 0)
-        const endAngle = Number(segment.endAngle || 0)
-
-        return {
-            ...segment,
-            y1: mirrorY(Number(segment.y1 || 0)),
-            y2: mirrorY(Number(segment.y2 || 0)),
-            cy: mirrorY(Number(segment.cy || 0)),
-            startAngle: PcbOutlineRecovery.#normalizeAngle(360 - startAngle),
-            endAngle: PcbOutlineRecovery.#normalizeAngle(360 - endAngle)
-        }
-    }
-
-    /**
-     * Normalizes one circular angle into the [0, 360) range.
-     * @param {number} angle
-     * @returns {number}
-     */
-    static #normalizeAngle(angle) {
-        const normalized = Number(angle || 0) % 360
-
-        return normalized < 0 ? normalized + 360 : normalized
-    }
 }

package/src/core/altium/PcbPadPrimitiveParser.mjs

@@ -0,0 +1,347 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbLayerIdCodec } from './PcbLayerIdCodec.mjs'
+import { PcbPadShapeCodec } from './PcbPadShapeCodec.mjs'
+import { PcbPadStackParser } from './PcbPadStackParser.mjs'
+import { PcbPrimitiveOwnershipIndexParser } from './PcbPrimitiveOwnershipIndexParser.mjs'
+
+/**
+ * Decodes Altium pad primitive streams.
+ */
+export class PcbPadPrimitiveParser {
+    static #PAD_OBJECT_ID = 2
+
+    static #PAD_SUBRECORD_COUNT = 6
+
+    static #PAD_MAIN_SUBRECORD_INDEX = 4
+
+    static #PAD_EXTENSION_SUBRECORD_INDEX = 5
+
+    static #PAD_MAIN_RECORD_MIN_BYTE_LENGTH = 61
+
+    /**
+     * Decodes one variable-length pad stream.
+     * @param {Uint8Array | ArrayBuffer} headerBytes
+     * @param {Uint8Array | ArrayBuffer} dataBytes
+     * @returns {{ x: number, y: number, sizeTopX: number, sizeTopY: number, sizeMidX: number, sizeMidY: number, sizeBottomX: number, sizeBottomY: number, holeDiameter: number, shapeTop: number, shapeMid: number, shapeBottom: number, shapeTopName: string | null, shapeMidName: string | null, shapeBottomName: string | null, padShapeNames: { top: string | null, middle: string | null, bottom: string | null }, rotation: number, isPlated: boolean, componentIndex: number | null, netIndex: number | null, polygonIndex: number | null, layerCode: number | null, layerId: number | null, legacyLayerId: number | null, layerV7SaveId: number | null, [key: string]: unknown }[]}
+     */
+    static parsePadStream(headerBytes, dataBytes) {
+        const count = PcbPadPrimitiveParser.#readRecordCount(headerBytes)
+        const normalizedData = PcbPadPrimitiveParser.#toUint8Array(dataBytes)
+
+        if (!count) {
+            return []
+        }
+
+        let offset = 0
+        const pads = []
+
+        for (let index = 0; index < count; index += 1) {
+            const record = PcbPadPrimitiveParser.#readPadRecordAt(
+                normalizedData,
+                offset
+            )
+
+            if (!record) {
+                return []
+            }
+
+            const pad = PcbPadPrimitiveParser.#parsePadSubrecords(
+                record.subrecords
+            )
+
+            if (!pad) {
+                return []
+            }
+
+            pads.push(pad)
+            offset = record.nextOffset
+
+            if (index < count - 1) {
+                const nextOffset =
+                    PcbPadPrimitiveParser.#findNextPadRecordOffset(
+                        normalizedData,
+                        offset,
+                        count - index - 1
+                    )
+
+                if (nextOffset === null) {
+                    return []
+                }
+
+                offset = nextOffset
+            }
+        }
+
+        return pads
+    }
+
+    /**
+     * Reads one pad record and its known subrecords from a stream offset.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @returns {{ subrecords: DataView[], nextOffset: number } | null}
+     */
+    static #readPadRecordAt(bytes, offset) {
+        if (
+            offset + 1 > bytes.byteLength ||
+            bytes[offset] !== PcbPadPrimitiveParser.#PAD_OBJECT_ID
+        ) {
+            return null
+        }
+
+        let cursor = offset + 1
+        const subrecords = []
+
+        for (
+            let subrecordIndex = 0;
+            subrecordIndex < PcbPadPrimitiveParser.#PAD_SUBRECORD_COUNT;
+            subrecordIndex += 1
+        ) {
+            const subrecord = PcbPadPrimitiveParser.#readSubrecordAt(
+                bytes,
+                cursor
+            )
+
+            if (!subrecord) {
+                return null
+            }
+
+            subrecords.push(subrecord.view)
+            cursor = subrecord.nextOffset
+        }
+
+        return { subrecords, nextOffset: cursor }
+    }
+
+    /**
+     * Reads one length-prefixed pad subrecord.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @returns {{ view: DataView, nextOffset: number } | null}
+     */
+    static #readSubrecordAt(bytes, offset) {
+        if (offset + 4 > bytes.byteLength) {
+            return null
+        }
+
+        const subrecordLength = PcbPadPrimitiveParser.#readUint32FromBytes(
+            bytes,
+            offset
+        )
+        const payloadOffset = offset + 4
+        const nextOffset = payloadOffset + subrecordLength
+
+        if (nextOffset > bytes.byteLength) {
+            return null
+        }
+
+        return {
+            view: new DataView(
+                bytes.buffer,
+                bytes.byteOffset + payloadOffset,
+                subrecordLength
+            ),
+            nextOffset
+        }
+    }
+
+    /**
+     * Finds the next pad record boundary after optional unknown subrecords.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} remainingCount
+     * @returns {number | null}
+     */
+    static #findNextPadRecordOffset(bytes, offset, remainingCount) {
+        let cursor = offset
+
+        while (cursor < bytes.byteLength) {
+            if (
+                PcbPadPrimitiveParser.#canReadPadRecordSequence(
+                    bytes,
+                    cursor,
+                    remainingCount
+                )
+            ) {
+                return cursor
+            }
+
+            const unknownSubrecord = PcbPadPrimitiveParser.#readSubrecordAt(
+                bytes,
+                cursor
+            )
+
+            if (!unknownSubrecord) {
+                return null
+            }
+
+            cursor = unknownSubrecord.nextOffset
+        }
+
+        return null
+    }
+
+    /**
+     * Checks whether the remaining pad records can be read from an offset.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} remainingCount
+     * @returns {boolean}
+     */
+    static #canReadPadRecordSequence(bytes, offset, remainingCount) {
+        const record = PcbPadPrimitiveParser.#readPadRecordAt(bytes, offset)
+
+        if (!record) {
+            return false
+        }
+
+        if (remainingCount <= 1) {
+            return true
+        }
+
+        return (
+            PcbPadPrimitiveParser.#findNextPadRecordOffset(
+                bytes,
+                record.nextOffset,
+                remainingCount - 1
+            ) !== null
+        )
+    }
+
+    /**
+     * Decodes one pad payload from its subrecords.
+     * @param {DataView[]} subrecords
+     * @returns {{ x: number, y: number, sizeTopX: number, sizeTopY: number, sizeMidX: number, sizeMidY: number, sizeBottomX: number, sizeBottomY: number, holeDiameter: number, shapeTop: number, shapeMid: number, shapeBottom: number, shapeTopName: string | null, shapeMidName: string | null, shapeBottomName: string | null, padShapeNames: { top: string | null, middle: string | null, bottom: string | null }, rotation: number, isPlated: boolean, componentIndex: number | null, netIndex: number | null, polygonIndex: number | null, layerCode: number | null, layerId: number | null, legacyLayerId: number | null, layerV7SaveId: number | null, [key: string]: unknown } | null}
+     */
+    static #parsePadSubrecords(subrecords) {
+        const mainRecord =
+            subrecords[PcbPadPrimitiveParser.#PAD_MAIN_SUBRECORD_INDEX]
+        const extensionRecord =
+            subrecords[PcbPadPrimitiveParser.#PAD_EXTENSION_SUBRECORD_INDEX]
+
+        if (
+            !mainRecord ||
+            mainRecord.byteLength <
+                PcbPadPrimitiveParser.#PAD_MAIN_RECORD_MIN_BYTE_LENGTH
+        ) {
+            return null
+        }
+
+        const layerState = PcbPadPrimitiveParser.#parsePadLayerState(mainRecord)
+        const ownershipIndexes =
+            PcbPrimitiveOwnershipIndexParser.readOwnershipIndexes(mainRecord, {
+                component: 7,
+                net: 3,
+                polygon: 5
+            })
+
+        const pad = {
+            x: PcbPadPrimitiveParser.#readMil(mainRecord, 13),
+            y: PcbPadPrimitiveParser.#readMil(mainRecord, 17),
+            sizeTopX: PcbPadPrimitiveParser.#readMil(mainRecord, 21),
+            sizeTopY: PcbPadPrimitiveParser.#readMil(mainRecord, 25),
+            sizeMidX: PcbPadPrimitiveParser.#readMil(mainRecord, 29),
+            sizeMidY: PcbPadPrimitiveParser.#readMil(mainRecord, 33),
+            sizeBottomX: PcbPadPrimitiveParser.#readMil(mainRecord, 37),
+            sizeBottomY: PcbPadPrimitiveParser.#readMil(mainRecord, 41),
+            holeDiameter: PcbPadPrimitiveParser.#readMil(mainRecord, 45),
+            shapeTop: mainRecord.getUint8(49),
+            shapeMid: mainRecord.getUint8(50),
+            shapeBottom: mainRecord.getUint8(51),
+            rotation: mainRecord.getFloat64(52, true),
+            isPlated: mainRecord.getUint8(60) !== 0,
+            ...ownershipIndexes,
+            layerCode: layerState.layerId,
+            layerId: layerState.layerId,
+            legacyLayerId: layerState.legacyLayerId,
+            layerV7SaveId: layerState.layerV7SaveId
+        }
+
+        return {
+            ...pad,
+            ...PcbPadShapeCodec.describePadShapes(pad),
+            ...PcbPadStackParser.parse(mainRecord, extensionRecord, pad)
+        }
+    }
+
+    /**
+     * Decodes the visible and hidden saved-layer state from one pad main record.
+     * @param {DataView} mainRecord
+     * @returns {{ layerId: number | null, legacyLayerId: number | null, layerV7SaveId: number | null }}
+     */
+    static #parsePadLayerState(mainRecord) {
+        const legacyLayerId = mainRecord.getUint8(0) || null
+        const layerV7SaveId =
+            mainRecord.byteLength >= 118
+                ? mainRecord.getUint32(114, true) || null
+                : null
+        const decodedLayerId =
+            PcbLayerIdCodec.legacyLayerIdFromV7SaveId(layerV7SaveId)
+
+        return {
+            layerId: decodedLayerId || legacyLayerId,
+            legacyLayerId,
+            layerV7SaveId
+        }
+    }
+
+    /**
+     * Reads one standard fixed-point mil value.
+     * @param {DataView} view
+     * @param {number} offset
+     * @returns {number}
+     */
+    static #readMil(view, offset) {
+        return view.getInt32(offset, true) / 10000
+    }
+
+    /**
+     * Reads the little-endian record count from one stream header.
+     * @param {Uint8Array | ArrayBuffer} headerBytes
+     * @returns {number}
+     */
+    static #readRecordCount(headerBytes) {
+        const normalizedHeader =
+            PcbPadPrimitiveParser.#toUint8Array(headerBytes)
+
+        if (normalizedHeader.byteLength < 4) {
+            return 0
+        }
+
+        return new DataView(
+            normalizedHeader.buffer,
+            normalizedHeader.byteOffset,
+            4
+        ).getUint32(0, true)
+    }
+
+    /**
+     * Reads one little-endian unsigned 32-bit value from a byte array.
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @returns {number}
+     */
+    static #readUint32FromBytes(bytes, offset) {
+        return new DataView(
+            bytes.buffer,
+            bytes.byteOffset + offset,
+            4
+        ).getUint32(0, true)
+    }
+
+    /**
+     * Converts an ArrayBuffer or view into a Uint8Array view.
+     * @param {Uint8Array | ArrayBuffer} bytes
+     * @returns {Uint8Array}
+     */
+    static #toUint8Array(bytes) {
+        if (bytes instanceof Uint8Array) {
+            return bytes
+        }
+
+        return new Uint8Array(bytes)
+    }
+}

package/src/core/altium/PcbPadShapeCodec.mjs

@@ -0,0 +1,158 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Maps Altium pad, drill, and pad-stack mode codes to stable model labels.
+ */
+export class PcbPadShapeCodec {
+    static #PAD_SHAPE_NAMES = new Map([
+        [0, 'none'],
+        [1, 'round'],
+        [2, 'rectangular'],
+        [3, 'octagonal'],
+        [9, 'rounded-rectangle']
+    ])
+
+    static #HOLE_SHAPE_NAMES = new Map([
+        [-1, 'none'],
+        [0, 'round'],
+        [1, 'square'],
+        [2, 'slot']
+    ])
+
+    static #PAD_MODE_NAMES = new Map([
+        [0, 'simple'],
+        [1, 'top-middle-bottom'],
+        [2, 'full-stack']
+    ])
+
+    /**
+     * Returns a stable normalized label for one raw pad shape code.
+     * @param {number | null | undefined} shape
+     * @returns {string | null}
+     */
+    static padShapeName(shape) {
+        return PcbPadShapeCodec.#mappedCodeName(
+            shape,
+            PcbPadShapeCodec.#PAD_SHAPE_NAMES
+        )
+    }
+
+    /**
+     * Returns a stable normalized label for one raw drill-hole shape code.
+     * @param {number | null | undefined} shape
+     * @returns {string | null}
+     */
+    static holeShapeName(shape) {
+        return PcbPadShapeCodec.#mappedCodeName(
+            shape,
+            PcbPadShapeCodec.#HOLE_SHAPE_NAMES
+        )
+    }
+
+    /**
+     * Returns a stable normalized label for one raw pad stack mode code.
+     * @param {number | null | undefined} mode
+     * @returns {string | null}
+     */
+    static padModeName(mode) {
+        return PcbPadShapeCodec.#mappedCodeName(
+            mode,
+            PcbPadShapeCodec.#PAD_MODE_NAMES
+        )
+    }
+
+    /**
+     * Builds normalized top/middle/bottom shape labels for one pad.
+     * @param {{ shapeTop?: number, shapeMid?: number, shapeBottom?: number }} pad
+     * @returns {{ shapeTopName: string | null, shapeMidName: string | null, shapeBottomName: string | null, padShapeNames: { top: string | null, middle: string | null, bottom: string | null } }}
+     */
+    static describePadShapes(pad) {
+        const top = PcbPadShapeCodec.padShapeName(pad.shapeTop)
+        const middle = PcbPadShapeCodec.padShapeName(pad.shapeMid)
+        const bottom = PcbPadShapeCodec.padShapeName(pad.shapeBottom)
+
+        return {
+            shapeTopName: top,
+            shapeMidName: middle,
+            shapeBottomName: bottom,
+            padShapeNames: {
+                top,
+                middle,
+                bottom
+            }
+        }
+    }
+
+    /**
+     * Adds normalized names and an effective fallback to one middle-layer shape.
+     * @param {number} shape
+     * @param {number | null | undefined} fallbackShape
+     * @returns {{ shape: number, shapeName: string | null, effectiveShape: number, effectiveShapeName: string | null }}
+     */
+    static describeMiddleLayerShape(shape, fallbackShape) {
+        const effectiveShape =
+            Number(shape) === 0 && Number.isFinite(Number(fallbackShape))
+                ? Number(fallbackShape)
+                : Number(shape)
+
+        return {
+            shape: Number(shape),
+            shapeName: PcbPadShapeCodec.padShapeName(shape),
+            effectiveShape,
+            effectiveShapeName: PcbPadShapeCodec.padShapeName(effectiveShape)
+        }
+    }
+
+    /**
+     * Builds normalized slot or drill geometry for one parsed pad hole.
+     * @param {{ shape: number | null, diameter: number, slotLength: number | null, rotation: number | null }} hole
+     * @returns {{ shape: number, shapeName: string | null, diameter: number, slotLength: number | null, rotation: number | null, length: number, width: number } | null}
+     */
+    static describeHoleGeometry(hole) {
+        if (hole.shape === null || hole.shape === undefined) {
+            return null
+        }
+
+        const diameter = Number(hole.diameter || 0)
+        const slotLength = Number(hole.slotLength || 0) || null
+        const length =
+            PcbPadShapeCodec.holeShapeName(hole.shape) === 'slot'
+                ? Math.max(Number(slotLength || 0), diameter)
+                : diameter
+
+        return {
+            shape: Number(hole.shape),
+            shapeName: PcbPadShapeCodec.holeShapeName(hole.shape),
+            diameter,
+            slotLength,
+            rotation: hole.rotation ?? null,
+            length,
+            width: diameter
+        }
+    }
+
+    /**
+     * Resolves a code through a mapping table while preserving unknown values.
+     * @param {number | null | undefined} code
+     * @param {Map<number, string>} mapping
+     * @returns {string | null}
+     */
+    static #mappedCodeName(code, mapping) {
+        if (code === null || code === undefined) {
+            return null
+        }
+
+        const numericCode = Number(code)
+        if (!Number.isFinite(numericCode)) {
+            return null
+        }
+
+        if (mapping.has(numericCode)) {
+            return mapping.get(numericCode) ?? null
+        }
+
+        return `unknown-${numericCode}`
+    }
+}