@risleylima/escpos 0.0.13 → 0.1.0

package/docs/COVERAGE_ANALYSIS.md

@@ -0,0 +1,98 @@
+# Test Coverage Analysis
+
+## Current Coverage Status
+
+- **Statements**: 100% ✅
+- **Branches**: 100% ✅ (was 88.09%, improved to 100%)
+- **Functions**: 100% ✅
+- **Lines**: 100% ✅
+
+**Status**: ✅ **100% Coverage Achieved!**
+
+## Uncovered Branches
+
+### 1. `commands.js` - `numToHexString` function (Line 12)
+
+```javascript
+if (!isNaN(num)) {
+  // This branch is covered
+} 
+// Missing: else branch when isNaN(num) === true
+```
+
+**Issue**: The function doesn't test the case when `Number(value)` results in `NaN`.
+
+**Current Test**: None - this function is only tested indirectly through other functions.
+
+**Fix Needed**: Test with invalid input (e.g., `numToHexString('invalid')` or `numToHexString(NaN)`).
+
+### 2. `commands.js` - `TXT_CUSTOM_SIZE` function (Lines 77-80)
+
+```javascript
+width = width > 8 ? 8 : width;      // Branch: width > 8 not tested
+width = width < 1 ? 1 : width;      // Branch: width < 1 not tested
+height = height > 8 ? 8 : height;   // Branch: height > 8 not tested
+height = height < 1 ? 1 : height;    // Branch: height < 1 not tested
+```
+
+**Issue**: The `size()` method is only tested with normal values (2, 2), not edge cases.
+
+**Current Test**: 
+```javascript
+it('should set text size', () => {
+  printer.size(2, 2);
+  // Only tests normal case
+});
+```
+
+**Missing Tests**:
+- `printer.size(10, 2)` - width > 8 (should clamp to 8)
+- `printer.size(0, 2)` - width < 1 (should clamp to 1)
+- `printer.size(2, 10)` - height > 8 (should clamp to 8)
+- `printer.size(2, 0)` - height < 1 (should clamp to 1)
+- `printer.size(10, 10)` - both > 8
+- `printer.size(0, 0)` - both < 1
+
+## Impact
+
+The uncovered branches are **edge case validations** that:
+- Clamp values to valid ranges (1-8 for width/height)
+- Handle invalid input gracefully
+
+While these branches are defensive code, they should be tested to ensure:
+1. The clamping logic works correctly
+2. Invalid inputs don't cause errors
+3. The behavior is documented through tests
+
+## ✅ Resolution
+
+Tests have been added for all uncovered branches:
+
+1. **`numToHexString` tests** (`tests/unit/printer/commands.test.js`):
+   - ✅ NaN input handling
+   - ✅ Invalid input handling
+   - ✅ Edge cases (zero, large numbers, odd-length hex)
+
+2. **`TXT_CUSTOM_SIZE` tests** (`tests/unit/printer/commands.test.js`):
+   - ✅ Width clamping (> 8, < 1)
+   - ✅ Height clamping (> 8, < 1)
+   - ✅ Both parameters out of range
+   - ✅ Boundary values (1 and 8)
+   - ✅ Valid range values
+
+3. **`size()` method tests** (`tests/unit/printer/printer.test.js`):
+   - ✅ Width > 8 clamping
+   - ✅ Width < 1 clamping
+   - ✅ Height > 8 clamping
+   - ✅ Height < 1 clamping
+   - ✅ Both out of range
+
+## Results
+
+- **Before**: 88.09% branch coverage (50% in commands.js)
+- **After**: 100% branch coverage ✅
+- **New Tests Added**: 19 tests
+- **Total Tests**: 145 (was 126)
+
+All edge cases are now properly tested and documented!
+

package/docs/DEPENDENCIES_REVIEW.md

@@ -0,0 +1,127 @@
+# Dependencies Review
+
+## Current Dependencies Status
+
+### Production Dependencies
+
+| Package | Current | Latest | Status | Notes |
+|---------|---------|--------|--------|-------|
+| `debug` | `^4.4.3` | `4.4.3` | ✅ Up to date | Updated from 4.3.1 |
+| `get-pixels` | `https://github.com/risleylima/get-pixels` | N/A | ✅ Custom | Custom fork, version not tracked |
+| `iconv-lite` | `^0.7.0` | `0.7.0` | ✅ Up to date | Updated from 0.6.3 |
+| `serialport` | `^13.0.0` | `13.0.0` | ✅ Up to date | Updated from 12.0.0 |
+| `usb` | `^2.16.0` | `2.16.0` | ✅ Up to date | Updated from 1.9.1 |
+
+### Development Dependencies
+
+| Package | Current | Latest | Status | Notes |
+|---------|---------|--------|--------|-------|
+| `jest` | `^30.2.0` | `30.2.0` | ✅ Up to date | Updated from 29.7.0 |
+
+## Detailed Analysis
+
+### 1. `debug` (4.3.1 → 4.4.3)
+- **Type**: Minor update
+- **Risk**: Low
+- **Breaking Changes**: None expected
+- **Recommendation**: ✅ Safe to update
+- **Changes**: Bug fixes and minor improvements
+
+### 2. `iconv-lite` (0.6.3 → 0.7.0)
+- **Type**: Major update
+- **Risk**: Medium
+- **Breaking Changes**: Possible
+- **Recommendation**: ⚠️ Review before updating
+- **Notes**: 
+  - Major version jump indicates potential breaking changes
+  - Need to verify API compatibility
+  - Check changelog for breaking changes
+
+### 3. `serialport` (12.0.0 → 13.0.0)
+- **Type**: Major update
+- **Risk**: High
+- **Breaking Changes**: Likely
+- **Recommendation**: ⚠️ Review carefully before updating
+- **Notes**:
+  - Major version jump (12 → 13)
+  - Serial adapter code may need updates
+  - Check migration guide
+  - Test thoroughly with hardware
+
+### 4. `jest` (29.7.0 → 30.2.0)
+- **Type**: Major update
+- **Risk**: Low to Medium
+- **Breaking Changes**: Possible
+- **Recommendation**: ⚠️ Review before updating
+- **Notes**:
+  - Major version jump (29 → 30)
+  - Test configuration may need updates
+  - Check Jest 30 migration guide
+  - All tests should still work, but config might need tweaks
+
+### 5. `usb` (2.16.0)
+- **Status**: ✅ Already updated
+- **Notes**: Recently migrated from 1.9.1 to 2.16.0
+
+## Update Recommendations
+
+### Priority 1: Safe Updates (Low Risk)
+1. **`debug`** → `^4.4.3`
+   - Minor version update
+   - No breaking changes expected
+   - Quick win
+
+### Priority 2: Review Required (Medium Risk)
+2. **`iconv-lite`** → `^0.7.0`
+   - Check changelog for breaking changes
+   - Test encoding functionality
+   - Verify all text encoding still works
+
+3. **`jest`** → `^30.2.0`
+   - Review Jest 30 release notes
+   - Check if test configuration needs updates
+   - Run all tests after update
+
+### Priority 3: Careful Review (High Risk)
+4. **`serialport`** → `^13.0.0`
+   - Major version jump
+   - Review migration guide
+   - Update serial adapter code if needed
+   - Test with real hardware
+   - May require significant code changes
+
+## Update Strategy
+
+### Option 1: Conservative (Recommended)
+- Update `debug` only (safe)
+- Keep others at current versions
+- Monitor for issues
+
+### Option 2: Moderate
+- Update `debug` and `iconv-lite`
+- Review and test `iconv-lite` changes
+- Keep `serialport` and `jest` for now
+
+### Option 3: Aggressive
+- Update all dependencies
+- Requires thorough testing
+- May need code changes for `serialport`
+- Higher risk of breaking changes
+
+## Testing Checklist (After Updates)
+
+- [ ] Run all unit tests
+- [ ] Run integration tests
+- [ ] Test USB adapter with real hardware
+- [ ] Test Serial adapter with real hardware
+- [ ] Test text encoding with various character sets
+- [ ] Verify all examples work
+- [ ] Check for deprecation warnings
+
+## Notes
+
+- `get-pixels` is a custom fork, version tracking not applicable
+- All major updates should be tested thoroughly
+- Consider updating one at a time to isolate issues
+- Keep backup of working `package-lock.json` before updates
+

package/docs/JSDOC_REVIEW.md

@@ -0,0 +1,122 @@
+# JSDoc Documentation Review
+
+## Overview
+
+This document reviews the JSDoc documentation coverage across the library.
+
+## Documentation Status
+
+### ✅ Fully Documented Modules
+
+#### 1. **Adapter Class** (`src/adapter/index.js`)
+- ✅ Class documentation with `@class` and `@classdesc`
+- ✅ Constructor with `@param` documentation
+- ✅ All abstract methods documented with `@abstract` and `@throws`
+
+#### 2. **Printer Class** (`src/printer/index.js`)
+- ✅ Class documentation with `@class` and `@classdesc`
+- ✅ Constructor with detailed `@param` documentation
+- ✅ All public methods have JSDoc with:
+  - `@param` for parameters
+  - `@return` or `@returns` for return values
+  - Method descriptions
+
+#### 3. **Image Class** (`src/printer/image.js`)
+- ✅ Class documentation with `@class` and `@classdesc`
+- ✅ Constructor with `@param` documentation
+- ✅ `toBitmap()` method documented
+- ✅ `toRaster()` method documented
+- ✅ `load()` static method documented with `@example`
+
+#### 4. **Utils Module** (`src/printer/utils.js`)
+- ✅ All exported functions have JSDoc:
+  - `getParityBit()` - with description
+  - `codeLength()` - with description
+  - `textLength()` - with description
+  - `textSubstring()` - with `@param` and `@returns`
+- ✅ Internal `charLength()` function documented
+
+#### 5. **Commands Module** (`src/printer/commands.js`)
+- ✅ `numToHexString()` function documented with `@example`
+
+### ✅ Recently Added Documentation
+
+#### 6. **USB Adapter** (`src/usb-adapter/index.js`)
+- ✅ `listUSB()` - `@async`, `@returns`
+- ✅ `connect()` - `@async`, `@param`, `@returns`, `@throws`, `@fires`
+- ✅ `open()` - `@async`, `@returns`, `@throws`, `@fires`
+- ✅ `close()` - `@async`, `@returns`, `@fires`
+- ✅ `disconnect()` - `@async`, `@returns`, `@fires`
+- ✅ `write()` - `@async`, `@param`, `@returns`, `@throws`
+- ✅ Private `getDescriptor()` function documented
+
+#### 7. **Serial Adapter** (`src/serial-adapter/index.js`)
+- ✅ `connect()` - `@async`, `@param`, `@returns`, `@throws`, `@fires`
+- ✅ `open()` - `@async`, `@returns`, `@throws`
+- ✅ `write()` - `@async`, `@param`, `@returns`, `@throws`
+- ✅ `close()` - `@async`, `@param`, `@returns`, `@fires`
+- ✅ `disconnect()` - `@param`, `@returns`
+- ✅ `read()` - `@returns`
+- ✅ Private `verifyPort()` function documented
+
+## Documentation Quality
+
+### Standards Applied
+
+1. **Class Documentation**:
+   - `@class` tag
+   - `@classdesc` for description
+   - `@extends` for inheritance
+
+2. **Method Documentation**:
+   - `@async` for async methods
+   - `@param {Type} name - Description` for parameters
+   - `@returns {Type} Description` for return values
+   - `@throws {Error} Description` for errors
+   - `@fires EventName` for events emitted
+   - `@example` for usage examples
+
+3. **Function Documentation**:
+   - Parameter types and descriptions
+   - Return types and descriptions
+   - Usage examples where helpful
+
+## Coverage Summary
+
+| Module | Classes | Methods | Functions | Coverage |
+|--------|---------|---------|-----------|----------|
+| `adapter/index.js` | 1 | 5 | 0 | 100% ✅ |
+| `usb-adapter/index.js` | 0 | 6 | 1 | 100% ✅ |
+| `serial-adapter/index.js` | 0 | 6 | 1 | 100% ✅ |
+| `printer/index.js` | 2 | 30+ | 0 | 100% ✅ |
+| `printer/image.js` | 1 | 3 | 0 | 100% ✅ |
+| `printer/utils.js` | 0 | 0 | 5 | 100% ✅ |
+| `printer/commands.js` | 0 | 0 | 1 | 100% ✅ |
+
+**Overall JSDoc Coverage: 100%** ✅
+
+## Benefits
+
+1. **IDE Support**: Better autocomplete and type hints
+2. **Documentation Generation**: Can generate HTML docs with tools like JSDoc
+3. **Type Safety**: Helps catch errors during development
+4. **Developer Experience**: Clear API documentation for users
+5. **Maintainability**: Self-documenting code
+
+## Notes
+
+- All public APIs are fully documented
+- Private/internal functions are marked with `@private` where appropriate
+- Event emissions are documented with `@fires`
+- Async methods are marked with `@async`
+- Error conditions are documented with `@throws`
+
+## Recommendations
+
+The library now has comprehensive JSDoc documentation. Consider:
+
+1. **Documentation Generation**: Use tools like `jsdoc` or `typedoc` to generate HTML documentation
+2. **Type Checking**: Consider adding TypeScript or using JSDoc with type checking tools
+3. **Examples**: Add more `@example` tags for complex methods
+4. **Event Documentation**: Document all events that adapters can emit
+