API reference / @evolu/common / Type / Id

Variable: Id

const Id: BrandType<
  Type<"String", string, string, StringError, string, StringError>,
  "Id",
  IdError,
  StringError
>;

Defined in: packages/common/src/Type.ts:1572

Globally unique identifier.

Evolu Id is 16 random bytes from a cryptographically secure random generator, encoded as 22-character Base64Url string. This provides strong collision resistance for distributed ID generation.

Design Rationale

Why Evolu Id over alternatives:

  • NanoID: No standard binary serialization format, and uses only ~126 bits of entropy (21 characters from 64-symbol alphabet) compared to Evolu Id's 128 bits.
  • UUID (v4): String format is 36 characters (with hyphens) compared to Evolu Id's 22 characters. While UUIDs can be stored as 16 bytes, their standard string representation is verbose.
  • UUID v7: Includes timestamp in the ID, which leaks information about when data was created. This is a privacy concern for local-first applications where creation time must remain private.

Evolu Id provides 128 bits of entropy, compact string representation (22 characters), standard and native string serialization (Base64Url), and no privacy leaks.

Future Consideration

For database-heavy workloads where insert performance is critical, a hybrid approach could be considered: timestamp ^ H(cluster_id, timestamp >> N) where H is a keyed hash function and N is a configurable parameter. This would maintain spatial locality for database caches (improving insert performance by an order of magnitude) while adding entropy to prevent timestamp leakage and correlation across systems. The parameter N would allow trading off cache locality (larger N = better locality) versus entropy distribution. See https://brooker.co.za/blog/2025/10/22/uuidv7.html for details on this approach.

Was this page helpful?