Added scanning barcodes with a camera
This commit is contained in:
295
quagga2/quagga2-1.12.1/docs/reference/dependencies.md
Normal file
295
quagga2/quagga2-1.12.1/docs/reference/dependencies.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# Quagga2 Dependencies
|
||||
|
||||
This document explains the dependency structure of Quagga2 and clarifies which packages are runtime code dependencies versus build/test tools.
|
||||
|
||||
## Background
|
||||
|
||||
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/`.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Runtime Code Dependencies
|
||||
|
||||
These packages contain code that is **imported by the source code** and **bundled into the final output**:
|
||||
|
||||
### Core Libraries
|
||||
|
||||
- **`gl-matrix`** (^3.4.4)
|
||||
- **Purpose**: High-performance vector and matrix math operations
|
||||
- **Usage**: Used throughout the codebase for geometric calculations
|
||||
- **Files**:
|
||||
- `src/quagga/quagga.ts` - vec2 operations for bounding boxes
|
||||
- `src/quagga/initBuffers.ts` - vec2 for buffer initialization
|
||||
- `src/locator/barcode_locator.js` - vec2, mat2 for barcode location
|
||||
- `src/common/image_wrapper.ts` - vec2 for image transforms
|
||||
- `src/common/cvutils/ImageRef.ts` - vec2, vec3 for computer vision
|
||||
- `src/common/cluster.js` - vec2 for clustering algorithms
|
||||
|
||||
- **`lodash`** (^4.17.21)
|
||||
- **Purpose**: Utility functions for object manipulation
|
||||
- **Usage**: Primarily `merge()` for config merging, `pick()` for object selection
|
||||
- **Files**:
|
||||
- `src/quagga.js` - merge() for configuration
|
||||
- `src/QuaggaStatic.ts` - merge() for configuration
|
||||
- `src/reader/ean_reader.ts` - merge() for config defaults
|
||||
- `src/reader/i2of5_reader.ts` - merge() for config defaults
|
||||
- `src/input/camera_access.ts` - pick() for MediaTrackConstraints
|
||||
- `src/locator/test/barcode_locator.spec.ts` - merge() in tests
|
||||
|
||||
### Image Processing
|
||||
|
||||
- **`ndarray`** (^1.0.19)
|
||||
- **Purpose**: N-dimensional array manipulation
|
||||
- **Usage**: Core data structure for image data processing
|
||||
- **Files**:
|
||||
- `src/input/input_stream/input_stream_base.ts` - NdArray type definitions
|
||||
- `src/input/input_stream/input_stream.ts` - NdArray for frame data
|
||||
- `src/input/frame_grabber.ts` - Ndarray for frame manipulation
|
||||
- `src/vendor.d.ts` - Type definitions
|
||||
|
||||
- **`ndarray-linear-interpolate`** (^1.0.0)
|
||||
- **Purpose**: Bilinear interpolation for ndarray data
|
||||
- **Usage**: Image scaling and transformations
|
||||
- **Files**:
|
||||
- `src/input/frame_grabber.ts` - `d2()` method for 2D interpolation
|
||||
|
||||
- **`ndarray-pixels`** (^5.0.1)
|
||||
- **Purpose**: Convert between image formats and ndarray
|
||||
- **Usage**: Loading image data from various sources
|
||||
- **Files**:
|
||||
- `src/input/input_stream/input_stream.ts` - `getPixels()` for image loading
|
||||
|
||||
### Polyfills (Deprecated)
|
||||
|
||||
- **`@babel/polyfill`** (^7.12.1)
|
||||
- **Status**: ⚠️ **DEPRECATED** by Babel team
|
||||
- **Purpose**: Legacy polyfill for ES6+ features
|
||||
- **Current Usage**: Not directly imported in source code
|
||||
- **Recommendation**: Should be removed in favor of `core-js` + `regenerator-runtime` or Babel's automatic polyfill injection
|
||||
- **Migration Path**: Use `@babel/preset-env` with `useBuiltIns: 'usage'` and explicit `core-js@3`
|
||||
|
||||
---
|
||||
|
||||
## Build & Development Tools
|
||||
|
||||
These packages are **only used during build/development** and are **not bundled into the final output**:
|
||||
|
||||
### TypeScript Toolchain
|
||||
|
||||
- **`typescript`** (^5.9.3) - TypeScript compiler
|
||||
- **`@types/*`** packages - Type definitions for TypeScript
|
||||
- `@types/chai`, `@types/gl-vec2`, `@types/lodash`, `@types/mocha`, `@types/node`, `@types/sinon`, `@types/sinon-chai`
|
||||
|
||||
### Webpack & Bundling
|
||||
|
||||
- **`webpack`** (^4.44.2) - Module bundler (used to create `dist/` and `lib/` outputs)
|
||||
- **`webpack-cli`** (^3.3.12) - Webpack command-line interface
|
||||
- **`babel-loader`** (^8.2.5) - Webpack loader for Babel transpilation
|
||||
- **`source-map-loader`** (^1.1.1) - Webpack loader for source maps
|
||||
|
||||
### Babel Transpilation
|
||||
|
||||
- **`@babel/core`** (^7.28.5) - Babel compiler core
|
||||
- **`@babel/preset-env`** (^7.28.5) - Smart transpilation based on target environments
|
||||
- **`@babel/preset-typescript`** (^7.28.5) - TypeScript support in Babel
|
||||
- **`@babel/plugin-*`** - Various syntax plugins:
|
||||
- `@babel/plugin-proposal-class-properties`
|
||||
- `@babel/plugin-proposal-nullish-coalescing-operator`
|
||||
- `@babel/plugin-proposal-object-rest-spread`
|
||||
- `@babel/plugin-proposal-optional-chaining`
|
||||
- `@babel/plugin-transform-runtime`
|
||||
- **`@babel/runtime`** (^7.28.4) - Babel runtime helpers
|
||||
- **`babel-plugin-add-module-exports`** (^1.0.4) - CommonJS module.exports handling
|
||||
- **`babel-plugin-istanbul`** (^7.0.1) - Code coverage instrumentation
|
||||
|
||||
### Testing
|
||||
|
||||
- **`mocha`** (^5.2.0) - Test framework
|
||||
- **`chai`** (^4.3.10) - Assertion library
|
||||
- **`sinon`** (^21.0.0) - Test spies, stubs, and mocks
|
||||
- **`sinon-chai`** (^3.7.0) - Sinon assertions for Chai
|
||||
- **`ts-mocha`** (^11.1.0) - TypeScript support for Mocha
|
||||
- **`ts-node`** (^10.9.2) - TypeScript execution for Node.js
|
||||
- **`cypress`** (^13.1.0) - End-to-end browser testing
|
||||
- **`@cypress/webpack-preprocessor`** (6.0.0) - Webpack integration for Cypress
|
||||
- **`@cypress/code-coverage`** (^3.12.4) - Code coverage for Cypress tests
|
||||
- **`nyc`** (^17.1.0) - Code coverage tool (Istanbul wrapper)
|
||||
|
||||
### Linting & Code Quality
|
||||
|
||||
- **`eslint`** (^8.57.1) - JavaScript/TypeScript linter
|
||||
- **`@typescript-eslint/eslint-plugin`** (^7.18.0) - TypeScript-specific ESLint rules
|
||||
- **`@typescript-eslint/parser`** (^7.18.0) - TypeScript parser for ESLint
|
||||
- **`eslint-config-airbnb-base`** (^15.0.0) - Airbnb JavaScript style guide
|
||||
- **`eslint-config-airbnb-typescript`** (^18.0.0) - Airbnb style for TypeScript
|
||||
- **`eslint-config-airbnb-typescript-base`** (^6.0.1) - Base Airbnb TypeScript config
|
||||
- **`eslint-plugin-import`** (^2.32.0) - Import/export validation
|
||||
- **`eslint-plugin-jsx-a11y`** (^6.10.2) - Accessibility linting
|
||||
- **`eslint-plugin-typescript-sort-keys`** (^3.3.0) - Enforce sorted object keys
|
||||
|
||||
### Utilities
|
||||
|
||||
- **`core-js`** (^3.46.0) - Modern JavaScript polyfills (used by Babel)
|
||||
- **`cross-env`** (^10.1.0) - Cross-platform environment variable setting
|
||||
|
||||
---
|
||||
|
||||
## Optional Dependencies
|
||||
|
||||
- **`fsevents`** (2.3.3)
|
||||
- **Platform**: macOS only
|
||||
- **Purpose**: Native file watching for better performance
|
||||
- **Usage**: Automatically used by Webpack/build tools on macOS
|
||||
|
||||
---
|
||||
|
||||
## Overrides
|
||||
|
||||
The `overrides` field forces specific versions of transitive dependencies:
|
||||
|
||||
```json
|
||||
"overrides": {
|
||||
"@cypress/request": "^3.0.9"
|
||||
}
|
||||
```
|
||||
|
||||
- **Purpose**: Security fix for `form-data` vulnerability (CVE in versions < 2.5.4)
|
||||
- **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`.
|
||||
|
||||
---
|
||||
|
||||
## Bundle Size Impact
|
||||
|
||||
When evaluating dependencies, consider their impact on bundle size:
|
||||
|
||||
| Package | Approximate Size | Bundled? |
|
||||
|---------|-----------------|----------|
|
||||
| `gl-matrix` | ~50 KB (minified) | ✅ Yes |
|
||||
| `lodash` | ~4 KB (only `merge` + `pick`) | ✅ Yes (tree-shaken) |
|
||||
| `ndarray` | ~5 KB | ✅ Yes |
|
||||
| `ndarray-linear-interpolate` | ~2 KB | ✅ Yes |
|
||||
| `ndarray-pixels` | ~10 KB | ✅ Yes (browser) |
|
||||
| `webpack` | ~1.5 MB | ❌ No (dev only) |
|
||||
| `typescript` | ~50 MB | ❌ No (dev only) |
|
||||
|
||||
---
|
||||
|
||||
## Adding New Dependencies
|
||||
|
||||
When adding a new dependency, consider:
|
||||
|
||||
1. **Is it a runtime dependency?**
|
||||
- Will the code be `import`ed in `src/` files?
|
||||
- Will it be bundled into `dist/` or `lib/` output?
|
||||
- → Add to `devDependencies` (all deps go here due to bundling)
|
||||
- → Document it in the "Runtime Code Dependencies" section above
|
||||
|
||||
2. **Is it a build/test tool?**
|
||||
- Is it only used by Webpack, Babel, ESLint, Mocha, etc.?
|
||||
- → Add to `devDependencies`
|
||||
- → Document it in the "Build & Development Tools" section above
|
||||
|
||||
3. **Bundle size impact?**
|
||||
- Run `npm run build` and check the size change in `dist/quagga.min.js`
|
||||
- Consider tree-shaking (does the library support ES modules?)
|
||||
- Look for lighter alternatives if the package is large
|
||||
|
||||
4. **Browser compatibility?**
|
||||
- Does the package work in browsers?
|
||||
- Does it require Node.js-specific APIs (`fs`, `path`, etc.)?
|
||||
- → Check if it's already shimmed in `configs/webpack.config.js` (e.g., `node: { fs: 'empty' }`)
|
||||
|
||||
---
|
||||
|
||||
## Version Constraints
|
||||
|
||||
### Pinned Versions
|
||||
|
||||
Some packages are pinned to specific versions due to compatibility issues:
|
||||
|
||||
- **`mocha@^5.2.0`** - Pinned to v5 because newer versions have breaking changes
|
||||
- **`chai@^4.3.10`** - Pinned to v4 because v5+ and v6+ are ESM-only, incompatible with CommonJS tests
|
||||
- **`sinon-chai@^3.7.0`** - Pinned to match `chai@4.x` compatibility
|
||||
- **`webpack@^4.44.2`** - Pinned to v4 because v5 requires significant config migration
|
||||
- **`cypress@^13.1.0`** - Pinned to v13 for stability
|
||||
|
||||
These are configured in `.ncurc.json` to prevent accidental upgrades via `npm-check-updates`.
|
||||
|
||||
### Upgrade Policy
|
||||
|
||||
- **TypeScript ecosystem** (`typescript`, `@typescript-eslint/*`, `ts-*`): Keep up-to-date
|
||||
- **Babel ecosystem** (`@babel/*`): Keep up-to-date for security and features
|
||||
- **Testing tools** (`mocha`, `chai`, `sinon`): Upgrade cautiously, test thoroughly
|
||||
- **Webpack & bundlers**: Major version upgrades require careful migration planning
|
||||
- **Runtime dependencies** (`gl-matrix`, `lodash`, `ndarray*`): Keep up-to-date unless breaking changes occur
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Known Issues
|
||||
|
||||
1. **`@babel/polyfill` is deprecated** - Should migrate to `core-js@3` + `regenerator-runtime`
|
||||
2. **Old `mocha` version** - v5.2.0 is from 2018, may have unpatched vulnerabilities
|
||||
3. **Webpack 4** - No longer receives updates, consider upgrading to Webpack 5
|
||||
|
||||
### Monitoring
|
||||
|
||||
- Run `npm audit` regularly to check for vulnerabilities
|
||||
- Use `npm run check-updates` to see available updates
|
||||
- Check GitHub Dependabot alerts
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Why are runtime dependencies in `devDependencies` instead of `dependencies`?**
|
||||
|
||||
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).
|
||||
|
||||
**Q: How can I tell if a package is actually used in the code?**
|
||||
|
||||
A: Search the `src/` directory:
|
||||
```bash
|
||||
# Search for imports
|
||||
grep -r "from 'package-name'" src/
|
||||
grep -r 'from "package-name"' src/
|
||||
grep -r "require('package-name')" src/
|
||||
```
|
||||
|
||||
**Q: What's the difference between `optionalDependencies` and `devDependencies`?**
|
||||
|
||||
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.
|
||||
|
||||
**Q: Can I remove `@babel/polyfill`?**
|
||||
|
||||
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.
|
||||
|
||||
**Q: Why can't I upgrade `chai` to version 5 or 6?**
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **`package.json`** - Dependency declarations
|
||||
- **`.ncurc.json`** - npm-check-updates configuration (blocks unsafe auto-upgrades)
|
||||
- **`configs/webpack.config.js`** - Build configuration showing which dependencies are bundled
|
||||
- **`configs/webpack.node.config.js`** - Node.js-specific build configuration
|
||||
- **`CHANGELOG.md`** - Version history and dependency changes
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
This document was created in November 2025 following the TypeScript 5.9.3 upgrade. It should be updated whenever:
|
||||
|
||||
- A new dependency is added or removed
|
||||
- A major version upgrade changes behavior
|
||||
- Security vulnerabilities are discovered and patched
|
||||
- Build tooling changes significantly
|
||||
|
||||
Last updated: 2025-11-16
|
||||
Reference in New Issue
Block a user