@v5x/serial 0.5.4 → 0.5.6

package/{dts/VexDevice.d.ts → dist/VexDeviceState.d.ts}

@@ -1,25 +1,48 @@
-/// <reference types="dom-serial" />
-import { type MatchMode, SerialDeviceType, type ISmartDeviceInfo, SmartDeviceType, FileVendor, type IProgramInfo, type IFileHandle, FileDownloadTarget, type IFileBasicInfo, type IFileWriteRequest, RadioChannelType } from "./Vex";
-import { V5SerialConnection } from "./VexConnection";
-import { VexEventTarget } from "./VexEvent";
-import { VexFirmwareVersion } from "./VexFirmwareVersion";
-import { type ProgramIniConfig } from "./VexIniConfig";
-export declare function downloadFileFromInternet(link: string): Promise<ArrayBuffer>;
-export declare function sleepUntilAsync(f: () => Promise<boolean>, timeout: number, interval?: number): Promise<boolean>;
-export declare function sleepUntil(f: () => boolean, timeout: number, interval?: number): Promise<boolean>;
-export declare function sleep(ms: number): Promise<unknown>;
-export declare abstract class VexSerialDevice extends VexEventTarget {
+import { type MatchMode, SerialDeviceType, type SlotNumber, type ISmartDeviceInfo, SmartDeviceType, FileVendor, type IProgramInfo, type IFileHandle, type IFileBasicInfo, type IFileWriteRequest, FileDownloadTarget, RadioChannelType } from "./Vex.js";
+import { type V5SerialConnection } from "./VexConnection.js";
+import { VexEventTarget } from "./VexEvent.js";
+import { VexFirmwareVersion } from "./VexFirmwareVersion.js";
+import { type ProgramIniConfig } from "./VexIniConfig.js";
+import { VexSerialError } from "./VexError.js";
+import { ResultAsync } from "neverthrow";
+import type { V5SerialDevice } from "./VexDevice.js";
+export interface VexSerialDeviceEvents {
+    disconnected: undefined;
+    error: unknown;
+}
+export declare abstract class VexSerialDevice extends VexEventTarget<VexSerialDeviceEvents> {
     connection: V5SerialConnection | undefined;
     defaultSerial: Serial;
     get isConnected(): boolean;
     get deviceType(): SerialDeviceType | undefined;
     constructor(defaultSerial: Serial);
-    abstract connect(conn?: V5SerialConnection): Promise<boolean>;
-    abstract disconnect(): void;
+    abstract connect(conn?: V5SerialConnection): ResultAsync<void, VexSerialError>;
+    abstract disconnect(): Promise<void>;
 }
-declare class V5SerialDeviceState {
+export declare class V5SerialDeviceState {
     _instance: V5SerialDevice;
-    _isFileTransferring: boolean;
+    /**
+     * Counter used only to pause automatic refresh while a file transfer
+     * is in flight. This is not a mutex: serialization of transfer
+     * operations lives on the {@link V5SerialConnection} transaction queue.
+     */
+    private refreshPauseDepth;
+    get isRefreshPaused(): boolean;
+    /**
+     * @deprecated Use {@link isRefreshPaused}. This flag only means that
+     * automatic refresh is paused, not that transfer operations are locked.
+     */
+    get isFileTransferring(): boolean;
+    /**
+     * Increment the refresh-pause depth, run the operation, and decrement
+     * the depth again. The actual transfer mutex lives on the connection.
+     */
+    withRefreshPaused<T>(operation: () => PromiseLike<T>): Promise<T>;
+    /**
+     * @deprecated Use {@link withRefreshPaused}. This only pauses automatic
+     * refresh and does not lock file transfers.
+     */
+    withFileTransfer<T>(operation: () => PromiseLike<T>): Promise<T>;
     brain: {
         activeProgram: number;
         battery: {
@@ -41,15 +64,11 @@ declare class V5SerialDeviceState {
         systemVersion: VexFirmwareVersion;
         uniqueId: number;
     };
-    controllers: ({
+    controllers: {
         battery: number;
         isAvailable: boolean;
         isCharging: boolean;
-    } | {
-        battery: number;
-        isAvailable: boolean;
-        isCharging?: undefined;
-    })[];
+    }[];
     devices: Array<ISmartDeviceInfo | undefined>;
     isFieldControllerConnected: boolean;
     matchMode: MatchMode;
@@ -67,10 +86,37 @@ declare class V5SerialDeviceState {
 }
 export declare class V5Brain {
     private readonly state;
+    private readonly batteryFacade;
+    private readonly buttonFacade;
+    private readonly settingsFacade;
     constructor(state: V5SerialDeviceState);
     get isRunningProgram(): boolean;
     get activeProgram(): number;
+    /**
+     * @deprecated Setting this property dispatches a fire-and-forget
+     * request that cannot be awaited. Use {@link setActiveProgram}
+     * instead, which returns a {@link ResultAsync} that resolves to an
+     * error result when the device refuses or is disconnected.
+     */
     set activeProgram(value: number);
+    /**
+     * Load a program slot on the brain, or stop the currently running
+     * program when called with `0`. Resolves to an error result when the
+     * device refuses, the request times out, or no connection is open.
+     */
+    setActiveProgram(value: SlotNumber | 0): ResultAsync<void, VexSerialError>;
+    /**
+     * Request that the brain start running the program in the given slot.
+     * Resolves to an error result when the device refuses, the request
+     * times out, or no connection is open.
+     */
+    runProgram(slot: SlotNumber | string): ResultAsync<void, VexSerialError>;
+    /**
+     * Request that the brain stop the currently running program. Resolves
+     * to an error result when the device refuses, the request times out,
+     * or no connection is open.
+     */
+    stopProgram(): ResultAsync<void, VexSerialError>;
     get battery(): V5Battery;
     get button(): V5BrainButton;
     get cpu0Version(): VexFirmwareVersion;
@@ -79,23 +125,23 @@ export declare class V5Brain {
     get settings(): V5BrainSettings;
     get systemVersion(): VexFirmwareVersion;
     get uniqueId(): number;
-    getValue(key: string): Promise<string | undefined>;
-    setValue(key: string, value: string): Promise<boolean>;
-    listFiles(vendor?: FileVendor): Promise<IFileHandle[] | undefined>;
-    listProgram(): Promise<IProgramInfo[] | undefined>;
-    readFile(request: IFileBasicInfo | string, downloadTarget?: FileDownloadTarget, progressCallback?: (current: number, total: number) => void): Promise<Uint8Array | undefined>;
-    removeFile(request: IFileBasicInfo | string): Promise<boolean | undefined>;
-    removeAllFiles(): Promise<boolean | undefined>;
-    uploadFirmware(publicUrl?: string, usingVersion?: string, progressCallback?: (state: string, current: number, total: number) => void): Promise<boolean | undefined>;
-    uploadProgram(iniConfig: ProgramIniConfig, binFileBuf: Uint8Array, coldFileBuf: Uint8Array | undefined, progressCallback: (state: string, current: number, total: number) => void): Promise<boolean | undefined>;
-    writeFile(request: IFileWriteRequest, progressCallback?: (current: number, total: number) => void): Promise<boolean | undefined>;
+    getValue(key: string): ResultAsync<string | undefined, VexSerialError>;
+    setValue(key: string, value: string): ResultAsync<void, VexSerialError>;
+    listFiles(vendor?: FileVendor): ResultAsync<IFileHandle[], VexSerialError>;
+    listProgram(): ResultAsync<IProgramInfo[], VexSerialError>;
+    readFile(request: IFileBasicInfo | string, downloadTarget?: FileDownloadTarget, progressCallback?: (current: number, total: number) => void): ResultAsync<Uint8Array, VexSerialError>;
+    removeFile(request: IFileBasicInfo | string): ResultAsync<void, VexSerialError>;
+    removeAllFiles(): ResultAsync<void, VexSerialError>;
+    uploadFirmware(publicUrl?: string, usingVersion?: string, progressCallback?: (state: string, current: number, total: number) => void): ResultAsync<boolean, VexSerialError>;
+    uploadProgram(iniConfig: ProgramIniConfig, binFileBuf: Uint8Array, coldFileBuf: Uint8Array | undefined, progressCallback: (state: string, current: number, total: number) => void): ResultAsync<boolean, VexSerialError>;
+    writeFile(request: IFileWriteRequest, progressCallback?: (current: number, total: number) => void): ResultAsync<boolean, VexSerialError>;
     /**
      *
      * @param progressCallback Informs the progress of the download.
      * @returns array of bytes where each pixel is represented by 3 consecutive bytes (rgb).
      * This array's length is 272 width * 480 height * 3 channels = 391680 bytes.
      */
-    captureScreen(progressCallback?: (current: number, total: number) => void): Promise<Uint8Array | undefined>;
+    captureScreen(progressCallback?: (current: number, total: number) => void): ResultAsync<Uint8Array, VexSerialError>;
 }
 export declare class V5Battery {
     private readonly state;
@@ -144,34 +190,5 @@ export declare class V5Radio {
     get isVexNet(): boolean;
     get isRadioData(): boolean;
     get latency(): number;
-    changeChannel(channel: RadioChannelType): Promise<boolean>;
-}
-export declare class V5SerialDevice extends VexSerialDevice {
-    autoReconnect: boolean;
-    autoRefresh: boolean;
-    pauseRefreshOnFileTransfer: boolean;
-    protected _isReconnecting: boolean;
-    private _refreshInterval;
-    state: V5SerialDeviceState;
-    constructor(defaultSerial: Serial);
-    get isV5Controller(): boolean;
-    get brain(): V5Brain;
-    get controllers(): [V5Controller, V5Controller];
-    get devices(): V5SmartDevice[];
-    get isFieldControllerConnected(): boolean;
-    get matchMode(): MatchMode;
-    set matchMode(value: MatchMode);
-    get radio(): V5Radio;
-    mockTouch(x: number, y: number, press: boolean): Promise<boolean>;
-    connect(conn?: V5SerialConnection): Promise<boolean>;
-    disconnect(): Promise<void>;
-    dispose(): Promise<void>;
-    /**
-     * @param timeout defaults to 0. If timeout is 0, then it will attempt to reconnect forever
-     * @returns
-     */
-    reconnect(timeout?: number): Promise<boolean>;
-    private doAfterConnect;
-    refresh(): Promise<boolean>;
+    changeChannel(channel: RadioChannelType): ResultAsync<void, VexSerialError>;
 }
-export {};

package/dist/VexError.d.ts

@@ -0,0 +1,50 @@
+import { type AckType } from "./Vex.js";
+/**
+ * Typed error hierarchy for the serial protocol package.
+ *
+ * Every public async API that can fail returns a {@link Result} (or
+ * {@link ResultAsync}) whose error channel is a {@link VexSerialError}.
+ * Each error carries a stable {@link VexSerialError.kind} discriminator
+ * so callers can branch on the failure category without parsing messages.
+ */
+export type VexSerialErrorKind = "not-connected" | "invalid-argument" | "protocol" | "transfer" | "download" | "firmware" | "io";
+/** Base class for every failure surfaced by the serial package. */
+export declare class VexSerialError extends Error {
+    readonly kind: VexSerialErrorKind;
+    readonly ackType: AckType | undefined;
+    constructor(kind: VexSerialErrorKind, message: string);
+}
+/** No connection is currently open to a device. */
+export declare class VexNotConnectedError extends VexSerialError {
+    constructor(message?: string);
+}
+/** A caller supplied an invalid argument value. */
+export declare class VexInvalidArgumentError extends VexSerialError {
+    constructor(message: string);
+}
+/** The device refused, timed out, or replied unexpectedly to a command. */
+export declare class VexProtocolError extends VexSerialError {
+    readonly ackType: AckType | undefined;
+    constructor(message: string, ackType?: AckType);
+}
+/** A file-transfer handshake, read, write, or exit failed. */
+export declare class VexTransferError extends VexSerialError {
+    constructor(message: string);
+}
+/** A remote resource download (catalog/VEXos) failed. */
+export declare class VexDownloadError extends VexSerialError {
+    constructor(message: string);
+}
+/** A firmware archive was malformed, oversized, or incomplete. */
+export declare class VexFirmwareError extends VexSerialError {
+    constructor(message: string);
+}
+/** An underlying transport (serial port, stream) error. */
+export declare class VexIoError extends VexSerialError {
+    constructor(message: string);
+}
+/**
+ * Coerce an arbitrary thrown value into a {@link VexSerialError} so it
+ * can be returned through the {@link Result} error channel.
+ */
+export declare function toVexSerialError(error: unknown, fallback?: VexSerialErrorKind): VexSerialError;

package/dist/VexEvent.d.ts

@@ -1,16 +1,21 @@
-export declare class VexEventEmitter {
-    handlerMap: Map<string | symbol, Array<(...args: unknown[]) => void>>;
+type EventName = string | symbol;
+type EventMapKey<TEvents> = Extract<keyof TEvents, EventName>;
+type EventListener<TValue> = (data: TValue) => void;
+export declare class VexEventEmitter<TEvents extends object = Record<EventName, unknown>> {
+    handlerMap: Map<EventName, Array<EventListener<unknown>>>;
     constructor();
-    on(eventName: string | symbol, listener: (...args: unknown[]) => void): void;
-    remove(eventName: string | symbol, listener: (...args: unknown[]) => void): void;
-    emit(eventName: string | symbol, data: unknown): void;
+    on<K extends EventMapKey<TEvents>>(eventName: K, listener: EventListener<TEvents[K]>): void;
+    remove<K extends EventMapKey<TEvents>>(eventName: K, listener: EventListener<TEvents[K]>): void;
+    emit<K extends EventMapKey<TEvents>>(eventName: K, data: TEvents[K]): void;
     clearListeners(): void;
 }
-export declare class VexEventTarget {
-    emitter: VexEventEmitter;
+export declare class VexEventTarget<TEvents extends object = Record<EventName, unknown>> {
+    emitter: VexEventEmitter<TEvents>;
     constructor();
-    emit(eventName: string | symbol, data: unknown): void;
-    on(eventName: string | symbol, listener: (...args: unknown[]) => void): void;
-    remove(eventName: string | symbol, listener: (...args: unknown[]) => void): void;
+    emit<K extends EventMapKey<TEvents>>(eventName: K, data: TEvents[K]): void;
+    on<K extends EventMapKey<TEvents>>(eventName: K, listener: EventListener<TEvents[K]>): void;
+    remove<K extends EventMapKey<TEvents>>(eventName: K, listener: EventListener<TEvents[K]>): void;
     clearListeners(): void;
+    private normalizeEventName;
 }
+export {};

package/dist/VexFirmware.d.ts

@@ -0,0 +1,47 @@
+import type { V5SerialDeviceState } from "./VexDeviceState.js";
+import { VexSerialError } from "./VexError.js";
+import { ResultAsync } from "neverthrow";
+export interface DownloadFileFromInternetOptions {
+    /** Maximum total bytes to read from the response body. */
+    maxBytes?: number;
+    /** Request timeout in milliseconds. */
+    timeout?: number;
+}
+/**
+ * Download a remote resource while enforcing a maximum body size. The
+ * declared `Content-Length` header is validated up front, and the body
+ * is streamed so an oversized payload is rejected before it is fully
+ * read into memory. Failures are returned as a {@link VexDownloadError}
+ * (or {@link VexInvalidArgumentError} for bad options) instead of
+ * thrown.
+ */
+export declare function downloadFileFromInternet(link: string, options?: DownloadFileFromInternetOptions): ResultAsync<ArrayBuffer, VexSerialError>;
+/**
+ * Poll an async predicate until it returns true or the timeout elapses.
+ * Argument errors are returned as {@link VexInvalidArgumentError}; a
+ * throwing predicate surfaces its error through the {@link Result}
+ * error channel.
+ */
+export declare function sleepUntilAsync(f: () => Promise<boolean>, timeout: number, interval?: number): ResultAsync<boolean, VexSerialError>;
+/**
+ * Poll a synchronous predicate until it returns true or the timeout
+ * elapses. The implementation uses a loop with `sleep` rather than
+ * `setInterval` so the timer is cleared as soon as the predicate
+ * resolves, and so predicate exceptions are surfaced without leaving a
+ * pending interval behind.
+ */
+export declare function sleepUntil(f: () => boolean, timeout: number, interval?: number): ResultAsync<boolean, VexSerialError>;
+/**
+ * Resolve after `ms` milliseconds. Returns a {@link VexInvalidArgumentError}
+ * when `ms` is negative.
+ */
+export declare function sleep(ms: number): ResultAsync<void, VexSerialError>;
+type FirmwareProgressCallback = (state: string, current: number, total: number) => void;
+/**
+ * Upload a VEXos firmware archive to a connected brain. Network and
+ * archive validation failures are returned as {@link VexSerialError}
+ * values rather than thrown; a device that refuses a step or a missing
+ * connection surfaces as {@link VexFirmwareError} / {@link VexNotConnectedError}.
+ */
+export declare function uploadFirmware(state: V5SerialDeviceState, publicUrl?: string, usingVersion?: string, progressCallback?: FirmwareProgressCallback): ResultAsync<boolean, VexSerialError>;
+export {};

package/dist/VexFirmwareVersion.d.ts

@@ -1,55 +1,16 @@
-/**
- * This is a class to make it easier to handle passing the VEXos version
- * information around in the application. This provides ways to get any
- * form of the string representation and quickly compare versions.
- */
 export declare class VexFirmwareVersion {
-    major: number;
-    minor: number;
-    build: number;
-    beta: number;
+    readonly major: number;
+    readonly minor: number;
+    readonly build: number;
+    readonly beta: number;
     constructor(major: number, minor: number, build: number, beta: number);
-    /**
-     * Take a a string of MAJOR.MINOR.BUILD.bBETA and converts it to a
-     * VexFirmwareVersion instance
-     * @param version the string to process
-     * @returns a VexFirmwareVersion representing the provided string
-     */
     static fromString(version: string): VexFirmwareVersion;
-    /**
-     * Take a a Uint8Array and converts it to a VexFirmwareVersion instance
-     * @param data the array to process
-     * @param offset the offset to start at
-     * @returns a VexFirmwareVersion representing the provided string
-     */
     static fromUint8Array(data: Uint8Array, offset?: number, reverse?: boolean): VexFirmwareVersion;
     static allZero(): VexFirmwareVersion;
-    /**
-     * Take a a string of MAJOR_MINOR_BUILD_BETA and converts it to a
-     * VexFirmwareVersion instance
-     * @param version the string to process
-     * @returns a VexFirmwareVersion representing the provided string
-     */
     static fromCatalogString(version: string): VexFirmwareVersion;
     isBeta(): boolean;
-    /**
-     * returns version as Uint Array
-     */
     toUint8Array(reverse?: boolean): Uint8Array;
-    /**
-     * returns version as major.minor.build
-     */
     toUserString(): string;
-    /**
-     * returns version as ${major}.${minor}.{build}.b${beta}
-     */
     toInternalString(): string;
-    /**
-     * compares this version to the provided version.
-     * * if this < b: negative
-     * * if this = b: 0
-     * * if this > b: positive
-     * @param that the version to compare again
-     */
     compare(that: VexFirmwareVersion): number;
 }

package/dist/VexIniConfig.d.ts

@@ -1,4 +1,4 @@
-import { type ZerobaseSlotNumber } from "./Vex";
+import { type ZerobaseSlotNumber } from "./Vex.js";
 export declare class ProgramIniConfig {
     baseName: string;
     autorun: boolean;
@@ -20,7 +20,6 @@ export declare class ProgramIniConfig {
     config: Record<number, string>;
     controller1: Record<string, string>;
     controller2: Record<string, string>;
-    constructor();
     setProgramDate(date: Date): void;
     createIni(): string;
     dec2(value: number): string;