feat(grid-matrix): add structured append controls

Author: Streetblock

libs/GridMatrixCore.js

@@ -74,13 +74,14 @@ export class GridMatrixCore {
 
   generate() {
     const { bytes, eci } = normalizeInput(this.data, this.options.eci)
+    const controls = normalizeControls(this.options)
     const requestedMode = this.options.mode == null ? 'auto' : String(this.options.mode).toLowerCase()
     if (!['auto', 'byte'].includes(requestedMode)) {
       throw new RangeError("Grid Matrix mode must be 'auto' or 'byte'.")
     }
     const { bits, modes } = requestedMode === 'byte'
-      ? { bits: encodeByteSegments(bytes, eci), modes: Array(bytes.length).fill(BYTE) }
-      : encodeOptimized(bytes, eci)
+      ? { bits: encodeByteSegments(bytes, eci, controls.prefix), modes: Array(bytes.length).fill(BYTE) }
+      : encodeOptimized(bytes, eci, controls.prefix)
     const dataCodewords = bitsToCodewords(bits)
     const layers = chooseLayers(dataCodewords.length, this.options.layers)
     const eccLevel = chooseEccLevel(dataCodewords.length, layers, this.options.eccLevel)
@@ -93,6 +94,8 @@ export class GridMatrixCore {
       layers,
       eccLevel,
       eci,
+      readerInitialization: controls.readerInitialization,
+      structuredAppend: controls.structuredAppend,
       encoding: requestedMode,
       modes: modes.map(mode => MODE_NAMES[mode - 1]),
       width: modules.length,
@@ -105,6 +108,44 @@ export class GridMatrixCore {
   }
 }
 
+function normalizeControls(options) {
+  const requestedReaderInitialization = options.readerInitialization === true
+  if (options.readerInitialization != null && typeof options.readerInitialization !== 'boolean') {
+    throw new TypeError('Grid Matrix readerInitialization must be boolean.')
+  }
+
+  let structuredAppend = null
+  if (options.structuredAppend != null) {
+    const value = options.structuredAppend
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new TypeError('Grid Matrix structuredAppend must be an object.')
+    }
+    const count = Number(value.count), index = Number(value.index)
+    const id = value.id == null ? 0 : Number(value.id)
+    if (!Number.isInteger(count) || count < 2 || count > 16) {
+      throw new RangeError('Grid Matrix structuredAppend count must be an integer from 2 to 16.')
+    }
+    if (!Number.isInteger(index) || index < 1 || index > count) {
+      throw new RangeError('Grid Matrix structuredAppend index must be an integer from 1 to count.')
+    }
+    if (!Number.isInteger(id) || id < 0 || id > 255) {
+      throw new RangeError('Grid Matrix structuredAppend id must be an integer from 0 to 255.')
+    }
+    structuredAppend = { index, count, id }
+  }
+
+  const readerInitialization = requestedReaderInitialization && (!structuredAppend || structuredAppend.index === 1)
+  const prefix = []
+  if (readerInitialization) appendBits(prefix, 10, 4)
+  if (structuredAppend) {
+    appendBits(prefix, 9, 4)
+    appendBits(prefix, structuredAppend.id, 8)
+    appendBits(prefix, structuredAppend.count - 1, 4)
+    appendBits(prefix, structuredAppend.index - 1, 4)
+  }
+  return { prefix, readerInitialization, structuredAppend }
+}
+
 function normalizeInput(value, requestedEci) {
   let bytes, automaticEci = 0
   if (typeof value === 'string') {
@@ -177,8 +218,8 @@ function buildGb2312EncodeMap() {
   return map
 }
 
-function encodeByteSegments(bytes, eci) {
-  const bits = []
+function encodeByteSegments(bytes, eci, prefix = []) {
+  const bits = [...prefix]
   appendEci(bits, eci)
   const flatBytes = Array.from(bytes).flatMap(value => value > 0xFF ? [value >> 8, value & 0xFF] : [value])
   for (let offset = 0; offset < flatBytes.length; offset += 512) {
@@ -193,8 +234,8 @@ function encodeByteSegments(bytes, eci) {
   return bits
 }
 
-function encodeOptimized(data, eci) {
-  const bits = []
+function encodeOptimized(data, eci, prefix = []) {
+  const bits = [...prefix]
   appendEci(bits, eci)
   const modes = defineModes(data)
   let position = 0, currentMode = 0, lastMode = 0

tests/grid-matrix-core.test.mjs

@@ -66,6 +66,36 @@ test('can force byte mode when compact high-level modes are not wanted', () => {
   assert.deepEqual(bytes.modes, ['byte', 'byte', 'byte'])
 })
 
+test('matches Reader Initialization and Structured Append reference vectors', () => {
+  const vectors = [
+    [{ readerInitialization: true }, [0x51, 0x11, 0x71, 0x7E, 0x40]],
+    [{ structuredAppend: { index: 1, count: 16 } }, [0x48, 0x03, 0x60, 0x24, 0x3C, 0x3F, 0x50]],
+    [{ readerInitialization: true, structuredAppend: { index: 1, count: 16 } }, [0x54, 0x40, 0x1E, 0x02, 0x23, 0x63, 0x7D, 0x00]],
+    [{ structuredAppend: { index: 2, count: 16 } }, [0x48, 0x03, 0x62, 0x24, 0x3C, 0x3F, 0x50]],
+    [{ structuredAppend: { index: 3, count: 3, id: 255 } }, [0x4F, 0x7C, 0x44, 0x24, 0x3C, 0x3F, 0x50]],
+  ]
+  for (const [options, expected] of vectors) {
+    assert.deepEqual(new GridMatrixCore('12', options).generate().dataCodewords, expected, JSON.stringify(options))
+  }
+})
+
+test('omits Reader Initialization after the first Structured Append symbol', () => {
+  const symbol = new GridMatrixCore('12', {
+    readerInitialization: true,
+    structuredAppend: { index: 2, count: 16 },
+  }).generate()
+  assert.equal(symbol.readerInitialization, false)
+  assert.deepEqual(symbol.dataCodewords, [0x48, 0x03, 0x62, 0x24, 0x3C, 0x3F, 0x50])
+})
+
+test('validates Reader Initialization and Structured Append metadata', () => {
+  assert.throws(() => new GridMatrixCore('A', { readerInitialization: 1 }).generate(), /boolean/)
+  assert.throws(() => new GridMatrixCore('A', { structuredAppend: true }).generate(), /object/)
+  assert.throws(() => new GridMatrixCore('A', { structuredAppend: { index: 1, count: 1 } }).generate(), /count/)
+  assert.throws(() => new GridMatrixCore('A', { structuredAppend: { index: 3, count: 2 } }).generate(), /index/)
+  assert.throws(() => new GridMatrixCore('A', { structuredAppend: { index: 1, count: 2, id: 256 } }).generate(), /id/)
+})
+
 test('supports all thirteen explicit versions and produces square boolean matrices', () => {
   for (let layers = 1; layers <= 13; layers++) {
     const symbol = new GridMatrixCore('A', { layers }).generate()