utilities.md

Utilities

Small helper functions and data structures exported from @relax.js/core/utils.

generateSequentialId

Generates compact, time-ordered unique identifiers. IDs sort lexicographically in creation order, making them useful for ordered collections and databases.

import { generateSequentialId } from '@relax.js/core/utils';

const id = generateSequentialId(1);
// Returns a Base36 string like 'k2j8m3n5p'

Parameters

Parameter	Type	Description
baseId	number	Unique identifier for the client/process (0 to 1,048,575)

Use different baseId values for different servers or processes to avoid collisions:

const SERVER_ID = parseInt(process.env.SERVER_ID || '0');
const orderId = generateSequentialId(SERVER_ID);

Structure

Each ID encodes 58 bits of data in Base36:

Bits	Field	Range
30	Timestamp (seconds since 2025-01-01)	Until ~2059
8	Per-second counter	256 IDs/second
20	Client identifier	~1M unique sources

Time-Sortable

IDs generated later sort after earlier IDs:

const id1 = generateSequentialId(0);
// ... wait ...
const id2 = generateSequentialId(0);
console.log(id1 < id2); // true

Errors

• Throws if baseId is out of range (0 to 1,048,575)
• Throws if more than 256 IDs are generated in a single second
• Throws if timestamp exceeds range (after ~2059)

resolveValue

Safely navigates nested object properties using a path array. Returns undefined if any segment is null or missing (no exceptions thrown).

import { resolveValue } from '@relax.js/core/utils';

const user = { address: { city: 'Stockholm' } };

resolveValue(['address', 'city'], user);
// Returns: 'Stockholm'

resolveValue(['address', 'zip'], user);
// Returns: undefined

// Safe with null values
const data = { user: null };
resolveValue(['user', 'name'], data);
// Returns: undefined (no error)

Use with Dot-Notation Paths

const path = 'user.profile.avatar'.split('.');
const avatar = resolveValue(path, context);

LinkedList

A doubly-linked list with O(1) insertion and removal at both ends.

import { LinkedList } from '@relax.js/core/utils';

const list = new LinkedList<string>();

list.addFirst('A');
list.addLast('B');
list.addLast('C');

console.log(list.length);      // 3
console.log(list.firstValue);  // 'A'
console.log(list.lastValue);   // 'C'

list.removeFirst(); // Returns 'A'
list.removeLast();  // Returns 'C'
console.log(list.length);      // 1

Node Access

Access the internal Node wrappers to traverse or remove specific nodes:

let node = list.first;
while (node) {
    console.log(node.value);
    node = node.next;
}

// Remove a specific node
const node = list.first;
node.remove(); // Removes from list and updates length

API

Method/Property	Description
addFirst(value)	Insert at the beginning
addLast(value)	Insert at the end
removeFirst()	Remove and return the first value
removeLast()	Remove and return the last value
length	Number of nodes
first	First Node (or undefined)
last	Last Node (or undefined)
firstValue	Value of the first node
lastValue	Value of the last node

Node Properties

Property	Description
value	The stored value
next	Next node (or null)
prev	Previous node (or null)
remove()	Remove this node from the list