cantraceviewer 0.1.0-rc.0

package/dist/protocol.d.ts

@@ -0,0 +1,73 @@
+/** Private wire protocol between an asynchronous client and its worker. @internal */
+import type { DbcMessageIdentity, EmbeddedDbc, Mf4SignalCatalog, ParsedDbc, TraceMetadata, TraceType } from './types.js';
+/** Serializable error envelope. The client rebuilds an Error preserving name and message. */
+export type WireError = {
+    name: string;
+    message: string;
+};
+/** Request bodies. The client stamps a monotonically increasing `id`; IDs are never recycled. */
+export type WorkerRequestBody = {
+    op: 'openDbc';
+    text: string;
+} | {
+    op: 'closeDbc';
+    dbcId: number;
+} | {
+    op: 'openTrace';
+    traceType: TraceType;
+    buffer: ArrayBuffer;
+} | {
+    op: 'closeTrace';
+    traceId: number;
+} | {
+    op: 'getSignalValues';
+    dbcId: number;
+    traceId: number;
+    messageIdentity: DbcMessageIdentity;
+    signalName: string;
+} | {
+    op: 'getMf4SignalValues';
+    traceId: number;
+    signalId: number;
+} | {
+    op: 'closeClient';
+};
+export type WorkerRequest = WorkerRequestBody & {
+    id: number;
+};
+/** Wire form of `OpenDbcResult`: the opaque handle becomes a worker-local id. */
+export type WireOpenDbc = {
+    dbcId: number;
+    catalog: ParsedDbc;
+};
+/** Wire form of `OpenTraceResult`: the opaque handle becomes a worker-local id. */
+export type WireOpenTrace = {
+    traceId: number;
+    metadata: TraceMetadata;
+    hasRawFrames: boolean;
+    mf4Catalog: Mf4SignalCatalog | null;
+    embeddedDbcs: EmbeddedDbc[];
+    warnings: string[];
+};
+/** Two Float64Array views reconstructed over one transferred ArrayBuffer. */
+export type SeriesPayload = {
+    buffer: ArrayBuffer;
+    timesByteOffset: number;
+    timesLength: number;
+    valuesByteOffset: number;
+    valuesLength: number;
+};
+export type WorkerResponse = {
+    type: 'ready';
+} | {
+    type: 'boot-error';
+    error: WireError;
+} | {
+    type: 'ok';
+    id: number;
+    result: unknown;
+} | {
+    type: 'error';
+    id: number;
+    error: WireError;
+};

package/dist/protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/rpc-client.d.ts

@@ -0,0 +1,53 @@
+import type { WorkerRequest } from './protocol.js';
+import type { DbcHandle, DbcMessageIdentity, DecodedSignalSeries, OpenDbcResult, OpenTraceResult, TraceHandle, TraceType } from './types.js';
+/**
+ * Asynchronous CAN trace client backed by one dedicated worker. The browser entry and the Node
+ * entry expose exactly this interface over their own transport.
+ *
+ * Every method is genuine worker RPC; the worker runs requests strictly serially in call order.
+ * Worker startup failure, a crash, or an unexpected exit is fatal for the client: every pending and
+ * future operation rejects, every handle is invalidated, and the worker is terminated without
+ * restart. Create a new client to recover.
+ */
+export type CanTraceClient = {
+    openDbc(text: string): Promise<OpenDbcResult>;
+    /** Idempotent for handles this client issued; repeat calls resolve without effect. */
+    closeDbc(handle: DbcHandle): Promise<void>;
+    /**
+     * Parse one trace. `buffer` must be the exact ArrayBuffer holding the file bytes: it is
+     * transferred to the worker and detached in the caller, and it stays consumed even when
+     * parsing fails. Typed-array views are rejected rather than silently copied.
+     */
+    openTrace(traceType: TraceType, buffer: ArrayBuffer): Promise<OpenTraceResult>;
+    /** Idempotent for handles this client issued; repeat calls resolve without effect. */
+    closeTrace(handle: TraceHandle): Promise<void>;
+    /** Both returned arrays are views over one ArrayBuffer transferred out of the worker. */
+    getSignalValues(dbcHandle: DbcHandle, traceHandle: TraceHandle, messageIdentity: DbcMessageIdentity, signalName: string): Promise<DecodedSignalSeries>;
+    getMf4SignalValues(traceHandle: TraceHandle, signalId: number): Promise<DecodedSignalSeries>;
+    /**
+     * Idempotent. Queues worker-side cleanup behind every previously posted operation, waits for
+     * its acknowledgement, invalidates every handle, then terminates the worker.
+     */
+    close(): Promise<void>;
+};
+/** Events a transport reports to the shared client core. @internal */
+export type RpcTransportHandlers = {
+    /** One structured-clone payload received from the worker. */
+    message(data: unknown): void;
+    /** Unrecoverable transport failure: crash, exit, or undeliverable message. */
+    fail(error: Error): void;
+};
+/** Worker transport the shared client core drives. @internal */
+export type RpcTransport = {
+    postMessage(message: WorkerRequest, transfer: ArrayBuffer[]): void;
+    /** Stop the worker. Resolves once it is gone; called at most once. */
+    terminate(): Promise<void>;
+};
+/** @internal */
+export type RpcTransportFactory = (handlers: RpcTransportHandlers) => RpcTransport;
+/**
+ * Shared asynchronous client core: request ids, the pending-request table, handle ownership,
+ * fatal-failure handling, and close semantics. It knows nothing about Web Workers or worker
+ * threads; a transport supplies those. @internal
+ */
+export declare function createRpcClient(createTransport: RpcTransportFactory): Promise<CanTraceClient>;

package/dist/rpc-client.js

@@ -0,0 +1,177 @@
+import { createHandleRegistry } from "./handles.js";
+/**
+ * Shared asynchronous client core: request ids, the pending-request table, handle ownership,
+ * fatal-failure handling, and close semantics. It knows nothing about Web Workers or worker
+ * threads; a transport supplies those. @internal
+ */
+export async function createRpcClient(createTransport) {
+    const handles = createHandleRegistry();
+    const pending = new Map();
+    // Request IDs are never recycled.
+    let nextRequestId = 1;
+    let fatalError = null;
+    let closePromise = null;
+    let termination = null;
+    // Assigned below, once the handlers it reports to exist.
+    let transport = null;
+    let ready;
+    const readyPromise = new Promise((resolve, reject) => {
+        ready = { resolve, reject };
+    });
+    function receive(data) {
+        const response = data;
+        if (response.type === 'ready') {
+            ready.resolve();
+            return;
+        }
+        if (response.type === 'boot-error') {
+            fail(fromWireError(response.error));
+            return;
+        }
+        const entry = pending.get(response.id);
+        if (!entry)
+            return;
+        pending.delete(response.id);
+        if (response.type === 'ok')
+            entry.resolve(response.result);
+        else
+            entry.reject(fromWireError(response.error));
+    }
+    /** Worker failure is terminal for this client: nothing ever restarts the worker. */
+    function fail(error) {
+        if (fatalError)
+            return;
+        fatalError = error;
+        handles.releaseAll();
+        const entries = [...pending.values()];
+        pending.clear();
+        for (const entry of entries)
+            entry.reject(error);
+        void terminate().catch(() => undefined);
+        ready.reject(error);
+    }
+    function terminate() {
+        // A transport that reports failure while it is still being created has nothing to stop yet.
+        if (!transport)
+            return Promise.resolve();
+        termination ??= transport.terminate();
+        return termination;
+    }
+    function send(body, transfer) {
+        const active = transport;
+        if (fatalError || !active) {
+            return Promise.reject(fatalError ?? new Error('client transport is unavailable'));
+        }
+        const id = nextRequestId++;
+        return new Promise((resolve, reject) => {
+            pending.set(id, { resolve: resolve, reject });
+            try {
+                active.postMessage({ ...body, id }, transfer);
+            }
+            catch (error) {
+                pending.delete(id);
+                reject(error);
+            }
+        });
+    }
+    transport = createTransport({ message: receive, fail });
+    if (fatalError)
+        void terminate().catch(() => undefined);
+    function assertOpen() {
+        if (fatalError)
+            throw fatalError;
+        if (closePromise)
+            throw new Error('client is closed');
+    }
+    /**
+     * After a fatal failure or client close, worker-side cleanup already happened or the whole
+     * direct client is being torn down; only the local handle mark is needed.
+     */
+    async function sendClose(body) {
+        if (fatalError || closePromise)
+            return;
+        await send(body, []);
+    }
+    await readyPromise;
+    return {
+        async openDbc(text) {
+            assertOpen();
+            const { dbcId, catalog } = await send({ op: 'openDbc', text }, []);
+            return { handle: handles.issue('dbc', dbcId), catalog };
+        },
+        async closeDbc(handle) {
+            const dbcId = handles.release('dbc', handle);
+            if (dbcId === null)
+                return;
+            await sendClose({ op: 'closeDbc', dbcId });
+        },
+        async openTrace(traceType, buffer) {
+            assertOpen();
+            if (!(buffer instanceof ArrayBuffer)) {
+                throw new Error('openTrace requires the exact ArrayBuffer to transfer; pass the underlying buffer, not a typed-array view');
+            }
+            const opened = await send({ op: 'openTrace', traceType, buffer }, [buffer]);
+            return {
+                handle: handles.issue('trace', opened.traceId),
+                metadata: opened.metadata,
+                hasRawFrames: opened.hasRawFrames,
+                mf4Catalog: opened.mf4Catalog,
+                embeddedDbcs: opened.embeddedDbcs,
+                warnings: opened.warnings
+            };
+        },
+        async closeTrace(handle) {
+            const traceId = handles.release('trace', handle);
+            if (traceId === null)
+                return;
+            await sendClose({ op: 'closeTrace', traceId });
+        },
+        async getSignalValues(dbcHandle, traceHandle, messageIdentity, signalName) {
+            assertOpen();
+            const dbcId = handles.payload('dbc', dbcHandle);
+            const traceId = handles.payload('trace', traceHandle);
+            return unpackSeries(await send({ op: 'getSignalValues', dbcId, traceId, messageIdentity, signalName }, []));
+        },
+        async getMf4SignalValues(traceHandle, signalId) {
+            assertOpen();
+            const traceId = handles.payload('trace', traceHandle);
+            return unpackSeries(await send({ op: 'getMf4SignalValues', traceId, signalId }, []));
+        },
+        close() {
+            closePromise ??= (async () => {
+                let cleanupError = null;
+                if (!fatalError) {
+                    try {
+                        // Runs after every previously posted request via the worker's serial queue.
+                        await send({ op: 'closeClient' }, []);
+                    }
+                    catch (error) {
+                        // A fatal crash mid-close still terminates cleanly below.
+                        if (error !== fatalError)
+                            cleanupError = error;
+                    }
+                }
+                handles.releaseAll();
+                await terminate();
+                if (cleanupError)
+                    throw cleanupError;
+            })();
+            return closePromise;
+        }
+    };
+}
+function unpackSeries(payload) {
+    return {
+        timesMs: new Float64Array(payload.buffer, payload.timesByteOffset, payload.timesLength),
+        values: new Float64Array(payload.buffer, payload.valuesByteOffset, payload.valuesLength)
+    };
+}
+/**
+ * Errors keep their diagnostic name and message across the wire. Neither is a stable contract:
+ * treat them as diagnostics, not as values to branch on.
+ */
+function fromWireError(error) {
+    const rebuilt = new Error(error.message);
+    rebuilt.name = error.name;
+    return rebuilt;
+}

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+export type DbcValueDescription = {
+    rawValue: number;
+    label: string;
+};
+/** Bit order of a DBC signal, as declared by `@1` (intel) or `@0` (motorola). */
+export type DbcEndianness = 'intel' | 'motorola';
+export type DbcSignedness = 'signed' | 'unsigned';
+export type DbcValueType = 'integer' | 'float32' | 'float64';
+export type DbcSignal = {
+    name: string;
+    startBit: number;
+    bitLength: number;
+    endianness: DbcEndianness;
+    signedness: DbcSignedness;
+    factor: number;
+    offset: number;
+    minimum: number;
+    maximum: number;
+    unit: string;
+    valueType: DbcValueType;
+    unsupportedMux: boolean;
+    receivers: string[];
+    valueDescriptions: DbcValueDescription[];
+};
+export type DbcMessage = {
+    name: string;
+    dbcId: number;
+    canId: number;
+    isExtended: boolean;
+    isFd: boolean;
+    sizeBytes: number;
+    transmitter: string;
+    signals: DbcSignal[];
+};
+/** Shape pinned by the `serializes_parsed_catalog` test in wasm/src/dbc/catalog.rs. */
+export type ParsedDbc = {
+    messages: DbcMessage[];
+};
+export type TraceMetadata = {
+    measurementStartMs: number | null;
+    validMessageCount: number;
+    skippedLineCount: number;
+    durationNs: number | null;
+};
+export type DecodedSignalSeries = {
+    timesMs: Float64Array;
+    values: Float64Array;
+};
+export type Mf4Signal = {
+    id: number;
+    name: string;
+    unit: string;
+};
+export type Mf4SignalGroup = {
+    name: string;
+    signals: Mf4Signal[];
+};
+export type Mf4SignalCatalog = {
+    groups: Mf4SignalGroup[];
+};
+export type EmbeddedDbc = {
+    name: string;
+    text: string;
+};
+export type TraceType = 'asc' | 'trc' | 'blf' | 'mf4';
+declare const DbcHandleBrand: unique symbol;
+declare const TraceHandleBrand: unique symbol;
+/**
+ * Opaque DBC handle. It has no readable fields: it only identifies one parsed DBC inside the
+ * client that issued it, until that handle or its client is closed. Handles are safe to spread and
+ * to store in deep-reactive stores, and every copy shares one lifetime.
+ */
+export type DbcHandle = {
+    readonly [DbcHandleBrand]: true;
+};
+/** Opaque trace handle, with the same identity and lifetime rules as {@link DbcHandle}. */
+export type TraceHandle = {
+    readonly [TraceHandleBrand]: true;
+};
+/** Everything one `openDbc` call produces. The catalog is plain data and outlives the handle. */
+export type OpenDbcResult = {
+    handle: DbcHandle;
+    catalog: ParsedDbc;
+};
+/** Everything one `openTrace` call produces. Every field except `handle` is plain data. */
+export type OpenTraceResult = {
+    handle: TraceHandle;
+    metadata: TraceMetadata;
+    /** True when the trace carries raw CAN frames that a DBC can decode. */
+    hasRawFrames: boolean;
+    /** Signals the trace itself already carries decoded; MF4 only, otherwise null. */
+    mf4Catalog: Mf4SignalCatalog | null;
+    /** DBC sources embedded in the trace file; MF4 only, otherwise empty. */
+    embeddedDbcs: EmbeddedDbc[];
+    /** Non-fatal parse diagnostics; MF4 only, otherwise empty. */
+    warnings: string[];
+};
+export type DbcMessageIdentity = Pick<DbcMessage, 'canId' | 'isExtended' | 'sizeBytes'>;
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/wasm-bindgen/cantraceviewer.d.ts

@@ -0,0 +1,95 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Parsed DBC model owned by WebAssembly.
+ */
+export class Dbc {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Return the browser catalog projection as JSON.
+     */
+    catalogJson(): string;
+    /**
+     * Decode one selected signal as packed parallel time/value arrays.
+     */
+    decodeSignal(trace: Trace, can_id: number, is_extended: boolean, size_bytes: number, signal_name: string): Float64Array;
+    /**
+     * Parse DBC text and retain the decoded model for subsequent signal work.
+     */
+    static parse(input: string): Dbc;
+}
+
+/**
+ * Parsed trace model owned by WebAssembly.
+ */
+export class Trace {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    decodeMf4Signal(signal_id: number): Float64Array;
+    mf4CatalogJson(): string;
+    mf4EmbeddedDbcsJson(): string;
+    mf4WarningsJson(): string;
+    static parseAsc(input: Uint8Array): Trace;
+    static parseBlf(input: Uint8Array): Trace;
+    static parseMf4(input: Uint8Array): Trace;
+    static parseTrc(input: Uint8Array): Trace;
+    readonly durationNs: number | undefined;
+    readonly hasRawFrames: boolean;
+    readonly measurementStartMs: number | undefined;
+    readonly skippedLineCount: number;
+    readonly validMessageCount: number;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_dbc_free: (a: number, b: number) => void;
+    readonly __wbg_trace_free: (a: number, b: number) => void;
+    readonly wasmdbc_catalogJson: (a: number, b: number) => void;
+    readonly wasmdbc_decodeSignal: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly wasmdbc_parse: (a: number, b: number, c: number) => void;
+    readonly wasmtrace_decodeMf4Signal: (a: number, b: number, c: number) => void;
+    readonly wasmtrace_durationNs: (a: number, b: number) => void;
+    readonly wasmtrace_hasRawFrames: (a: number) => number;
+    readonly wasmtrace_measurementStartMs: (a: number, b: number) => void;
+    readonly wasmtrace_mf4CatalogJson: (a: number, b: number) => void;
+    readonly wasmtrace_mf4EmbeddedDbcsJson: (a: number, b: number) => void;
+    readonly wasmtrace_mf4WarningsJson: (a: number, b: number) => void;
+    readonly wasmtrace_parseAsc: (a: number, b: number, c: number) => void;
+    readonly wasmtrace_parseBlf: (a: number, b: number, c: number) => void;
+    readonly wasmtrace_parseMf4: (a: number, b: number, c: number) => void;
+    readonly wasmtrace_parseTrc: (a: number, b: number, c: number) => void;
+    readonly wasmtrace_skippedLineCount: (a: number) => number;
+    readonly wasmtrace_validMessageCount: (a: number) => number;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export2: (a: number, b: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number, d: number) => number;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;