digital-link.js

digital-link.js is a JavaScript library for creating, verifying, and representing/transferring GS1 Digital Links in JavaScript frontend and backend applications. It can be used to create UIs for Digital Link creation, as well as a validation step for data storage/processing systems.

This is the library powering the EVRYTHNG GS1 Digital Link Tools project, which allows easy generation and validation of GS1 Digital Links via a UI.

Installation

The library is installed via npm:

npm i --save digital-link.js

Once installation is completed, include the library using require (for web applications, a modern bundler such as Webpack or Parcel is recommended):

const { DigitalLink, Utils } = require('digital-link.js');

Usage Examples

Create a DigitalLink using the setter functions, useful if the UI handles each set of elements separately, or the elements come from different sources/datasets:

const { DigitalLink } = require('digital-link.js');

const dl = DigitalLink();
dl.setDomain('https://dlnkd.tn.gg');
dl.setIdentifier('01', '9780345418913');
dl.setKeyQualifier('21', '43786');
dl.setAttribute('thngId', 'UMwxDXBdUbxgtyRaR2HBrc4r');

Alternatively, create from an object describing individual elements:

const { DigitalLink } = require('digital-link.js');

const dl = DigitalLink({
  domain: 'https://dlnkd.tn.gg',
  identifier: {
    '01': '9780345418913',
  },
  keyQualifiers: {
    '21': '43786',
  },
  attributes: {
    thngId: 'UMwxDXBdUbxgtyRaR2HBrc4r',
  },
});

Finally, create from an existing (possibly user input) URI string:

const { DigitalLink } = require('digital-link.js');

const uri = 'https://dlnkd.tn.gg/01/9780345418913/21/43786?thngId=UMwxDXBdUbxgtyRaR2HBrc4r';

const dl = DigitalLink(uri);

Once created, a DigitalLink can validate itself:

const { DigitalLink } = require('digital-link.js');

const uri = 'https://dlnkd.tn.gg/01/9780345418913';
const dl = DigitalLink(uri);

console.log(`Is this Digital Link valid? ${dl.isValid()}`);

Lastly, it can also generate URI string and JSON string representations as results:

const { DigitalLink } = require('digital-link.js');

const uri = 'https://dlnkd.tn.gg/01/9780345418913';
const dl = DigitalLink(uri);

console.log(dl.toWebUriString());
console.log(dl.toJsonString());

There are also some utility functions available for specific use-cases (see Function Reference below). Also, see the README.md file for more usage examples.

Function Reference

Creation

A DigitalLink object can be created using multiple input representations.

DigitalLink();        // Create empty object to be populated with setters
DigitalLink(string);  // Create from URI string
DigitalLink(object);  // Create from object (see examples)

Once created, all the functions below apply to each instance.

Setters

Use setters to add/change one part of the overall Digital Link object.

.setDomain(domain);            // Set the URI domain

.setIdentifier(key, value);    // Set the identifier

.setKeyQualifier(key, value);  // Set a single key qualifier

.setAttribute(key, value);     // Set a single attribute

Getters

Use getters to retrieve one part of the Digital Link object. Useful if the input was a raw URI string.

.getDomain();           // Get the domain

.getIdentifier();       // Get the identifier

.getKeyQualifier(key);  // Get a single key qualifier

.getKeyQualifiers();    // Get the list of key qualifiers

.getAttribute(key);     // Get a single attribute

.getAttributes();       // Get the list of attributes

Outputs

The outputs of a DigitalLink object after construction allow easy conversion to multiple output formats, as well as validation with trace details.

.toWebUriString();      // Output a GS1 Digital Link URI string

.toJsonString();        // Output a JSON representation of the DigitalLink that
                        // can be used to construct a modified version directly

.isValid();             // Outputs true if the URI string is valid.

.getValidationTrace();  // Output an object containing an array of major
                        // validation steps. Useful for debugging purposes

### Utilities

There are a couple of utility functions also available for specific use-cases such as HTML generation and validation of individual rules according to the underlying grammar scheme. First, make sure to import Utils:

const { DigitalLink, Utils } = require('digital-link.js');

Then, use each utility function directly from the Utils import:

Utils.Rules                           // Object of rules available to use with 
                                      // the testRule() function

Utils.testRule(rule, value)           // Test a single rule from Rules

Utils.generateStatsHtml(uriString)    // Generate apglib HTML for stats

Utils.generateTraceHtml(uriString)    // Generate apglib HTML for validation
                                      // trace results

Utils.generateResultsHtml(uriString)  // Generate apglib HTML for validation 
                                      // results details