TimestampCodec
TimestampCodec<
Brand> =object
Defined in: src/codecs/timestamp/index.ts:39
A brand-scoped codec for generating and validating public-facing IDs.
Wire format: {brand}_ plus 26 lowercase Crockford base32 characters encoding a
16-byte payload (6-byte ms timestamp + 10 random bytes). IDs sort by creation
time in ascending order.
For encrypted IDs, use createOpaqueTimestampId from @smonn/ids/opaque.
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/timestamp/index.ts:76
Standard Schema validate entry point.
Methods
Section titled “Methods”extractTimestamp()
Section titled “extractTimestamp()”extractTimestamp(
id):Date
Defined in: src/codecs/timestamp/index.ts:64
Decodes the creation Date from an Id<Brand>. Trusts the type — use safeParse() at boundaries first. See ADR-0002.
Best-effort: 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/timestamp/index.ts:88
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/timestamp/index.ts:41
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/timestamp/index.ts:43
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/timestamp/index.ts:48
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/timestamp/index.ts:68
Tight upper bound for any ID generated at date (random portion 0xff). 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/timestamp/index.ts:66
Tight lower bound for any ID generated at date (random portion 0x00). 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/timestamp/index.ts:52
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/timestamp/index.ts:93
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/timestamp/index.ts:56
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/timestamp/index.ts:74
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/timestamp/index.ts:82
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