@risleylima/escpos 0.2.1 → 1.0.1

package/docs/PRE_PUBLISH_CHECKLIST.md

@@ -1,331 +0,0 @@
-# Pre-Publish Checklist
-
-This document lists all additional checks possible before publishing a new version to NPM.
-
-## ✅ Basic Checks (Already Done)
-
-- [x] Tests passing (145 tests, 100% coverage)
-- [x] Exports working correctly
-- [x] Essential files present (index.js, README.md, LICENSE)
-- [x] Valid package.json
-- [x] CHANGELOG.md created
-
-## 🔍 Additional Recommended Checks
-
-### 1. NPM Package Verification
-
-```bash
-# Simulate what will be published
-npm pack --dry-run
-
-# Check package size
-npm pack
-tar -tzf *.tgz | wc -l  # Count files
-du -h *.tgz             # Tarball size
-rm *.tgz                # Clean up
-```
-
-**What to check:**
-- ✅ Only necessary files are included
-- ✅ `node_modules` is not included
-- ✅ Build/test files are not included
-- ✅ `.git` is not included
-- ✅ Reasonable package size
-
-### 2. Dependencies Verification
-
-```bash
-# Check installed dependencies
-yarn list --depth=0
-
-# Check vulnerabilities
-npm audit
-# or
-yarn audit
-
-# Check outdated dependencies
-npm outdated
-# or
-yarn outdated
-```
-
-**What to check:**
-- ✅ No known vulnerabilities
-- ✅ Dependencies are at correct versions
-- ✅ Peer dependencies documented (if any)
-
-### 3. Code Verification
-
-```bash
-# Check syntax (if using linter)
-npm run lint  # if configured
-
-# Check types (if using TypeScript)
-npm run type-check  # if configured
-
-# Check formatting
-npm run format:check  # if configured
-```
-
-**What to check:**
-- ✅ No syntax errors
-- ✅ No critical warnings
-- ✅ Code consistently formatted
-
-### 4. Test Verification
-
-```bash
-# Run all tests
-yarn test
-
-# Run tests with coverage
-yarn test:coverage
-
-# Check if coverage is above threshold
-# (if configured in jest.config.js)
-```
-
-**What to check:**
-- ✅ All tests passing
-- ✅ Adequate coverage (100% in our case)
-- ✅ Integration tests passing
-- ✅ Tests on different Node.js versions (if applicable)
-
-### 5. Compatibility Verification
-
-```bash
-# Test on different Node.js versions
-nvm use 18
-yarn test
-
-nvm use 20
-yarn test
-
-# Check engines in package.json
-node -e "console.log(require('./package.json').engines)"
-```
-
-**What to check:**
-- ✅ Compatible with Node.js >= 18.0.0 (as per package.json)
-- ✅ Tested on minimum supported version
-- ✅ Tested on current LTS version
-
-### 6. Documentation Verification
-
-```bash
-# Check if README is updated
-# Check if CHANGELOG is updated
-# Check if examples work
-node examples/printTest.js  # (without connecting real hardware)
-```
-
-**What to check:**
-- ✅ README.md complete and updated
-- ✅ CHANGELOG.md with all changes
-- ✅ Code examples work
-- ✅ API documentation is correct
-- ✅ Links working
-
-### 7. Git Verification
-
-```bash
-# Check git status
-git status
-
-# Check for uncommitted changes
-git diff
-
-# Check existing tags
-git tag -l
-
-# Check last commit
-git log -1
-```
-
-**What to check:**
-- ✅ All changes committed (or intentionally uncommitted)
-- ✅ Correct branch (usually `main` or `master`)
-- ✅ No sensitive files (tokens, passwords, etc.)
-- ✅ `.gitignore` properly configured
-
-### 8. Build Verification (if applicable)
-
-```bash
-# If there's a build step
-npm run build
-
-# Check if build files were generated
-ls -la dist/  # or build folder
-```
-
-**What to check:**
-- ✅ Build completes without errors
-- ✅ Build files generated correctly
-- ✅ Build files included in package (if necessary)
-
-### 9. Local Publication Verification
-
-```bash
-# Install package locally to test
-npm link
-# or
-cd /tmp
-npm install /path/to/escpos
-
-# Test import
-node -e "const { USB, Serial, Printer } = require('@risleylima/escpos'); console.log('OK')"
-```
-
-**What to check:**
-- ✅ Package can be installed
-- ✅ Exports work after installation
-- ✅ Dependencies are installed correctly
-
-### 10. Versioning Verification
-
-```bash
-# Check current version
-node -e "console.log(require('./package.json').version)"
-
-# Check if version follows semantic versioning
-# MAJOR.MINOR.PATCH
-# 0.0.14 -> 0.1.0 (minor update)
-```
-
-**What to check:**
-- ✅ Version follows Semantic Versioning
-- ✅ Version in package.json is correct
-- ✅ Version in CHANGELOG is correct
-- ✅ Breaking changes documented (if any)
-
-### 11. Package Metadata Verification
-
-```bash
-# Check package.json
-node -e "const pkg = require('./package.json'); console.log(JSON.stringify({
-  name: pkg.name,
-  version: pkg.version,
-  description: pkg.description,
-  main: pkg.main,
-  keywords: pkg.keywords,
-  author: pkg.author,
-  license: pkg.license,
-  repository: pkg.repository,
-  bugs: pkg.bugs,
-  homepage: pkg.homepage
-}, null, 2))"
-```
-
-**What to check:**
-- ✅ Package name correct
-- ✅ Clear and updated description
-- ✅ Relevant keywords
-- ✅ Correct author and license
-- ✅ Repository, bugs, and homepage links working
-
-### 12. Security Verification
-
-```bash
-# Check vulnerabilities
-npm audit
-yarn audit
-
-# Check for sensitive files
-grep -r "password\|secret\|token\|api_key" --exclude-dir=node_modules .
-```
-
-**What to check:**
-- ✅ No known vulnerabilities
-- ✅ No hardcoded credentials
-- ✅ No tokens or API keys in code
-
-### 13. Performance Verification (Optional)
-
-```bash
-# Test load time
-time node -e "require('./index.js')"
-
-# Check bundle size (if applicable)
-npm run build:analyze  # if configured
-```
-
-**What to check:**
-- ✅ Reasonable load time
-- ✅ Optimized package size
-- ✅ No unnecessary dependencies
-
-### 14. Accessibility Verification (Optional)
-
-```bash
-# Check if README is readable
-# Check if examples are clear
-# Check if documentation is complete
-```
-
-**What to check:**
-- ✅ README well formatted
-- ✅ Clear and functional examples
-- ✅ Complete documentation
-
-## 🚀 `np` Commands
-
-The `np` tool automatically performs many of these checks:
-
-```bash
-npx np minor
-```
-
-**What `np` automatically checks:**
-- ✅ Git status (uncommitted changes)
-- ✅ Correct branch
-- ✅ Tests (if configured)
-- ✅ Build (if configured)
-- ✅ Versioning
-- ✅ Git tag
-- ✅ NPM publication
-
-## 📋 Final Checklist Before Publishing
-
-- [ ] All tests passing
-- [ ] Adequate test coverage
-- [ ] CHANGELOG.md updated
-- [ ] README.md updated
-- [ ] No known vulnerabilities
-- [ ] Dependencies updated
-- [ ] Code reviewed
-- [ ] Git status clean (or intentional changes)
-- [ ] Correct version in package.json
-- [ ] Correct version in CHANGELOG
-- [ ] Package metadata correct
-- [ ] Examples tested (if possible)
-- [ ] Compatibility verified
-
-## 🎯 Specific Recommendations for This Version
-
-For v0.1.0, check especially:
-
-1. **Major Dependency Updates:**
-   - [x] `usb@^2.16.0` - Promise-based API working
-   - [x] `serialport@^13.0.0` - Promise-based API working
-   - [x] Tests updated for new APIs
-
-2. **Documentation:**
-   - [x] Complete README
-   - [x] CHANGELOG created
-   - [x] Complete JSDoc
-
-3. **Tests:**
-   - [x] 100% coverage
-   - [x] All tests passing
-
-4. **Compatibility:**
-   - [x] Public API maintained (no breaking changes)
-   - [x] Exports working
-
-## ⚠️ Important Notes
-
-- **Internal Breaking Changes**: The `usb` and `serialport` updates are major, but the library's public API has not changed. It's safe to publish as a minor update.
-
-- **Hardware Testing**: If possible, test with real hardware before publishing, especially after the `usb` and `serialport` updates.
-
-- **Rollback Plan**: Have a rollback plan in case something goes wrong after publication.

package/docs/PUBLIC_API_ANALYSIS.md

@@ -1,223 +0,0 @@
-# Public API Analysis - Breaking Changes Impact
-
-## 📦 What the Library Exports
-
-### Main Exports (`index.js`)
-```javascript
-module.exports = { 
-  USB,      // USB Adapter instance
-  Serial,   // Serial Adapter instance  
-  Printer,  // Printer class
-  Adapter,  // Base Adapter class
-  Image     // Image class
-}
-```
-
-## 🔌 Public API - Adapters
-
-### USB Adapter Public Methods
-```javascript
-USB.connect(vid, pid)      // Returns: Promise<boolean>
-USB.open()                 // Returns: Promise<boolean>
-USB.write(data)            // Returns: Promise<boolean>
-USB.close()                // Returns: Promise<boolean>
-USB.disconnect()           // Returns: Promise<boolean>
-USB.listUSB()              // Returns: Promise<Device[]>
-```
-
-### Serial Adapter Public Methods
-```javascript
-Serial.connect(port, options)  // Returns: Promise<boolean>
-Serial.open()                  // Returns: Promise<boolean>
-Serial.write(data)             // Returns: Promise<boolean>
-Serial.close(timeout)          // Returns: Promise<boolean>
-Serial.disconnect(timeout)     // Returns: Promise<boolean>
-Serial.read()                  // Returns: Promise<Buffer>
-```
-
-### Printer Public Methods
-```javascript
-// Constructor
-new Printer(adapter, options)
-
-// Text operations
-printer.text(content, encoding)
-printer.textln(content, encoding)
-printer.print(content)
-printer.println(content)
-
-// Formatting
-printer.align('lt'|'ct'|'rt')
-printer.size(width, height)
-printer.font('A'|'B'|'C')
-printer.style('B'|'I'|'U'|'NORMAL'|...)
-printer.encode(encoding)
-
-// Paper control
-printer.feed(n)
-printer.drawLine(character)
-printer.cut(partial, feed)
-
-// Hardware
-printer.hardware('init'|'select'|'reset')
-printer.beep(n, t)
-printer.cashdraw(pin)
-
-// Barcodes
-printer.barcode(code, type, options)
-
-// Images
-printer.image(image, density)
-printer.raster(image, mode)
-
-// Colors
-printer.color(0|1)
-printer.setReverseColors(bool)
-
-// Raw commands
-printer.raw(data)
-
-// Control
-printer.flush()    // Returns: Promise<Printer>
-printer.close()    // Returns: Promise<Printer>
-```
-
-## 🔍 Impact Analysis
-
-### ✅ GOOD NEWS: No Breaking Changes to Public API!
-
-#### 1. Adapter Interface Remains the Same
-- **USB Adapter**: All methods already return Promises
-- **Serial Adapter**: All methods already return Promises
-- **Method signatures**: Unchanged
-- **Return types**: Unchanged (all Promises)
-
-#### 2. Internal Implementation Changes Only
-- **USB v2 migration**: Internal implementation changed (callbacks → Promises)
-- **SerialPort v13 migration**: Internal implementation will change (callbacks → Promises)
-- **Public API**: Remains exactly the same
-
-#### 3. Printer Class Unaffected
-- Printer class doesn't directly use USB/SerialPort
-- Uses adapters through the Adapter interface
-- No changes needed
-
-### 📊 Compatibility Matrix
-
-| Component | Internal Change | Public API Change | Breaking Change? |
-|-----------|----------------|-------------------|------------------|
-| USB Adapter | ✅ v1 → v2 (callbacks → Promises) | ❌ None | ❌ **NO** |
-| Serial Adapter | ✅ v12 → v13 (callbacks → Promises) | ❌ None | ❌ **NO** |
-| Printer | ❌ None | ❌ None | ❌ **NO** |
-| Adapter Base | ❌ None | ❌ None | ❌ **NO** |
-| Image | ❌ None | ❌ None | ❌ **NO** |
-
-## 🎯 User Code Examples
-
-### Example 1: USB Usage (Won't Change)
-```javascript
-const { USB, Printer } = require('@risleylima/escpos');
-
-// This code will work EXACTLY the same after updates
-await USB.connect(1046, 20497);
-const printer = new Printer(USB);
-await USB.open();
-printer.textln('Hello');
-await printer.flush();
-await USB.close();
-await USB.disconnect();
-```
-
-### Example 2: Serial Usage (Won't Change)
-```javascript
-const { Serial, Printer } = require('@risleylima/escpos');
-
-// This code will work EXACTLY the same after updates
-await Serial.connect('/dev/ttyUSB0');
-const printer = new Printer(Serial);
-await Serial.open();
-printer.textln('Hello');
-await printer.flush();
-await Serial.close();
-```
-
-### Example 3: Printer Usage (Won't Change)
-```javascript
-const { Printer } = require('@risleylima/escpos');
-
-// All Printer methods remain the same
-printer
-  .align('ct')
-  .size(2, 2)
-  .textln('Title')
-  .cut(true);
-await printer.flush();
-```
-
-## ✅ Conclusion
-
-### **NO BREAKING CHANGES FOR USERS!**
-
-1. **Public API**: Completely unchanged
-2. **Method signatures**: Identical
-3. **Return types**: Same (all Promises)
-4. **Usage patterns**: No changes needed
-5. **Backward compatibility**: 100% maintained
-
-### Why No Breaking Changes?
-
-1. **Abstraction Layer**: Adapters abstract away the underlying libraries
-2. **Promise-based API**: Public API was already Promise-based
-3. **Internal Only**: Changes are purely internal implementation
-4. **Interface Contract**: Adapter interface contract remains the same
-
-### What Users Need to Know
-
-#### ✅ No Action Required
-- Existing code will continue to work
-- No code changes needed
-- No API changes
-
-#### ⚠️ Potential Considerations
-- **Node.js version**: Ensure Node.js >= 18.0.0 (already required)
-- **Native modules**: May need rebuild after `npm install`
-- **Dependencies**: Will get updated versions automatically
-
-### Version Strategy
-
-Since there are **NO breaking changes** to the public API:
-- **Minor version bump**: `0.0.14` → `0.1.0` (published)
-
-**NOT a major version** because public API is unchanged.
-
-## 📝 Migration Notes for Library Maintainers
-
-### Internal Changes Summary
-
-1. **USB Adapter** (`src/usb-adapter/index.js`)
-   - ✅ Updated to use `usb@^2.16.0`
-   - ✅ Converted callbacks to async/await
-   - ✅ Public API unchanged
-
-2. **Serial Adapter** (`src/serial-adapter/index.js`) - To be done
-   - ⏳ Will update to `serialport@^13.0.0`
-   - ⏳ Will convert callbacks to async/await
-   - ✅ Public API will remain unchanged
-
-3. **Printer** (`src/printer/index.js`)
-   - ✅ No changes needed
-   - ✅ Uses adapters through interface
-
-### Testing Strategy
-
-1. ✅ Unit tests updated for new implementations
-2. ✅ Integration tests verify public API
-3. ⚠️ Test with real hardware (recommended)
-4. ✅ Backward compatibility verified
-
-## 🎉 Summary
-
-**Users can update with confidence!** 
-
-The library maintains 100% backward compatibility. All changes are internal improvements that don't affect the public API. Existing code will work without any modifications.
-

package/docs/README.md

@@ -1,37 +0,0 @@
-# Documentation
-
-This directory contains additional documentation for the EscPos library.
-
-## Available Documents
-
-### [Library Overview](./LIBRARY_OVERVIEW.md) ⭐
-Comprehensive overview of the library including architecture, features, test coverage, dependencies, and recent improvements.
-
-### [USB v2 Review](./USB_V2_REVIEW.md)
-Complete review of codebase compatibility with USB v2, including all changes made, test updates, and verification checklist.
-
-### [SerialPort v13 Migration](./SERIALPORT_V13_MIGRATION_COMPLETE.md)
-Documentation about the migration from `serialport@^12.0.0` to `serialport@^13.0.0`, including API changes and implementation details.
-
-### [Dependencies Review](./DEPENDENCIES_REVIEW.md)
-Current status of all dependencies, update history, and recommendations.
-
-### [Tests Implementation](./TESTS_IMPLEMENTED.md)
-Complete documentation about the test suite implementation, coverage, and testing strategy.
-
-### [Test Coverage Analysis](./COVERAGE_ANALYSIS.md)
-Detailed analysis of test coverage, including branch coverage and steps taken to achieve 100% coverage.
-
-### [JSDoc Review](./JSDOC_REVIEW.md)
-Complete review of JSDoc documentation coverage across the library.
-
-### [Public API Analysis](./PUBLIC_API_ANALYSIS.md)
-Detailed analysis of the public API and exported modules, including breaking changes impact assessment.
-
-### [Versioning Rules](./VERSIONING.md) ⚠️
-Explicit semantic versioning rules for the project. **Read this before publishing any version update.**
-
-## Main Documentation
-
-- **README.md** (root) - Main project documentation with installation, usage examples, and API reference
-- **tests/README.md** - Test suite documentation

package/docs/SERIALPORT_V13_MIGRATION_COMPLETE.md

@@ -1,127 +0,0 @@
-# SerialPort v13 Migration - Complete
-
-## ✅ Migration Executed
-
-Successfully migrated from `serialport@^12.0.0` to `serialport@^13.0.0`.
-
-## Changes Made
-
-### 1. Package Update
-- ✅ Updated `package.json`: `"serialport": "^12.0.0"` → `"serialport": "^13.0.0"`
-
-### 2. Code Migration (`src/serial-adapter/index.js`)
-
-#### Constructor Changes
-**Before (v12):**
-```javascript
-scope.port = new SerialPort({ path, autoOpen: true }, (err) => {
-  // callback
-});
-```
-
-**After (v13):**
-```javascript
-scope.port = new SerialPort({ path, autoOpen: false });
-// Handle errors via events
-scope.port.on('error', (err) => { /* ... */ });
-await scope.port.open(); // Open manually
-```
-
-#### Method Conversions
-
-| Method | v12 (Callback) | v13 (Promise) |
-|--------|----------------|---------------|
-| `connect()` | Callback-based | ✅ `async/await` |
-| `open()` | `port.open(callback)` | ✅ `await port.open()` |
-| `write()` | `port.write(data, callback)` | ✅ `await port.write(data)` |
-| `close()` | Nested callbacks | ✅ `async/await` chain |
-| `flush()` | `port.flush(callback)` | ✅ `await port.flush()` |
-| `drain()` | `port.drain(callback)` | ✅ `await port.drain()` |
-
-### 3. Test Updates (`tests/unit/adapters/serial-adapter.test.js`)
-
-- ✅ Updated mocks to return Promises
-- ✅ Changed callback-based mocks to async functions
-- ✅ Updated test expectations
-- ✅ Added verification of method calls
-
-## Key Improvements
-
-### 1. Cleaner Code
-- Removed nested callbacks
-- Modern async/await syntax
-- Better error handling with try/catch
-
-### 2. Better Error Handling
-- Errors now propagate via exceptions
-- Try/catch blocks for cleaner error handling
-- Proper cleanup on errors
-
-### 3. Consistent API
-- All methods now use async/await consistently
-- Matches USB adapter pattern (already migrated)
-
-## Public API - No Breaking Changes
-
-✅ **All public methods maintain the same signature:**
-- `Serial.connect(port, options)` → `Promise<boolean>`
-- `Serial.open()` → `Promise<boolean>`
-- `Serial.write(data)` → `Promise<boolean>`
-- `Serial.close(timeout)` → `Promise<boolean>`
-- `Serial.disconnect(timeout)` → `Promise<boolean>`
-- `Serial.read()` → `Promise<Buffer>`
-
-## Files Modified
-
-1. ✅ `package.json` - Version updated
-2. ✅ `src/serial-adapter/index.js` - Complete migration
-3. ✅ `tests/unit/adapters/serial-adapter.test.js` - Tests updated
-
-## Testing
-
-### Unit Tests
-- ✅ All tests updated for v13 API
-- ✅ Mocks properly simulate Promise-based API
-- ✅ Test expectations verified
-
-### Next Steps
-1. Run tests: `npm test`
-2. Test with real hardware (if available)
-3. Verify all functionality works as expected
-
-## Compatibility
-
-### ✅ Backward Compatible
-- Public API unchanged
-- Method signatures identical
-- Return types unchanged (all Promises)
-- No breaking changes for users
-
-### Requirements
-- Node.js >= 18.0.0 (already specified)
-- Native module compilation may be required
-
-## Migration Summary
-
-| Aspect | Status |
-|--------|--------|
-| Package Update | ✅ Complete |
-| Code Migration | ✅ Complete |
-| Test Updates | ✅ Complete |
-| Public API | ✅ Unchanged |
-| Breaking Changes | ❌ None |
-
-## Notes
-
-- Constructor no longer accepts callback (v13 change)
-- `autoOpen: false` now required, open manually
-- All methods return Promises (consistent with v13)
-- Error handling via try/catch instead of callbacks
-- Event-based error handling for constructor errors
-
-## References
-
-- [SerialPort Documentation](https://serialport.io/)
-- [Migration Plan](./SERIALPORT_V13_MIGRATION_PLAN.md)
-- [Public API Analysis](./PUBLIC_API_ANALYSIS.md)
-