label-printer 0.7.1 → 0.7.3

package/README.md

@@ -2,6 +2,7 @@
 
 > :warning: `label-printer` is still under heavy development and is subject to frequent API changes
 
+
 This package provides a TypeScript/JavaScript API to:
 
 - **Build labels** in a printer-language-independent way
@@ -20,16 +21,16 @@ npm install label-printer
 
 The library exposes three main areas:
 
-- **Commands**: `import { Command } from "label-printer"`
-- **Labels**: `import { Label } from "label-printer"`
-- **Printers**: `import { PrinterService } from "label-printer"`
+- **Commands**: `import { commands } from "label-printer"`
+- **Labels**: `import { labels } from "label-printer"`
+- **Printers**: `import { printers } from "label-printer"`
 
 ## Runtime support (Browser vs Node)
 
 ### Browser
 
 - Uses **WebUSB** to communicate with USB label printers.
-- Typical entry point: `PrinterService.requestPrinter()`.
+- Typical entry point: `printers.PrinterService.requestPrinter()`.
 
 ### Node.js
 
@@ -45,31 +46,31 @@ The library exposes three main areas:
 ### Discover printers
 
 ```ts
-import { PrinterService } from "label-printer"
+import { printers } from "label-printer"
 
-const printers = await PrinterService.getPrinters()
-if(printers.length === 0) {
+const printersList = await printers.PrinterService.getPrinters()
+if(printersList.length === 0) {
   throw new Error("No printers found")
 }
 
-const printer = printers[0]
+const printer = printersList[0]
 ```
 
 ### Request a printer (browser-focused)
 
 ```ts
-import { PrinterService } from "label-printer"
+import { printers } from "label-printer"
 
-const printer = await PrinterService.requestPrinter()
+const printer = await printers.PrinterService.requestPrinter()
 if(!printer) throw new Error("No printer selected")
 ```
 
 ### Print or display a label
 
 ```ts
-import { Label } from "label-printer"
+import { labels } from "label-printer"
 
-const label = new Label(50, 25)
+const label = new labels.Label(50, 25)
 // 1 label, 3mm gap
 await printer.print(label, 1, 3)
 // or
@@ -78,15 +79,48 @@ await printer.display(label)
 await printer.close()
 ```
 
-### Direct network usage (Node.js)
+### Connect directly (bypass discovery)
+
+If you already know how to reach your printer (network address or USB identifiers), you can create a printer instance directly.
+
+Auto-detect language (recommended default):
+
+```ts
+import { printers } from "label-printer"
+
+const printer = await printers.PrinterService.connect({ network: { host: "192.168.100.31" } })
+if(!printer) throw new Error("Printer not found or not supported")
+```
+
+Explicit TSPL (when you know it's a TSPL printer):
+
+```ts
+import { printers } from "label-printer"
+
+const printer = await printers.PrinterService.connectTSPL({ network: { host: "192.168.100.31", port: 9100 } })
+if(!printer) throw new Error("Not a TSPL printer")
+```
+
+USB (Node.js - filter without a prompt):
+
+```ts
+import { printers } from "label-printer"
+
+const printer = await printers.PrinterService.connect({
+  usb: { vendorId: 0x1234, productId: 0x5678, serialNumber: "ABC" }
+})
+if(!printer) throw new Error("Printer not found or not supported")
+```
 
-If you already know the printer IP and want to bypass discovery:
+USB (Browser - shows a picker; you can optionally filter by `vendorId` / `productId`):
 
 ```ts
-import TSPLPrinter from "label-printer/dist/printers/TSPLPrinter"
-import NetworkDevice from "label-printer/dist/helpers/NetworkDevice"
+import { printers } from "label-printer"
 
-const printer = new TSPLPrinter(new NetworkDevice("192.168.100.31", 9100))
+const printer = await printers.PrinterService.connect({
+  usb: { vendorId: 0x1234, productId: 0x5678 }
+})
+if(!printer) throw new Error("No printer selected")
 ```
 
 ## Device abstraction
@@ -94,16 +128,16 @@ const printer = new TSPLPrinter(new NetworkDevice("192.168.100.31", 9100))
 Commands write to a transport-agnostic `Device` interface. This enables the same printer and label APIs to work over different transports.
 
 - **USB** device implementation is internal to `USBUtils`.
-- **NetworkDevice** is a TCP implementation used in Node.js.
+- **Network** support uses a TCP implementation in Node.js.
 
 ## Label layer
 
 The label layer provides a language-independent way to construct labels, which can then be rendered to commands for the chosen printer language.
 
 ```ts
-import { Label } from "label-printer"
+import { labels } from "label-printer"
 
-const label = new Label(50, 25)
+const label = new labels.Label(50, 25)
 // label.add(...fields)
 ```
 
@@ -113,19 +147,18 @@ const label = new Label(50, 25)
 
 ## Fields
 
-Fields live under `label-printer/dist/labels/fields` in the built output.
+Fields are available from the package root export.
 
 ### Text
 
 Create a text field at (`x`, `y`) in **dots**.
 
 ```ts
-import { Label } from "label-printer/dist/labels"
-import { Text } from "label-printer/dist/labels/fields"
+import { labels } from "label-printer"
 
-const label = new Label(50, 25)
+const label = new labels.Label(50, 25)
 
-const text = new Text("Hello", 20, 20, true)
+const text = new labels.Text("Hello", 20, 20, true)
 text.setSingleLine(200)
 
 label.add(text)
@@ -148,9 +181,9 @@ Formatted text (when `formatted = true`) supports basic tags:
 Draw a line between two points (values in **dots**).
 
 ```ts
-import { Line } from "label-printer/dist/labels/fields"
+import { labels } from "label-printer"
 
-label.add(new Line({ x: 10, y: 10 }, { x: 300, y: 10 }, 3))
+label.add(new labels.Line({ x: 10, y: 10 }, { x: 300, y: 10 }, 3))
 ```
 
 ### Image
@@ -159,9 +192,9 @@ Draw a black/white bitmap image. You can either provide a bitmap-like object dir
 or use the async helper to load/convert an image.
 
 ```ts
-import { Image } from "label-printer/dist/labels/fields"
+import { labels } from "label-printer"
 
-const img = await Image.create("./logo.png", 10, 60, 200)
+const img = await labels.Image.create("./logo.png", 10, 60, 200)
 label.add(img)
 ```
 
@@ -170,9 +203,9 @@ label.add(img)
 Draw a barcode (TSPL-backed). Values are in **dots**.
 
 ```ts
-import { BarCode } from "label-printer/dist/labels/fields"
+import { labels } from "label-printer"
 
-const barcode = new BarCode("123456789", 20, 120, "CODE128", 80)
+const barcode = new labels.BarCode("123456789", 20, 120, "CODE128", 80)
 barcode.setHumanReadable("bottom")
 barcode.setRotation(0)
 
@@ -184,9 +217,9 @@ label.add(barcode)
 Draw a QR code.
 
 ```ts
-import { QRCode } from "label-printer/dist/labels/fields"
+import { labels } from "label-printer"
 
-label.add(new QRCode("https://example.com", 20, 220, 6))
+label.add(new labels.QRCode("https://example.com", 20, 220, 6))
 ```
 
 ### Table
@@ -194,12 +227,11 @@ label.add(new QRCode("https://example.com", 20, 220, 6))
 The `Table` field draws a grid and places text into each cell. It uses the existing `Text` field for cell contents and the existing `Line` field for the grid lines.
 
 ```ts
-import { Label } from "label-printer/dist/labels"
-import { Table } from "label-printer/dist/labels/fields"
+import { labels } from "label-printer"
 
-const label = new Label(50, 25)
+const label = new labels.Label(50, 25)
 
-const table = new Table(10, 10, [
+const table = new labels.Table(10, 10, [
   ["A1", "A2"],
   ["B1", "B2"],
 ], {
@@ -281,9 +313,9 @@ Registering fonts enables better text measurement (for wrapping) and ensures the
 as part of the generated print/display command sequence.
 
 ```ts
-import { Label } from "label-printer/dist/labels"
+import { labels } from "label-printer"
 
-const label = new Label(50, 25)
+const label = new labels.Label(50, 25)
 
 await label.registerFont({
   name: "MyFont",

package/dist/index.d.mts

@@ -846,6 +846,88 @@ declare abstract class Printer {
     static try(_device: Device): Promise<boolean>;
 }
 
+declare class NetworkDevice implements Device {
+    private socket?;
+    private readonly host;
+    private readonly port;
+    private readonly connectTimeoutMs;
+    private readonly readTimeoutMs;
+    /**
+     * Create a TCP-based device.
+     *
+     * This is intended for raw printing ports (typically 9100). It is Node-only.
+     *
+     * @param host Hostname or IP
+     * @param port TCP port (defaults to 9100)
+     * @param connectTimeoutMs Connection timeout
+     * @param readTimeoutMs Read timeout used by `readData`/`readString`
+     */
+    constructor(host: string, port?: number, connectTimeoutMs?: number, readTimeoutMs?: number);
+    get opened(): boolean;
+    openAndConfigure(): Promise<void>;
+    close(): Promise<void>;
+    writeData(data: Uint8Array | ArrayBuffer): Promise<void>;
+    writeString(text: string): Promise<void>;
+    readData(length: number): Promise<DataView | undefined>;
+    readString(length: number): Promise<string | undefined>;
+}
+
+declare class TSPLPrinter extends Printer {
+    get language(): PrinterLanguage;
+    feedLabel(): Promise<void>;
+    getModelname(): Promise<string>;
+    getStatus(): Promise<PrinterStatus>;
+    private static statusFor;
+    static try(device: Device): Promise<boolean>;
+    /**
+     * Discover TSPL-capable printers on the local network.
+     *
+     * Strategy:
+     * - Use Bonjour/mDNS to discover "printer-ish" services to obtain a set of candidate hosts.
+     * - For each unique host, probe TCP/9100 by sending the TSPL identify command (~!I).
+     * - Only return devices that respond to the TSPL probe.
+     * - If Bonjour yields no candidates (e.g. mDNS is blocked), fall back to a conservative
+     *   subnet scan on local private /24 networks (still verified by the same TSPL probe).
+     */
+    static discoverDevices(): Promise<NetworkDevice[]>;
+    /**
+     * Fallback discovery mechanism used when Bonjour/mDNS returns no printer candidates.
+     *
+     * It derives local private IPv4 /24 prefixes from the current machine's network interfaces
+     * and probes TCP/9100 using the TSPL identify command.
+     *
+     * The scan is intentionally conservative:
+     * - Limited number of prefixes
+     * - Concurrency limits
+     * - Total time cap
+     * - Early-exit when at least one printer is found
+     */
+    private static discoverHostsBySubnetScan;
+    /**
+     * Returns a Node-style `require` function.
+     *
+     * This is used to keep runtime dependencies Node-only while still allowing the library to
+     * be imported/bundled in browser contexts.
+     *
+     * Tests may inject a custom require implementation via `globalThis.__label_printer_require`.
+     */
+    private static getNodeRequire;
+}
+
+type PrinterServiceUsbConnectOptions = {
+    vendorId?: number;
+    productId?: number;
+    serialNumber?: string;
+};
+type PrinterServiceNetworkConnectOptions = {
+    host: string;
+    port?: number;
+};
+type PrinterServiceConnectOptions = {
+    usb: PrinterServiceUsbConnectOptions;
+} | {
+    network: PrinterServiceNetworkConnectOptions;
+};
 declare class PrinterService {
     /**
      * Try each type of printer and return the one that mathces the usb device
@@ -875,6 +957,34 @@ declare class PrinterService {
      * printer, it may return undefined. In node, use `getPrinters` instead
      */
     static requestPrinter(): Promise<Printer | undefined>;
+    /**
+     * Create a printer instance using explicit connection information.
+     *
+     * This is useful when you already know your printer's network address or USB identifiers
+     * and want to bypass discovery.
+     *
+     * Behavior differs by environment:
+     * - **Node.js**
+     *   - `network`: connects via TCP (defaults to port `9100`)
+     *   - `usb`: selects the first connected USB device matching the provided filters
+     * - **Browser**
+     *   - `usb`: shows the WebUSB picker (optionally filtered by `vendorId`/`productId`)
+     *   - `network`: not supported (will throw if network transport is used in the browser)
+     */
+    static connect(options: PrinterServiceConnectOptions): Promise<Printer | undefined>;
+    /**
+     * Create a TSPL printer instance using explicit connection information.
+     *
+     * This still verifies the target by probing it with the TSPL identify command (`~!I`).
+     * If the probe fails, `undefined` is returned.
+     */
+    static connectTSPL(options: PrinterServiceConnectOptions): Promise<TSPLPrinter | undefined>;
+    /**
+     * Convert user-facing connect options into a concrete device.
+     *
+     * This keeps transport details (USB vs TCP socket) out of the public API.
+     */
+    private static deviceForConnectOptions;
 }
 
 type index_Printer = Printer;

package/dist/index.d.ts

@@ -846,6 +846,88 @@ declare abstract class Printer {
     static try(_device: Device): Promise<boolean>;
 }
 
+declare class NetworkDevice implements Device {
+    private socket?;
+    private readonly host;
+    private readonly port;
+    private readonly connectTimeoutMs;
+    private readonly readTimeoutMs;
+    /**
+     * Create a TCP-based device.
+     *
+     * This is intended for raw printing ports (typically 9100). It is Node-only.
+     *
+     * @param host Hostname or IP
+     * @param port TCP port (defaults to 9100)
+     * @param connectTimeoutMs Connection timeout
+     * @param readTimeoutMs Read timeout used by `readData`/`readString`
+     */
+    constructor(host: string, port?: number, connectTimeoutMs?: number, readTimeoutMs?: number);
+    get opened(): boolean;
+    openAndConfigure(): Promise<void>;
+    close(): Promise<void>;
+    writeData(data: Uint8Array | ArrayBuffer): Promise<void>;
+    writeString(text: string): Promise<void>;
+    readData(length: number): Promise<DataView | undefined>;
+    readString(length: number): Promise<string | undefined>;
+}
+
+declare class TSPLPrinter extends Printer {
+    get language(): PrinterLanguage;
+    feedLabel(): Promise<void>;
+    getModelname(): Promise<string>;
+    getStatus(): Promise<PrinterStatus>;
+    private static statusFor;
+    static try(device: Device): Promise<boolean>;
+    /**
+     * Discover TSPL-capable printers on the local network.
+     *
+     * Strategy:
+     * - Use Bonjour/mDNS to discover "printer-ish" services to obtain a set of candidate hosts.
+     * - For each unique host, probe TCP/9100 by sending the TSPL identify command (~!I).
+     * - Only return devices that respond to the TSPL probe.
+     * - If Bonjour yields no candidates (e.g. mDNS is blocked), fall back to a conservative
+     *   subnet scan on local private /24 networks (still verified by the same TSPL probe).
+     */
+    static discoverDevices(): Promise<NetworkDevice[]>;
+    /**
+     * Fallback discovery mechanism used when Bonjour/mDNS returns no printer candidates.
+     *
+     * It derives local private IPv4 /24 prefixes from the current machine's network interfaces
+     * and probes TCP/9100 using the TSPL identify command.
+     *
+     * The scan is intentionally conservative:
+     * - Limited number of prefixes
+     * - Concurrency limits
+     * - Total time cap
+     * - Early-exit when at least one printer is found
+     */
+    private static discoverHostsBySubnetScan;
+    /**
+     * Returns a Node-style `require` function.
+     *
+     * This is used to keep runtime dependencies Node-only while still allowing the library to
+     * be imported/bundled in browser contexts.
+     *
+     * Tests may inject a custom require implementation via `globalThis.__label_printer_require`.
+     */
+    private static getNodeRequire;
+}
+
+type PrinterServiceUsbConnectOptions = {
+    vendorId?: number;
+    productId?: number;
+    serialNumber?: string;
+};
+type PrinterServiceNetworkConnectOptions = {
+    host: string;
+    port?: number;
+};
+type PrinterServiceConnectOptions = {
+    usb: PrinterServiceUsbConnectOptions;
+} | {
+    network: PrinterServiceNetworkConnectOptions;
+};
 declare class PrinterService {
     /**
      * Try each type of printer and return the one that mathces the usb device
@@ -875,6 +957,34 @@ declare class PrinterService {
      * printer, it may return undefined. In node, use `getPrinters` instead
      */
     static requestPrinter(): Promise<Printer | undefined>;
+    /**
+     * Create a printer instance using explicit connection information.
+     *
+     * This is useful when you already know your printer's network address or USB identifiers
+     * and want to bypass discovery.
+     *
+     * Behavior differs by environment:
+     * - **Node.js**
+     *   - `network`: connects via TCP (defaults to port `9100`)
+     *   - `usb`: selects the first connected USB device matching the provided filters
+     * - **Browser**
+     *   - `usb`: shows the WebUSB picker (optionally filtered by `vendorId`/`productId`)
+     *   - `network`: not supported (will throw if network transport is used in the browser)
+     */
+    static connect(options: PrinterServiceConnectOptions): Promise<Printer | undefined>;
+    /**
+     * Create a TSPL printer instance using explicit connection information.
+     *
+     * This still verifies the target by probing it with the TSPL identify command (`~!I`).
+     * If the probe fails, `undefined` is returned.
+     */
+    static connectTSPL(options: PrinterServiceConnectOptions): Promise<TSPLPrinter | undefined>;
+    /**
+     * Convert user-facing connect options into a concrete device.
+     *
+     * This keeps transport details (USB vs TCP socket) out of the public API.
+     */
+    private static deviceForConnectOptions;
 }
 
 type index_Printer = Printer;

package/dist/index.js

@@ -1436,10 +1436,28 @@ var requestDevice = () => __async(null, null, function* () {
     return void 0;
   }
 });
+var requestDeviceWithFilters = (..._0) => __async(null, [..._0], function* (filters = []) {
+  const agent = yield getUSB();
+  const device = yield agent.requestDevice({ filters });
+  if (device) {
+    return new UsbDevice(device);
+  } else {
+    return void 0;
+  }
+});
 var UsbDevice = class {
   get opened() {
     return this.device.opened;
   }
+  get vendorId() {
+    return this.device.vendorId;
+  }
+  get productId() {
+    return this.device.productId;
+  }
+  get serialNumber() {
+    return this.device.serialNumber;
+  }
   /**
    * All available endpoints
    */
@@ -2021,6 +2039,69 @@ var PrinterService = class _PrinterService {
       }
     });
   }
+  /**
+   * Create a printer instance using explicit connection information.
+   *
+   * This is useful when you already know your printer's network address or USB identifiers
+   * and want to bypass discovery.
+   *
+   * Behavior differs by environment:
+   * - **Node.js**
+   *   - `network`: connects via TCP (defaults to port `9100`)
+   *   - `usb`: selects the first connected USB device matching the provided filters
+   * - **Browser**
+   *   - `usb`: shows the WebUSB picker (optionally filtered by `vendorId`/`productId`)
+   *   - `network`: not supported (will throw if network transport is used in the browser)
+   */
+  static connect(options) {
+    return __async(this, null, function* () {
+      const device = yield _PrinterService.deviceForConnectOptions(options);
+      if (!device) return void 0;
+      return _PrinterService.printerForDevice(device);
+    });
+  }
+  /**
+   * Create a TSPL printer instance using explicit connection information.
+   *
+   * This still verifies the target by probing it with the TSPL identify command (`~!I`).
+   * If the probe fails, `undefined` is returned.
+   */
+  static connectTSPL(options) {
+    return __async(this, null, function* () {
+      const device = yield _PrinterService.deviceForConnectOptions(options);
+      if (!device) return void 0;
+      const ok = yield TSPLPrinter.try(device);
+      if (!ok) return void 0;
+      return new TSPLPrinter(device);
+    });
+  }
+  /**
+   * Convert user-facing connect options into a concrete device.
+   *
+   * This keeps transport details (USB vs TCP socket) out of the public API.
+   */
+  static deviceForConnectOptions(options) {
+    return __async(this, null, function* () {
+      var _a;
+      if ("network" in options) {
+        const port = (_a = options.network.port) != null ? _a : 9100;
+        return new NetworkDevice(options.network.host, port);
+      }
+      const filters = [{ vendorId: options.usb.vendorId, productId: options.usb.productId }].filter((f) => f.vendorId != null || f.productId != null);
+      if (typeof window !== "undefined") {
+        if (filters.length > 0) return requestDeviceWithFilters(filters);
+        return requestDevice();
+      }
+      const devices = yield getDevices();
+      const matching = devices.filter((d) => {
+        if (options.usb.vendorId != null && d.vendorId !== options.usb.vendorId) return false;
+        if (options.usb.productId != null && d.productId !== options.usb.productId) return false;
+        if (options.usb.serialNumber != null && d.serialNumber !== options.usb.serialNumber) return false;
+        return true;
+      });
+      return matching[0];
+    });
+  }
 };
 
 // src/labels/index.ts