@risleylima/escpos 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2025-11-23
+
+### Added
+- Versioning documentation (`docs/VERSIONING.md`) with explicit semantic versioning rules
+
+## [0.2.0] - 2025-11-23
+
+### Added
+- `Serial.listSerial()` method to list all available serial ports
+  - Returns array of serial port objects with path, manufacturer, vendorId, productId, etc.
+  - Similar functionality to `USB.listUSB()` for consistency between adapters
+
 ## [0.1.0] - 2025-11-23
 
 ### Added
@@ -55,6 +67,8 @@ Initial stable release with USB and Serial adapter support.
 
 ## Version History
 
+- **0.2.1** - Added versioning documentation
+- **0.2.0** - Added `Serial.listSerial()` method for listing available serial ports
 - **0.1.0** - Major dependency updates, 100% test coverage, complete documentation
 - **0.0.14** - Initial stable release
 

package/README.md

@@ -215,6 +215,14 @@ await USB.disconnect();
 
 #### Methods
 
+##### `Serial.listSerial()`
+List all available serial ports.
+
+```javascript
+const ports = await Serial.listSerial();
+console.log(ports); // Array of serial port objects with path, manufacturer, vendorId, productId, etc.
+```
+
 ##### `Serial.connect(port, options)`
 Connect to a serial port printer.
 

package/docs/README.md

@@ -28,6 +28,9 @@ 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

package/docs/VERSIONING.md

@@ -0,0 +1,102 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@risleylima/escpos",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Library to deal with ESCPOS using some adapters",
   "main": "index.js",
   "author": "Rlima Info",

package/src/serial-adapter/index.js

@@ -26,6 +26,22 @@ const scope = {
 // Create Adapter instance first, so it's the same object used internally and exported
 const Serial = new Adapter();
 
+/**
+ * List all available serial ports
+ * @async
+ * @returns {Promise<Array<Object>>} Array of serial port objects with properties like path, manufacturer, vendorId, productId, etc.
+ * @example
+ * const ports = await Serial.listSerial();
+ * console.log(ports);
+ * // [
+ * //   { path: '/dev/ttyUSB0', manufacturer: 'FTDI', vendorId: '0403', productId: '6001' },
+ * //   { path: '/dev/ttyUSB1', manufacturer: 'Prolific', vendorId: '067b', productId: '2303' }
+ * // ]
+ */
+Serial.listSerial = async () => {
+  return await SerialPort.list();
+};
+
 /**
  * Connect to a serial port printer
  * @async

package/tests/unit/adapters/serial-adapter.test.js

@@ -49,6 +49,20 @@ describe('Serial Adapter', () => {
     jest.clearAllMocks();
   });
 
+  describe('listSerial', () => {
+    it('should list all available serial ports', async () => {
+      const ports = await Serial.listSerial();
+      expect(Array.isArray(ports)).toBe(true);
+      expect(SerialPort.list).toHaveBeenCalled();
+    });
+
+    it('should return port objects with path property', async () => {
+      const ports = await Serial.listSerial();
+      expect(ports.length).toBeGreaterThan(0);
+      expect(ports[0]).toHaveProperty('path');
+    });
+  });
+
   describe('connect', () => {
     it('should connect to serial port', async () => {
       const result = await Serial.connect('/dev/ttyUSB0');