# freedom-git/escposencoder architecture

> Architecture diagram of the GitHub repository freedom-git/escposencoder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/freedom-git/escposencoder
- Repository: https://github.com/freedom-git/escposencoder

## Overview

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: [`src/esc-pos-encoder.ts`](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts) (ESC/POS API), [`src/esc-pos-img-encoder.ts`](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-img-encoder.ts) (Image encoder), [`src/tspl-label-encoder.ts`](https://github.com/freedom-git/escposencoder/blob/master/src/tspl-label-encoder.ts) (TSPL encoder), [`dist/esc-pos-encoder.js`](https://github.com/freedom-git/escposencoder/blob/master/dist/esc-pos-encoder.js) (Published API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_src["Source"]
  node_escpos_api["ESC/POS API<br/>fluent encoder<br/>[esc-pos-encoder.ts]"]
  node_escpos_state["Encoder state<br/>printer state<br/>[esc-pos-encoder.ts]"]
  node_escpos_text["Text pipeline<br/>text encoding<br/>[esc-pos-encoder.ts]"]
  node_escpos_style["Style commands<br/>formatting<br/>[esc-pos-encoder.ts]"]
  node_escpos_barcode["Barcode & QR<br/>symbology commands<br/>[esc-pos-encoder.ts]"]
  node_escpos_cut["Cut control<br/>paper handling<br/>[esc-pos-encoder.ts]"]
  node_escpos_raw["Raw escape hatch<br/>direct bytes<br/>[esc-pos-encoder.ts]"]
  node_escpos_bytes(("Byte output<br/>Uint8Array<br/>[esc-pos-encoder.ts]"))
  node_img_api["Image encoder<br/>image rasterizer"]
  node_img_inputs["Image inputs<br/>browser/node bridge"]
  node_img_preprocess["Preprocess image<br/>mono+dither"]
  node_tspl_api["TSPL encoder<br/>label dialect"]
end

subgraph group_g_dist["Distributed"]
  node_dist_api["Published API<br/>compiled output<br/>[esc-pos-encoder.js]"]
  node_dist_img["Image bundle<br/>compiled output"]
  node_dist_tspl["TSPL bundle<br/>compiled output"]
end

subgraph group_g_test["Tests"]
  node_tests["Encoder tests<br/>runtime checks<br/>[esc-pos-encoder.js]"]
end

node_caller(("Caller code<br/>consumer"))
node_printer(("Printer device<br/>external sink"))

node_caller -->|"use"| node_escpos_api
node_escpos_api -->|"maintain"| node_escpos_state
node_escpos_api -->|"encode text"| node_escpos_text
node_escpos_api -->|"apply styles"| node_escpos_style
node_escpos_api -->|"emit codes"| node_escpos_barcode
node_escpos_api -->|"cut paper"| node_escpos_cut
node_escpos_api -->|"inject raw"| node_escpos_raw
node_escpos_api -->|"encode"| node_escpos_bytes
node_escpos_text -->|"bytes"| node_escpos_bytes
node_escpos_style -->|"bytes"| node_escpos_bytes
node_escpos_barcode -->|"bytes"| node_escpos_bytes
node_escpos_cut -->|"bytes"| node_escpos_bytes
node_escpos_raw -->|"bytes"| node_escpos_bytes
node_img_inputs -->|"prepare"| node_img_preprocess
node_img_preprocess -->|"rasterize"| node_img_api
node_img_api -->|"bytes"| node_escpos_bytes
node_tspl_api -->|"bytes"| node_printer
node_escpos_bytes -->|"send"| node_printer
node_dist_api -.->|"compiled from"| node_escpos_api
node_dist_img -.->|"compiled from"| node_img_api
node_dist_tspl -.->|"compiled from"| node_tspl_api
node_tests -.->|"verify"| node_escpos_api

click node_escpos_api "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts"
click node_escpos_state "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts"
click node_escpos_text "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts"
click node_escpos_style "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts"
click node_escpos_barcode "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts"
click node_escpos_cut "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts"
click node_escpos_raw "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts"
click node_escpos_bytes "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts"
click node_img_api "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-img-encoder.ts"
click node_img_inputs "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-img-encoder.ts"
click node_img_preprocess "https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-img-encoder.ts"
click node_tspl_api "https://github.com/freedom-git/escposencoder/blob/master/src/tspl-label-encoder.ts"
click node_dist_api "https://github.com/freedom-git/escposencoder/blob/master/dist/esc-pos-encoder.js"
click node_dist_img "https://github.com/freedom-git/escposencoder/blob/master/dist/esc-pos-img-encoder.js"
click node_dist_tspl "https://github.com/freedom-git/escposencoder/blob/master/dist/tspl-label-encoder.js"
click node_tests "https://github.com/freedom-git/escposencoder/blob/master/test/esc-pos-encoder.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_escpos_api,node_escpos_state,node_escpos_text,node_escpos_style,node_escpos_barcode,node_escpos_cut,node_escpos_raw,node_escpos_bytes,node_img_api,node_img_inputs,node_img_preprocess,node_tspl_api toneBlue
class node_dist_api,node_dist_img,node_dist_tspl toneAmber
class node_tests toneMint
class node_caller,node_printer toneNeutral
```

## Components

### Source

TypeScript implementation of the encoder library

- [ESC/POS API](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts): fluent encoder · Primary chainable command builder for receipt-printer commands · `src/esc-pos-encoder.ts`
- [Encoder state](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts): printer state · Tracks code page, alignment, text sizing, and style state across commands · `src/esc-pos-encoder.ts`
- [Text pipeline](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts): text encoding · Handles wrapping, line breaking, ASCII fallback, and code page-aware text emission · `src/esc-pos-encoder.ts`
- [Style commands](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts): formatting · Bold, underline, italic, alignment, and related print styling controls · `src/esc-pos-encoder.ts`
- [Barcode & QR](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts): symbology commands · Native ESC/POS generation for barcodes and QR codes with printer parameters · `src/esc-pos-encoder.ts`
- [Cut control](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts): paper handling · Full and partial cut commands for supported devices · `src/esc-pos-encoder.ts`
- [Raw escape hatch](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts): direct bytes · Bypasses higher-level modeling and injects unsupported printer commands directly · `src/esc-pos-encoder.ts`
- [Byte output](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-encoder.ts): Uint8Array · Final encoded command stream returned by encode() · `src/esc-pos-encoder.ts`
- [Image encoder](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-img-encoder.ts): image rasterizer · Separate ESC/POS image command builder for bitmap printing · `src/esc-pos-img-encoder.ts`
- [Image inputs](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-img-encoder.ts): browser/node bridge · Accepts browser elements or Node canvas objects as image sources · `src/esc-pos-img-encoder.ts`
- [Preprocess image](https://github.com/freedom-git/escposencoder/blob/master/src/esc-pos-img-encoder.ts): mono+dither · Converts images to monochrome and optionally dithers before rasterization · `src/esc-pos-img-encoder.ts`
- [TSPL encoder](https://github.com/freedom-git/escposencoder/blob/master/src/tspl-label-encoder.ts): label dialect · 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](https://github.com/freedom-git/escposencoder/blob/master/dist/esc-pos-encoder.js): compiled output · Bundled JavaScript and type definitions exposed from dist artifacts · `dist/esc-pos-encoder.js`
- [Image bundle](https://github.com/freedom-git/escposencoder/blob/master/dist/esc-pos-img-encoder.js): compiled output · Compiled ESC/POS image encoder and typings · `dist/esc-pos-img-encoder.js`
- [TSPL bundle](https://github.com/freedom-git/escposencoder/blob/master/dist/tspl-label-encoder.js): compiled output · Compiled TSPL label encoder and typings · `dist/tspl-label-encoder.js`

### Tests

Focused runtime checks for the encoder API

- [Encoder tests](https://github.com/freedom-git/escposencoder/blob/master/test/esc-pos-encoder.js): runtime checks · Test coverage for the ESC/POS encoder behavior · `test/esc-pos-encoder.js`

### Other components

- **Caller code**: consumer · Application code that uses the library to build printer command streams
- **Printer device**: external sink · Physical receipt or label printer that consumes protocol-specific bytes

## Connections

- 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
