Notes about version 4.0

[metafloor]

Version 4 was released 2023-08-04. It was released as a major version bump even though it should be 100% backward compatible with version 3. The reasoning is that existing interfaces are given new functionality, specifically the named symbol exports in the ES6 modules.

The motivation behind this release is to support SVG, both as a generic toSVG() method and in the named symbol exports. It's the latter that caused a major change in the internal logic of the library. And with the goal to keep backward compatibility, required making the methods polymorphic.

One benefit from this new architecture is that using custom drawing objects is now supported with the named symbol exports.

An example of how it works. This shows code for the browser, but similar functionality exists for node-js and react-native:

import { qrcode, drawingSVG } from 'bwip-js';

// Use the default drawing interface 
const canvas = document.getElementById('my-canvas');
qrcode({ text:'0123456789', ... }, canvas);

// Render the barcode in SVG
const svg = qrcode({ text:'0123456789', ... }, drawingSVG());

// Render the barcode using a custom drawing object.  
// This particular example is asynchronous and returns a Promise.
qrcode({ text:'0123456789', ... }, MyAsyncDrawing())
    .then((res) => {
        // ... do something with the result ...
    }).catch((e) => {
        console.log(e);
    });

The above usage is fully tree-shakable, meaning that bundlers such as webpack and esbuild can reduce the BWIPP module down to what is required to support only qrcode.

If you don't need the bundler to do tree-shaking, you can use the generic toSVG() method:

import { toSVG } from 'bwip-js';

const svg = toSVG({ bcid:'qrcode', text:'0123456789', ... });

[metafloor]

Version 4 implements a new method on the drawing interface that allows the options object to be provided after object construction.

The motivation behind this feature is the following pattern:

import { datamatrix } from 'bwip-js';

const res = datamatrix({ text:'0123456789', ... }, MyCustomDrawing());

In previous versions, if the custom drawing object needed access to the options, for example to implement the backgroundcolor or any of the padding values, the options object had to be passed to the constructor call. This resulted in an awkward code pattern:

const options = { text:'0123456789', backgroundcolor:'#abc' };
datamatrix(options, MyCustomDrawing(options));

The new release supports an optional setopts(options) method that can be implemented on drawing objects. These are the comments extracted from the code in examples/drawing-example.js:

        // setopts() is called after the options are fixed-up/normalized,
        // but before calling into BWIPP.
        //
        // This method allows omitting the options object in the constructor call,
        // which simplifies the pattern:
        //
        //      bwipjs.render({ bcid:'code128', ... }, myDrawing());
        //
        // In the above, it is awkward to pass the options object to the drawing
        // constructor.
        //
        // The method is optional.  Implemented in v4.0.
        setopts(options) {
            opts = options;
        }

[metafloor]

More complete typescript type files (.d.ts) have been requested for this project. Since I don't use typescript, it took a bit of research to understand the syntax and how to provide the linkages in package.json to the corresponding platform-specific type files. The type files provided in this release rely on modern typescript. Because bwip-js is multi-platform (browser, node-js, react-native, electron) and each platform implements different interfaces, there are no plans to provide a single type file via the main types entry in package.json.

Instead, the type files will be specified in the exports map where they can be called out by platform. This is the proposed exports map for the new release (only the types entries shown for clarity):

  "exports": {
      "browser": {
          "types": "./dist/bwip-js.d.ts",
          ...
      },
      "electron": {
          "node": {
              "types": "./dist/bwip-js-node.d.ts",
              ...
          },
          "types": "./dist/bwip-js.d.ts",
          ...
      },
      "react-native": {
          "types": "./dist/bwip-js-rn.d.ts",
          ...
      },
      "node": {
          "types": "./dist/bwip-js-node.d.ts",
          ...
      }
  },

You can read more about the typescript support for exports here: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html

The typescript implementation was modeled after the node-js implementation. You can read about it here: https://nodejs.org/api/packages.html#conditional-exports

[TheSeg]

Filling in the gaps on how to deal with this new TypeScript configuration.

1. Remove @types/bwip-js, if installed.
2. Add "customConditions" to "compilerOptions" in your tsconfig.json as follows:

{
  "compilerOptions": {
    "customConditions": ["browser"],
  }
}

[metafloor]

Thank you for providing this.