ReverseTimestampCodec
ReverseTimestampCodec<
Brand> =object
Defined in: src/codecs/reverse/index.ts:43
A brand-scoped codec for generating and validating Reverse Timestamp IDs.
Wire format: {brand}_ plus 26 lowercase Crockford base32 characters encoding a
16-byte payload (6-byte bitwise-inverted ms timestamp + 10 random bytes). IDs sort
by creation time in descending (newest-first) order.
Range queries across a time interval [t_old, t_new] should scan from
minIdForTime(t_new) to maxIdForTime(t_old) — the reversed sort order means
newer timestamps produce lexicographically smaller IDs.
Constructed via createReverseTimestampId(brand) from @smonn/ids/reverse.
Type Parameters
Section titled “Type Parameters”Brand extends string
Properties
Section titled “Properties”~standard
Section titled “~standard”
readonly~standard:StandardSchemaProps<Brand>
Defined in: src/codecs/reverse/index.ts:91
Standard Schema validate entry point.
Methods
Section titled “Methods”extractTimestamp()
Section titled “extractTimestamp()”extractTimestamp(
id):Date
Defined in: src/codecs/reverse/index.ts:69
Decodes the creation Date from an Id<Brand> by inverting the timestamp bytes.
Trusts the type — use safeParse() at boundaries first.
Best-effort: inverts and decodes the timestamp bytes in the payload without any
additional verification. An ID that bypassed safeParse() (e.g. via a type
assertion) may return a plausible-looking but incorrect Date.
Parameters
Section titled “Parameters”Id<Brand>
Returns
Section titled “Returns”Date
fromUUID()
Section titled “fromUUID()”fromUUID(
value):Id<Brand>
Defined in: src/codecs/reverse/index.ts:103
Parses a UUID string into an Id<Brand>. Accepts case-insensitive 8-4-4-4-12
hyphenated form only. Throws IdsError with code: "invalid_id" on bad input.
See ADR-0024.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Id<Brand>
generate()
Section titled “generate()”generate():
Id<Brand>
Defined in: src/codecs/reverse/index.ts:45
Produces a new canonical ID using the codec’s now and rng.
Returns
Section titled “Returns”Id<Brand>
generateAt()
Section titled “generateAt()”generateAt(
date):Id<Brand>
Defined in: src/codecs/reverse/index.ts:47
Produces a new canonical ID with timestamp bytes from date and a fresh random tail. Throws on invalid dates.
Parameters
Section titled “Parameters”Date
Returns
Section titled “Returns”Id<Brand>
is(
value):value is Id<Brand>
Defined in: src/codecs/reverse/index.ts:52
Strict type guard: true only for already-canonical strings for this brand.
For untrusted input, use safeParse() or parse() instead. See ADR-0003.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”value is Id<Brand>
maxIdForTime()
Section titled “maxIdForTime()”maxIdForTime(
date):Id<Brand>
Defined in: src/codecs/reverse/index.ts:83
Lexicographically largest ID for any ID generated at date (random portion 0xff).
Because timestamps are inverted, an older date yields a lexicographically larger result —
use maxIdForTime(t_old) as the upper bound when scanning [t_old, t_new].
Throws on invalid dates.
Parameters
Section titled “Parameters”Date
Returns
Section titled “Returns”Id<Brand>
minIdForTime()
Section titled “minIdForTime()”minIdForTime(
date):Id<Brand>
Defined in: src/codecs/reverse/index.ts:76
Lexicographically smallest ID for any ID generated at date (random portion 0x00).
Because timestamps are inverted, a newer date yields a lexicographically smaller result —
use minIdForTime(t_new) as the lower bound when scanning [t_old, t_new].
Throws on invalid dates.
Parameters
Section titled “Parameters”Date
Returns
Section titled “Returns”Id<Brand>
parse()
Section titled “parse()”parse(
value):Id<Brand>
Defined in: src/codecs/reverse/index.ts:56
Lenient parse: normalises case and Crockford aliases, returns canonical Id<Brand>, or throws.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”Id<Brand>
safeFromUUID()
Section titled “safeFromUUID()”safeFromUUID(
value):ParseResult<Brand>
Defined in: src/codecs/reverse/index.ts:108
Non-throwing UUID parse. Returns { ok: true, id } or
{ ok: false, error: "not_string" | "invalid_uuid" }. See ADR-0024.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”ParseResult<Brand>
safeParse()
Section titled “safeParse()”safeParse(
value):ParseResult<Brand>
Defined in: src/codecs/reverse/index.ts:60
Lenient parse without throwing: normalises to canonical form, or returns { ok: false, error }.
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”ParseResult<Brand>
toJsonSchema()
Section titled “toJsonSchema()”toJsonSchema():
JsonSchema
Defined in: src/codecs/reverse/index.ts:89
JSON Schema for the canonical wire form. The pattern matches the canonical stored
form only and is deliberately stricter than parse()/safeParse(), which accept
uppercase letters and Crockford aliases (o/i/l) before normalising. See ADR-0003.
Returns
Section titled “Returns”toUUID()
Section titled “toUUID()”toUUID(
id):string
Defined in: src/codecs/reverse/index.ts:97
Converts a trusted Id<Brand> to an RFC 9562 canonical (lowercase, hyphenated)
UUID string by reinterpreting the 16-byte payload verbatim. Total — cannot fail.
Returns a plain string (brand is shed). See ADR-0024.
Parameters
Section titled “Parameters”Id<Brand>
Returns
Section titled “Returns”string