Migrate to uniku v1
Prepare for the v1 entry-point contract without changing identifier data.
uniku v1 keeps its canonical identifier formats stable while finalizing its pre-v1 entry points and machine-readable error contract.
Move CUID v2 to the versioned entry point
uniku/cuid2 is a pre-v1 alias. Use the canonical versioned import before upgrading:
- import { cuid2 } from 'uniku/cuid2'
+ import { cuidv2 } from 'uniku/cuid/v2'The generator behavior is the same. This is an import migration, not a data migration: existing CUID v2 values remain valid.
Update error-code matches
Pre-v1 error codes included the generator name. V1 uses strategy-agnostic codes and reports the generator separately through error.strategy:
if (error instanceof ParseError) {
- if (error.code === 'ULID_INVALID_CHAR') {
+ if (error.code === 'INVALID_CHAR' && error.strategy === 'ulid') {
// handle an invalid ULID character
}
}uniku/errors exports ERROR_CODES, the authoritative runtime catalog, and its derived ErrorCode type. The _tag classes and human-readable messages keep their existing roles.
This table maps every machine-readable code emitted by uniku@0.4.3 to its v1 replacement:
| Pre-v1 code(s) | V1 code |
|---|---|
UUID_TIMESTAMP_OUT_OF_RANGE, ULID_TIMESTAMP_OUT_OF_RANGE, ULID_TIMESTAMP_OVERFLOW, KSUID_TIMESTAMP_TOO_LOW, KSUID_TIMESTAMP_TOO_HIGH, OBJECTID_TIMESTAMP_OUT_OF_RANGE, XID_TIMESTAMP_OUT_OF_RANGE, TSID_TIMESTAMP_INVALID, TSID_TIMESTAMP_OUT_OF_RANGE | TIMESTAMP_OUT_OF_RANGE |
UUID_INVALID_HEX_CHAR, ULID_INVALID_CHAR, KSUID_INVALID_CHAR, OBJECTID_INVALID_CHAR, XID_INVALID_CHAR, TSID_INVALID_CHAR, TYPEID_SUFFIX_INVALID_CHARACTER | INVALID_CHAR |
UUID_INVALID_LENGTH, ULID_INVALID_LENGTH, KSUID_INVALID_LENGTH, OBJECTID_INVALID_LENGTH, XID_INVALID_LENGTH, TSID_INVALID_LENGTH, TYPEID_SUFFIX_INVALID_LENGTH | INVALID_LENGTH |
UUID_INVALID_SEPARATORS, TYPEID_INVALID_FORMAT | INVALID_FORMAT |
KSUID_OVERFLOW, TYPEID_SUFFIX_OVERFLOW, TSID_LEADING_CHAR_OUT_OF_RANGE, TSID_VALUE_OUT_OF_RANGE | VALUE_OUT_OF_RANGE |
XID_NON_CANONICAL | NON_CANONICAL |
UUID_BYTES_INVALID_LENGTH, ULID_BYTES_INVALID_LENGTH, KSUID_BYTES_INVALID_LENGTH, KSUID_BYTES_TOO_SHORT, OBJECTID_BYTES_INVALID_LENGTH, OBJECTID_BYTES_TOO_SHORT, XID_BYTES_INVALID_LENGTH, TSID_BYTES_INVALID_LENGTH, TYPEID_UUID_BYTES_INVALID_LENGTH | BYTES_INVALID_LENGTH |
UUID_BUFFER_OUT_OF_BOUNDS, ULID_BUFFER_OUT_OF_BOUNDS, KSUID_BUFFER_OUT_OF_BOUNDS, OBJECTID_BUFFER_OUT_OF_BOUNDS, XID_BUFFER_OUT_OF_BOUNDS, TSID_BUFFER_OUT_OF_BOUNDS | BUFFER_OUT_OF_BOUNDS |
UUID_RANDOM_BYTES_TOO_SHORT, ULID_RANDOM_BYTES_TOO_SHORT, KSUID_RANDOM_BYTES_TOO_SHORT, OBJECTID_RANDOM_BYTES_TOO_SHORT, NANOID_RANDOM_BYTES_INSUFFICIENT, CUID2_RANDOM_BYTES_EMPTY | RANDOM_BYTES_TOO_SHORT |
UUID_SEQUENCE_OUT_OF_RANGE, OBJECTID_COUNTER_OUT_OF_RANGE, XID_COUNTER_OUT_OF_RANGE, TSID_COUNTER_OUT_OF_RANGE | COUNTER_OUT_OF_RANGE |
TSID_NODE_OUT_OF_RANGE | NODE_OUT_OF_RANGE |
TSID_NODE_BITS_OUT_OF_RANGE | NODE_BITS_OUT_OF_RANGE |
TSID_EPOCH_INVALID | EPOCH_INVALID |
XID_PROCESS_ID_OUT_OF_RANGE | PROCESS_ID_OUT_OF_RANGE |
XID_MACHINE_ID_BYTES_TOO_SHORT | MACHINE_ID_BYTES_TOO_SHORT |
TYPEID_PREFIX_TOO_LONG | PREFIX_TOO_LONG |
TYPEID_PREFIX_INVALID_CHARACTER | PREFIX_INVALID_CHAR |
TYPEID_PREFIX_INVALID_BOUNDARY | PREFIX_INVALID_BOUNDARY |
TYPEID_UUID_NOT_V7 | UUID_NOT_V7 |
NANOID_ALPHABET_TOO_SHORT, NANOID_ALPHABET_TOO_LONG | ALPHABET_OUT_OF_RANGE |
NANOID_ALPHABET_INVALID_CHAR | ALPHABET_INVALID_CHAR |
NANOID_ALPHABET_DUPLICATE | ALPHABET_DUPLICATE |
NANOID_SIZE_INVALID, NANOID_SIZE_TOO_LARGE, CUID2_LENGTH_OUT_OF_RANGE | LENGTH_OUT_OF_RANGE |
Several old codes intentionally converge on one v1 meaning. This only changes error handling; generated and persisted identifier data is unaffected.
Removed codes
ULID_RANDOM_OVERFLOW has no v1 replacement. Exhausting ULID's 80-bit monotonic
random portion no longer fails: the generator advances its timestamp by one
millisecond and continues, which is what UUID v7 already did with its counter. The
RANDOM_OVERFLOW code that briefly replaced it is gone for the same reason — there
is no longer a failure to report. If you matched on either code, delete the branch.
A ULID or UUID v7 whose 48-bit timestamp field is already at its maximum now
throws TIMESTAMP_OUT_OF_RANGE instead, because borrowing the next millisecond
would no longer fit.
What remains stable
Within 1.x, uniku will not remove or rename documented entry points, exports, options, methods, or constants. Canonical string formats, byte order, timestamp units, and documented error codes are part of the contract.
Read the stability contract for the full release and runtime policy.