Package Exports

identifiers-js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (identifiers-js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

JavaScript implementation of Identifiers spec

Installation and Usage

npm install identifiers-js

For yarn:

yarn add identifiers-js

Identifiers-js is written in TypeScript and generates ES5 JavaScript.

TypeScript

import * as IDs from "identifiers";

JavaScript

const IDs = require('identifiers');

The IDs reference comes with methods to parse Identifier strings as well as a factory to create Identifier instances. For further details see the Factory API Reference section.

Immutability

Identifier instances are immutable. Their values are also immutable.

const integerId = IDs.factory.integer(22);
/*
  Identifiers have the following shape:
  {
      value: data value
      type: identifier type string
      toString() -> returns a debug-friendly string of the identifier's type and value
      toDataString() -> returns base-128 encoded identifier string
      toHumanString() -> return Crockford base-32 encoded identifier string
      toJSON() -> called by JSON.stringify() and returns  base-128 encoded identifier string
  }
 */
console.log(integerId.value);
// -> 22

// encode the identifier
const dataString = integerId.toDataString();
const humanString = integerId.toHumanString();

// decode the identifier
const decodedId = IDs.parse(dataString);
// parse() can decode either type of encoded string
const decodedId2 = IDs.parse(humanString);

console.log(decodedId.value === decodedId2.value);
// -> true

Lists and Map Identifiers

Identifiers-js supports list and map identifiers in the factories. Each type factory has a .list() and .map() factory method which sets the type of structure.

const listId = IDs.factory.boolean.list(true, true, false);
const mapId = IDs.factory.long.map({a: 335843, b: -997});

Composite Identifiers

A composite identifier is a list or map of mixed-type identifiers. One can compose a single identifier from multiple types of identifiers. A composite identifier can include any other type of identifier.

const id1 = IDs.factory.boolean(true);
const id2 = IDs.factory.string.list('q', 'pr');

// composite list
const compositeListId = IDs.factory.composite.list(id1, id2);

// composite map
const compositeMapId = IDs.factory.composite.map({a: id1, b: id2});

The values of a composite are the identifiers themselves, so one would read them as normal identifiers in a collection.

// given the example composite IDs above...

const aBooleanValue = compositeListId.value[0].value;

const aStringListValue = compositeMapId.value.b.value;

JSON Support

Identifiers-js has support for both generating and parsing JSON data values. Identifier instances safely encode themselves into a JSON.stringify() process. Additionally, a JSON reviver is provided for JSON.parse() calls.

const id = IDs.factory.string('Hello, World!');
const anObject = { a: 'a message', b: id };
const json = JSON.stringify(anObject);

console.log(json);
// -> { "a": "a message", "b": "Ç/IÒÁIÖêqÉ34uwâêl7Tþ" }

const parsedObject = JSON.parse(json, IDs.JSON_reviver);
const parsedId = parsedObject.b;

console.log(parsedId.value);
// -> 'Hello, World!'

Supported Types

These types are defined in the Identifiers specification.

Primitive identifiers

string
boolean
integer
float
long
bytes

Semantic Identifiers

uuid
datetime
geo

Structured Variants

list
map

Composites

list
map

Factory API Reference

The factory has methods for each type of identifier. These methods can consume various inputs to build an identifier.

Each identifier type's factory has methods to construct structural identifiers of their type. Each structural factory method accepts the same inputs as the single value methods, but in structural form.

String

const id = IDs.factory.string('Hello');
console.log(id.type)
// -> 'string'
console.log(typeof id.value);
// -> 'string'

// list factory functions can accept a vararg of values
IDs.factory.string.list('Hello', 'friend', 'welcome!');
// list factory functions can accept a single array of values too
IDs.factory.string.list(['an', 'array', 'of', 'strings']);

IDs.factory.string.map({a: 'oil', b: 'vinegar'});

Boolean

const id = IDs.factory.boolean(true);

console.log(id.type)
// -> 'boolean'
console.log(typeof id.value);
// -> 'boolean'

IDs.factory.boolean.list(true, false, true);
IDs.factory.boolean.list([false, false, true]);

IDs.factory.boolean.map({a: false, b: true});

Integer

const id = IDs.factory.integer(15);

console.log(id.type)
// -> 'integer'
console.log(typeof id.value);
// -> 'number'

IDs.factory.integer.list(-10000, 0, 2234);
IDs.factory.integer.list([1, 2, 4]);

IDs.factory.integer.map({a: 55, b: -9550});

Float

const id = IDs.factory.float(-0.58305);

console.log(id.type)
// -> 'float'
console.log(typeof id.value);
// -> 'number'

IDs.factory.float.list(3.665, 0.1, -664.12234);
IDs.factory.float.list([1.1, 2.2, 4.4]);

IDs.factory.float.map({a: 80.1, b: -625.11});

Long

const id = IDs.factory.long(8125);

console.log(id.type)
// -> 'long'
console.log(typeof id.value);
// -> 'object'
// id is a long-like object
console.log(id.value)
// { low: 8125, high: 0 }

// Accepts long-like objects
IDs.factory.long({low: -4434, high: 22});
IDs.factory.long.list(-10, 21, {low: 96, high: 34});
IDs.factory.long.list([{low: 224456, high: -4}, 2, 4]);

IDs.factory.long.map({a: {low: -1, high: 0}, b: -95503343432});

Bytes

const id = IDs.factory.bytes([100, 0, 12, 33]);

console.log(id.type)
// -> 'bytes'
console.log(typeof id.value);
// -> 'array'

// bytes can accept Buffer
IDs.factory.bytes(Buffer.from([255, 0, 128]));
// bytes can accept ArrayBuffer
IDs.factory.bytes(new ArrayBuffer(16));
// bytes can accept Array-Like objects
IDs.factory.bytes(Uint8Array.of(255, 0, 128));
IDs.factory.bytes(Uint8ClampedArray.of(100, 99, 38));
IDs.factory.bytes({length: 2, '0': 1, '1': 75});

IDs.factory.bytes.list([10, 1, 0, 0], [212, 196]);
IDs.factory.bytes.list([[1, 2, 4]]);

IDs.factory.bytes.map({a: [50, 0], b: [45, 61, 121]});

Semantic Identifiers

UUID

Base identifier type is bytes so the factory accepts multiple types of byte array inputs. The array-like input must contain 16 bytes. The factory also accepts a uuid-encoded string.

const id = IDs.factory.uuid('8cdcbe23-c04e-4ea2-ae51-15c9cf16e1b3');

console.log(id.type)
// -> 'uuid'
console.log(typeof id.value);
// -> 'object'
/*
  uuid's id.value is a uuid-like object: 
  {
    bytes: array of 16 bytes
    toString() -> uuid-encoded string
  }
 */

// Accepts a 16-byte array, as well as any other array-like type the bytes identifier accepts
IDs.factory.uuid([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]);
IDs.factory.uuid(Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]));
IDs.factory.uuid(Uint8Array.of(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15));

// can mix input types in factory
IDs.factory.uuid.list([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], '13f3eae9-18d6-46fc-9b3a-d6d32aaee26c');

// can accept a single array of values
IDs.factory.uuid.list([
  'cebfc569-2ba6-4cd7-ba25-f51d64c13087', 
  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], 
  Uint8ClampedArray.of(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15)]);

IDs.factory.uuid.map({
  a: '7894746d-62a5-425f-adb7-0a609ababf3f',
  b: Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
});

Datetime

Base identifier type is long so the factory accepts the same multiple types of long inputs. It also accepts a JS Date object as an input.

const id = IDs.factory.datetime(new Date());

console.log(id.type)
// -> 'datetime'
console.log(typeof id.value)
// -> 'object'
/*
  datetime produces an immutable Date-like object with some of the methods in Date implemented:
  {
    time: number // the unix time value
    toString() -> same as Date.toString()
    toUTCString() -> same as Date.toUTCString()
    toISOString() -> same as Date.toISOString()
    toJSON(key) -> same as Date.toJSON(key)
    toDate() -> returns a standard JS Date instance. Changes to this object will not affect the Identifier
  }
 */

//accepts unix time values
IDs.factory.datetime(10000000);

IDs.factory.datetime.list(new Date(), 10000000);
IDs.factory.datetime.list([3576585434, new Date(10000000)]);

IDs.factory.datetime.map({a: 3576585434, b: new Date()});

Geo

Base identifier type of geo is a list of 2 floats. Factory accepts a geo-like object or a list of 2 floats (lat, then long).

/*
  {
    latitude: number between -90.0 and 90.0
    longitude: number between -180.0 and 180.0
  }
 */

const id = IDs.factory.geo({latitude: 14.8653, longitude: -23.0987877});

console.log(id.type)
// -> 'geo'
console.log(typeof id.value)
// -> 'object'
/* 
  geo produces a geo-like object identical to the input object shape:
  {
    latitude: number between -90.0 and 90.0
    longitude: number between -180.0 and 180.0
  }
 */

// accepts two floats; first is latitude, second is longitude
IDs.factory.geo(-45.6768494, 13.224);

// accepts mixed types of inputs (both geo-like and 2-element float arrays
IDs.factory.geo.list({latitude: 14.8653, longitude: -23.0987877}, [90.0, 100.7685944]);

// accepts a single array of geos
IDs.factory.geo.list([[0.23433, -0.1001002], {latitude: 0.0, longitude: 10.11}]);

// accepts mixed types of inputs to create a map
IDs.factory.geo.map({a: {latitude: 14.262, longitude: -123.0923}, b: [10.0021, longitude: 90.4}});