Identifier

Identifier is a base class for creating fixed-length binary identifiers in Node.js. It provides a structured binary representation composed of timestamp, cryptographically secure random data, and a sequential counter.

The class is designed to be extended to create application-specific identifier types such as user IDs, session IDs, request IDs, or trace IDs.

Table of Contents

• Installation
• Importing
• Usage
• API
  • Identifier([input])
  • Properties
  • Methods
  • Built-in Overrides
  • Subclassing and Formatting
• Contributing
• License

Installation

Install Identifier using npm:

npm install identifier

Importing

Identifier supports both ECMAScript modules and CommonJS.

ECMAScript Modules

import Identifier from 'identifier-class';

CommonJS

const Identifier = require('identifier-class');

Usage

The Identifier class, is intended to be extended by application-specific identifier classes.

A subclass defines the total identifier size and the size of each binary segment.

import Identifier from 'identifier';

class SessionId extends Identifier {
  static BYTE_LENGTH = 16;

  static FORMAT = {
    timestamp: 6,
    random: 7,
    counter: 3,
  };
}

Generate an identifier

When instantiated without an argument, the identifier is generated using the current timestamp, random data, and counter.

const sessionId = new SessionId();

console.log(sessionId.hex);
console.log(sessionId.timestamp);

Create from hexadecimal data

const sessionId = new SessionId(
  '018bcfe56a7b1234567890abcdef0000'
);

console.log(sessionId.hex);

Create from a Buffer

const buffer = Buffer.from(
  '018bcfe56a7b1234567890abcdef0000',
  'hex'
);

const sessionId = new SessionId(buffer);

Create from a timestamp

const sessionId = new SessionId(Date.now());

A Date object can also be used:

const sessionId = new SessionId(new Date('2024-01-01'));

Compare identifiers

const first = new SessionId();
const second = new SessionId(first.hex);

console.log(first.equals(second)); // true

API

Identifier([input])

Creates an instance of an Identifier subclass.

When input is omitted, a new identifier is generated using the current timestamp.

Parameters

| Name | Type | Description | | ------- | ------------------------------ | ------------------------------------ | | input | IdentifierInput (optional) | Value used to create the identifier. |

Supported input types include:

• hexadecimal string
• Buffer
• Uint8Array
• number[]
• timestamp number
• Date
• another identifier of the same type
• undefined

Throws

| Error | Description | | ------------ | ---------------------------------------------------------------------------------------------- | | TypeError | The input type, hexadecimal format, or byte length is invalid. | | RangeError | The timestamp is outside the supported range, the Date is invalid, or the counter overflows. |

Properties

buffer

Buffer

Returns a copy of the identifier's internal binary representation.

Modifying the returned buffer does not modify the identifier.

const buffer = sessionId.buffer;

buffer[0] = 0xff;

console.log(sessionId.buffer[0]); // unchanged

hex

string

Returns the hexadecimal representation of the identifier.

The returned string always uses lowercase hexadecimal characters.

// 018bcfe56a7b1234567890abcdef0000
console.log(sessionId.hex);

timestamp

number

Returns the timestamp stored in the identifier.

The timestamp occupies the number of bytes specified by the timestamp segment in FORMAT.

Methods

Identifier#equals(other)

Compares the identifier with another identifier.

first.equals(second);

Returns true only when both identifiers:

1. belong to the same identifier subclass, and
2. contain the same binary value.

Otherwise, it returns false.

const first = new SessionId('018bcfe56a7b1234567890abcdef0000');
const second = new SessionId(first.hex);

first.equals(second); // true

Identifiers from different subclasses are not considered equal, even when their binary representations are identical.

Built-in Overrides

toString()

Returns the hexadecimal representation.

// 018bcfe56a7b1234567890abcdef0000
String(sessionId);

toJSON()

Returns the hexadecimal representation for JSON serialization.

// {"id":"018bcfe56a7b1234567890abcdef0000"}
JSON.stringify({ id: sessionId });

Symbol.toPrimitive

Converts the identifier to its hexadecimal representation when used in a string context.

// 018bcfe56a7b1234567890abcdef0000
`${sessionId}`;

Numeric conversion is rejected with a TypeError.

// TypeError
Number(sessionId);

Symbol.toStringTag

The identifier reports its concrete subclass name through Symbol.toStringTag.

// [object SessionId]
Object.prototype.toString.call(sessionId);

util.inspect.custom

Node.js inspection produces a concise representation containing the concrete identifier type and hexadecimal value.

// SessionId('018bcfe56a7b1234567890abcdef0000')
console.log(sessionId);

Subclassing and Formatting

Custom identifier types are created by extending Identifier and defining BYTE_LENGTH and FORMAT.

class UserId extends Identifier {
  static BYTE_LENGTH = 12;

  static FORMAT = {
    timestamp: 6,
    random: 3,
    counter: 3,
  };
}

The three format segments are expressed in bytes:

| Segment | Description | | ----------- | -------------------------------------------------------------------------- | | timestamp | Timestamp component stored at the beginning of the identifier. | | random | Cryptographically secure random data. | | counter | Sequential counter used for identifiers generated with the same timestamp. |

The sum of all segments must equal BYTE_LENGTH:

timestamp + random + counter = BYTE_LENGTH

For example:

6 + 3 + 3 = 12

The size of the timestamp segment determines the maximum representable timestamp. The counter size determines how many identifiers can be generated for the same timestamp before the counter overflows.

Contributing

Contributions, bug reports, feature requests, and pull requests are welcome.

Please open an issues or submit a pull request through the project's GitHub repository.

License

Distributed under the MIT License. See LICENSE for more information.