quadqr-js 1.0.2 → 1.3.0

package/dist/esm/benchmark.js

@@ -11,6 +11,7 @@ import {
   encodeBytes,
   decodeMatrix,
   getVersionInfo,
+  compressPayload,
   MAX_VERSION
 } from "./quadqr.js";
 
@@ -29,6 +30,16 @@ function normalizeEcc(ecc = "M") {
   return value;
 }
 
+function resolveHighDensity(options = {}) {
+  if (typeof options.highDensity === "boolean") return options.highDensity;
+  // Backward compatibility for the first experimental Triangle16 branch.
+  return options.cellEncoding === "triangle16";
+}
+
+function encodingForHighDensity(highDensity) {
+  return highDensity ? "triangle16" : "rgbw";
+}
+
 function nowMs() {
   if (typeof performance !== "undefined" && typeof performance.now === "function") {
     return performance.now();
@@ -75,9 +86,11 @@ export function getStandardQrByteCapacity(version, ecc = "M") {
   return STANDARD_QR_BYTE_CAPACITY[normalizeEcc(ecc)][version - 1];
 }
 
-export function compareCapacity(version, ecc = "M") {
+export function compareCapacity(version, ecc = "M", options = {}) {
   const level = normalizeEcc(ecc);
-  const quadqr = getVersionInfo(version, { ecc: level });
+  const highDensity = resolveHighDensity(options);
+  const cellEncoding = encodingForHighDensity(highDensity);
+  const quadqr = getVersionInfo(version, { ecc: level, highDensity });
   const standardQrBytes = getStandardQrByteCapacity(version, level);
   const quadqrBytes = quadqr.capacityBytes;
   const differenceBytes = quadqrBytes - standardQrBytes;
@@ -93,6 +106,8 @@ export function compareCapacity(version, ecc = "M") {
     differenceBytes,
     ratio,
     gainPercent,
+    highDensity,
+    cellEncoding: quadqr.cellEncoding,
     quadqrBitsPerDataCell: quadqr.bitsPerDataCell,
     quadqrPayloadEfficiencyPercent: quadqr.theoreticalBits > 0
       ? (quadqrBytes * 8 / quadqr.theoreticalBits) * 100
@@ -103,14 +118,100 @@ export function compareCapacity(version, ecc = "M") {
   };
 }
 
+
+/** Calculate the smallest QuadQR and standard QR versions for a payload size. */
+export function calculateCapacityPlan(options = {}) {
+  const ecc = normalizeEcc(options.ecc ?? "M");
+  const highDensity = resolveHighDensity(options);
+  const cellEncoding = encodingForHighDensity(highDensity);
+  let sourceBytes;
+  const hasConcretePayload = options.payload instanceof Uint8Array || typeof options.payload === "string";
+  if (options.payload instanceof Uint8Array) sourceBytes = options.payload;
+  else if (typeof options.payload === "string") sourceBytes = new TextEncoder().encode(options.payload);
+  else sourceBytes = new Uint8Array(Math.max(0, Math.floor(options.payloadBytes ?? 0)));
+
+  const requestedCompression = options.compression ?? "none";
+  const signed = Boolean(options.signed);
+  const keyIdBytes = options.keyId ? new TextEncoder().encode(String(options.keyId)).length : 0;
+  const envelopeHeaderBytes = 16;
+  const signingBytes = signed ? 64 + keyIdBytes + (options.embedPublicKey ? 32 : 0) : 0;
+  let compression = requestedCompression;
+  let storedBytes = sourceBytes.length;
+  let compressed = false;
+
+  if (requestedCompression !== "none" && hasConcretePayload) {
+    const candidate = compressPayload(sourceBytes);
+    if (requestedCompression === "lz" || candidate.length < sourceBytes.length - 2) {
+      storedBytes = candidate.length;
+      compressed = true;
+      compression = "lz";
+    } else {
+      compression = "none";
+    }
+  } else if (requestedCompression !== "none" && !hasConcretePayload) {
+    compression = "unknown";
+  }
+
+  const needsEnvelope = signed || compressed || requestedCompression === "lz";
+  const encodedBytes = storedBytes + (needsEnvelope ? envelopeHeaderBytes + signingBytes : 0);
+  const extensionOverheadBytes = encodedBytes - storedBytes;
+
+  let quadqrVersion = null;
+  let quadqrInfo = null;
+  for (let version = 1; version <= MAX_VERSION; version++) {
+    const info = getVersionInfo(version, { ecc, highDensity });
+    if (encodedBytes <= info.capacityBytes) {
+      quadqrVersion = version;
+      quadqrInfo = info;
+      break;
+    }
+  }
+
+  const standard = STANDARD_QR_BYTE_CAPACITY[ecc];
+  let standardQrVersion = null;
+  for (let version = 1; version <= MAX_VERSION; version++) {
+    if (sourceBytes.length <= standard[version - 1]) {
+      standardQrVersion = version;
+      break;
+    }
+  }
+
+  return {
+    ecc,
+    highDensity,
+    cellEncoding,
+    sourceBytes: sourceBytes.length,
+    encodedBytes,
+    storedBytes,
+    extensionOverheadBytes,
+    compression,
+    compressed,
+    signed,
+    quadqrVersion,
+    quadqrSize: quadqrInfo?.size ?? null,
+    quadqrCapacityBytes: quadqrInfo?.capacityBytes ?? null,
+    remainingBytes: quadqrInfo ? quadqrInfo.capacityBytes - encodedBytes : null,
+    utilizationPercent: quadqrInfo ? encodedBytes / quadqrInfo.capacityBytes * 100 : null,
+    standardQrVersion,
+    standardQrSize: standardQrVersion ? 21 + 4 * (standardQrVersion - 1) : null,
+    matrixWidthSavingsPercent: quadqrInfo && standardQrVersion
+      ? (1 - quadqrInfo.size / (21 + 4 * (standardQrVersion - 1))) * 100
+      : null,
+    note: "Compression is measured only when concrete payload bytes are provided. Byte-count-only estimates cannot predict compression gain."
+  };
+}
+
 export function buildCapacityComparison(options = {}) {
   const ecc = normalizeEcc(options.ecc ?? "M");
+  const highDensity = resolveHighDensity(options);
   const versions = options.versions ?? Array.from({ length: MAX_VERSION }, (_, i) => i + 1);
-  return versions.map((version) => compareCapacity(version, ecc));
+  return versions.map((version) => compareCapacity(version, ecc, { highDensity }));
 }
 
 export function benchmarkCodec(options = {}) {
   const ecc = normalizeEcc(options.ecc ?? "M");
+  const highDensity = resolveHighDensity(options);
+  const cellEncoding = encodingForHighDensity(highDensity);
   const iterations = Math.max(1, Math.floor(options.iterations ?? 30));
   const warmup = Math.max(0, Math.floor(options.warmup ?? Math.min(5, iterations)));
   const requestedSizes = options.payloadSizes ?? [24, 32, 128, 512, 1024, 2048];
@@ -122,14 +223,14 @@ export function benchmarkCodec(options = {}) {
 
     let probe;
     try {
-      probe = encodeBytes(payload, { ecc });
+      probe = encodeBytes(payload, { ecc, highDensity });
     } catch (error) {
       results.push({ payloadBytes, skipped: true, reason: error.message });
       continue;
     }
 
     for (let i = 0; i < warmup; i++) {
-      const encoded = encodeBytes(payload, { ecc, version: probe.version });
+      const encoded = encodeBytes(payload, { ecc, highDensity, version: probe.version });
       decodeMatrix(encoded.matrix);
     }
 
@@ -139,7 +240,7 @@ export function benchmarkCodec(options = {}) {
 
     for (let i = 0; i < iterations; i++) {
       let start = nowMs();
-      encoded = encodeBytes(payload, { ecc, version: probe.version });
+      encoded = encodeBytes(payload, { ecc, highDensity, version: probe.version });
       encodeSamples.push(nowMs() - start);
 
       start = nowMs();
@@ -151,7 +252,7 @@ export function benchmarkCodec(options = {}) {
       }
     }
 
-    const versionInfo = getVersionInfo(encoded.version, { ecc });
+    const versionInfo = getVersionInfo(encoded.version, { ecc, highDensity });
     results.push({
       payloadBytes,
       skipped: false,
@@ -170,6 +271,8 @@ export function benchmarkCodec(options = {}) {
   return {
     format: "QuadQR",
     ecc,
+    highDensity,
+    cellEncoding,
     iterations,
     warmup,
     generatedAt: new Date().toISOString(),
@@ -179,11 +282,13 @@ export function benchmarkCodec(options = {}) {
 
 export function benchmarkReport(options = {}) {
   const ecc = normalizeEcc(options.ecc ?? "M");
+  const highDensity = resolveHighDensity(options);
   const versions = options.versions ?? [1, 2, 5, 10, 20, 30, 40];
   return {
-    capacity: buildCapacityComparison({ ecc, versions }),
+    capacity: buildCapacityComparison({ ecc, versions, highDensity }),
     performance: benchmarkCodec({
       ecc,
+      highDensity,
       iterations: options.iterations ?? 30,
       warmup: options.warmup,
       payloadSizes: options.payloadSizes

package/dist/esm/node.js

@@ -10,7 +10,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import { deflateSync, inflateSync } from "node:zlib";
 import { webcrypto } from "node:crypto";
 
-import { renderToImageData, scanImageData } from "./quadqr.js";
+import { renderToImageData, renderToSVG, scanImageData } from "./quadqr.js";
 
 if (!globalThis.crypto) globalThis.crypto = webcrypto;
 
@@ -242,6 +242,18 @@ export async function savePNG(codeOrMatrix, filename, options = {}) {
   return { filename, bytes: png.length };
 }
 
+/** Render a QuadQR code/matrix directly to an SVG string. */
+export function toSVG(codeOrMatrix, options = {}) {
+  return renderToSVG(codeOrMatrix, options);
+}
+
+/** Render a QuadQR code/matrix and save it as SVG. */
+export async function saveSVG(codeOrMatrix, filename, options = {}) {
+  const svg = toSVG(codeOrMatrix, options);
+  await writeFile(filename, svg, "utf8");
+  return { filename, bytes: Buffer.byteLength(svg, "utf8") };
+}
+
 async function decodeWithOptionalSharp(buffer) {
   try {
     const { default: sharp } = await import("sharp");