webserial-core/dist/queue/CommandQueue.d.ts

A strongly-typed, event-driven, abstract TypeScript library for the Web Serial API with custom parsers, command queue, handshake validation, and auto-reconnect.

/**
 * @file CommandQueue.ts
 *
 * FIFO command queue for serial communication. Commands are sent one at a
 * time; the next command is held until the caller invokes `advance()` (e.g.
 * on receiving a response) or the per-command timeout elapses.
 *
 * Setting `commandTimeout` to `0` disables the timeout and sends commands
 * back-to-back as fast as the port allows.
 */
/** Options for constructing a {@link CommandQueue}. */
export interface CommandQueueOptions {
    /**
     * Maximum time in milliseconds to wait for a response before advancing.
     * Set to `0` to disable per-command timeouts.
     */
    commandTimeout: number;
    /**
     * Called when the queue is ready to transmit the next command.
     * Must write the bytes to the physical port.
     *
     * @param command - The raw bytes to send.
     */
    onSend: (command: Uint8Array) => Promise<void>;
    /**
     * Called when a command's timeout elapses before `advance()` is invoked.
     *
     * @param command - The command that timed out.
     */
    onTimeout: (command: Uint8Array) => void;
}
/**
 * FIFO queue that serializes serial commands, optionally waiting for a
 * response (or timeout) between each transmission.
 */
export declare class CommandQueue {
    private queue;
    /** `true` while the queue is waiting for a response to the current command. */
    isProcessing: boolean;
    private isPaused;
    private timeoutId;
    private readonly commandTimeout;
    private readonly onSend;
    private readonly onTimeout;
    /**
     * @param options - Queue configuration. See {@link CommandQueueOptions}.
     */
    constructor(options: CommandQueueOptions);
    /**
     * The number of commands currently waiting in the queue.
     */
    get queueSize(): number;
    /**
     * Adds a command to the end of the queue and triggers processing
     * if the queue is running and idle.
     *
     * @param command - Raw bytes to enqueue.
     */
    enqueue(command: Uint8Array): void;
    /**
     * Signals that a response has been received (or processing is otherwise
     * complete) and advances to the next command.
     *
     * Call this after each expected response to keep the queue moving.
     */
    advance(): void;
    /**
     * Pauses the queue. In-flight commands are not cancelled, but no new
     * command will be dequeued until `resume()` is called.
     */
    pause(): void;
    /**
     * Resumes a paused queue and immediately processes the next command
     * if one is available.
     */
    resume(): void;
    /**
     * Discards all pending commands and cancels any active timeout.
     * Does not affect the paused/running state.
     */
    clear(): void;
    /**
     * Returns a shallow copy of the current queue contents, leaving the
     * queue unchanged.
     *
     * @returns A snapshot array of pending commands.
     */
    snapshot(): Uint8Array[];
    /**
     * Prepends a previously saved snapshot to the current queue.
     * Useful for restoring commands after a failed handshake.
     *
     * @param saved - Commands to prepend.
     */
    restore(saved: Uint8Array[]): void;
    private tryProcessNext;
    private clearCommandTimeout;
}