@risleylima/escpos 0.0.13 → 0.1.0

package/src/serial-adapter/index.js

@@ -1,12 +1,19 @@
 'use strict';
 const { SerialPort } = require('serialport');
-const EventEmitter = require('events');
 const Adapter = require('../adapter');
 
 const debug = require('debug')('escpos:serial-adapter');
 
 const scope = {
   port: null,
+  /**
+   * Verify that a serial port exists
+   * @private
+   * @async
+   * @param {String} port - Serial port path to verify
+   * @returns {Promise<String>} Verified port path
+   * @throws {Error} If port does not exist
+   */
   verifyPort: async (port) => {
     let ports = await SerialPort.list();
     if (!ports.find((i) => i.path === port)) {
@@ -16,110 +23,151 @@ const scope = {
   }
 }
 
-const Serial = new EventEmitter();
-
-Serial.connect = (port, options) => {
-  return new Promise((resolve, reject) => {
-    let connectListener = () => {
-      Serial.removeListener('close', connectListener);
-      scope.verifyPort(port).catch(e => reject(e)).then((portVerified) => {
-        if (portVerified) {
-          scope.port = new SerialPort(Object.assign(options || {}, { path: portVerified, autoOpen: true }), (err) => {
-            if (err) {
-              debug('Error Opening the Selected Port: ', err);
-              if (scope.port) {
-                scope.port.close(async () => {
-                  await connectListener();
-                })
-              }
-            }
-
-            let clearPort = () => {
-              Serial.emit('disconnect', scope.port);
-              scope.port.removeListener('close', clearPort);
-              scope.port = null;
-            }
-
-            scope.port.on('close', clearPort);
-
-            debug('Device Connected and Open!');
-            Serial.emit('connect', scope.port);
-
-            resolve(true);
-          });
-        }
-      });
+// Create Adapter instance first, so it's the same object used internally and exported
+const Serial = new Adapter();
+
+/**
+ * Connect to a serial port printer
+ * @async
+ * @param {String} port - Serial port path (e.g., '/dev/ttyUSB0' or 'COM3')
+ * @param {Object} [options] - Serial port options (baudRate, dataBits, etc.)
+ * @returns {Promise<Boolean>} True if connection successful
+ * @throws {Error} If port does not exist or cannot be opened
+ * @fires Serial#connect
+ * @fires Serial#close (if reconnecting)
+ */
+Serial.connect = async (port, options) => {
+  // Close existing connection if any
+  if (scope.port) {
+    try {
+      await scope.port.close();
+    } catch (e) {
+      debug('Error closing existing port: ', e);
     }
+    Serial.emit('close');
+  }
 
-    Serial.on('close', connectListener);
+  // Verify port exists
+  const portVerified = await scope.verifyPort(port);
+  
+  // Create SerialPort instance (v13: no callback, autoOpen: false)
+  scope.port = new SerialPort(Object.assign(options || {}, { 
+    path: portVerified, 
+    autoOpen: false 
+  }));
+
+  // Handle errors via events
+  scope.port.on('error', (err) => {
+    debug('Error on Serial Port: ', err);
+  });
 
+  // Handle close event
+  let clearPort = () => {
+    Serial.emit('disconnect', scope.port);
+    scope.port.removeListener('close', clearPort);
+    scope.port = null;
+  };
+  scope.port.on('close', clearPort);
+
+  // Open the port manually (v13: returns Promise)
+  try {
+    await scope.port.open();
+    debug('Device Connected and Open!');
+    Serial.emit('connect', scope.port);
+    return true;
+  } catch (err) {
+    debug('Error Opening the Selected Port: ', err);
     if (scope.port) {
-      scope.port.close((e) => {
-        Serial.emit('close');
-      });
-    } else {
-      Serial.emit('close');
+      try {
+        await scope.port.close();
+      } catch (closeErr) {
+        debug('Error closing port after open failure: ', closeErr);
+      }
     }
-  });
+    throw err;
+  }
 }
 
-Serial.open = () => {
-  return new Promise((resolve, reject) => {
-    if (!scope.port.isOpen) {
-      scope.port.open((err) => {
-        if (err)
-          reject(err)
-        debug('Device Opened!');
-        resolve(scope.port.isOpen);
-      });
-    } else {
-      debug('Device is already Opened!');
-      resolve(true)
+/**
+ * Open the serial port if it's closed
+ * @async
+ * @returns {Promise<Boolean>} True if port is open (or was already open)
+ * @throws {Error} If port cannot be opened
+ */
+Serial.open = async () => {
+  if (!scope.port.isOpen) {
+    try {
+      await scope.port.open();
+      debug('Device Opened!');
+      return scope.port.isOpen;
+    } catch (err) {
+      throw err;
     }
-  });
+  } else {
+    debug('Device is already Opened!');
+    return true;
+  }
 };
 
-Serial.write = (data) => {
-  return new Promise((resolve, reject) => {
-    scope.port.write(data, (e) => {
-      if (e)
-        reject(e);
-      scope.port.drain(() => {
-        resolve(true);
-      })
-    });
-  });
+/**
+ * Write data to the serial port
+ * @async
+ * @param {Buffer} data - Data buffer to send to printer
+ * @returns {Promise<Boolean>} True if write successful
+ * @throws {Error} If write fails
+ */
+Serial.write = async (data) => {
+  try {
+    await scope.port.write(data);
+    await scope.port.drain();
+    return true;
+  } catch (e) {
+    throw e;
+  }
 };
 
-Serial.close = (timeout) => {
+/**
+ * Close the serial port connection
+ * @async
+ * @param {Number} [timeout] - Timeout in milliseconds before closing (default: 50ms)
+ * @returns {Promise<Boolean>} True if port closed successfully
+ * @fires Serial#close
+ */
+Serial.close = async (timeout) => {
   let time = Number(timeout);
   if (Number.isNaN(time)) {
-    time = 50
+    time = 50;
   }
 
-  return new Promise((resolve, reject) => {
-    scope.port.flush((e) => {
-      setTimeout(() => {
-        if (e)
-          debug('Error while Flush Device: ', e);
-        scope.port.drain(() => {
-          scope.port.close((eClosing) => {
-            if (eClosing)
-              debug('Error while Close Device: ', eClosing);
-            Serial.emit('close');
-            resolve(true);
-          });
-        })
-      }, time);
-    });
-  });
-
+  try {
+    await scope.port.flush();
+    await new Promise(resolve => setTimeout(resolve, time));
+    await scope.port.drain();
+    await scope.port.close();
+    // Emit event synchronously - this ensures listeners are called immediately
+    Serial.emit('close');
+    return true;
+  } catch (e) {
+    debug('Error while closing device: ', e);
+    // Emit event synchronously even on error - this ensures listeners are called immediately
+    Serial.emit('close');
+    return true; // Still resolve to allow cleanup
+  }
 }
 
+/**
+ * Disconnect from the serial port (calls close internally)
+ * @param {Number} [timeout] - Timeout in milliseconds before closing (default: 50ms)
+ * @returns {Promise<Boolean>} True if disconnection successful
+ */
 Serial.disconnect = (timeout) => {
   return Serial.close(timeout);
 }
 
+/**
+ * Read data from the serial port
+ * @returns {Promise<Buffer>} Data received from the port
+ */
 Serial.read = () => {
   return new Promise((resolve, reject) => {
     let dataHandler = (data) => {
@@ -130,4 +178,5 @@ Serial.read = () => {
   });
 };
 
-module.exports = new Adapter(Serial);
+// Serial is already an Adapter instance, so export it directly
+module.exports = Serial;

package/src/usb-adapter/index.js

@@ -1,5 +1,4 @@
 'use strict'
-const { EventEmitter } = require('stream');
 const Adapter = require('../adapter');
 const usb = require('usb');
 const os = require('os');
@@ -23,16 +22,28 @@ const IFACE_CLASS = {
   HUB: 0x09
 };
 
-const USB = new EventEmitter();
+// Create Adapter instance first, so it's the same object used internally and exported
+const USB = new Adapter();
 
+/**
+ * List all available USB printer devices
+ * @async
+ * @returns {Promise<Array>} Array of USB printer devices with manufacturer and product information
+ */
 USB.listUSB = async () => {
   const devices = usb.getDeviceList().filter((device) => {
     try {
-      return device.configDescriptor.interfaces.filter((iface) => {
-        return iface.filter((conf) => {
-          return conf.bInterfaceClass === IFACE_CLASS.PRINTER;
-        }).length;
-      }).length;
+      // In v2, we need to check configDescriptor for interface class
+      const configDescriptor = device.configDescriptor;
+      if (!configDescriptor || !configDescriptor.interfaces) {
+        return false;
+      }
+      // configDescriptor.interfaces is an array of arrays (alternate settings)
+      return configDescriptor.interfaces.some((ifaceArray) => {
+        return ifaceArray.some((iface) => {
+          return iface.bInterfaceClass === IFACE_CLASS.PRINTER;
+        });
+      });
     } catch (e) {
       debug('Error while get device info: ', e);
       return false;
@@ -41,21 +52,30 @@ USB.listUSB = async () => {
 
   let retorno = [];
 
-  const getDescriptor = (device, type) => new Promise((resolve, reject) => {
+  /**
+   * Get string descriptor from USB device
+   * @private
+   * @async
+   * @param {Object} device - USB device object
+   * @param {Number} type - Descriptor type index
+   * @returns {Promise<String|Boolean>} Descriptor string or false on error
+   */
+  const getDescriptor = async (device, type) => {
     try {
-      device.open();
-      device.getStringDescriptor(type, (err, data) => {
-        if (err) {
-          reject(new Error('Error while read selected Description: ', e));
-        }
-        device.close();
-        resolve(data);
-      });
+      await device.open();
+      const data = await device.getStringDescriptor(type);
+      await device.close();
+      return data;
     } catch (e) {
-      debug(new Error('Error while read device description: ', e));
-      resolve(false);
+      debug('Error while read device description: ', e);
+      try {
+        await device.close();
+      } catch (closeErr) {
+        // Ignore close errors
+      }
+      return false;
     }
-  });
+  };
 
   for (let device of devices) {
     device.manufacturer = await getDescriptor(device, device.deviceDescriptor.iManufacturer);
@@ -68,6 +88,15 @@ USB.listUSB = async () => {
   return retorno;
 };
 
+/**
+ * Connect to a USB printer device
+ * @async
+ * @param {Number} [vid] - Vendor ID (optional, if not provided, uses first available printer)
+ * @param {Number} [pid] - Product ID (optional, if not provided, uses first available printer)
+ * @returns {Promise<Boolean>} True if connection successful
+ * @throws {Error} If printer cannot be found
+ * @fires USB#connect
+ */
 USB.connect = async (vid, pid) => {
   scope.device = null;
   scope.endpoint = null;
@@ -96,27 +125,52 @@ USB.connect = async (vid, pid) => {
   return true;
 };
 
+/**
+ * Open the USB device and claim the printer interface
+ * @async
+ * @returns {Promise<Boolean>} True if device opened successfully
+ * @throws {Error} If interfaces cannot be accessed or endpoint not found
+ * @fires USB#connect
+ */
 USB.open = async () => {
-  scope.device.open();
-  for (let iface of scope.device.interfaces) {
+  await scope.device.open();
+  
+  // In v2, device.interfaces is a direct array of Interface objects
+  // We need to iterate through all interfaces to find the printer interface
+  const interfaces = scope.device.interfaces;
+  if (!interfaces || interfaces.length === 0) {
+    throw new Error('Cannot access device interfaces');
+  }
+
+  for (let interfaceObj of interfaces) {
     if (scope.endpoint) {
       break;
     }
 
+    // Check if this interface is a printer interface
+    const descriptor = interfaceObj.descriptor;
+    if (descriptor && descriptor.bInterfaceClass !== IFACE_CLASS.PRINTER) {
+      continue;
+    }
+
+    // Claim interface (required on all platforms)
     if ("win32" !== os.platform()) {
-      if (iface.isKernelDriverActive()) {
+      // On Linux/macOS, detach kernel driver first if active
+      if (interfaceObj.isKernelDriverActive()) {
         try {
-          iface.detachKernelDriver();
+          await interfaceObj.detachKernelDriver();
         } catch (e) {
-          throw new Error("[ERROR] Could not detatch kernel driver: %s", e);
+          throw new Error(`[ERROR] Could not detach kernel driver: ${e.message}`);
         }
       }
-      iface.claim(); // must be called before using any endpoints of this interface.
     }
-    for (let endpoint of iface.endpoints) {
+    // Claim interface (required on all platforms before using endpoints)
+    await interfaceObj.claim();
+    
+    for (let endpoint of interfaceObj.endpoints) {
       if (scope.endpoint) {
         break;
-      } else if (endpoint.direction == 'out') {
+      } else if (endpoint.direction === 'out') {
         scope.endpoint = endpoint;
         USB.emit('connect', scope.device);
         debug('Device Opened!');
@@ -130,40 +184,100 @@ USB.open = async () => {
   return true;
 };
 
+/**
+ * Close the USB device connection and release interfaces
+ * @async
+ * @returns {Promise<Boolean>} True if device closed successfully
+ * @fires USB#close
+ */
 USB.close = async () => {
+  const device = scope.device; // Save device reference before cleanup
+  
   if (scope.device) {
-    await scope.device.close();
+    try {
+      // Release interfaces before closing
+      // Only release the interface we actually claimed
+      if (scope.endpoint && scope.endpoint.interface) {
+        const interfaceObj = scope.endpoint.interface;
+        try {
+          // Check if interface is still valid and was claimed
+          if (interfaceObj && typeof interfaceObj.release === 'function') {
+            await interfaceObj.release();
+          }
+        } catch (e) {
+          debug('Error releasing interface: ', e);
+        }
+      } else {
+        // Fallback: try to release all interfaces
+        const interfaces = scope.device.interfaces;
+        if (interfaces && interfaces.length > 0) {
+          for (let interfaceObj of interfaces) {
+            try {
+              // Only release if we claimed it (kernel driver was detached)
+              if (interfaceObj && typeof interfaceObj.release === 'function' && !interfaceObj.isKernelDriverActive()) {
+                await interfaceObj.release();
+              }
+            } catch (e) {
+              debug('Error releasing interface: ', e);
+            }
+          }
+        }
+      }
+      await scope.device.close();
+    } catch (e) {
+      debug('Error closing device: ', e);
+    }
   }
 
-  USB.emit('close', scope.device);
-  debug('Device Closed!');
+  // Clear endpoint before emitting event
   scope.endpoint = null;
+  
+  // Emit event synchronously - this ensures listeners are called immediately
+  USB.emit('close', device);
+  debug('Device Closed!');
 
   return true;
 }
 
+/**
+ * Disconnect from the USB device (calls close internally)
+ * @async
+ * @returns {Promise<Boolean>} True if disconnection successful
+ * @fires USB#disconnect
+ */
 USB.disconnect = async () => {
+  const device = scope.device; // Save device reference before cleanup
+  
   if (scope.device) {
     await USB.close().catch(e => { debug(e); return true });
   }
-  USB.emit('disconnect', scope.device);
-  debug('Device Disconnected!');
+  
+  // Clear scope before emitting event
   scope.endpoint = null;
   scope.device = null;
+  
+  // Emit event synchronously - this ensures listeners are called immediately
+  USB.emit('disconnect', device);
+  debug('Device Disconnected!');
 
   return true;
 }
 
-
-USB.write = (data) => {
-  return new Promise((resolve, reject) => {
-    scope.endpoint.transfer(data, (e) => {
-      if (e) {
-        reject(e);
-      }
-      resolve(true);
-    });
-  })
+/**
+ * Write data to the USB printer
+ * @async
+ * @param {Buffer} data - Data buffer to send to printer
+ * @returns {Promise<Boolean>} True if write successful
+ * @throws {Error} If write fails
+ */
+USB.write = async (data) => {
+  try {
+    await scope.endpoint.transfer(data);
+    return true;
+  } catch (e) {
+    throw e;
+  }
 }
 
-module.exports = new Adapter(USB);
+// USB is already an Adapter instance, so export it directly
+module.exports = USB;

package/tests/README.md

@@ -0,0 +1,67 @@
+# Tests - EscPos
+
+This directory contains the test suite for the EscPos library.
+
+## Structure
+
+```
+tests/
+├── unit/              # Isolated unit tests
+│   ├── printer/       # Printer class tests
+│   ├── adapters/      # Adapter tests (USB/Serial)
+│   ├── image/         # Image processing tests
+│   └── utils/         # Utility functions tests
+└── integration/       # Integration tests
+    └── printer-flow/  # Complete flow tests
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run in watch mode
+npm run test:watch
+
+# Run with coverage
+npm run test:coverage
+```
+
+## Coverage
+
+The tests cover:
+- ✅ Buffer operations
+- ✅ Text formatting
+- ✅ ESC/POS commands
+- ✅ Image processing
+- ✅ Barcodes
+- ✅ Adapters (with mocks)
+- ✅ Complete print flows
+
+## Mocks
+
+The tests use mocks for:
+- **USB Adapter**: Mock of `usb` module
+- **Serial Adapter**: Mock of `serialport` module
+- **Image**: Mock of `get-pixels` module
+
+This allows running tests without requiring real hardware.
+
+## Adding New Tests
+
+1. Create the test file in `tests/unit/` or `tests/integration/`
+2. Use the `*.test.js` convention
+3. Follow Jest's describe/it pattern
+4. Use mocks for external dependencies
+
+## Example
+
+```javascript
+describe('MyFeature', () => {
+  it('should do something', () => {
+    // test here
+  });
+});
+```
+