Identifiers spec
JavaScript implementation ofAbout Identifiers
Identifiers are self-describing strings of data that can be decoded into semantically-meaningful values. Identifiers can define basic data types, like numbers and bytes. They can also describe values like geolocations, date-times and uuids.
Try out an online version at identifiers.io
Installation and Usage
Identifiers-js is published to NPM and includes packaging for TypeScript, node modules and minified JS.
npm install identifiers-js
For yarn:
yarn add identifiers-js
TypeScript
;
JavaScript
const ID = ;
Browsers
The ID
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 = IDfactory;/* 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;// -> 22 // encode the identifierconst dataString = integerId;const humanString = integerId; // decode the identifierconst decodedId = ID; // parse() can decode either type of encoded stringconst decodedId2 = ID; console;// -> 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 = IDfactoryboolean;const mapId = IDfactorylong;
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 = IDfactory;const id2 = IDfactorystring; // composite listconst compositeListId = IDfactorycomposite; // composite mapconst compositeMapId = IDfactorycomposite;
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 = compositeListIdvalue0value; const aStringListValue = compositeMapIdvaluebvalue;
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 = IDfactory;const anObject = a: 'a message' b: id ;const json = JSON; console;// -> { "a": "a message", "b": "Ç/IÒÁIÖêqÉ34uwâêl7Tþ" } const parsedObject = JSON;const parsedId = parsedObjectb; console;// -> '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 = IDfactory;console;// -> 'string'console;// -> 'string' // list factory functions can accept a vararg of valuesIDfactorystring; // list factory functions can accept a single array of values tooIDfactorystring; IDfactorystring;
Boolean
const id = IDfactory; console;// -> 'boolean'console;// -> 'boolean' IDfactoryboolean;IDfactoryboolean; IDfactoryboolean;
Integer
const id = IDfactory; console;// -> 'integer'console;// -> 'number' IDfactoryinteger;IDfactoryinteger; IDfactoryinteger;
Float
const id = IDfactory; console;// -> 'float'console;// -> 'number' IDfactoryfloat;IDfactoryfloat; IDfactoryfloat;
Long
const id = IDfactory; console;// -> 'long'console;// -> 'object'// id is a long-like objectconsole;// { low: 8125, high: 0 } // Accepts long-like objectsIDfactory;IDfactorylong;IDfactorylong; IDfactorylong;
Bytes
const id = IDfactory; console;// -> 'bytes'console;// -> 'array' // bytes can accept BufferIDfactory; // bytes can accept ArrayBufferIDfactory; // bytes can accept Array-Like objectsIDfactory;IDfactory;IDfactory; IDfactorybytes;IDfactorybytes; IDfactorybytes;
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 = IDfactory; console;// -> 'uuid'console;// -> '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 acceptsIDfactory;IDfactory;IDfactory; // can mix input types in factoryIDfactoryuuid; // can accept a single array of valuesIDfactoryuuid; IDfactoryuuid;
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 = IDfactory; console;// -> 'datetime'console;// -> '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 valuesIDfactory; IDfactorydatetime;IDfactorydatetime; IDfactorydatetime;
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 = IDfactory; console;// -> 'geo'console;// -> '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 longitudeIDfactory; // accepts mixed types of inputs (both geo-like and 2-element float arraysIDfactorygeo; // accepts a single array of geosIDfactorygeo; // accepts mixed types of inputs to create a mapIDfactorygeo;