digital-link.js

digital-link.js is a JavaScript library for creating, verifying, and representing/transferring GS1 Digital Links in JavaScript front-end and back-end applications. It can 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 through a UI.

Installation

The library is installed through npm:

npm i --save digital-link.js

After you finish installing, 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 the DigitalLink 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 the DigitalLink 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);

After it's 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()}`);

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());

Some utility functions are 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)

After it's created, all the functions below apply to each instance.

Setters

Use setters to add or 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 construct a changed 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, 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