Composite Timestamp

A lightweight, zero-dependency TypeScript/JavaScript utility to create and manage unique, sortable timestamps.

This package helps you avoid timestamp collisions, which can occur when multiple events are recorded in the same millisecond. It achieves this by appending a secondary index to a standard millisecond timestamp, creating a "composite timestamp."

Why is this useful?

In distributed systems or high-frequency applications, it's common for multiple events to share the exact same millisecond timestamp from Date.now(). This can lead to issues with data ordering, overwrites, and race conditions.

A composite timestamp solves this by creating a unique, lexicographically sortable string in the format ${timeMilliseconds}##${index}.

For example, instead of two events having the timestamp 1678886400000, they would be represented as:

• 1678886400000##000
• 1678886400000##001

This ensures that every event has a unique and ordered identifier, even if they occur at the same millisecond.

Installation

npm install @andyrmitchell/composite-timestamps

How to use

The library is simple to use and provides functions for creating, parsing, and comparing composite timestamps.

Creating Timestamps

You can easily create a composite timestamp from a millisecond value and an optional index.

import { createCompositeTimestamp, createParsedCompositeTimestamp } from 'composite-timestamp';

// Create a composite timestamp string
const tsString = createCompositeTimestamp(Date.now(), 0);
// => "1678886400000##000"

// Create a parsed composite timestamp object
const parsedTs = createParsedCompositeTimestamp(Date.now(), 1);
/*
=> {
     composite: "1678886400001##001",
     time_ms: 1678886400001,
     index: 1
   }
*/

Sorting

The library provides robust sorting functions that can handle numbers, composite timestamp strings, and parsed timestamp objects.

import { sortCompositeTimestamp, sortCompositeTimestampIncParsed } from 'composite-timestamp';

// Sort an array of numbers and composite timestamp strings
const timestamps = [1678886400001, '1678886400000##001', 1678886400000];
timestamps.sort(sortCompositeTimestamp);
// => [1678886400000, '1678886400000##001', 1678886400001]

// Sort an array including parsed objects
const mixedTimestamps = [
    1678886400002,
    { composite: '1678886400000##001', time_ms: 1678886400000, index: 1 },
    '1678886400001##000'
];
mixedTimestamps.sort(sortCompositeTimestampIncParsed);

Comparisons

Easily compare timestamps to determine their order.

import { gtCompositeTimestamp, gteCompositeTimestamp } from 'composite-timestamp';

// Greater than
gtCompositeTimestamp('1678886400000##001', 1678886400000); // => true

// Greater than or equal to
gteCompositeTimestamp('1678886400000##000', 1678886400000); // => true

Parsing Timestamps

Parse a composite timestamp string to access its constituent parts, for manual comparisons.

import { parseCompositeTimestamp } from 'composite-timestamp';

const parsed = parseCompositeTimestamp("1678886400000##005");
/*
=> {
     composite: "1678886400000##005",
     time_ms: 1678886400000,
     index: 5
   }
*/

Guaranteed Monotonic Timestamps

For applications requiring a strict guarantee that every new timestamp is greater than the last, the monotonicNowFactory factory function is provided. This is particularly useful for versioning, event sourcing, or CRDTs where a reliable and chronological order is critical.

The factory creates a monotonicNow function that ensures timestamps are always increasing, even if the system clock is adjusted backward or if multiple timestamps are generated within the same millisecond.

import { monotonicNowFactory } from '@andyrmitchell/composite-timestamps';

// Create the generator function
const monotonicNow = monotonicNowFactory();

// Generate a sequence of timestamps
const t1 = monotonicNow(); // e.g., "1678886400000##000"
const t2 = monotonicNow(); // e.g., "1678886400000##001"
const t3 = monotonicNow(); // e.g., "1678886400001##000"

// The factory guarantees that t1 < t2 < t3 is always true
console.log(t1 < t2); // true
console.log(t2 < t3); // true

Avoiding Timestamp Clashes Manually

The createCompositeTimestamp function includes an optional third parameter, existingTimestampThatCannotClash. This parameter ensures that the newly generated timestamp is guaranteed to be greater than the existing one if they share the same millisecond value.

It works by checking if the timeMs values are identical; if they are, it sets the new index to be one greater than the existing timestamp's index.

But it's not fully monotonic, as if the timeMs is older it will use the older timestamp (going backwards, which is not monotonic).

This is a useful utility for ensuring order relative to a specific known timestamp, but for system-wide guarantees, the monotonicNowFactory function is the recommended approach.

API

Types

• CompositeTimestamp: A string in the format ${timeMilliseconds}##${index}.
• ParsedCompositeTimestamp: An object with composite, time_ms, and index properties.
• FlexibleTimestamp: A number or CompositeTimestamp.
• FlexibleTimestampIncParsed: A FlexibleTimestamp or ParsedCompositeTimestamp.

Functions

• createCompositeTimestamp(timeMs: number, index?: number, existingTimestampThatCannotClash?: FlexibleTimestamp): CompositeTimestamp
• createParsedCompositeTimestamp(timeMs: number, index?: number): ParsedCompositeTimestamp
• parseCompositeTimestamp(timestamp: FlexibleTimestamp): ParsedCompositeTimestamp
• incrementCompositeTimestampIndex(timestamp: CompositeTimestamp): CompositeTimestamp
• sortCompositeTimestamp(a: FlexibleTimestamp, b: FlexibleTimestamp): 0 | -1 | 1
• sortCompositeTimestampIncParsed(a: FlexibleTimestampIncParsed, b: FlexibleTimestampIncParsed): 0 | -1 | 1
• gtCompositeTimestamp(a: FlexibleTimestamp, b: FlexibleTimestamp): boolean
• gteCompositeTimestamp(a: FlexibleTimestamp, b: FlexibleTimestamp): boolean
• isCompositeTimestamp(x: unknown, verifyParsing?: boolean): x is CompositeTimestamp
• isParsedCompositeTimestamp(x: unknown): x is ParsedCompositeTimestamp

### Classes

• MontonicCompositeTimestampFactory

## Comparison with ULID

ULID (e.g. https://www.npmjs.com/package/ulid) is first and foremost a random ID generator, that also encodes a timestamp and indexing.

Primary Goal:

• Composite Timestamps: To ensure unique, ordered timestamps within a single system or process, especially during high-frequency events. Uniqueness is guaranteed locally by an incrementing index.
• ULID: To generate globally unique identifiers that are also sortable. Uniqueness is achieved by combining a timestamp with a large amount of random data.

Structure:

• Composite Timestamps: [Timestamp]##[Simple Index]. It is human-readable.
• ULID: [48-bit Timestamp][80-bit Randomness]. It is encoded as a 26-character string.

Because their formats and uniqueness strategies are completely different, a Composite Timestamp and a ULID cannot be directly compared to determine chronological order. Choose this library if your primary need is simple, human-readable, and locally-ordered timestamps. Choose ULID if you need globally unique, sortable identifiers.