@ericblade/quagga2 1.10.0 → 1.10.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,295 @@
1
+ # Quagga2 Dependencies
2
+
3
+ This document explains the dependency structure of Quagga2 and clarifies which packages are runtime code dependencies versus build/test tools.
4
+
5
+ ## Background
6
+
7
+ Quagga2 bundles all its code with Webpack, producing standalone browser and Node.js builds. As a result, **all packages are listed as `devDependencies`** in `package.json` because consumers never directly install them - they only use the pre-built bundles in `dist/` and `lib/`.
8
+
9
+ However, this makes it unclear which packages are actual code dependencies (bundled into the final output) versus which are just build/test tools. This document clarifies that distinction.
10
+
11
+ ---
12
+
13
+ ## Runtime Code Dependencies
14
+
15
+ These packages contain code that is **imported by the source code** and **bundled into the final output**:
16
+
17
+ ### Core Libraries
18
+
19
+ - **`gl-matrix`** (^3.4.4)
20
+ - **Purpose**: High-performance vector and matrix math operations
21
+ - **Usage**: Used throughout the codebase for geometric calculations
22
+ - **Files**:
23
+ - `src/quagga/quagga.ts` - vec2 operations for bounding boxes
24
+ - `src/quagga/initBuffers.ts` - vec2 for buffer initialization
25
+ - `src/locator/barcode_locator.js` - vec2, mat2 for barcode location
26
+ - `src/common/image_wrapper.ts` - vec2 for image transforms
27
+ - `src/common/cvutils/ImageRef.ts` - vec2, vec3 for computer vision
28
+ - `src/common/cluster.js` - vec2 for clustering algorithms
29
+
30
+ - **`lodash`** (^4.17.21)
31
+ - **Purpose**: Utility functions for object manipulation
32
+ - **Usage**: Primarily `merge()` for config merging, `pick()` for object selection
33
+ - **Files**:
34
+ - `src/quagga.js` - merge() for configuration
35
+ - `src/QuaggaStatic.ts` - merge() for configuration
36
+ - `src/reader/ean_reader.ts` - merge() for config defaults
37
+ - `src/reader/i2of5_reader.ts` - merge() for config defaults
38
+ - `src/input/camera_access.ts` - pick() for MediaTrackConstraints
39
+ - `src/locator/test/barcode_locator.spec.ts` - merge() in tests
40
+
41
+ ### Image Processing
42
+
43
+ - **`ndarray`** (^1.0.19)
44
+ - **Purpose**: N-dimensional array manipulation
45
+ - **Usage**: Core data structure for image data processing
46
+ - **Files**:
47
+ - `src/input/input_stream/input_stream_base.ts` - NdArray type definitions
48
+ - `src/input/input_stream/input_stream.ts` - NdArray for frame data
49
+ - `src/input/frame_grabber.ts` - Ndarray for frame manipulation
50
+ - `src/vendor.d.ts` - Type definitions
51
+
52
+ - **`ndarray-linear-interpolate`** (^1.0.0)
53
+ - **Purpose**: Bilinear interpolation for ndarray data
54
+ - **Usage**: Image scaling and transformations
55
+ - **Files**:
56
+ - `src/input/frame_grabber.ts` - `d2()` method for 2D interpolation
57
+
58
+ - **`ndarray-pixels`** (^5.0.1)
59
+ - **Purpose**: Convert between image formats and ndarray
60
+ - **Usage**: Loading image data from various sources
61
+ - **Files**:
62
+ - `src/input/input_stream/input_stream.ts` - `getPixels()` for image loading
63
+
64
+ ### Polyfills (Deprecated)
65
+
66
+ - **`@babel/polyfill`** (^7.12.1)
67
+ - **Status**: ⚠️ **DEPRECATED** by Babel team
68
+ - **Purpose**: Legacy polyfill for ES6+ features
69
+ - **Current Usage**: Not directly imported in source code
70
+ - **Recommendation**: Should be removed in favor of `core-js` + `regenerator-runtime` or Babel's automatic polyfill injection
71
+ - **Migration Path**: Use `@babel/preset-env` with `useBuiltIns: 'usage'` and explicit `core-js@3`
72
+
73
+ ---
74
+
75
+ ## Build & Development Tools
76
+
77
+ These packages are **only used during build/development** and are **not bundled into the final output**:
78
+
79
+ ### TypeScript Toolchain
80
+
81
+ - **`typescript`** (^5.9.3) - TypeScript compiler
82
+ - **`@types/*`** packages - Type definitions for TypeScript
83
+ - `@types/chai`, `@types/gl-vec2`, `@types/lodash`, `@types/mocha`, `@types/node`, `@types/sinon`, `@types/sinon-chai`
84
+
85
+ ### Webpack & Bundling
86
+
87
+ - **`webpack`** (^4.44.2) - Module bundler (used to create `dist/` and `lib/` outputs)
88
+ - **`webpack-cli`** (^3.3.12) - Webpack command-line interface
89
+ - **`babel-loader`** (^8.2.5) - Webpack loader for Babel transpilation
90
+ - **`source-map-loader`** (^1.1.1) - Webpack loader for source maps
91
+
92
+ ### Babel Transpilation
93
+
94
+ - **`@babel/core`** (^7.28.5) - Babel compiler core
95
+ - **`@babel/preset-env`** (^7.28.5) - Smart transpilation based on target environments
96
+ - **`@babel/preset-typescript`** (^7.28.5) - TypeScript support in Babel
97
+ - **`@babel/plugin-*`** - Various syntax plugins:
98
+ - `@babel/plugin-proposal-class-properties`
99
+ - `@babel/plugin-proposal-nullish-coalescing-operator`
100
+ - `@babel/plugin-proposal-object-rest-spread`
101
+ - `@babel/plugin-proposal-optional-chaining`
102
+ - `@babel/plugin-transform-runtime`
103
+ - **`@babel/runtime`** (^7.28.4) - Babel runtime helpers
104
+ - **`babel-plugin-add-module-exports`** (^1.0.4) - CommonJS module.exports handling
105
+ - **`babel-plugin-istanbul`** (^7.0.1) - Code coverage instrumentation
106
+
107
+ ### Testing
108
+
109
+ - **`mocha`** (^5.2.0) - Test framework
110
+ - **`chai`** (^4.3.10) - Assertion library
111
+ - **`sinon`** (^21.0.0) - Test spies, stubs, and mocks
112
+ - **`sinon-chai`** (^3.7.0) - Sinon assertions for Chai
113
+ - **`ts-mocha`** (^11.1.0) - TypeScript support for Mocha
114
+ - **`ts-node`** (^10.9.2) - TypeScript execution for Node.js
115
+ - **`cypress`** (^13.1.0) - End-to-end browser testing
116
+ - **`@cypress/webpack-preprocessor`** (6.0.0) - Webpack integration for Cypress
117
+ - **`@cypress/code-coverage`** (^3.12.4) - Code coverage for Cypress tests
118
+ - **`nyc`** (^17.1.0) - Code coverage tool (Istanbul wrapper)
119
+
120
+ ### Linting & Code Quality
121
+
122
+ - **`eslint`** (^8.57.1) - JavaScript/TypeScript linter
123
+ - **`@typescript-eslint/eslint-plugin`** (^7.18.0) - TypeScript-specific ESLint rules
124
+ - **`@typescript-eslint/parser`** (^7.18.0) - TypeScript parser for ESLint
125
+ - **`eslint-config-airbnb-base`** (^15.0.0) - Airbnb JavaScript style guide
126
+ - **`eslint-config-airbnb-typescript`** (^18.0.0) - Airbnb style for TypeScript
127
+ - **`eslint-config-airbnb-typescript-base`** (^6.0.1) - Base Airbnb TypeScript config
128
+ - **`eslint-plugin-import`** (^2.32.0) - Import/export validation
129
+ - **`eslint-plugin-jsx-a11y`** (^6.10.2) - Accessibility linting
130
+ - **`eslint-plugin-typescript-sort-keys`** (^3.3.0) - Enforce sorted object keys
131
+
132
+ ### Utilities
133
+
134
+ - **`core-js`** (^3.46.0) - Modern JavaScript polyfills (used by Babel)
135
+ - **`cross-env`** (^10.1.0) - Cross-platform environment variable setting
136
+
137
+ ---
138
+
139
+ ## Optional Dependencies
140
+
141
+ - **`fsevents`** (2.3.3)
142
+ - **Platform**: macOS only
143
+ - **Purpose**: Native file watching for better performance
144
+ - **Usage**: Automatically used by Webpack/build tools on macOS
145
+
146
+ ---
147
+
148
+ ## Overrides
149
+
150
+ The `overrides` field forces specific versions of transitive dependencies:
151
+
152
+ ```json
153
+ "overrides": {
154
+ "@cypress/request": "^3.0.9"
155
+ }
156
+ ```
157
+
158
+ - **Purpose**: Security fix for `form-data` vulnerability (CVE in versions < 2.5.4)
159
+ - **Details**: Cypress 13.1.0 bundles `@cypress/request@3.0.0` which depends on vulnerable `form-data@2.3.3`. This override forces `@cypress/request@^3.0.9` which uses safe `form-data@~4.0.4`.
160
+
161
+ ---
162
+
163
+ ## Bundle Size Impact
164
+
165
+ When evaluating dependencies, consider their impact on bundle size:
166
+
167
+ | Package | Approximate Size | Bundled? |
168
+ |---------|-----------------|----------|
169
+ | `gl-matrix` | ~50 KB (minified) | ✅ Yes |
170
+ | `lodash` | ~4 KB (only `merge` + `pick`) | ✅ Yes (tree-shaken) |
171
+ | `ndarray` | ~5 KB | ✅ Yes |
172
+ | `ndarray-linear-interpolate` | ~2 KB | ✅ Yes |
173
+ | `ndarray-pixels` | ~10 KB | ✅ Yes (browser) |
174
+ | `webpack` | ~1.5 MB | ❌ No (dev only) |
175
+ | `typescript` | ~50 MB | ❌ No (dev only) |
176
+
177
+ ---
178
+
179
+ ## Adding New Dependencies
180
+
181
+ When adding a new dependency, consider:
182
+
183
+ 1. **Is it a runtime dependency?**
184
+ - Will the code be `import`ed in `src/` files?
185
+ - Will it be bundled into `dist/` or `lib/` output?
186
+ - → Add to `devDependencies` (all deps go here due to bundling)
187
+ - → Document it in the "Runtime Code Dependencies" section above
188
+
189
+ 2. **Is it a build/test tool?**
190
+ - Is it only used by Webpack, Babel, ESLint, Mocha, etc.?
191
+ - → Add to `devDependencies`
192
+ - → Document it in the "Build & Development Tools" section above
193
+
194
+ 3. **Bundle size impact?**
195
+ - Run `npm run build` and check the size change in `dist/quagga.min.js`
196
+ - Consider tree-shaking (does the library support ES modules?)
197
+ - Look for lighter alternatives if the package is large
198
+
199
+ 4. **Browser compatibility?**
200
+ - Does the package work in browsers?
201
+ - Does it require Node.js-specific APIs (`fs`, `path`, etc.)?
202
+ - → Check if it's already shimmed in `configs/webpack.config.js` (e.g., `node: { fs: 'empty' }`)
203
+
204
+ ---
205
+
206
+ ## Version Constraints
207
+
208
+ ### Pinned Versions
209
+
210
+ Some packages are pinned to specific versions due to compatibility issues:
211
+
212
+ - **`mocha@^5.2.0`** - Pinned to v5 because newer versions have breaking changes
213
+ - **`chai@^4.3.10`** - Pinned to v4 because v5+ and v6+ are ESM-only, incompatible with CommonJS tests
214
+ - **`sinon-chai@^3.7.0`** - Pinned to match `chai@4.x` compatibility
215
+ - **`webpack@^4.44.2`** - Pinned to v4 because v5 requires significant config migration
216
+ - **`cypress@^13.1.0`** - Pinned to v13 for stability
217
+
218
+ These are configured in `.ncurc.json` to prevent accidental upgrades via `npm-check-updates`.
219
+
220
+ ### Upgrade Policy
221
+
222
+ - **TypeScript ecosystem** (`typescript`, `@typescript-eslint/*`, `ts-*`): Keep up-to-date
223
+ - **Babel ecosystem** (`@babel/*`): Keep up-to-date for security and features
224
+ - **Testing tools** (`mocha`, `chai`, `sinon`): Upgrade cautiously, test thoroughly
225
+ - **Webpack & bundlers**: Major version upgrades require careful migration planning
226
+ - **Runtime dependencies** (`gl-matrix`, `lodash`, `ndarray*`): Keep up-to-date unless breaking changes occur
227
+
228
+ ---
229
+
230
+ ## Security Considerations
231
+
232
+ ### Known Issues
233
+
234
+ 1. **`@babel/polyfill` is deprecated** - Should migrate to `core-js@3` + `regenerator-runtime`
235
+ 2. **Old `mocha` version** - v5.2.0 is from 2018, may have unpatched vulnerabilities
236
+ 3. **Webpack 4** - No longer receives updates, consider upgrading to Webpack 5
237
+
238
+ ### Monitoring
239
+
240
+ - Run `npm audit` regularly to check for vulnerabilities
241
+ - Use `npm run check-updates` to see available updates
242
+ - Check GitHub Dependabot alerts
243
+
244
+ ---
245
+
246
+ ## FAQ
247
+
248
+ **Q: Why are runtime dependencies in `devDependencies` instead of `dependencies`?**
249
+
250
+ A: Quagga2 is a **bundled library**. Consumers install the package and use the pre-built files (`dist/quagga.min.js` or `lib/quagga.js`), not the source code. They never run `npm install` on Quagga2's dependencies. Therefore, from npm's perspective, all packages are development dependencies (used during build), not runtime dependencies (used after install).
251
+
252
+ **Q: How can I tell if a package is actually used in the code?**
253
+
254
+ A: Search the `src/` directory:
255
+ ```bash
256
+ # Search for imports
257
+ grep -r "from 'package-name'" src/
258
+ grep -r 'from "package-name"' src/
259
+ grep -r "require('package-name')" src/
260
+ ```
261
+
262
+ **Q: What's the difference between `optionalDependencies` and `devDependencies`?**
263
+
264
+ A: `optionalDependencies` are packages that enhance functionality if available but aren't required (like `fsevents` for macOS file watching). `devDependencies` are required for development but not for using the published package.
265
+
266
+ **Q: Can I remove `@babel/polyfill`?**
267
+
268
+ A: Yes, but carefully. It's deprecated and not directly imported anymore. Remove it from `package.json` and verify that `@babel/preset-env` is configured to polyfill features automatically via `core-js@3`. Test thoroughly in older browsers (IE11, older Safari) after removal.
269
+
270
+ **Q: Why can't I upgrade `chai` to version 5 or 6?**
271
+
272
+ A: `chai@5+` and `chai@6+` are ESM-only (ES modules). Quagga2's tests use CommonJS (`require()`), and `mocha@5` doesn't support ESM. Upgrading `chai` requires also upgrading `mocha` to v9.1.0+ and migrating all test files to ESM syntax.
273
+
274
+ ---
275
+
276
+ ## Related Files
277
+
278
+ - **`package.json`** - Dependency declarations
279
+ - **`.ncurc.json`** - npm-check-updates configuration (blocks unsafe auto-upgrades)
280
+ - **`configs/webpack.config.js`** - Build configuration showing which dependencies are bundled
281
+ - **`configs/webpack.node.config.js`** - Node.js-specific build configuration
282
+ - **`CHANGELOG.md`** - Version history and dependency changes
283
+
284
+ ---
285
+
286
+ ## Maintenance Notes
287
+
288
+ This document was created in November 2025 following the TypeScript 5.9.3 upgrade. It should be updated whenever:
289
+
290
+ - A new dependency is added or removed
291
+ - A major version upgrade changes behavior
292
+ - Security vulnerabilities are discovered and patched
293
+ - Build tooling changes significantly
294
+
295
+ Last updated: 2025-11-16
package/README.md CHANGED
@@ -507,7 +507,10 @@ The `inputStream` property defines the sources of images/videos within QuaggaJS.
507
507
  left: "0%", // left offset
508
508
  bottom: "0%" // bottom offset
509
509
  },
510
- singleChannel: false // true: only the red color-channel is read
510
+ singleChannel: false, // true: only the red color-channel is read
511
+ debug: {
512
+ showImageDetails: false // logs frame grabber info and canvas size adjustments to console
513
+ }
511
514
  }
512
515
  ```
513
516
 
@@ -556,7 +559,8 @@ options within the `decoder` are for debugging/visualization purposes only.
556
559
  drawBoundingBox: false,
557
560
  showFrequency: false,
558
561
  drawScanline: false,
559
- showPattern: false
562
+ showPattern: false,
563
+ printReaderInfo: false // logs reader registration and initialization to console
560
564
  }
561
565
  multiple: false
562
566
  }
@@ -644,6 +648,8 @@ Only two properties are relevant for the use in Quagga (`halfSample` and
644
648
  showLabels: false,
645
649
  showPatchLabels: false,
646
650
  showRemainingPatchLabels: false,
651
+ showPatchSize: false, // logs calculated patch size to console
652
+ showImageDetails: false, // logs image wrapper size and canvas details to console
647
653
  boxFromPatches: {
648
654
  showTransformed: false,
649
655
  showTransformedBox: false,