altium-toolkit 1.1.3 → 1.1.23

package/src/core/BinaryReader.mjs

@@ -2,6 +2,145 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+/**
+ * Reads sequential little-endian primitive values from a BinaryReader.
+ */
+export class BinaryReaderCursor {
+    #offset
+
+    #reader
+
+    /**
+     * @param {BinaryReader} reader
+     * @param {number} [offset]
+     */
+    constructor(reader, offset = 0) {
+        const normalizedOffset = Number(offset)
+        if (
+            !Number.isInteger(normalizedOffset) ||
+            normalizedOffset < 0 ||
+            normalizedOffset > reader.byteLength
+        ) {
+            throw new RangeError(
+                'BinaryReader cursor offset is out of bounds: ' +
+                    normalizedOffset
+            )
+        }
+
+        this.#reader = reader
+        this.#offset = normalizedOffset
+    }
+
+    /**
+     * Returns the current cursor offset.
+     * @returns {number}
+     */
+    get offset() {
+        return this.#offset
+    }
+
+    /**
+     * Reads one unsigned byte and advances the cursor.
+     * @returns {number}
+     */
+    readUint8() {
+        return this.#readNumber(1, (offset) => this.#reader.readUint8(offset))
+    }
+
+    /**
+     * Reads one signed 16-bit integer and advances the cursor.
+     * @returns {number}
+     */
+    readInt16() {
+        return this.#readNumber(2, (offset) => this.#reader.readInt16(offset))
+    }
+
+    /**
+     * Reads one unsigned 16-bit integer and advances the cursor.
+     * @returns {number}
+     */
+    readUint16() {
+        return this.#readNumber(2, (offset) => this.#reader.readUint16(offset))
+    }
+
+    /**
+     * Reads one unsigned 32-bit integer and advances the cursor.
+     * @returns {number}
+     */
+    readUint32() {
+        return this.#readNumber(4, (offset) => this.#reader.readUint32(offset))
+    }
+
+    /**
+     * Reads one signed 32-bit integer and advances the cursor.
+     * @returns {number}
+     */
+    readInt32() {
+        return this.#readNumber(4, (offset) => this.#reader.readInt32(offset))
+    }
+
+    /**
+     * Reads one unsigned 64-bit integer and advances the cursor.
+     * @returns {number}
+     */
+    readUint64() {
+        return this.#readNumber(8, (offset) => this.#reader.readUint64(offset))
+    }
+
+    /**
+     * Reads one 64-bit floating-point value and advances the cursor.
+     * @returns {number}
+     */
+    readFloat64() {
+        return this.#readNumber(8, (offset) => this.#reader.readFloat64(offset))
+    }
+
+    /**
+     * Reads one byte slice and advances the cursor.
+     * @param {number} length
+     * @returns {Uint8Array}
+     */
+    readBytes(length) {
+        const bytes = this.#reader.readBytes(this.#offset, length)
+        this.#offset += Number(length)
+        return bytes
+    }
+
+    /**
+     * Reads one length-prefixed string and advances the cursor.
+     * @param {string} [encoding]
+     * @returns {string}
+     */
+    readPascalString(encoding = 'utf-8') {
+        const length = this.#reader.readUint8(this.#offset)
+        const value = this.#reader.readPascalString(this.#offset, encoding)
+        this.#offset += 1 + length
+        return value
+    }
+
+    /**
+     * Reads one length-prefixed block and advances the cursor.
+     * @returns {{ byteLength: number, flags: number, dataOffset: number, nextOffset: number, bytes: Uint8Array }}
+     */
+    readSizedBlock() {
+        const block = this.#reader.readSizedBlock(this.#offset)
+        this.#offset = block.nextOffset
+        return block
+    }
+
+    /**
+     * Reads one fixed-width numeric value and advances the cursor.
+     * @param {number} size
+     * @param {(offset: number) => number} reader
+     * @returns {number}
+     */
+    #readNumber(size, reader) {
+        const value = reader(this.#offset)
+        this.#offset += size
+        return value
+    }
+}
+
 /**
  * Reads little-endian primitive values from an ArrayBuffer with bounds checks.
  */
@@ -39,6 +178,16 @@ export class BinaryReader {
         return this.#dataView.getUint8(offset)
     }
 
+    /**
+     * Reads one signed 16-bit integer.
+     * @param {number} offset
+     * @returns {number}
+     */
+    readInt16(offset) {
+        this.#assertReadable(offset, 2)
+        return this.#dataView.getInt16(offset, true)
+    }
+
     /**
      * Reads one unsigned 16-bit integer.
      * @param {number} offset
@@ -69,6 +218,16 @@ export class BinaryReader {
         return this.#dataView.getInt32(offset, true)
     }
 
+    /**
+     * Reads one 64-bit floating-point value.
+     * @param {number} offset
+     * @returns {number}
+     */
+    readFloat64(offset) {
+        this.#assertReadable(offset, 8)
+        return this.#dataView.getFloat64(offset, true)
+    }
+
     /**
      * Reads one unsigned 64-bit integer as a JavaScript number.
      * @param {number} offset
@@ -97,8 +256,58 @@ export class BinaryReader {
      * @returns {Uint8Array}
      */
     readBytes(offset, length) {
-        this.#assertReadable(offset, length)
-        return new Uint8Array(this.#arrayBuffer.slice(offset, offset + length))
+        const normalizedOffset = Number(offset)
+        const normalizedLength = Number(length)
+        this.#assertReadable(normalizedOffset, normalizedLength)
+        return new Uint8Array(
+            this.#arrayBuffer.slice(
+                normalizedOffset,
+                normalizedOffset + normalizedLength
+            )
+        )
+    }
+
+    /**
+     * Reads one one-byte length-prefixed string.
+     * @param {number} offset
+     * @param {string} [encoding]
+     * @returns {string}
+     */
+    readPascalString(offset, encoding = 'utf-8') {
+        const length = this.readUint8(offset)
+        const bytes = this.readBytes(offset + 1, length)
+        return new TextDecoder(encoding).decode(bytes)
+    }
+
+    /**
+     * Reads one 32-bit length-prefixed byte block.
+     * @param {number} offset
+     * @returns {{ byteLength: number, flags: number, dataOffset: number, nextOffset: number, bytes: Uint8Array }}
+     */
+    readSizedBlock(offset) {
+        const normalizedOffset = Number(offset)
+        const rawLength = this.readUint32(normalizedOffset)
+        const byteLength = rawLength & 0x00ffffff
+        const flags = rawLength >>> 24
+        const dataOffset = normalizedOffset + 4
+        const bytes = this.readBytes(dataOffset, byteLength)
+
+        return {
+            byteLength,
+            flags,
+            dataOffset,
+            nextOffset: dataOffset + byteLength,
+            bytes
+        }
+    }
+
+    /**
+     * Creates a sequential cursor over this reader.
+     * @param {number} [offset]
+     * @returns {BinaryReaderCursor}
+     */
+    cursor(offset = 0) {
+        return new BinaryReaderCursor(this, offset)
     }
 
     /**
@@ -112,7 +321,9 @@ export class BinaryReader {
 
         if (
             !Number.isInteger(normalizedOffset) ||
+            !Number.isInteger(normalizedSize) ||
             normalizedOffset < 0 ||
+            normalizedSize < 0 ||
             normalizedOffset + normalizedSize > this.#byteLength
         ) {
             throw new RangeError(

package/src/core/altium/AltiumLibraryBatchExporter.mjs

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { AltiumPcbLibExporter } from './AltiumPcbLibExporter.mjs'
+import { AltiumSchLibExporter } from './AltiumSchLibExporter.mjs'
+import { SourceBundleExporter } from './SourceBundleExporter.mjs'
+
+/**
+ * Orchestrates source lookup and local library export.
+ */
+export class AltiumLibraryBatchExporter {
+    #client
+
+    /**
+     * @param {{ client?: { fetchComponentBundle?: Function, searchComponents?: Function } }} [options] Batch options.
+     */
+    constructor(options = {}) {
+        this.#client = options.client || null
+    }
+
+    /**
+     * Searches components and exports the matching ids.
+     * @param {string} query Search query.
+     * @param {object} [options] Export options.
+     * @returns {Promise<object>}
+     */
+    async searchAndExport(query, options = {}) {
+        const rows = await this.#requireClient().searchComponents(
+            query,
+            options
+        )
+        return this.exportIds(
+            rows.map((row) => row.id).filter(Boolean),
+            options
+        )
+    }
+
+    /**
+     * Exports one list of provider ids.
+     * @param {string[]} ids Component ids.
+     * @param {{ appendManifest?: { completedIds?: string[] }, includeSourceBundle?: boolean, includeSchLib?: boolean, includePcbLib?: boolean, merged?: boolean, continueOnError?: boolean, onProgress?: Function }} [options] Export options.
+     * @returns {Promise<{ entries: object[], bundles: object[], diagnostics: object[], checkpoint: { completedIds: string[] } }>}
+     */
+    async exportIds(ids, options = {}) {
+        const completedIds = [
+            ...new Set(options.appendManifest?.completedIds || [])
+        ]
+        const completedSet = new Set(completedIds)
+        const entries = []
+        const bundles = []
+        const diagnostics = []
+
+        for (const id of ids
+            .map((value) => String(value || ''))
+            .filter(Boolean)) {
+            if (completedSet.has(id)) {
+                AltiumLibraryBatchExporter.#emitProgress(options, {
+                    id,
+                    status: 'skipped'
+                })
+                continue
+            }
+
+            try {
+                const bundle =
+                    await this.#requireClient().fetchComponentBundle(id)
+                bundles.push(bundle)
+                entries.push(
+                    ...AltiumLibraryBatchExporter.#buildPerComponentEntries(
+                        id,
+                        bundle,
+                        options
+                    )
+                )
+                completedSet.add(id)
+                completedIds.push(id)
+                AltiumLibraryBatchExporter.#emitProgress(options, {
+                    id,
+                    status: 'exported'
+                })
+            } catch (error) {
+                diagnostics.push({
+                    id,
+                    severity: 'error',
+                    message: String(error?.message || error)
+                })
+                AltiumLibraryBatchExporter.#emitProgress(options, {
+                    id,
+                    status: 'failed'
+                })
+                if (!options.continueOnError) {
+                    throw error
+                }
+            }
+        }
+
+        if (options.merged && bundles.length) {
+            entries.push(
+                ...AltiumLibraryBatchExporter.#buildMergedEntries(bundles)
+            )
+        }
+
+        return {
+            entries,
+            bundles,
+            diagnostics,
+            checkpoint: { completedIds }
+        }
+    }
+
+    /**
+     * Builds per-component export entries.
+     * @param {string} id Component id.
+     * @param {object} bundle Normalized bundle.
+     * @param {object} options Export options.
+     * @returns {object[]}
+     */
+    static #buildPerComponentEntries(id, bundle, options) {
+        const prefix = AltiumLibraryBatchExporter.#safePathSegment(id) + '/'
+        const entries = []
+
+        if (options.includeSourceBundle) {
+            entries.push(
+                ...SourceBundleExporter.export(bundle).entries.map((entry) => ({
+                    ...entry,
+                    path: prefix + entry.path
+                }))
+            )
+        }
+
+        if (options.includeSchLib) {
+            entries.push({
+                path: prefix + 'library.SchLib',
+                bytes: AltiumSchLibExporter.export([bundle]),
+                contentType: 'application/octet-stream'
+            })
+        }
+
+        if (options.includePcbLib) {
+            entries.push({
+                path: prefix + 'library.PcbLib',
+                bytes: AltiumPcbLibExporter.export([bundle]),
+                contentType: 'application/octet-stream'
+            })
+        }
+
+        return entries
+    }
+
+    /**
+     * Builds merged library output entries.
+     * @param {object[]} bundles Normalized bundles.
+     * @returns {object[]}
+     */
+    static #buildMergedEntries(bundles) {
+        return [
+            {
+                path: 'merged/library.SchLib',
+                bytes: AltiumSchLibExporter.export(bundles),
+                contentType: 'application/octet-stream'
+            },
+            {
+                path: 'merged/library.PcbLib',
+                bytes: AltiumPcbLibExporter.export(bundles),
+                contentType: 'application/octet-stream'
+            }
+        ]
+    }
+
+    /**
+     * Emits progress.
+     * @param {object} options Export options.
+     * @param {object} event Progress event.
+     * @returns {void}
+     */
+    static #emitProgress(options, event) {
+        if (typeof options.onProgress === 'function') {
+            options.onProgress(event)
+        }
+    }
+
+    /**
+     * Sanitizes one path segment.
+     * @param {string} value Raw value.
+     * @returns {string}
+     */
+    static #safePathSegment(value) {
+        return String(value || 'component').replace(
+            /[\\/:\u0000-\u001f]/gu,
+            '_'
+        )
+    }
+
+    /**
+     * Returns the configured client or throws.
+     * @returns {{ fetchComponentBundle?: Function, searchComponents?: Function }}
+     */
+    #requireClient() {
+        if (!this.#client) {
+            throw new Error('AltiumLibraryBatchExporter client is required.')
+        }
+
+        return this.#client
+    }
+}