@thermal-label/brother-ql-core 0.0.1

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@thermal-label/brother-ql-core",
+  "version": "0.0.1",
+  "description": "Protocol encoding, device registry, and media registry for Brother QL label printers",
+  "keywords": [
+    "brother",
+    "brother-ql",
+    "label-printer",
+    "thermal-label",
+    "usb",
+    "protocol"
+  ],
+  "type": "module",
+  "author": "Mannes Brak",
+  "license": "MIT",
+  "homepage": "https://thermal-label.github.io/brother-ql/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thermal-label/brother-ql.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/thermal-label/brother-ql/issues"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/mannes"
+    },
+    {
+      "type": "ko-fi",
+      "url": "https://ko-fi.com/mannes"
+    }
+  ],
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@mbtech-nl/bitmap": "^0.1.0"
+  },
+  "devDependencies": {
+    "@mbtech-nl/tsconfig": "^1.0.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "typescript": "~5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/__tests__/devices.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { DEVICES, findDevice, isMassStorageMode } from '../devices.js';
+
+describe('findDevice', () => {
+  it('returns correct descriptor for QL-820NWB', () => {
+    const dev = findDevice(0x04f9, 0x20a7);
+    expect(dev).toBeDefined();
+    expect(dev!.name).toBe('QL-820NWB');
+    expect(dev!.twoColor).toBe(true);
+  });
+
+  it('returns correct descriptor for QL-820NWBc', () => {
+    const dev = findDevice(0x04f9, 0x209d);
+    expect(dev).toBeDefined();
+    expect(dev!.name).toBe('QL-820NWBc');
+    expect(dev!.twoColor).toBe(true);
+  });
+
+  it('returns correct descriptor for QL-500', () => {
+    const dev = findDevice(0x04f9, 0x2013);
+    expect(dev).toBeDefined();
+    expect(dev!.name).toBe('QL-500');
+    expect(dev!.autocut).toBe(false);
+  });
+
+  it('returns undefined for unknown PID', () => {
+    expect(findDevice(0x04f9, 0x9999)).toBeUndefined();
+  });
+
+  it('returns undefined for unknown VID', () => {
+    expect(findDevice(0x1234, 0x20a7)).toBeUndefined();
+  });
+});
+
+describe('isMassStorageMode', () => {
+  it('returns true for 0x20AA (QL-1100 mass storage)', () => {
+    expect(isMassStorageMode(0x20aa)).toBe(true);
+  });
+
+  it('returns true for 0x20AB (QL-1110NWB mass storage)', () => {
+    expect(isMassStorageMode(0x20ab)).toBe(true);
+  });
+
+  it('returns false for all printer-class PIDs', () => {
+    for (const dev of Object.values(DEVICES)) {
+      expect(isMassStorageMode(dev.pid)).toBe(false);
+    }
+  });
+});
+
+describe('Device registry invariants', () => {
+  it('every two-color device has bytesPerRow 90', () => {
+    for (const dev of Object.values(DEVICES)) {
+      if (dev.twoColor) {
+        expect(dev.bytesPerRow).toBe(90);
+      }
+    }
+  });
+
+  it('every device with headPins 1296 has bytesPerRow 162', () => {
+    for (const dev of Object.values(DEVICES)) {
+      if (dev.headPins === 1296) {
+        expect(dev.bytesPerRow).toBe(162);
+      }
+    }
+  });
+
+  it('every device has bluetooth: false (BT out of scope)', () => {
+    for (const dev of Object.values(DEVICES)) {
+      expect(dev.bluetooth).toBe(false);
+    }
+  });
+});

package/src/__tests__/media.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { MEDIA, findMedia, findMediaByWidth } from '../media.js';
+
+describe('findMedia', () => {
+  it('returns correct descriptor for 62mm continuous (ID 259)', () => {
+    const m = findMedia(259);
+    expect(m).toBeDefined();
+    expect(m!.widthMm).toBe(62);
+    expect(m!.type).toBe('continuous');
+    expect(m!.lengthMm).toBe(0);
+  });
+
+  it('returns correct descriptor for 62x29mm die-cut (ID 274)', () => {
+    const m = findMedia(274);
+    expect(m).toBeDefined();
+    expect(m!.type).toBe('die-cut');
+    expect(m!.lengthMm).toBeGreaterThan(0);
+  });
+
+  it('returns undefined for unknown ID', () => {
+    expect(findMedia(9999)).toBeUndefined();
+  });
+});
+
+describe('findMediaByWidth', () => {
+  it('returns all 62mm continuous options', () => {
+    const results = findMediaByWidth(62, 'continuous');
+    expect(results.length).toBeGreaterThan(0);
+    for (const m of results) {
+      expect(m.widthMm).toBe(62);
+      expect(m.type).toBe('continuous');
+    }
+  });
+
+  it('returns die-cut for 62mm die-cut', () => {
+    const results = findMediaByWidth(62, 'die-cut');
+    expect(results.length).toBeGreaterThan(0);
+    for (const m of results) {
+      expect(m.type).toBe('die-cut');
+    }
+  });
+
+  it('returns empty array for unknown width', () => {
+    expect(findMediaByWidth(999, 'continuous')).toHaveLength(0);
+  });
+});
+
+describe('Media registry invariants', () => {
+  it('die-cut media has non-zero lengthMm', () => {
+    for (const m of Object.values(MEDIA)) {
+      if (m.type === 'die-cut') {
+        expect(m.lengthMm).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it('continuous media has lengthMm === 0', () => {
+    for (const m of Object.values(MEDIA)) {
+      if (m.type === 'continuous') {
+        expect(m.lengthMm).toBe(0);
+      }
+    }
+  });
+
+  it('all IDs are unique', () => {
+    const ids = Object.values(MEDIA).map(m => m.id);
+    const unique = new Set(ids);
+    expect(unique.size).toBe(ids.length);
+  });
+});

package/src/__tests__/protocol.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect } from 'vitest';
+import { createBitmap } from '@mbtech-nl/bitmap';
+import {
+  buildInvalidate,
+  buildInitialize,
+  buildRasterMode,
+  buildRasterRow,
+  buildPrintCommand,
+  buildPrintInfo,
+  buildZeroRow,
+  buildCompression,
+  buildStatusNotification,
+  buildVariousMode,
+  buildExpandedMode,
+  encodeJob,
+} from '../protocol.js';
+import { type PageData } from '../types.js';
+import { MEDIA } from '../media.js';
+
+describe('buildInvalidate', () => {
+  it('returns exactly 200 zero bytes', () => {
+    const buf = buildInvalidate();
+    expect(buf.length).toBe(200);
+    expect(buf.every(b => b === 0)).toBe(true);
+  });
+});
+
+describe('buildInitialize', () => {
+  it('returns [0x1B, 0x40]', () => {
+    expect(Array.from(buildInitialize())).toEqual([0x1b, 0x40]);
+  });
+});
+
+describe('buildRasterRow', () => {
+  it('single-color black: [0x67][0x00][len][data]', () => {
+    const payload = new Uint8Array(90).fill(0xaa);
+    const row = buildRasterRow(payload, 'black');
+    expect(row[0]).toBe(0x67);
+    expect(row[1]).toBe(0x00);
+    expect(row[2]).toBe(90);
+    expect(row.length).toBe(93);
+  });
+
+  it('two-color black: [0x77][0x01][len][data]', () => {
+    const payload = new Uint8Array(90);
+    const row = buildRasterRow(payload, 'black', true);
+    expect(row[0]).toBe(0x77);
+    expect(row[1]).toBe(0x01);
+    expect(row[2]).toBe(90);
+  });
+
+  it('two-color red: [0x77][0x02][len][data]', () => {
+    const payload = new Uint8Array(90);
+    const row = buildRasterRow(payload, 'red', true);
+    expect(row[0]).toBe(0x77);
+    expect(row[1]).toBe(0x02);
+    expect(row[2]).toBe(90);
+  });
+});
+
+describe('buildPrintCommand', () => {
+  it('last page returns [0x1A]', () => {
+    expect(Array.from(buildPrintCommand(true))).toEqual([0x1a]);
+  });
+
+  it('non-last page returns [0x0C]', () => {
+    expect(Array.from(buildPrintCommand(false))).toEqual([0x0c]);
+  });
+});
+
+describe('buildPrintInfo', () => {
+  it('byte 5 contains correct media width, bytes 7-8 correct row count LE', () => {
+    const media = MEDIA[259]!; // 62mm continuous
+    const buf = buildPrintInfo(media, 200, 0);
+    expect(buf[5]).toBe(62); // widthMm
+    // rowCount 200 = 0xC8 at bytes 7-8
+    expect(buf[7]).toBe(0xc8);
+    expect(buf[8]).toBe(0x00);
+  });
+
+  it('page index is at byte 9', () => {
+    const media = MEDIA[259]!;
+    const buf = buildPrintInfo(media, 100, 3);
+    expect(buf[9]).toBe(3);
+  });
+
+  it('die-cut media sets mediaType byte to 0x0b', () => {
+    const media = MEDIA[271]!; // 29x90mm die-cut
+    const buf = buildPrintInfo(media, 100, 0);
+    expect(buf[4]).toBe(0x0b);
+  });
+});
+
+describe('encodeJob', () => {
+  const media62 = MEDIA[259]!; // 62mm, 696 printAreaDots
+
+  function makePage(widthPx: number, heightPx: number): PageData {
+    const bitmap = createBitmap(widthPx, heightPx);
+    return { bitmap, media: media62 };
+  }
+
+  it('single page: contains ESC i a + 200 zero invalidate, ends with 0x1A', () => {
+    const page = makePage(696, 50);
+    const buf = encodeJob([page]);
+    // Starts with ESC i a 01 (raster mode, 4 bytes) then 200 zero invalidate bytes
+    expect(buf[0]).toBe(0x1b);
+    expect(buf[1]).toBe(0x69);
+    expect(buf[2]).toBe(0x61);
+    expect(buf[3]).toBe(0x01);
+    for (let i = 4; i < 204; i++) expect(buf[i]).toBe(0);
+    expect(buf.at(-1)).toBe(0x1a);
+  });
+
+  it('two-page job: second page has control codes, ends with 0x1A', () => {
+    const page1 = makePage(696, 10);
+    const page2 = makePage(696, 10);
+    const buf = encodeJob([page1, page2]);
+    expect(buf.at(-1)).toBe(0x1a);
+    // 0x0C should appear as the inter-page print command somewhere before the last byte
+    const printCmds = [];
+    for (let i = 0; i < buf.length; i++) {
+      if (buf[i] === 0x0c) printCmds.push(i);
+    }
+    expect(printCmds.length).toBeGreaterThan(0);
+  });
+
+  it('two-color job: black rows [0x77,0x01,len], red rows [0x77,0x02,len], interleaved', () => {
+    const bitmap = createBitmap(696, 5);
+    const redBitmap = createBitmap(696, 5);
+    const page: PageData = { bitmap, redBitmap, media: media62 };
+    const buf = encodeJob([page]);
+    const rowLen = 90;
+    const blackRows: number[] = [];
+    const redRows: number[] = [];
+    for (let i = 0; i < buf.length - 2; i++) {
+      if (buf[i] === 0x77 && buf[i + 1] === 0x01 && buf[i + 2] === rowLen) blackRows.push(i);
+      if (buf[i] === 0x77 && buf[i + 1] === 0x02 && buf[i + 2] === rowLen) redRows.push(i);
+    }
+    expect(blackRows.length).toBe(5);
+    expect(redRows.length).toBe(5);
+    // Verify interleaving: each black row is immediately followed by a red row (93 bytes apart)
+    for (let r = 0; r < 5; r++) {
+      expect(redRows[r]! - blackRows[r]!).toBe(93); // 3 header + 90 data
+    }
+  });
+
+  it('two-color job: throws if red bitmap dimensions mismatch', () => {
+    const bitmap = createBitmap(720, 5);
+    const redBitmap = createBitmap(720, 10); // different height
+    const page: PageData = { bitmap, redBitmap, media: media62 };
+    expect(() => encodeJob([page])).toThrow('identical dimensions');
+  });
+
+  it('copies option repeats the job', () => {
+    const page = makePage(720, 2);
+    const buf1 = encodeJob([page]);
+    const buf2 = encodeJob([page], { copies: 2 });
+    expect(buf2.length).toBeGreaterThan(buf1.length);
+  });
+
+  it('compress option includes compression command [0x4D, 0x02]', () => {
+    const page: PageData = { ...makePage(696, 5), options: { compress: true } };
+    const buf = encodeJob([page]);
+    let found = false;
+    for (let i = 0; i < buf.length - 1; i++) {
+      if (buf[i] === 0x4d && buf[i + 1] === 0x02) {
+        found = true;
+        break;
+      }
+    }
+    expect(found).toBe(true);
+  });
+});
+
+describe('buildRasterMode', () => {
+  it('returns correct bytes', () => {
+    expect(Array.from(buildRasterMode())).toEqual([0x1b, 0x69, 0x61, 0x01]);
+  });
+});
+
+describe('buildStatusNotification', () => {
+  it('disabled returns [0x1B, 0x69, 0x21, 0x00]', () => {
+    expect(Array.from(buildStatusNotification(false))).toEqual([0x1b, 0x69, 0x21, 0x00]);
+  });
+
+  it('enabled returns [0x1B, 0x69, 0x21, 0x01]', () => {
+    expect(Array.from(buildStatusNotification(true))).toEqual([0x1b, 0x69, 0x21, 0x01]);
+  });
+});
+
+describe('buildVariousMode', () => {
+  it('autoCut=true returns 0x40 flag', () => {
+    expect(buildVariousMode(true)[3]).toBe(0x40);
+  });
+
+  it('autoCut=false returns 0x00 flag', () => {
+    expect(buildVariousMode(false)[3]).toBe(0x00);
+  });
+});
+
+describe('buildExpandedMode', () => {
+  it('cutAtEnd=true sets bit 3', () => {
+    expect((buildExpandedMode(true, false)[3] ?? 0) & 0x08).toBe(0x08);
+  });
+
+  it('highRes=true sets bit 4', () => {
+    expect((buildExpandedMode(false, true)[3] ?? 0) & 0x10).toBe(0x10);
+  });
+
+  it('twoColor=true sets bit 0', () => {
+    expect((buildExpandedMode(false, false, true)[3] ?? 0) & 0x01).toBe(0x01);
+  });
+
+  it('both false returns 0x00 flags', () => {
+    expect(buildExpandedMode(false, false)[3]).toBe(0x00);
+  });
+});
+
+describe('buildPrintInfo twoColor flag', () => {
+  it('always uses 0xCE valid flags (Python brother_ql behaviour for two-color capable models)', () => {
+    const media = MEDIA[259]!;
+    const buf = buildPrintInfo(media, 100, 0);
+    expect(buf[3]).toBe(0xce);
+  });
+});
+
+describe('buildZeroRow', () => {
+  it('returns [0x5A]', () => {
+    expect(Array.from(buildZeroRow())).toEqual([0x5a]);
+  });
+});
+
+describe('buildCompression', () => {
+  it('enabled returns [0x4D, 0x02]', () => {
+    expect(Array.from(buildCompression(true))).toEqual([0x4d, 0x02]);
+  });
+
+  it('disabled returns [0x4D, 0x00]', () => {
+    expect(Array.from(buildCompression(false))).toEqual([0x4d, 0x00]);
+  });
+});

package/src/__tests__/status.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import { parseStatus, STATUS_REQUEST } from '../status.js';
+
+function makeStatusBytes(
+  overrides?: Partial<{
+    errInfo1: number;
+    errInfo2: number;
+    mediaWidthMm: number;
+    mediaLengthMm: number;
+    mediaTypeByte: number;
+    statusType: number;
+  }>,
+): Uint8Array {
+  const bytes = new Uint8Array(32);
+  bytes[0] = 0x80;
+  bytes[1] = 0x20;
+  bytes[2] = 0x42;
+  bytes[3] = 0x30;
+  bytes[8] = overrides?.errInfo1 ?? 0;
+  bytes[9] = overrides?.errInfo2 ?? 0;
+  bytes[10] = overrides?.mediaWidthMm ?? 62;
+  bytes[11] = overrides?.mediaTypeByte ?? 0x0a;
+  bytes[17] = overrides?.mediaLengthMm ?? 0;
+  bytes[18] = overrides?.statusType ?? 0x00;
+  return bytes;
+}
+
+describe('parseStatus', () => {
+  it('throws on short input', () => {
+    expect(() => parseStatus(new Uint8Array(10))).toThrow('too short');
+  });
+
+  it('returns ready=true with no errors', () => {
+    const status = parseStatus(makeStatusBytes());
+    expect(status.ready).toBe(true);
+    expect(status.errors).toHaveLength(0);
+  });
+
+  it('parses media width and type', () => {
+    const status = parseStatus(makeStatusBytes({ mediaWidthMm: 62, mediaTypeByte: 0x0a }));
+    expect(status.mediaWidthMm).toBe(62);
+    expect(status.mediaType).toBe('continuous');
+  });
+
+  it('parses media length from byte 17 (0 for continuous, mm for die-cut)', () => {
+    const cont = parseStatus(makeStatusBytes({ mediaLengthMm: 0 }));
+    expect(cont.mediaLengthMm).toBe(0);
+    const diecut = parseStatus(makeStatusBytes({ mediaTypeByte: 0x0b, mediaLengthMm: 90 }));
+    expect(diecut.mediaLengthMm).toBe(90);
+  });
+
+  it('parses die-cut media type', () => {
+    const status = parseStatus(makeStatusBytes({ mediaTypeByte: 0x0b }));
+    expect(status.mediaType).toBe('die-cut');
+  });
+
+  it('returns null mediaType for unknown byte', () => {
+    const status = parseStatus(makeStatusBytes({ mediaTypeByte: 0xff }));
+    expect(status.mediaType).toBeNull();
+  });
+
+  it('parses error info 1 bits', () => {
+    const status = parseStatus(makeStatusBytes({ errInfo1: 0b00000001 })); // No media
+    expect(status.errors).toContain('No media');
+    expect(status.ready).toBe(false);
+  });
+
+  it('parses error info 2 bits', () => {
+    const status = parseStatus(makeStatusBytes({ errInfo2: 0b00010000 })); // Cover open
+    expect(status.errors).toContain('Cover open');
+    expect(status.ready).toBe(false);
+  });
+
+  it('ready=false when statusType is error (0x02)', () => {
+    const status = parseStatus(makeStatusBytes({ statusType: 0x02 }));
+    expect(status.ready).toBe(false);
+  });
+
+  it('rawBytes contains the full 32-byte input', () => {
+    const bytes = makeStatusBytes();
+    const status = parseStatus(bytes);
+    expect(status.rawBytes).toEqual(bytes);
+  });
+
+  it('editorLiteMode is false (detected at discovery time, not from status bytes)', () => {
+    const status = parseStatus(makeStatusBytes());
+    expect(status.editorLiteMode).toBe(false);
+  });
+});
+
+describe('STATUS_REQUEST', () => {
+  it('is the correct byte sequence', () => {
+    expect(Array.from(STATUS_REQUEST)).toEqual([0x1b, 0x69, 0x53]);
+  });
+});