@risleylima/escpos 0.2.1 → 1.0.0

package/docs/TESTS_IMPLEMENTED.md

@@ -1,129 +0,0 @@
-# ✅ Tests Implemented
-
-## 📋 Summary
-
-A complete test suite has been implemented for the EscPos library using Jest.
-
-## 📁 Created Structure
-
-```
-tests/
-├── unit/
-│   ├── printer/
-│   │   ├── buffer.test.js          # SpecBuffer tests
-│   │   └── printer.test.js        # Printer class tests
-│   ├── adapters/
-│   │   ├── adapter.test.js        # Base Adapter class tests
-│   │   ├── usb-adapter.test.js    # USB Adapter tests (mocked)
-│   │   └── serial-adapter.test.js # Serial Adapter tests (mocked)
-│   ├── image/
-│   │   └── image.test.js          # Image processing tests
-│   └── utils/
-│       └── utils.test.js          # Utility functions tests
-├── integration/
-│   └── printer-flow.test.js      # Complete flow tests
-└── README.md                      # Test documentation
-```
-
-## 🧪 Test Coverage
-
-### ✅ SpecBuffer
-- Empty buffer initialization
-- Data writing (ASCII, hex)
-- Multiple writes concatenation
-- Flush and buffer clearing
-
-### ✅ Printer
-- **Constructor**: Initialization with adapter and options
-- **Text**: print, println, text, textln, newLine
-- **Alignment**: left, center, right
-- **Formatting**: size, font, style (bold, italic, underline)
-- **Paper**: feed, drawLine, cut (partial/full)
-- **Hardware**: init, beep, cashdraw
-- **Barcodes**: EAN13, EAN8, with validations
-- **Raw Commands**: direct hex command writing
-- **Method Chaining**: method chaining support
-- **Flush/Close**: data sending and closing
-- **Colors**: primary/secondary, reverse colors
-
-### ✅ Utils
-- `getParityBit`: parity bit calculation
-- `codeLength`: hex length calculation
-- `textLength`: character counting (ASCII and multi-byte)
-- `textSubstring`: substring extraction considering multi-byte
-
-### ✅ Image
-- Image loading (with mock)
-- Bitmap conversion (different densities)
-- Raster conversion
-- Pixel processing (black/white/transparent)
-
-### ✅ Adapters
-- **Base Adapter**: abstract methods validation
-- **USB Adapter**: connect, open, write, close, disconnect (mocked)
-- **Serial Adapter**: connect, open, write, close, read (mocked)
-
-### ✅ Integration
-- Complete receipt print flow
-- Print with barcode
-- Multiple sequential prints
-- Complex formatting (mixed styles)
-- Error handling
-
-## 🚀 How to Run
-
-### Install Jest
-```bash
-npm install --save-dev jest
-```
-
-**Note**: If there's an error compiling the `usb` module, don't worry - the tests use mocks and don't need the compiled module.
-
-### Run Tests
-```bash
-# All tests
-npm test
-
-# Watch mode (re-runs on save)
-npm run test:watch
-
-# With coverage
-npm run test:coverage
-```
-
-## 🎯 Mocking Strategy
-
-The tests use mocks to isolate dependencies:
-
-- **USB Adapter**: Mock of `usb` module (no hardware needed)
-- **Serial Adapter**: Mock of `serialport` module (no hardware needed)
-- **Image**: Mock of `get-pixels` module (no real files needed)
-
-This allows:
-- ✅ Running tests without hardware
-- ✅ Fast tests
-- ✅ Reliable and reproducible tests
-- ✅ CI/CD without external dependencies
-
-## 📊 Statistics
-
-- **Total test files**: 8
-- **Categories**: Unit + Integration
-- **Mocks**: 3 main modules
-- **Expected coverage**: 70-85%
-
-## 🔄 Next Steps (Optional)
-
-1. Add tests for QR Code (when implemented)
-2. Add performance tests
-3. Add E2E tests with real printer (optional)
-4. Configure CI/CD (GitHub Actions, etc.)
-5. Add snapshot tests for complex buffers
-
-## 📝 Notes
-
-- All tests are independent and can run in parallel
-- Mocks ensure tests don't depend on real hardware
-- The structure allows easy addition of new tests
-- Tests also serve as API usage documentation
-

package/docs/USB_V2_REVIEW.md

@@ -1,148 +0,0 @@
-# USB v2 Compatibility Review
-
-## Review Summary
-
-Complete review of the codebase to ensure compatibility with `usb@^2.16.0` (upgraded from `usb@^1.9.1`).
-
-## Files Reviewed
-
-### ✅ Core Code
-- **`src/usb-adapter/index.js`** - Fully updated to v2 API
-  - All callbacks converted to Promises/async-await
-  - Interface access updated for v2 structure
-  - Improved error handling
-  - Better interface release logic
-
-### ✅ Tests
-- **`tests/unit/adapters/usb-adapter.test.js`** - Completely updated
-  - Mocks updated to reflect v2 Promise-based API
-  - Added comprehensive test cases
-  - Improved mock structure with proper endpoint-interface linking
-  - Added tests for error scenarios
-
-### ✅ Examples
-- **`examples/printTest.js`** - Compatible (uses adapter API, not direct USB)
-  - No changes needed - uses the adapter abstraction
-
-### ✅ Package Configuration
-- **`package.json`** - Updated dependency
-  - `"usb": "^2.16.0"` ✓
-
-## Key Changes Made
-
-### 1. USB Adapter Code Improvements
-
-#### Interface Release Logic
-- **Before**: Attempted to release all interfaces
-- **After**: Prioritizes releasing the specific interface that was claimed
-- **Fallback**: Releases all interfaces if endpoint.interface is not available
-
-```javascript
-// Improved release logic
-if (scope.endpoint && scope.endpoint.interface) {
-  const interfaceObj = scope.endpoint.interface;
-  if (interfaceObj && typeof interfaceObj.release === 'function') {
-    await interfaceObj.release();
-  }
-}
-```
-
-### 2. Test Improvements
-
-#### Enhanced Mock Structure
-- Added proper endpoint-interface linking (`endpoint.interface`)
-- All async methods return Promises
-- More realistic mock structure matching v2 API
-
-#### Additional Test Cases
-- Test for devices without descriptors
-- Verification of interface claiming
-- Verification of endpoint transfer calls
-- Verification of interface release
-
-### 3. Error Handling
-- Better error messages with context
-- Graceful handling of descriptor errors
-- Proper cleanup on errors
-
-## API Compatibility Checklist
-
-### ✅ Device Operations
-- [x] `device.open()` - Returns Promise
-- [x] `device.close()` - Returns Promise
-- [x] `device.getStringDescriptor()` - Returns Promise
-- [x] `device.configDescriptor` - Accessible
-- [x] `device.interfaces` - Array of Interface objects
-
-### ✅ Interface Operations
-- [x] `interface.claim()` - Returns Promise
-- [x] `interface.release()` - Returns Promise
-- [x] `interface.detachKernelDriver()` - Returns Promise
-- [x] `interface.isKernelDriverActive()` - Returns boolean
-- [x] `interface.descriptor` - Accessible
-- [x] `interface.endpoints` - Array of Endpoint objects
-
-### ✅ Endpoint Operations
-- [x] `endpoint.transfer()` - Returns Promise
-- [x] `endpoint.direction` - Accessible
-- [x] `endpoint.interface` - Available (v2 feature)
-
-### ✅ USB Module Operations
-- [x] `usb.getDeviceList()` - Returns array
-- [x] `usb.findByIds()` - Returns Device or undefined
-- [x] `usb.on('detach')` - Event emitter
-
-## Testing Status
-
-All tests updated and verified:
-- ✅ Unit tests for USB adapter
-- ✅ Mock structure matches v2 API
-- ✅ Error scenarios covered
-- ✅ Integration tests compatible
-
-## Breaking Changes Handled
-
-1. **Callbacks → Promises**: All callback-based methods converted
-2. **Interface Access**: Updated to use `device.interfaces` array
-3. **Error Handling**: Changed from error-first callbacks to try/catch
-4. **Endpoint Structure**: Added support for `endpoint.interface` property
-
-## Remaining Considerations
-
-### Platform-Specific Notes
-- Windows: Interface claiming handled differently (no kernel driver)
-- Linux/macOS: Kernel driver detach/attach properly handled
-
-### Performance
-- No performance degradation expected
-- Promise-based code may be slightly more efficient
-
-### Backward Compatibility
-- **Not compatible** with v1 API
-- Users must upgrade to v2 if using this library
-
-## Verification Steps
-
-To verify the update:
-
-1. **Install dependencies**:
-   ```bash
-   npm install
-   ```
-
-2. **Run tests**:
-   ```bash
-   npm test
-   ```
-
-3. **Test with real hardware** (if available):
-   ```bash
-   node examples/printTest.js
-   ```
-
-## References
-
-- [node-usb v2 Documentation](https://node-usb.github.io/node-usb/)
-- [node-usb GitHub](https://github.com/node-usb/node-usb)
-- [Migration Guide](./USB_V2_MIGRATION.md)
-

package/docs/VERIFICATION_RESULTS.md

@@ -1,172 +0,0 @@
-# Pre-Publish Verification Results
-
-Date: 2025-11-23  
-Version: 0.1.0 (published)
-
-## ✅ All Verifications Passed
-
-### 1. NPM Package Verification ✅
-- **Status**: PASSED
-- **Package Name**: `@risleylima/escpos`
-- **Current Version**: `0.0.14`
-- **Files Included**: 
-  - ✅ Essential files (index.js, README.md, LICENSE, CHANGELOG.md)
-  - ✅ Source code (src/)
-  - ✅ Documentation (docs/)
-  - ✅ Examples (examples/)
-  - ✅ Configuration (package.json, jest.config.js)
-  - ✅ No node_modules included
-  - ✅ No test files included
-  - ✅ No .git included
-- **Package Size**: Reasonable (all files listed correctly)
-
-### 2. Dependencies Verification ✅
-- **Status**: PASSED
-- **Vulnerabilities**: 0 found (yarn audit)
-- **Outdated Dependencies**: 
-  - Only `get-pixels` shows as "exotic" (custom fork from GitHub - expected)
-  - All other dependencies are up to date
-- **Dependency Versions**:
-  - `usb@^2.16.0` ✅
-  - `serialport@^13.0.0` ✅
-  - `debug@^4.4.3` ✅
-  - `iconv-lite@^0.7.0` ✅
-  - `jest@^30.2.0` ✅
-
-### 3. Code Verification ✅
-- **Status**: PASSED
-- **Syntax**: No errors
-- **Exports**: All working correctly
-- **Load Time**: 0.083s (excellent performance)
-
-### 4. Test Verification ✅
-- **Status**: PASSED
-- **Total Tests**: 145
-- **Test Suites**: 9
-- **All Tests**: ✅ PASSING
-- **Coverage**:
-  - Statements: 100%
-  - Branches: 100%
-  - Functions: 100%
-  - Lines: 100%
-- **Result**: Perfect coverage achieved
-
-### 5. Compatibility Verification ✅
-- **Status**: PASSED
-- **Node.js Version**: v20.19.5 (current)
-- **Required Version**: >=18.0.0
-- **Compatibility**: ✅ Compatible
-- **Note**: Should test on Node.js 18 (minimum version) if possible
-
-### 6. Documentation Verification ✅
-- **Status**: PASSED
-- **README.md**: ✅ Complete and updated
-- **CHANGELOG.md**: ✅ Created with all changes
-- **JSDoc**: ✅ Complete (100% coverage)
-- **Additional Docs**: ✅ All translated to English
-- **Examples**: ✅ Present and documented
-
-### 7. Git Verification ✅
-- **Status**: PASSED
-- **Current Branch**: `main`
-- **Tags**: v0.0.5 through v0.0.9 exist
-- **Status**: Changes present (expected before commit)
-- **Sensitive Files**: ✅ None found (only documentation mentions)
-
-### 8. Build Verification ✅
-- **Status**: N/A (No build step required)
-- **Note**: This is a pure JavaScript library, no compilation needed
-
-### 9. Local Publication Verification ✅
-- **Status**: PASSED
-- **Exports Test**: ✅ All exports working
-  - USB ✅
-  - Serial ✅
-  - Printer ✅
-  - Adapter ✅
-  - Image ✅
-
-### 10. Versioning Verification ✅
-- **Status**: PASSED
-- **Current Version**: 0.0.14
-- **Next Version**: 0.1.0 (minor update)
-- **Semantic Versioning**: ✅ Follows semver
-- **CHANGELOG**: ✅ Version 0.0.14 found in CHANGELOG
-- **Breaking Changes**: None in public API
-
-### 11. Package Metadata Verification ✅
-- **Status**: PASSED
-- **Name**: `@risleylima/escpos` ✅
-- **Version**: `0.0.14` ✅
-- **Description**: "Library to deal with ESCPOS using some adapters" ✅
-- **Main**: `index.js` ✅
-- **Keywords**: ["EscPos", "USB"] ✅
-- **Author**: "Rlima Info" ✅
-- **License**: "MIT" ✅
-- **Repository**: `git+https://github.com/risleylima/escpos.git` ✅
-- **Bugs**: `https://github.com/risleylima/escpos/issues` ✅
-- **Homepage**: `https://github.com/risleylima/escpos#readme` ✅
-
-### 12. Security Verification ✅
-- **Status**: PASSED
-- **Vulnerabilities**: 0 found
-- **Sensitive Data**: ✅ None found
-  - No passwords
-  - No secrets
-  - No tokens
-  - No API keys
-- **Note**: Only documentation mentions of these terms (expected)
-
-### 13. Performance Verification ✅
-- **Status**: PASSED
-- **Load Time**: 0.083s (excellent)
-- **Package Size**: Reasonable
-- **Dependencies**: Only necessary ones included
-
-### 14. Essential Files Verification ✅
-- **Status**: PASSED
-- **index.js**: ✅ Present
-- **README.md**: ✅ Present
-- **LICENSE**: ✅ Present
-- **CHANGELOG.md**: ✅ Present
-- **package.json**: ✅ Present
-
-## 📊 Summary
-
-| Category | Status | Details |
-|----------|--------|---------|
-| Package | ✅ PASSED | All files correctly included |
-| Dependencies | ✅ PASSED | 0 vulnerabilities, all up to date |
-| Code | ✅ PASSED | No errors, fast load time |
-| Tests | ✅ PASSED | 145 tests, 100% coverage |
-| Compatibility | ✅ PASSED | Node.js >=18.0.0 |
-| Documentation | ✅ PASSED | Complete and in English |
-| Git | ✅ PASSED | On main branch |
-| Exports | ✅ PASSED | All working |
-| Versioning | ✅ PASSED | Follows semver |
-| Metadata | ✅ PASSED | All correct |
-| Security | ✅ PASSED | 0 vulnerabilities |
-| Performance | ✅ PASSED | Excellent |
-| Files | ✅ PASSED | All present |
-
-## 🎯 Ready for Publication
-
-**All verifications passed!** The package was successfully published as v0.1.0.
-
-### Next Steps:
-1. Review CHANGELOG.md
-2. Commit changes (if needed)
-3. Run `npx np minor` to publish
-
-### Notes:
-- The package is in excellent condition
-- All dependencies are up to date
-- 100% test coverage achieved
-- Documentation is complete and in English
-- No security vulnerabilities
-- Performance is excellent
-
----
-
-**Verification completed successfully! ✅**
-

package/docs/VERSIONING.md

@@ -1,102 +0,0 @@
-# Semantic Versioning Rules
-
-This document defines the explicit versioning rules for this project.
-
-## Version Format
-
-Following [Semantic Versioning](https://semver.org/spec/v2.0.0.html): `MAJOR.MINOR.PATCH`
-
-## Versioning Rules
-
-### Starting from `0.0.0`:
-
-#### MINOR Update: `0.0.0` → `0.0.1`
-- **When to use**: Adding new features, functions, or methods
-- **Examples**:
-  - Adding a new function like `Serial.listSerial()`
-  - Adding a new method to an existing class
-  - Adding new functionality that doesn't break existing code
-- **Rule**: New features = increment MINOR (third number)
-
-#### MAJOR Update: `0.0.0` → `0.1.0`
-- **When to use**: Significant changes, major updates, or substantial improvements
-- **Examples**:
-  - Major dependency updates (e.g., `usb@^1.9.1` → `usb@^2.16.0`)
-  - Major refactoring
-  - Significant architectural changes
-  - Multiple new features bundled together
-- **Rule**: Major changes = increment MAJOR (second number) when in `0.x.x` range
-
-#### BREAKING CHANGES: `0.0.0` → `1.0.0`
-- **When to use**: Breaking changes to the public API
-- **Examples**:
-  - Removing or renaming public methods
-  - Changing method signatures in a way that breaks existing code
-  - Removing exported modules
-  - Changing behavior in a way that breaks backward compatibility
-- **Rule**: Breaking changes = increment to `1.0.0` (first number)
-
-## Examples from This Project
-
-### `0.0.14` → `0.0.15` (MINOR)
-- Adding a single new function: `Serial.listSerial()`
-- This is a **MINOR** update (patch increment)
-
-### `0.0.14` → `0.1.0` (MAJOR)
-- Major dependency updates (usb v1 → v2, serialport v12 → v13)
-- Complete test suite addition
-- Comprehensive documentation
-- Multiple significant improvements bundled together
-- This is a **MAJOR** update (minor increment in 0.x.x range)
-
-### Future: `0.x.x` → `1.0.0` (BREAKING)
-- If we remove `USB.listUSB()` method
-- If we change `Printer` constructor signature
-- If we remove support for a feature
-- This would be a **BREAKING** change (major increment to 1.0.0)
-
-## Decision Tree
-
-```
-Is it a bug fix or small correction?
-  YES → PATCH (0.0.0 → 0.0.1)
-
-Is it a single new feature/function?
-  YES → MINOR (0.0.0 → 0.0.1)
-
-Is it multiple features or major updates?
-  YES → MAJOR (0.0.0 → 0.1.0)
-
-Does it break existing code/API?
-  YES → BREAKING (0.0.0 → 1.0.0)
-```
-
-## Important Notes
-
-1. **In `0.x.x` range**: 
-   - The second number (MINOR) acts as MAJOR
-   - The third number (PATCH) acts as MINOR
-   - This is standard Semantic Versioning behavior for pre-1.0.0 versions
-
-2. **After `1.0.0`**:
-   - Standard semver rules apply
-   - MAJOR.MINOR.PATCH
-   - Breaking changes = MAJOR increment
-   - New features = MINOR increment
-   - Bug fixes = PATCH increment
-
-3. **Always consider**:
-   - Impact on users
-   - Backward compatibility
-   - Number of changes
-   - Significance of changes
-
-## Summary Table
-
-| Change Type | From `0.0.0` | Example |
-|-------------|--------------|---------|
-| Bug fix | `0.0.1` | Fix typo, fix error handling |
-| New function/method | `0.0.1` | Add `Serial.listSerial()` |
-| Major updates | `0.1.0` | Dependency updates, major refactoring |
-| Breaking changes | `1.0.0` | Remove API, change signatures |
-

package/examples/printTest.js

@@ -1,59 +0,0 @@
-'use strict';
-// DEBUGGER
-const debug = require('debug')('escpos:test-printer');
-
-//IMPORT USB ADAPTER
-const USB = require('../src/usb-adapter');
-
-//IMPORT PRINTER MANAGER
-const Printer = require('../src/printer');
-
-let print = async (printer, n) => {
-  printer.hardware('init');
-  printer
-    .beep(2, 1)
-    .encode(860)
-    .size(2, 2)
-    .align('ct')
-    .textln('PRINT CUPOM TEST')
-    .size(1, 1)
-    .textln(`Cupom Nº ${n}`)
-    .align('lt')
-    .textln(`Mr. Fulano Maluco`)
-    .textln(`TEL: +55 (11) 3453-6549`)
-    .textln(`ADDRESS: Rua Prof. Vida Louca, 500 - Casa B`)
-    .textln(`POSTAL CODE: 56589-085  - MARINGA - PR`)
-    .align('ct')
-    .textln(`What is your favorite color?`)
-    .align('lt')
-    .textln('(___) Red')
-    .textln('(___) Green')
-    .textln('(___) Other: __________________________')
-    .align('ct')
-    .raw(printer.commands.TEXT_FORMAT.TXT_BOLDER)
-    .textln('Check the rules of this promotion')
-    .textln('FREE DISTRIBUTION')
-    .raw(printer.commands.TEXT_FORMAT.TXT_NORMAL)
-    .drawLine()
-    .cut(true);
-
-  await printer.flush();
-};
-
-(async () => {
-  let vid = 1046, pid = 20497;
-  await USB.connect(vid, pid);
-  const printerDevice = new Printer(USB);
-
-  for (let i = 0; i < 3; i++) {
-    await USB.open();
-    await print(printerDevice, i);
-    debug('Printed ' + i + ' of ' + 3);
-    await USB.close();
-  }
-  await USB.disconnect();
-  process.exit();
-})().catch(e => {
-  debug(e);
-  process.exit();
-});

package/index.js

@@ -1,7 +0,0 @@
-const USB = require('./src/usb-adapter');
-const Serial = require('./src/serial-adapter');
-const Printer = require('./src/printer');
-const Adapter = require('./src/adapter');
-const Image = require('./src/printer/image');
-
-module.exports = { USB, Serial, Printer, Adapter, Image }

package/jest.config.js

@@ -1,16 +0,0 @@
-module.exports = {
-  testEnvironment: 'node',
-  testMatch: [
-    '**/tests/**/*.test.js',
-    '**/__tests__/**/*.js'
-  ],
-  collectCoverageFrom: [
-    'src/**/*.js',
-    '!src/**/index.js'
-  ],
-  coverageDirectory: 'coverage',
-  coverageReporters: ['text', 'lcov', 'html'],
-  verbose: true,
-  testTimeout: 10000
-};
-

package/src/adapter/index.js

@@ -1,75 +0,0 @@
-'use strict'
-const EventEmitter = require('events');
-
-class NotImplementedException extends Error {
-  // Nothing.
-}
-
-/**
- * Generic Adapter that will implement the different types of adapter that will be constructed
- * @class
- * @extends EventEmitter
- * @classdesc Base adapter class that provides the interface for USB and Serial adapters
- */
-class Adapter extends EventEmitter {
-  /**
-   * Creates an instance of Adapter
-   * @param {Adapter} [adapter] - Optional adapter instance to copy properties from
-   */
-  constructor(adapter) {
-    super();
-    if (adapter) {
-      for(let key of Object.keys(adapter)){
-        this[key] = adapter[key];
-      }
-    }
-  }
-
-  /**
-   * Connect to the device
-   * @abstract
-   * @throws {NotImplementedException} Must be implemented by subclasses
-   */
-  connect() {
-    throw new NotImplementedException();
-  }
-
-  /**
-   * Open the device connection
-   * @abstract
-   * @throws {NotImplementedException} Must be implemented by subclasses
-   */
-  open() {
-    throw new NotImplementedException();
-  }
-
-  /**
-   * Write data to the device
-   * @abstract
-   * @param {Buffer} data - Data to write
-   * @throws {NotImplementedException} Must be implemented by subclasses
-   */
-  write() {
-    throw new NotImplementedException();
-  }
-
-  /**
-   * Close the device connection
-   * @abstract
-   * @throws {NotImplementedException} Must be implemented by subclasses
-   */
-  close() {
-    throw new NotImplementedException();
-  }
-
-  /**
-   * Read data from the device
-   * @abstract
-   * @throws {NotImplementedException} Must be implemented by subclasses
-   */
-  read() {
-    throw new NotImplementedException();
-  }
-}
-
-module.exports = Adapter;