Globally Unique, Monotonically Increasing Event IDs

2.0.1 · active · verified Sun Apr 19

eventid is a JavaScript/TypeScript utility for generating unique event identifiers that are globally unique across a network of services and monotonically increasing locally on each machine. Currently at stable version 2.0.1, the library typically receives updates for Node.js compatibility and internal dependency management, with new major versions signifying breaking changes like increased minimum Node.js requirements. It provides a robust alternative to standard JavaScript timestamps, which often lack the necessary millisecond resolution for accurately ordering rapidly occurring events within distributed systems. Its core differentiation lies in producing lexicographically comparable IDs that maintain local monotonicity while guaranteeing global uniqueness, thereby facilitating event ordering across diverse services without relying on imprecise timestamp comparisons.

Common errors

```
TypeError: EventId is not a constructor
```
cause Incorrectly importing EventId using named import syntax (e.g., `import { EventId } from 'eventid';`) when it is exported as a default.

fix Use the correct default import syntax: `import EventId from 'eventid';` for ESM/TypeScript or `const EventId = require('eventid');` for CommonJS.
```
Error [ERR_REQUIRE_ESM]: require() of ES Module ...eventid/index.js from ... not supported.
```
cause Attempting to use `require('eventid')` in an ECMAScript Module (ESM) context in Node.js without proper Babel/Webpack configuration.

fix In an ESM context, use `import EventId from 'eventid';`. If you must use `require`, ensure your project is configured for CommonJS or use a build tool to transpile.
```
ReferenceError: EventId is not defined
```
cause The `EventId` class has not been imported or required correctly, or an attempt to use it was made before it was in scope.

fix Ensure `import EventId from 'eventid';` or `const EventId = require('eventid');` is present and correctly positioned in your module before `new EventId()` is called.

Warnings

breaking Version 2.0.0 and above explicitly require Node.js 10 or higher. Previous versions of Node.js are no longer supported.
Fix: Upgrade your Node.js environment to version 10 or greater. For older Node.js environments, you must use a version of `eventid` prior to 2.0.0 (e.g., `npm install eventid@^1.0.0`).
breaking Version 1.0.0 dropped support for Node.js versions 4.x, 6.x, and 9.x, which had reached or were nearing End-Of-Life (EOL).
Fix: Ensure your Node.js environment is at least version 8.x for `eventid` v1.x, or upgrade to Node.js 10+ for `eventid` v2.x.
gotcha This package is not an official Google product. While developed and open-sourced by Google employees, it does not carry official Google product support or guarantees.
Fix: Be aware that support and maintenance are community-driven and subject to the availability of contributors. Do not assume enterprise-level support or SLAs.
gotcha The `d64` dependency was removed in v2.0.1. While this was a dependency fix, users who might have implicitly relied on `d64` being present in their node_modules (which is not recommended practice) might find it missing.
Fix: If `d64` is required by your application, install it as a direct dependency (`npm install d64`). Do not rely on transitive dependencies.

Install

npm install eventid npm
yarn add eventid yarn
pnpm add eventid pnpm

Imports

EventId
wrong:
```
import { EventId } from 'eventid';
```
correct:
```
import EventId from 'eventid';
```
The EventId class is exported as the default export of the module for both ESM and CommonJS. Named imports will fail.
EventId (CommonJS)
wrong:
```
const { EventId } = require('eventid');
```
correct:
```
const EventId = require('eventid');
```
For CommonJS, the class constructor is directly exported, not as a property of an object.
EventId type
wrong:
```
import { EventId } from 'eventid';
```
correct:
```
import type EventId from 'eventid';
// or
type MyEventId = InstanceType<typeof EventId>;
```
Since 'EventId' is the default export (a class), its type can be imported using 'import type EventId from 'eventid';' or by inferring the instance type.

Quickstart

Demonstrates instantiation of EventId, generation of unique IDs, and verification of their local monotonic increase. It highlights how different instances ensure global uniqueness while individual instances maintain local order.

import EventId from 'eventid';

// Instantiate a generator. A single instance is sufficient for an application.
const eventIdGenerator = new EventId();

// Generate a globally unique identifier.
const id1: string = eventIdGenerator.new(); 
console.log(`Generated ID 1: ${id1}`);

// Subsequent calls from the same generator instance will produce
// monotonically increasing local IDs.
const id2: string = eventIdGenerator.new();
console.log(`Generated ID 2: ${id2}`);

// Verify monotonic increase locally
if (id1 < id2) {
  console.log('id1 is lexicographically smaller than id2, as expected.');
} else {
  console.error('ID generation is not monotonically increasing locally!');
}

// Another instance (e.g., in a different service or process) will use
// a different base GUID, ensuring global uniqueness.
const anotherGenerator = new EventId();
const id3: string = anotherGenerator.new();
console.log(`Generated ID 3 (from another generator): ${id3}`);

// Example of how they compare - generally, IDs from different generators
// are not necessarily ordered relative to each other.
// But IDs from the *same* generator are strictly ordered.

view raw JSON →