@sec-ant/barcode-detector - npm Package Compare versions

Comparing version 1.1.2 to 1.2.0

package.json

 {
   "name": "@sec-ant/barcode-detector",
+  "description": "A Barcode Detection API polyfill that uses ZXing webassembly under the hood",
   "private": false,
-  "version": "1.1.2",
+  "version": "1.2.0",
   "type": "module",
@@ -9,25 +10,21 @@ "files": [
   ],
-  "main": "./dist/index.js",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/es/index.js",
   "exports": {
-    ".": "./dist/index.js",
-    "./pure": "./dist/pure.js",
-    "./side-effects": "./dist/side-effects.js"
+    ".": {
+      "import": "./dist/es/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/es/index.js"
+    },
+    "./pure": {
+      "import": "./dist/es/pure.js",
+      "require": "./dist/cjs/pure.js",
+      "default": "./dist/es/pure.js"
+    },
+    "./side-effects": {
+      "import": "./dist/es/side-effects.js",
+      "require": "./dist/cjs/side-effects.js",
+      "default": "./dist/es/side-effects.js"
+    }
   },
-  "config": {
-    "port": "18080"
-  },
-  "scripts": {
-    "dev": "vite",
-    "type-check": "tsc --noEmit --emitDeclarationOnly false",
-    "build": "npm run type-check && vite build && tsc",
-    "start": "vite preview --outDir ./tests --port $npm_package_config_port -l silent",
-    "pretest": "node ./scripts/list-dir.js",
-    "pretest:ui": "node ./scripts/list-dir.js",
-    "precoverage": "node ./scripts/list-dir.js",
-    "test": "start-server-and-test $npm_package_config_port 'vitest --coverage'",
-    "test:ui": "start-server-and-test $npm_package_config_port 'vitest --ui --coverage'",
-    "coverage": "start-server-and-test $npm_package_config_port 'vitest run --coverage'",
-    "preview": "vite preview",
-    "prepublishOnly": "npm run build"
-  },
   "repository": {
@@ -54,13 +51,37 @@ "type": "git",
   "license": "MIT",
+  "config": {
+    "port": "18080"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit --emitDeclarationOnly false",
+    "prebuild": "npm run type-check",
+    "build:es": "vite build",
+    "build:cjs": "node ./scripts/build-cjs.js",
+    "build:iife": "node ./scripts/build-iife.js",
+    "postbuild:es": "tsc --declarationDir ./dist/es",
+    "postbuild:cjs": "tsc --declarationDir ./dist/cjs",
+    "build": "npm run build:es && npm run build:cjs && npm run build:iife",
+    "start": "vite preview --outDir ./tests --port $npm_package_config_port -l silent",
+    "pretest": "npm run build && node ./scripts/list-dir.js",
+    "pretest:ui": "npm run build && node ./scripts/list-dir.js",
+    "precoverage": "npm run build && node ./scripts/list-dir.js",
+    "test": "start-server-and-test $npm_package_config_port 'vitest --coverage'",
+    "test:ui": "start-server-and-test $npm_package_config_port 'vitest --ui --coverage'",
+    "coverage": "start-server-and-test $npm_package_config_port 'vitest run --coverage'",
+    "prepublishOnly": "npm run build",
+    "ncu": "npx npm-check-updates -u",
+    "postncu": "npm i"
+  },
   "devDependencies": {
     "@types/dom-webcodecs": "^0.1.8",
-    "@vitest/browser": "^0.34.1",
-    "@vitest/coverage-istanbul": "^0.34.1",
-    "@vitest/ui": "^0.34.1",
+    "@vitest/browser": "^0.34.2",
+    "@vitest/coverage-istanbul": "^0.34.2",
+    "@vitest/ui": "^0.34.2",
     "http-server": "^14.1.1",
-    "playwright": "^1.36.2",
+    "playwright": "^1.37.1",
+    "rimraf": "^5.0.1",
     "start-server-and-test": "^2.0.0",
     "typescript": "^5.1.6",
-    "vite": "^4.4.8",
-    "vitest": "^0.34.1"
+    "vite": "^4.4.9",
+    "vitest": "^0.34.2"
   },
@@ -67,0 +88,0 @@ "dependencies": {

README.md

@@ -7,2 +7,4 @@ # @sec-ant/barcode-detector
 
+To install, run the following command:
+
 ```bash
@@ -12,5 +14,5 @@ npm i @sec-ant/barcode-detector
 
-## Usage
+## Recommended Usage with Node + ESM
 
-You can use this package in 3 ways:
+This package can be imported in three different ways:
 
@@ -23,3 +25,3 @@ ### Pure Module
 
-or rename the export to prevent possible namespace collisions:
+To avoid potential namespace collisions, you can also rename the export:
 
@@ -30,7 +32,4 @@ ```ts
 
-This is useful when you don't want to pollute `globalThis`:
+This approach is beneficial when you want to use a package to detect barcodes without polluting `globalThis`, or when your runtime already provides an implementation of the Barcode Detection API, but you still want this package to function.
 
-- You just want to use a package to detect barcodes.
-- The runtime you're using has already provided an implementation of the Barcode Detection API but you still want this package to work.
-
 ### Side Effects
@@ -42,6 +41,4 @@
 
-This is useful when you just need a drop-in polyfill.
+This approach is beneficial when you need a drop-in polyfill. If there's already an implementation of Barcode Detection API on `globalThis`, this won't take effect (type declarations will, as we cannot optionally declare types). In such cases, please use the [pure module](#pure-module) instead.
 
-If there's already an implementation of Barcode Detection API on `globalThis`, this won't take effect. Please instead use [pure module](#pure-module).
-
 ### Both
@@ -53,20 +50,159 @@
 
-This is the combination of [pure module](#pure-module) and [side effects](#side-effects).
+This approach combines the [pure module](#pure-module) and [side effects](#side-effects).
 
+## Recommended Usage in Modern Browsers
+
+For [modern browsers that support ES modules](https://caniuse.com/es6-module), this package can be imported via the `<script type="module">` tags:
+
+1. Include side effects:
+
+   ```html
+   <!-- register -->
+   <script
+     type="module"
+     src="https://cdn.jsdelivr.net/npm/@sec-ant/barcode-detector@1.2/dist/es/side-effects.min.js"
+   ></script>
+
+   <!-- use -->
+   <script type="module">
+     const barcodeDetector = new BarcodeDetector();
+   </script>
+   ```
+
+2. Script scoped access:
+
+   ```html
+   <script type="module">
+     import { BarcodeDetector } from "https://cdn.jsdelivr.net/npm/@sec-ant/barcode-detector@1.2/dist/es/pure.min.js";
+     const barcodeDetector = new BarcodeDetector();
+   </script>
+   ```
+
+3. With import maps:
+
+   ```html
+   <!-- import map -->
+   <script type="importmap">
+     {
+       "imports": {
+         "@sec-ant/barcode-detector/pure": "https://cdn.jsdelivr.net/npm/@sec-ant/barcode-detector@1.2/dist/es/pure.min.js"
+       }
+     }
+   </script>
+
+   <!-- script scoped access -->
+   <script type="module">
+     import { BarcodeDetector } from "@sec-ant/barcode-detector/pure";
+     const barcodeDetector = new BarcodeDetector();
+   </script>
+   ```
+
+## Usage with Legacy Compatibility
+
+Starting from v1.2, this package supports IIFE and CJS build outputs for use cases that require legacy compatibility.
+
+### IIFE
+
+For legacy browsers that lack support for module type `<script>` tags, or for userscripts, IIFE is the preferred choice. Upon executing the IIFE script, a variable named `BarcodeDetectionAPI` will be registered in the global.
+
+```html
+<!-- 
+  IIFE pure.js registers:
+  window.BarcodeDetectionAPI.BarcodeDetector
+  window.BarcodeDetectionAPI.setZXingModuleOverrides
+  -->
+<script src="https://cdn.jsdelivr.net/npm/@sec-ant/barcode-detector@1.2/dist/iife/pure.min.js"></script>
+
+<!-- 
+  IIFE side-effects.js registers:
+  window.BarcodeDetector
+  window.BarcodeDetectionAPI.setZXingModuleOverrides
+  -->
+<script src="https://cdn.jsdelivr.net/npm/@sec-ant/barcode-detector@1.2/dist/iife/side-effects.min.js"></script>
+
+<!-- 
+  IIFE index.js registers:
+  window.BarcodeDetector
+  window.BarcodeDetectionAPI.BarcodeDetector
+  window.BarcodeDetectionAPI.setZXingModuleOverrides
+  -->
+<script src="https://cdn.jsdelivr.net/npm/@sec-ant/barcode-detector@1.2/dist/iife/index.min.js"></script>
+```
+
+### CJS
+
+This package can also be consumed as a commonjs package:
+
+1. Vanilla Javascript:
+
+   ```js
+   // src/index.js
+   const { BarcodeDetector } = require("@sec-ant/barcode-detector/pure");
+   ```
+
+2. With Typescript:
+
+   ```ts
+   // src/index.ts
+   import { BarcodeDetector } from "@sec-ant/barcode-detector/pure";
+   ```
+
+   ```json
+   // tsconfig.json
+   {
+     "compilerOptions": {
+       "module": "CommonJS",
+       "moduleResolution": "Node",
+       "skipLibCheck": true
+     },
+     "include": ["src"]
+   }
+   ```
+
 ## `setZXingModuleOverrides`
 
-Apart from `BarcodeDetector`, there's also an exported function called `setZXingModuleOverrides`. This package uses [Sec-ant/zxing-wasm](https://github.com/Sec-ant/zxing-wasm) to provide the core function of reading barcodes. So there will be a `.wasm` binary file to load. By default, the path of the `.wasm` binary file is:
+In addition to `BarcodeDetector`, this package exports another function called `setZXingModuleOverrides`.
 
+This package employs [Sec-ant/zxing-wasm](https://github.com/Sec-ant/zxing-wasm) to enable the core barcode reading functionality. As a result, a `.wasm` binary file is fetched at runtime. The default fetch path for this binary file is:
+
 ```
-https://cdn.jsdelivr.net/npm/@sec-ant/zxing-wasm@{version}/dist/reader/zxing_reader.wasm
+https://cdn.jsdelivr.net/npm/@sec-ant/zxing-wasm@<version>/dist/reader/zxing_reader.wasm
 ```
 
-`setZXingModuleOverrides` is useful when you want to take control of the location where the `.wasm` binary file will be served, so you can use this package in a local network or you want to choose another CDN. You have to use this function prior to `new BarcodeDetector()` for it to take effect. For more information on how to use it, please check [the notes here](https://github.com/Sec-ant/zxing-wasm#notes).
+The `setZXingModuleOverrides` function allows you to govern where the `.wasm` binary is served from, thereby enabling offline use of the package, use within a local network, or within a site having strict [CSP](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_webassembly_execution) rules.
 
-This function is also exported from the [side effects](#side-effects) subpath.
+For instance, should you want to inline this `.wasm` file in your build output for offline usage, with the assistance of build tools, you could try:
 
 ```ts
-import { setZXingModuleOverrides } from "@sec-ant/barcode-detector/side-effects";
+// src/index.ts
+import wasmFile from "../node_modules/@sec-ant/zxing-wasm/dist/reader/zxing_reader.wasm?url";
+
+import {
+  setZXingModuleOverrides,
+  BarcodeDetector,
+} from "@sec-ant/barcode-detector/pure";
+
+setZXingModuleOverrides({
+  locateFile: (path, prefix) => {
+    if (path.endsWith(".wasm")) {
+      return wasmFile;
+    }
+    return prefix + path;
+  },
+});
+
+const barcodeDetector = new BarcodeDetector();
+
+// detect barcodes
+// ...
 ```
 
+Alternatively, the `.wasm` file could be copied to your dist folder to be served from your local server, without incorporating it into the output as an extensive base64 data URL.
+
+It's noteworthy that you'll always want to choose the correct version of the `.wasm` file, so the APIs exported by it are exactly what the js code expected.
+
+For more information on how to use this function, you can check [the notes here](https://github.com/Sec-ant/zxing-wasm#notes) and [discussions here](https://github.com/gruhn/vue-qrcode-reader/issues/354).
+
+This function is exported from all the subpaths, including the [side effects](#side-effects).
+
 ## API
@@ -91,1 +227,9 @@
 ```
+
+## License
+
+The source code in this repository, as well as the build output, except for the parts listed below, is licensed under the [MIT license](./LICENSE).
+
+Test samples and resources are collected from [zxing-cpp/zxing-cpp](https://github.com/zxing-cpp/zxing-cpp), which is licensed under the [Apache-2.0 license](https://raw.githubusercontent.com/zxing-cpp/zxing-cpp/master/LICENSE), and [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt), which is licensed under the [3-Clause BSD license](https://raw.githubusercontent.com/web-platform-tests/wpt/master/LICENSE.md).
+
+This package has an indirect dependency on [Sec-ant/zxing-wasm-build](https://github.com/Sec-ant/zxing-wasm-build), which is licensed under the [Apache-2.0 license](https://raw.githubusercontent.com/Sec-ant/zxing-wasm-build/main/LICENSE).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

268250

increased by256.9%

Number of package files

23

increased by109.09%

Lines of code

2912

increased by40.47%

Number of lines in readme file

229

increased by169.41%

Worsened metrics

Dev dependency count

11

increased by10%

Number of low quality alerts

1

increased byInfinity%

Number of medium supply chain risk alerts

21

increased by425%

No dependency changes