QR 0.3.14 · MIT · No runtime dependencies
Choosing a QR library
Choose @forgesworn/qr when you need to make and read QR codes, control your
own camera interface, and keep scanning inside your application. The TypeScript
package has no runtime dependencies, performs no network requests and needs no
API key. The optional WebAssembly backend is loaded explicitly by your code.
The library and its Kotlin and Rust sources are MIT licensed.
Where it fits
| Requirement | What QR provides |
|---|---|
| Generate and read in one package | Text and byte encoding, SVG/canvas/terminal rendering, pixel and module-grid decoding |
| Browser, worker and Node integration | Typed ESM API; synchronous operations after optional WASM initialisation |
| Repeated camera frames | Independent tracked sessions, fresh payload reads and same-call full-frame recovery |
| Difficult QR images | Perspective, rotation, inversion, mirroring and bounded recovery for damaged or bent symbols |
| Inspectable behaviour | A written specification, shared conformance vectors and reproducible comparison receipts |
| Local processing | No built-in upload, telemetry, camera service or hosted decoding dependency |
Local processing describes the library. Your application, chosen asset host and camera permissions determine its wider privacy behaviour.
Measured accuracy
The comparison uses QR and pinned ZXing-WASM 3.1.7. The final packaged TypeScript and WASM results match across all 2,264 accuracy and regression cases. Each reader receives the same inputs. A correct read requires the expected payload; the synthetic suites also check its bytes.
| Dataset | QR | ZXing-WASM |
|---|---|---|
| Existing photograph collection | 180/184 | 171/184 |
| 192-case synthetic regression set | 174/192 | 169/192 |
| Frozen stress set: positive frames | 172/224 | 150/224 |
| Previously qualified synthetic positives | 69/128 | 55/128 |
| Eroded finders within that stress set | 18/28 | 3/28 |
| Wrong payloads in the stress set | 0 | 0 |
| False reads on its 32 negative controls | 0 | 0 |
| Evaluated curved distortion set | 52/96 | 42/96 |
| Earlier curved distortion set | 124/128 | 106/128 |
| Previous curved holdout | 80/128 | 52/128 |
| Earlier separate curved holdout | 82/128 | 67/128 |
| Previous curved set frozen before evaluation | 90/128 | 70/128 |
| Previous curved set frozen before version-peer evaluation | 79/128 | 53/128 |
| Curved set frozen before alternate-grid evaluation | 77/128 | 57/128 |
| Curved set frozen before header-rediscovery evaluation | 72/128 | 53/128 |
| Curved set frozen before selected-mesh evaluation | 87/128 | 69/128 |
| New curved set frozen before quadratic evaluation | 118/256 | 77/256 |
These are finite datasets, including synthetic images made with our existing renderer. They do not establish accuracy on every camera, application or kind of damage. The evaluated sets are regression data, not unseen validation. Both readers miss all 28 finder-occlusion cases in that stress set. QR 0.3.14 reads 2,872/2,944 rotated, mirrored and inverted views of the 184 photographs, including all 16 views of one dense curved photo. These transformations are related views, not independent photographs.
Version 0.3.14 fits a terminal quadratic surface to six already measured alignment nodes and three finder anchors. It runs only after all earlier reads fail, chooses the first strict format agreement before one symbol read, and preserves the existing version and payload checks. Across the earlier 1,120 curved frames QR improves from 653 to 743 exact reads against ZXing's 569. The separately frozen 256-frame set improves from 65 to 118 against ZXing's 77. Combined, that is 861/1,376 versus 646/1,376, with 143 gains over 0.3.13. Both read 632; QR alone reads 229, ZXing alone reads 14, and neither reads 501. Earlier complete successful results and inputs are preserved, with no wrong QR payloads observed. The 888-case regression suite and its 64 negative controls are unchanged.
The new validation set contains 64 images per mathematical profile: QR reads 61 parabolas versus ZXing's 27, 32 circular arches versus 23, and 25 cubic skews versus 27. Neither reads any of its 64 double-wave cases. Pixels and payloads were disjoint from the earlier 1,120 before evaluation; version sizes overlap earlier work. These are synthetic renderings, not evidence of accuracy on arbitrary physical surfaces or cameras, and the evaluated set is now regression data. See the release evidence and full methodology and history.
Speed and trade-offs
| Fixed frame | QR 0.3.14 WASM median | ZXing-WASM 3.1.7 median |
|---|---|---|
| Clean | 1.595–1.618 ms | 2.016–2.027 ms |
| Blank | 1.216–1.238 ms | 2.231–2.237 ms |
| Noise | 21.304–21.321 ms | 8.013–8.079 ms |
These are public-API timings on three fixed 1280 × 720 RGBA frames. Two sequential native Node 24.21.0 processes on an M4 Max use 60 alternating pairs after at least ten warm-up pairs and 500 ms. Complete results and inputs stay unchanged. Other desktop applications were open; no task-owned QR computation ran concurrently. This does not establish mobile latency or general throughput.
The twelve sampled new curved reads cost 0.18–4.27% more WASM median time than the earlier misses; TypeScript costs 0.66–6.06% more. Two confirmed terminal-sampling misses cost 0.10–1.53% more in WASM and 1.24–2.04% more in TypeScript. Accuracy improves at a measured runtime cost. Random-noise rejection remains about 2.6× slower than ZXing.
Version 0.3.14 keeps the eight legacy second looks, 11,500,000 alignment probes and 720 maps, then permits one additional terminal threshold computation, at most 4,761 bilinear module samples and one symbol read. Legacy Work does not count this added pass. Earlier successful paths can still pay for one bounded offset snapshot. The descriptor uses 144 logical bytes plus metadata; the existing 281,961-byte retained-grid bound excludes the new active grid, threshold buffers, temporaries and allocator capacity. These are not peak-heap bounds. The packaged WASM is 261,831 bytes, 8,908 bytes larger than 0.3.13.
Accuracy takes priority over rejecting an unsuccessful frame quickly. A tested mandatory finder-ring filter was rejected because it excluded known successful damaged-code paths. Speed improvements must preserve existing successful regression cases and must not introduce incorrect payloads. See the full performance report for raw timings, p95 values, source identities, earlier releases and remaining limitations.
When another library is a better fit
- You need formats beyond ordinary QR Code Model 2, such as Data Matrix, Aztec, PDF417, Micro QR or linear barcodes.
- You want a ready-made camera interface, permission flow and viewfinder.
- You require CommonJS, an older JavaScript target, or an established native mobile SDK with device evidence for your supported hardware.
- Your workload is dominated by rapidly rejecting highly textured images: ZXing is faster on our recorded random-noise test.
QR returns one result per decode call. It does not promise multi-code detection, authenticate the contents of a QR code, or decide whether a decoded URL is safe. Treat decoded payloads as untrusted input in the application.
Evaluate it in your application
Start with the installation and recipes. Test your own cameras, lighting, printed sizes and damaged examples; measure exact payloads, misses, false reads and time to the first correct read. Use a worker, keep at most one frame in flight, and reset a tracked session when changing cameras. Compare the TypeScript and optional WASM backends on your actual devices.