Typed ID generation
For @arki/[email protected] · source docs/upgrades/typed-ids.md
defineId(prefix).create() now returns the unchanged ID string or an exact
IdGenerationFailure. RandomSourceUnavailable means the runtime has no usable
Web Crypto provider. UnexpectedDefect reports a broken provider with a private
cause. Both definitions come from ID_GENERATION_FAILURES.
- Narrow with
isFailurebefore interpolation, storage or further work. Native handlers return the failure and declareID_GENERATION_FAILURESin their existing failure/error map. Do not wrap public generators inorThrow. - Derive stored ID types from
IdOf<typeof declaration>orz.output<typeof declaration.schema>.ReturnType<typeof declaration.create>now includes failures and is inappropriate for an ID field. - Auth's four ID generators forward the same exact outcomes. Auth schemas still accept plain strings and return their precise prefixed ID.
idColumnsbridges only at Drizzle's foreign string callback. Owned DB transactions restore admitted canonical failures, roll back, and return the original object without retrying it.TRANSACTION_FAILURESincludes the ID definitions.- FS
createUploadreturns an ID failure before inserting or signing.CREATE_UPLOAD_FAILURESdrives both its return type and native RPC map. - Test fixture setup can use
orThrowto fail the test immediately. Runtime code must propagate or handle the failure at its owning boundary.
Prefixes and successful ID format do not change. Sampling uses Web Crypto only;
there is no Math.random fallback. Providers must implement the synchronous
Web Crypto buffer protocol. Broken output, rejected asynchronous output and
exhausted rejection sampling return a defect instead of yielding partial IDs.
Legacy DB generation now shares the same supervised entropy primitive. Migrate declarations to defineId(prefix) and server columns to idColumns(declaration); see the DB migration guide. IdOf<typeof declaration> infers the canonical schema output, retaining domain brands instead of reconstructing a type from the prefix. Empty and punctuation prefixes preserve existing stored formats. Same-format kinds use literal domain brands; bounded custom alphabet/length formats preserve existing nanoid-style generation. See the domain ID guide.