webserial-core 1.2.0 → 2.0.0-dev.1

package/{LICENSE → LICENSE.md}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 danidoble
+Copyright (c) 2026 danidoble
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,30 +1,43 @@
-# WebSerial Core
+# webserial-core
 
-An easy way to connect to a serial port from a web page.
-
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/danidoble/webserial-core)
 [![npm version](https://badge.fury.io/js/webserial-core.svg)](https://www.npmjs.com/package/webserial-core)
+[![npm downloads](https://img.shields.io/npm/dm/webserial-core)](https://www.npmjs.com/package/webserial-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue)
+![bundle size](https://img.shields.io/bundlephobia/minzip/webserial-core)
+![GitHub release](https://img.shields.io/github/v/release/danidoble/webserial-core)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/danidoble/webserial-core)
+
+
+A strongly-typed, event-driven, abstract TypeScript library for serial
+communication on the web. Supports **Web Serial**, **WebUSB**, **Web
+Bluetooth**, and **WebSocket** transports through a unified API.
 
-> [!NOTE]
-> Since version 1.0.7 default response is an instance of Uint8Array.
-> To change the response put this code inside your constructor to change the default response.
-> `this.getResponseAsArrayBuffer()`
-> `this.getResponseAsArrayHex()`
-> `this.getResponseAsUint8Array()`
-> `this.getResponseAsString()`
-> Only choose one of them.
+---
+
+> **⚠️ Breaking Changes — v2**
+>
+> Version 2 is a complete rewrite. Tthe public API is completally changed,
+> please if you has an implementation of this library is better read docs as like a
+> new integration See the [Migration Guide](docs/guide/migration-v1-v2.md) before upgrading.
+
+---
 
 ## Features
 
-- 🔌 Easy serial port connection from web browsers
-- 🎯 TypeScript support with full type definitions
-- 🧪 Comprehensive test suite with Vitest
-- 📦 Multiple module formats (ESM, UMD)
-- 🔍 Source maps for debugging
-- 🌐 Socket.io integration for remote connections
-- ⚡ Event-driven architecture
-- 🛡️ Custom error handling with `SerialError`
+- **Provider-agnostic** — swap between Web Serial, WebUSB, Web Bluetooth, or
+  WebSocket transport by injecting a single provider.
+- **Strictly typed** — full TypeScript generics, no implicit `any`, compatible
+  with `strict: true`.
+- **Typed events** — `connecting`, `connected`, `disconnected`, `data`,
+  `sent`, `error`, `timeout`, `reconnecting`, and more — all fully typed.
+- **Built-in parsers** — `delimiter`, `fixedLength`, `raw`. Implement
+  `SerialParser<T>` for any custom binary or text protocol.
+- **Command queue** — FIFO write queue with optional per-command timeouts.
+- **Auto-reconnect** — configurable reconnect loop with back-off.
+- **WebUSB polyfill** — full WebUSB serial polyfill (CDC ACM, CP210x, CH340).
+- **BLE NUS adapter** — Nordic UART Service over Web Bluetooth GATT.
+- **WebSocket bridge** — relay serial I/O through a Node.js bridge server.
 
 ## Installation
 
@@ -32,301 +45,143 @@ An easy way to connect to a serial port from a web page.
 npm install webserial-core
 ```
 
-## Usage
+## Quick start
 
-> [!NOTE]
-> If you are using Linux, you need to add your user to the `dialout` group to access the serial port.
-> ```bash
-> sudo usermod -a -G dialout $USER
-> ```
-> After that, you need to log out and log in again to apply the changes.
+```ts
+import { AbstractSerialDevice, delimiter } from "webserial-core";
 
-You need to create a new class to configure your device functions. In this example, we are going to create a class to
-connect to an Arduino device.
+class MyDevice extends AbstractSerialDevice<string> {
+  constructor() {
+    super({
+      baudRate: 9600,
+      parser: delimiter("\n"),
+      autoReconnect: true,
+    });
+  }
 
-The first step is having the Arduino code ready. In this case, we are going to use the following code.
+  protected async handshake(): Promise<boolean> {
+    return true; // return false to reject the port
+  }
+}
 
-```cpp
-// serial.ino
+const device = new MyDevice();
 
-void setup() {
-  Serial.begin(9600);
-}
+device.on("serial:connected", () => console.log("Connected!"));
+device.on("serial:data", (line) => console.log("←", line));
+device.on("serial:disconnected", () => console.log("Disconnected."));
+device.on("serial:error", (err) => console.error(err.message));
 
-void loop() {
-  if (Serial.available() > 0) { // Check if data to read is available
-    String comando = Serial.readStringUntil('\n'); // read the data until a new line is found
-
-    if(comando.startsWith("CONNECT")){
-      Serial.println("connected");
-    } else if (comando.startsWith("CREDITS")) {
-      Serial.println("created by danidoble");
-    } else if (comando.startsWith("HI")) {
-      Serial.println("hello there");
-    } else {
-      Serial.println("ara ara, what are you doing?");
-    }
-  }
-}
+await device.connect(); // opens the browser port picker
+await device.send("PING\n"); // enqueues a write
+await device.disconnect();
 ```
 
-Create a new class to connect to the device.
-
-```javascript
-// arduino.js
-import { Core } from 'webserial-core';
-
-export class Arduino extends Core {
-  constructor(
-    {
-      filters = null,
-      config_port = {
-        baudRate: 9600,
-        dataBits: 8,
-        stopBits: 1,
-        parity: "none",
-        bufferSize: 32768,
-        flowControl: "none",
-      },
-      no_device = 1,
-    } = {
-      filters: null,
-      config_port: {
-        baudRate: 9600,
-        dataBits: 8,
-        stopBits: 1,
-        parity: "none",
-        bufferSize: 32768,
-        flowControl: "none",
-      },
-      no_device: 1,
-    }
-  ) {
-    super({ filters, config_port, no_device });
-    this.__internal__.device.type = "arduino";
-    Devices.registerType(this.__internal__.device.type);
-    if (Devices.getByNumber(this.typeDevice, no_device)) {
-      throw new Error(`Device ${this.typeDevice} ${no_device} already exists`);
-    }
-    this.__internal__.time.response_connection = 2e3;
-    this.__internal__.time.response_general = 2e3;
-    this.__internal__.serial.delay_first_connection = 1_000;
-    this.#registerAvailableListenersArduino();
-    Devices.add(this);
-    this.getResponseAsString();
-  }
+## Transport adapters
 
-  #registerAvailableListenersArduino() {
-    /*const _ = [
-    'my_own_event_dispatched',
-    'my_other_own_event_dispatched',
-    ];
-    for (const event of _) {
-        this.serialRegisterAvailableListener(event)
-    }
-    */
-  }
+All four adapters expose the same `SerialProvider` interface. Inject your
+chosen adapter once before constructing any device:
 
-  serialMessage(codex) {
-    const message = {
-      code: [],
-      name: "",
-      description: "",
-      request: "",
-      no_code: 0,
-    };
-
-    message.code = codex;
-
-    switch (codex) {
-      case "connected":
-        message.name = "connected";
-        message.description = "Connection established";
-        message.request = "connect";
-        message.no_code = 100;
-        break;
-      case "created by danidoble":
-        message.name = "thanks";
-        message.description = "thanks for using this software";
-        message.request = "credits";
-        message.no_code = 101;
-        break;
-      case "hello there":
-        message.name = "hello there";
-        message.description = "hi human";
-        message.request = "hi";
-        message.no_code = 102;
-        break;
-      case "ara ara":
-        message.name = "ara ara";
-        message.description = "troll";
-        message.request = "ara ara";
-        message.no_code = 404;
-        break;
-      default:
-        message.name = "unknown";
-        message.description = "Unknown command";
-        message.request = "unknown";
-        message.no_code = 400;
-        break;
-    }
-
-    this.dispatch("serial:message", message);
-  }
+```ts
+import { AbstractSerialDevice, WebUsbProvider } from "webserial-core";
+import { createBluetoothProvider } from "webserial-core";
+import { createWebSocketProvider } from "webserial-core";
 
-  serialSetConnectionConstant() {
-    return this.add0x(this.parseStringToBytes("CONNECT"));
-  }
+// WebUSB polyfill (Android Chrome, or desktop for testing)
+AbstractSerialDevice.setProvider(new WebUsbProvider());
 
-  async sayCredits() {
-    const arr = this.parseStringToBytes("CREDITS");
-    await this.appendToQueue(arr, "credits");
-  }
+// Web Bluetooth (Nordic UART Service over BLE GATT)
+AbstractSerialDevice.setProvider(createBluetoothProvider());
 
-  async sayHi() {
-    const arr = this.parseStringToBytes("HI");
-    await this.appendToQueue(arr, "hi");
-  }
+// WebSocket bridge (requires Node.js server — see demos/websocket/)
+AbstractSerialDevice.setProvider(
+  createWebSocketProvider("ws://localhost:8080"),
+);
+```
 
-  async sayAra() {
-    const arr = this.parseStringToBytes("OTHER");
-    await this.appendToQueue(arr, "ara");
-  }
+## Parsers
 
-  async sendCustomCode({ code = "" } = { code: "" }) {
-    if (typeof code !== "string") throw new Error("Invalid string");
-    const arr = this.parseStringToBytes(code);
-    await this.appendToQueue(arr, "custom");
-  }
-}
+```ts
+import { delimiter, fixedLength, raw } from "webserial-core";
+
+// Newline-delimited strings (Arduino Serial.println)
+parser: delimiter("\n");
+
+// 16-byte binary packets
+parser: fixedLength(16);
+
+// Raw Uint8Array chunks
+parser: raw();
 ```
 
-Then you can use the class to connect to your device.
-
-```javascript 
-// serialConnection.js
-
-import { Arduino } from './arduino.js';
-
-const arduino = new Arduino();
-
-arduino.on('serial:message', (message) => {
-  console.log(message);
-});
-
-arduino.on('serial:timeout', (data) => {
-  console.log('serial:timeout', data.detail);
-});
-
-// if you need to debug the data sent
-// arduino.on('serial:sent', data => {
-//     console.log('serial:sent',data.detail);
-// });
-
-arduino.on('serial:error', (event) => {
-  document.getElementById('log').innerText += event.detail.message + '\n\n';
-});
-
-// eslint-disable-next-line no-unused-vars
-arduino.on('serial:disconnected', (event) => {
-  document.getElementById('log').innerText += 'Disconnected\n\n';
-
-  document.getElementById('disconnected').classList.remove('hidden');
-  document.getElementById('connect').classList.remove('hidden');
-  document.getElementById("disconnect")?.classList.add("hidden");
-});
-
-// eslint-disable-next-line no-unused-vars
-arduino.on('serial:connecting', (event) => {
-  document.getElementById('log').innerText += 'Connecting\n\n';
-});
-
-// eslint-disable-next-line no-unused-vars
-arduino.on('serial:connected', (event) => {
-  document.getElementById('log').innerText += 'Connected\n\n';
-
-  document.getElementById('disconnected').classList.add('hidden');
-  document.getElementById('need-permission').classList.add('hidden');
-  document.getElementById('connect').classList.add('hidden');
-  document.getElementById("disconnect")?.classList.remove("hidden");
-});
-
-// eslint-disable-next-line no-unused-vars
-arduino.on('serial:need-permission', (event) => {
-  document.getElementById('disconnected').classList.remove('hidden');
-  document.getElementById('need-permission').classList.remove('hidden');
-  document.getElementById('connect').classList.remove('hidden');
-  document.getElementById("disconnect")?.classList.add("hidden");
-});
-
-// eslint-disable-next-line no-unused-vars
-arduino.on('serial:soft-reload', (event) => {
-  // reset your variables
-});
-
-// eslint-disable-next-line no-unused-vars
-arduino.on('serial:unsupported', (event) => {
-  document.getElementById('unsupported').classList.remove('hidden');
-});
-
-function tryConnect() {
-  arduino
-    .connect()
-    .then(() => {})
-    .catch(console.error);
-}
+## Events
 
-document.addEventListener('DOMContentLoaded', () => {
-  tryConnect();
-  document.getElementById('connect')?.addEventListener('click', tryConnect);
-  document.getElementById("disconnect")?.addEventListener("click", async () => {
-    await board.disconnect().catch(console.error);
-    document.getElementById('log')?.innerText += 'Disconnected by user\n\n';
-  });
-});
+| Event                    | Payload      | Description                                   |
+| ------------------------ | ------------ | --------------------------------------------- |
+| `serial:connecting`      | —            | `connect()` called, port picker about to open |
+| `serial:connected`       | —            | Port open, handshake passed                   |
+| `serial:disconnected`    | —            | Port closed                                   |
+| `serial:data`            | `T`          | Parser emitted a complete message             |
+| `serial:sent`            | `Uint8Array` | Bytes written to the port                     |
+| `serial:error`           | `Error`      | Unrecoverable error                           |
+| `serial:need-permission` | —            | User denied access                            |
+| `serial:timeout`         | `Uint8Array` | Command timed out                             |
+| `serial:queue-empty`     | —            | Write queue is now idle                       |
+| `serial:reconnecting`    | —            | Auto-reconnect attempt starting               |
 
+## Project structure
+
+```
+src/
+  core/           AbstractSerialDevice, SerialEventEmitter, SerialRegistry
+  adapters/
+    web-usb/      WebUsbProvider (WebUSB polyfill)
+    web-bluetooth/ createBluetoothProvider (BLE NUS)
+    websocket/    createWebSocketProvider (Node.js bridge)
+  parsers/        delimiter, fixedLength, raw
+  queue/          CommandQueue
+  errors/         SerialPortConflictError, SerialPermissionError, …
+  types/          SerialDeviceOptions, SerialProvider, SerialParser, …
+demos/
+  web-serial/     Native Web Serial demo
+  web-usb/        WebUSB polyfill demo
+  web-bluetooth/  Web Bluetooth BLE demo
+  websocket/      WebSocket bridge demo + Node.js server
+docs/             VitePress documentation site
 ```
 
-But wait still need to create the HTML file.
+## Building
 
-```html
-<!doctype html>
-<html lang="en">
+```bash
+npm run build
+```
 
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Webserial</title>
-    <script src="./serialConnection.js" type="module"></script>
-</head>
+Output in `dist/`:
 
-<body class="bg-neutral-950 text-white p-4 w-full">
+| File                     | Format     | Use case                  |
+| ------------------------ | ---------- | ------------------------- |
+| `webserial-core.mjs`     | ESM        | Bundlers, modern browsers |
+| `webserial-core.cjs`     | CJS        | Node.js, legacy bundlers  |
+| `webserial-core.umd.cjs` | UMD        | `<script>` tag, CDN       |
+| `index.d.ts`             | TypeScript | Type declarations         |
 
-    <div class="webserial w-full max-w-xl mx-auto grid grid-cols-1 gap-y-4">
-        <div class="my-6"></div>
-        <button id="connect" class="hidden px-4 py-3 bg-gray-800 rounded-lg">Connect to serial</button>
-        <button id="disconnect" class="hidden px-4 py-3 bg-rose-800 rounded-lg">Disconnect device</button>
+## Documentation
 
-        <div id="need-permission" class="hidden p-4 bg-rose-900 rounded-lg">
-            Woooah! It seems that you need to give permission to access the serial port.
-            Please, click the button 'Connect to serial' to try again.
-        </div>
+```bash
+npm run docs:dev   # live VitePress server
+npm run docs:build # static build → docs/.vitepress/dist
+```
 
-        <div id="disconnected" class="hidden p-4 bg-neutral-900 w-full">
-            The arduino is disconnected. Please, check the connection.
-        </div>
+## Browser compatibility
 
-        <div id="unsupported" class="hidden p-4 bg-orange-700 w-full absolute bottom-0 left-0">
-            This browser does not support the WebSerial API. Please, use a compatible browser.
-        </div>
+| Feature       | Browser requirement  |
+| ------------- | -------------------- |
+| Web Serial    | Chrome 89+, Edge 89+ |
+| WebUSB        | Chrome 61+, Edge 79+ |
+| Web Bluetooth | Chrome 56+, Edge 79+ |
+| WebSocket     | All modern browsers  |
 
-        <div id="log" class="bg-neutral-800 p-4 rounded-lg">
-            Log: <br>
-        </div>
-    </div>
+All browser APIs require a **secure context** (HTTPS or `localhost`).
 
-    <script src="https://cdn.tailwindcss.com?plugins=forms,typography,aspect-ratio,container-queries"></script>
-</body>
+## License
 
-</html>
-```
+MIT © [danidoble](https://github.com/danidoble/webserial-core)

package/dist/adapters/web-bluetooth/WebBluetoothProvider.d.ts

@@ -0,0 +1,19 @@
+import { SerialProvider } from '../../types/index.js';
+/**
+ * Creates a {@link SerialProvider} that uses the Web Bluetooth API
+ * to communicate with Nordic UART Service (NUS) devices.
+ *
+ * Pass the returned provider to `AbstractSerialDevice.setProvider()` before
+ * calling `connect()`.
+ *
+ * @returns A `SerialProvider` backed by the Web Bluetooth API.
+ * @throws {Error} If `navigator.bluetooth` is not available in the current environment.
+ *
+ * @example
+ * ```ts
+ * import { createBluetoothProvider, AbstractSerialDevice } from 'webserial-core';
+ *
+ * AbstractSerialDevice.setProvider(createBluetoothProvider());
+ * ```
+ */
+export declare function createBluetoothProvider(): SerialProvider;

package/dist/adapters/web-bluetooth/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file index.ts
+ * Web Bluetooth adapter — re-exports `createBluetoothProvider` as the public API
+ * for using the Web Bluetooth (Nordic UART Service) transport.
+ */
+export { createBluetoothProvider } from './WebBluetoothProvider.js';

package/dist/adapters/web-usb/WebUsbProvider.d.ts

@@ -0,0 +1,127 @@
+import { SerialPolyfillOptions, SerialPortFilter, SerialProvider } from '../../types/index.js';
+interface USBDeviceFilter {
+    vendorId?: number;
+    productId?: number;
+    classCode?: number;
+    subclassCode?: number;
+    protocolCode?: number;
+    serialNumber?: string;
+}
+interface USBEndpoint {
+    readonly endpointNumber: number;
+    readonly direction: "in" | "out";
+    readonly type: "bulk" | "interrupt" | "isochronous";
+    readonly packetSize: number;
+}
+interface USBAlternateInterface {
+    readonly alternateSetting: number;
+    readonly interfaceClass: number;
+    readonly interfaceSubclass: number;
+    readonly interfaceProtocol: number;
+    readonly interfaceName: string | undefined;
+    readonly endpoints: readonly USBEndpoint[];
+}
+interface USBInterface {
+    readonly interfaceNumber: number;
+    readonly alternate: USBAlternateInterface;
+    readonly alternates: readonly USBAlternateInterface[];
+    readonly claimed: boolean;
+}
+interface USBConfiguration {
+    readonly configurationValue: number;
+    readonly configurationName: string | undefined;
+    readonly interfaces: readonly USBInterface[];
+}
+interface USBInTransferResult {
+    readonly data: DataView | undefined;
+    readonly status: "ok" | "stall" | "babble";
+}
+interface USBOutTransferResult {
+    readonly bytesWritten: number;
+    readonly status: "ok" | "stall";
+}
+interface USBControlTransferParameters {
+    requestType: "standard" | "class" | "vendor";
+    recipient: "device" | "interface" | "endpoint" | "other";
+    request: number;
+    value: number;
+    index: number;
+}
+interface USBDevice {
+    readonly vendorId: number;
+    readonly productId: number;
+    readonly configuration: USBConfiguration | null;
+    readonly configurations: readonly USBConfiguration[];
+    readonly opened: boolean;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    forget(): Promise<void>;
+    selectConfiguration(configurationValue: number): Promise<void>;
+    claimInterface(interfaceNumber: number): Promise<void>;
+    releaseInterface(interfaceNumber: number): Promise<void>;
+    controlTransferOut(setup: USBControlTransferParameters, data?: BufferSource): Promise<USBOutTransferResult>;
+    transferIn(endpointNumber: number, length: number): Promise<USBInTransferResult>;
+    transferOut(endpointNumber: number, data: ArrayBuffer): Promise<USBOutTransferResult>;
+}
+interface USB {
+    requestDevice(options: {
+        filters: USBDeviceFilter[];
+    }): Promise<USBDevice>;
+    getDevices(): Promise<USBDevice[]>;
+}
+declare global {
+    interface Navigator {
+        readonly usb: USB;
+    }
+}
+/**
+ * A {@link SerialProvider} implementation that uses the WebUSB API.
+ *
+ * Supported protocols (auto-detected unless overridden via `protocol`):
+ * - `cdc_acm`  — Standard CDC ACM (auto-detected for interface class 2).
+ * - `cp210x`   — Silicon Labs CP2102/CP2104 (auto-detected for vendorId `0x10c4`).
+ * - `none`     — Raw bulk transfer, no initialization commands sent.
+ *
+ * @example
+ * ```ts
+ * import { WebUsbProvider, AbstractSerialDevice } from 'webserial-core';
+ *
+ * // Standard CDC ACM device (class 2, auto-detected)
+ * AbstractSerialDevice.setProvider(new WebUsbProvider());
+ *
+ * // Vendor-specific device with CP210x (e.g. ESP32 with CP2102)
+ * AbstractSerialDevice.setProvider(new WebUsbProvider({
+ *   usbControlInterfaceClass: 255,
+ *   usbTransferInterfaceClass: 255,
+ * }));
+ * ```
+ */
+export declare class WebUsbProvider implements SerialProvider {
+    private readonly options_;
+    /**
+     * @param options - Optional USB interface class and protocol settings.
+     *   Defaults to CDC ACM (interface class 2).
+     */
+    constructor(options?: SerialPolyfillOptions);
+    /**
+     * Prompts the user to select a USB device and returns a `SerialPort`-
+     * compatible wrapper for it.
+     *
+     * @param options - Optional filter list to narrow the USB device picker.
+     * @param polyfillOptions - Per-request override of polyfill settings.
+     * @returns A `SerialPort`-compatible object backed by the selected USB device.
+     * @throws {DOMException} If the user cancels the device picker.
+     */
+    requestPort(options?: {
+        filters?: SerialPortFilter[];
+    }, polyfillOptions?: SerialPolyfillOptions): Promise<SerialPort>;
+    /**
+     * Returns `SerialPort`-compatible wrappers for all previously granted
+     * USB devices.
+     *
+     * @param polyfillOptions - Per-request override of polyfill settings.
+     * @returns An array of `SerialPort`-compatible objects.
+     */
+    getPorts(polyfillOptions?: SerialPolyfillOptions): Promise<SerialPort[]>;
+}
+export {};

package/dist/adapters/web-usb/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file index.ts
+ * Web USB adapter — re-exports `WebUsbProvider` as the public API
+ * for using the WebUSB API as a serial transport.
+ */
+export { WebUsbProvider } from './WebUsbProvider.js';

package/dist/adapters/websocket/WebSocketProvider.d.ts

@@ -0,0 +1,20 @@
+import { SerialProvider } from '../../types/index.js';
+/**
+ * Creates a {@link SerialProvider} that communicates with a Node.js serial
+ * bridge server over WebSockets.
+ *
+ * The bridge server must implement the JSON wire protocol described in this
+ * file's module documentation. A reference implementation is provided in
+ * `demos/websocket/server.js`.
+ *
+ * @param serverUrl - The WebSocket URL of the bridge server (e.g. `"ws://localhost:8080"`).
+ * @returns A `SerialProvider` that relays serial I/O over WebSocket.
+ *
+ * @example
+ * ```ts
+ * import { createWebSocketProvider, AbstractSerialDevice } from 'webserial-core';
+ *
+ * AbstractSerialDevice.setProvider(createWebSocketProvider('ws://localhost:8080'));
+ * ```
+ */
+export declare function createWebSocketProvider(serverUrl: string): SerialProvider;