barcode-detector-api-polyfill 1.0.0 → 1.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 ## The problem
 
-The web [BarcodeDetector API](https://developer.mozilla.org/en-US/docs/Web/API/BarcodeDetector) is amazing because it's very easy to use and it works surprizingly well even with detecting muliple barcodes in a single image. However there is a problem with this API - [its current browser support](https://caniuse.com/mdn-api_barcodedetector) (or the lack of such, to be more precise). The current browser support can be summarized like this:
+The web [BarcodeDetector API](https://developer.mozilla.org/en-US/docs/Web/API/BarcodeDetector) is amazing because it's very easy to use and it works surprisingly well even with detecting multiple barcodes in a single image. However there is a problem with this API - [its current browser support](https://caniuse.com/mdn-api_barcodedetector) (or the lack of such, to be more precise). The current browser support can be summarized like this:
 
 - Mobile
   - Android - only Chromium-based browsers
@@ -18,15 +18,36 @@ As you can see there is a huge gap in the support across mobile and desktop plat
 
 This project implements a polyfill for the BarcodeDetector API that follows the [W3C specification](https://wicg.github.io/shape-detection-api/#barcode-detection-api) with the help of the [ZXing library](https://github.com/zxing-js/library) and [its browser layer](https://github.com/zxing-js/browser). ZXing ("zebra crossing") is a popular open-source library that works with 1D and 2D barcode formats. It was originally written in Java but was eventually ported to many different languages including JavaScript and TypeScript.
 
-## How to use?
+## How to install?
 
 ### Standalone browser script
 
-Download the latest build and use it as a regular JS file in a `<script>` tag or include it to your script imports if you use a bundler. This build takes care of adding the missing BarcodeDetector object to the global scope and you are able to use it the same way as the real BarcodeDetector API.
+Download the latest build and use it as a regular JS file in a `<script>` tag. This build takes care of adding the missing BarcodeDetector object to the global scope and you are able to use it the same way as the real BarcodeDetector API.
 
-### Module import
+```html
+<script src="barcode-detector-polyfill.min.js"></script>
+```
 
-If you just want to have the detector and handle the polyfilling by yourself you can simply import the `BarcodeDetector` class in your code. A valid use case for this could be if you use a bundler and you want to lazy load the polyfill only when its needed.
+
+### NPM module
+
+```shell
+npm install barcode-detector-api-polyfill
+```
+
+Include `node_modules/barcode-detector-api-polyfill/browser/barcode-detector-polyfill.min.js` to your script imports if you use a bundler.
+
+If you just want to have the detector and handle the polyfilling by yourself you can simply import the `BarcodeDetector` class in your code.
+
+```ts
+import { BarcodeDetector, WindowWithBarcodeDetector } from 'barcode-detector-api-polyfill';
+
+if (!('BarcodeDetector' in window)) {
+  (window as WindowWithBarcodeDetector).BarcodeDetector = BarcodeDetector;
+}
+```
+
+A valid use case for this could be if you use a bundler and you want to lazy load the polyfill only when it's needed.
 
 ## Important notes and known drawbacks
 
@@ -34,7 +55,7 @@ If you just want to have the detector and handle the polyfilling by yourself you
 
 The ZXing reader detects only a single barcode from the image source. Because of that, you can never have more than 1 barcode result.
 
-Barcode results from ZXing don't always include 4 corner points. For example, for 1-dimensional barcodes it returns only 2 points so you end up with coordinates for a line rather than a quadrangle. This might be an issue if you want to use these coordinates in your app to draw an outline of the detected barcode on a canvas.
+Barcode results from ZXing don't always include 4 corner points. For example, for 1-dimensional barcodes it returns only 2 points, so you end up with coordinates for a line rather than a quadrangle. This might be an issue if you want to use these coordinates in your app to draw an outline of the detected barcode on a canvas.
 
 ### Reliability
 
@@ -48,6 +69,8 @@ Although for the most part ZXing works well, it's not as reliable as the native
 
 Although it might be obvious, the image recognition logic is now handled entirely in the JavaScript code, therefore you can't expect performance as good as the native API. If you are going to use the detector with static images, you don't need to worry about that, but if you want to use the detector continuously on a streaming video, you can potentially expect performance issues.
 
+*NOTE: I'm open for duscussions on weather we should use a web worker implementation to make detection process smoother!*
+
 ### Bundle size
 
 Due to the presence of all ZXing decoders, the minified JS build of the polyfill is ~430 kb (before gzip compression). This could be a deal breaker for low bandwidth connections and Core Web Vitals scores. You can potentially work your way around this by lazy loading the polyfill which involves additional effort.
@@ -58,4 +81,4 @@ This section here is for the curious ones who are interested in the development
 
 The implementation of the `detect()` method was a challenge because unlike the BarcodeDetector API, ZXing doesn't have this silver bullet detection method that accepts all kinds of image sources but rather has different methods that decode from different sources (canvas, video, image, stream, etc.). Because of this, the polyfill implementation conditionally calls different methods for one-time detection based on the type of the image source.
 
-Another challange was to align the differences between the barcode formats of ZXing and the BarcodeDetector API. The barcode formats in ZXing are presented as an `enum` while the BarcodeDetector API accepts (and returns) strings. To make the methods of the polyfill work as expected, two special map-like objects had to be created to make it possible to map barcode formats back and forth.
+Another challenge was to align the differences between the barcode formats of ZXing and the BarcodeDetector API. The barcode formats in ZXing are presented as an `enum` while the BarcodeDetector API accepts (and returns) strings. To make the methods of the polyfill work as expected, two special map-like objects had to be created to make it possible to map barcode formats back and forth.