How freedom-git/escposencoder works
1. This repository is a small TypeScript library for generating printer command streams, not a printer driver. Its main job is to build byte sequences that can be sent to supported receipt/label printers over whatever transport the caller uses.
2. The core product is the ESC/POS encoder in src/esc-pos-encoder.ts, with matching compiled outputs in dist/esc-pos-encoder.js and types in dist/esc-pos-encoder.d.ts. The public API is a fluent, chainable command builder that accumulates printer instructions and emits a final Uint8Array from encode().
3. The command pipeline is stateful. The encoder remembers printer-related settings such as code page, alignment, text size, and style toggles so later commands can be interpreted correctly. This matters because the library is modeling printer state, not just concatenating bytes.
4. Text handling is a major subsystem. It includes code page selection, ASCII fallback/stripping when no code page is set, word wrapping, line breaking, and style commands like bold, underline, italic, and alignment. These are translated into ESC/POS control sequences plus encoded text bytes.
5. Image printing is handled separately in src/esc-pos-img-encoder.ts with its own dist artifact. The readme shows that images can come from browser elements or Node canvas objects, then get converted to monochrome and optionally dithered before being rasterized into printer commands. This introduces the main cross-environment boundary in the library: browser DOM/canvas on one side, printer byte output on the other.
6. Barcode and QR code support are native command generators inside the ESC/POS encoder. They are not treated as images; instead they produce printer-specific barcode/QR command sequences with parameters such as symbology, model, size, and error correction level.
7. There is a low-level escape hatch via raw(). This allows callers to inject unsupported printer commands directly, which is important for architecture because the library is intentionally extensible without requiring every vendor-specific feature to be modeled in the API.
8. Cutting is another direct printer-control feature. The encoder emits full or partial cut commands when supported by the target device, so paper handling is part of the command stream alongside text and graphics.
9. The presence of src/tspl-label-encoder.ts and matching dist/tspl-label-encoder.* indicates a second printer-language implementation in the same package. That suggests the repository is structured around multiple printer dialects sharing the same “build commands, emit bytes” pattern, even though ESC/POS is the primary documented surface.
10. The build and packaging story is straightforward: TypeScript source in src, generated distributables in dist, and tests in test/ with at least one JS test file for the ESC/POS encoder. Tooling files like tsconfig.json, ESLint config, and package-lock.json show a conventional Node.js library workflow rather than an application runtime.
11. The main external boundary is the printer itself. The library stops at generating protocol-specific bytes; transport, device discovery, buffering, and actual I/O to USB/serial/network printers are explicitly outside its scope and must be handled by the consuming application.
12. For an architecture diagram, the key flow is: caller code -> encoder API -> stateful command builder -> protocol-specific byte encoding -> Uint8Array output -> external printer transport. Image input adds an extra preprocessing branch before byte emission, while raw() bypasses higher-level modeling and injects protocol bytes directly.
Main entry points: esc-pos-encoder.ts ESC/POS API · esc-pos-img-encoder.ts Image encoder · tspl-label-encoder.ts TSPL encoder · esc-pos-encoder.js Published API
Components 18
Source
TypeScript implementation of the encoder library
- ESC/POS API · Primary chainable command builder for receipt-printer commands
src/esc-pos-encoder.ts - Encoder state · Tracks code page, alignment, text sizing, and style state across commands
src/esc-pos-encoder.ts - Text pipeline · Handles wrapping, line breaking, ASCII fallback, and code page-aware text emission
src/esc-pos-encoder.ts - Style commands · Bold, underline, italic, alignment, and related print styling controls
src/esc-pos-encoder.ts - Barcode & QR · Native ESC/POS generation for barcodes and QR codes with printer parameters
src/esc-pos-encoder.ts - Cut control · Full and partial cut commands for supported devices
src/esc-pos-encoder.ts - Raw escape hatch · Bypasses higher-level modeling and injects unsupported printer commands directly
src/esc-pos-encoder.ts - Byte output · Final encoded command stream returned by encode()
src/esc-pos-encoder.ts - Image encoder · Separate ESC/POS image command builder for bitmap printing
src/esc-pos-img-encoder.ts - Image inputs · Accepts browser elements or Node canvas objects as image sources
src/esc-pos-img-encoder.ts - Preprocess image · Converts images to monochrome and optionally dithers before rasterization
src/esc-pos-img-encoder.ts - TSPL encoder · Second printer-language implementation for label-printing byte streams
src/tspl-label-encoder.ts
Distributed
Compiled JavaScript and type definitions published from the package
- Published API · Bundled JavaScript and type definitions exposed from dist artifacts
dist/esc-pos-encoder.js - Image bundle · Compiled ESC/POS image encoder and typings
dist/esc-pos-img-encoder.js - TSPL bundle · Compiled TSPL label encoder and typings
dist/tspl-label-encoder.js
Tests
Focused runtime checks for the encoder API
- Encoder tests · Test coverage for the ESC/POS encoder behavior
test/esc-pos-encoder.js
Other components
- Caller code · Application code that uses the library to build printer command streams
- Printer device · Physical receipt or label printer that consumes protocol-specific bytes
Connections 22
- Caller code → ESC/POS API: use · Caller builds printer commands through the fluent API
- ESC/POS API → Encoder state: maintain · Command methods update printer state as the stream is built
- ESC/POS API → Text pipeline: encode text · Text commands go through code page selection and wrapping logic
- ESC/POS API → Style commands: apply styles · Formatting commands translate into ESC/POS control sequences
- ESC/POS API → Barcode & QR: emit codes · Barcode and QR helpers generate native printer commands
- ESC/POS API → Cut control: cut paper · Cut commands are appended to the printer stream
- ESC/POS API → Raw escape hatch: inject raw · Low-level escape hatch inserts vendor-specific bytes directly
- ESC/POS API → Byte output: encode · encode() finalizes the accumulated command stream as bytes
- Text pipeline → Byte output: bytes · Encoded text and control sequences flow into the final output
- Style commands → Byte output: bytes · Style state is converted into printer control bytes
- Barcode & QR → Byte output: bytes · Barcode and QR commands are emitted as protocol bytes
- Cut control → Byte output: bytes · Cut instructions are appended to the final byte stream
- Raw escape hatch → Byte output: bytes · Raw commands pass straight into the output stream
- Image inputs → Preprocess image: prepare · Source images are normalized before rasterization
- Preprocess image → Image encoder: rasterize · Monochrome/dithered pixels become ESC/POS image commands
- Image encoder → Byte output: bytes · Image encoder produces printer command bytes
- TSPL encoder → Printer device: bytes · TSPL encoder targets a label printer command stream
- Byte output → Printer device: send · Application transports the encoded bytes to a printer
- Published API → ESC/POS API: compiled from · Published ESC/POS API mirrors the TypeScript source
- Image bundle → Image encoder: compiled from · Published image encoder mirrors the TypeScript source
- TSPL bundle → TSPL encoder: compiled from · Published TSPL encoder mirrors the TypeScript source
- Encoder tests → ESC/POS API: verify · Tests exercise the ESC/POS command builder