@uncaged/oid

Universal typed object IDs — ULID with type prefix.

task_01JAXBK7M9QRSTVWXYZ123456

One ID, everywhere. Self-describing, sortable, decentralized.

Install

npm install @uncaged/oid

Usage

import { oid, parseOid, isOid } from '@uncaged/oid'

// Generate
const taskId = oid('task')
// → "task_01JAXBK7M9QRSTVWXYZ123456"

// Parse
const { type, ulid, timestamp } = parseOid(taskId)
// → { type: 'task', ulid: '01JAXBK7M9...', timestamp: 1712345678000 }

// Validate
isOid(taskId)          // → true
isOid(taskId, 'task')  // → true (type match)
isOid('not-an-oid')    // → false

Format

{type}_{ulid}

| Part | Description | |------|-------------| | type | Object type. Lowercase, starts with letter: ^[a-z][a-z0-9_]*$ | | _ | Separator | | ulid | 26-char Crockford Base32 ULID (128 bit: 48 timestamp + 80 random) |

Examples

task_01JAXBK7M9QRSTVWXYZ123456
agent_01JAXBK7M9QRSTVWXYZ654321
session_01JAXBK7M9QRSTVWXYZ000001
comment_01JAXBK7M9QRSTVWXYZ111111

API

oid(type: string): string

Generate a new OID with the given type. Monotonic — IDs generated in the same millisecond are strictly increasing.

parseOid(id: string): { type: string, ulid: string, timestamp: number }

Parse an OID string. Throws if invalid.

isOid(value: unknown, type?: string): boolean

Check if a value is a valid OID. Optionally checks type match.

Properties

• Zero dependencies — self-contained ULID implementation
• Monotonic — same-millisecond IDs are strictly ordered
• Case insensitive — parsing normalizes to uppercase
• Fuzzy tolerant — I/i → 1, L/l → 1, O/o → 0 (Crockford spec)
• Sortable — natural string sort = chronological order (within same type)
• Decentralized — no central authority needed, generate anywhere

License

MIT