Skip to main content

Crate svid

Crate svid 

Source
Expand description

§SVID (Stateless Verifiable ID)

A WASM-compatible, 64-bit ID generation module designed for unified server and client (WASM) usage.

§Bit Layout (default bits-balanced profile)

 63 62                   34 33                            8 7  6     0
┌──┬──────────────────────┬───────────────────────────────┬──┬────────┐
│S0│    TIMESTAMP (T)     │         RANDOM (M)            │W │  TAG  │
│1b│     29 bits          │         26 bits               │1b│ 7 bits│
└──┴──────────────────────┴───────────────────────────────┴──┴────────┘
  • Sign bit (63): Always 0 (ensures positive i64).
  • Timestamp: T bits, seconds since 2026-01-01. Sits at the top so i64 ordering matches chronological order (like ULID/Snowflake/UUIDv7).
  • Random: M bits of cryptographic randomness. T + M = 55.
  • WASM/Source bit (7): 1 = Client/WASM, 0 = Server.
  • TAG (0-6): 7 bits (0-127) for domain-specific entity types. Always at the LSB so id & 0x7F extracts the tag in any profile. Value 127 is reserved as RANDOM_ID_TAG for untyped/random IDs minted via SvidGenerator::generate_random — a nanoid/uuidv4-style drop-in. User #[derive(Svid)] enums cannot reuse this value.

§Profile selection (Cargo features)

Enable exactly one:

  • bits-long-life: T=31 (68 yr), M=24 — original timestamp range
  • bits-balanced (default): T=29 (17 yr), M=26 — recommended
  • bits-high-rand: T=28 (8.5 yr), M=27 — short-lived high-rate apps

Re-exports§

pub use generator::GenerateId;
pub use generator::IdGenerator;
pub use generator::SvidKind;
pub use type_bits::decode_i64_base58;
pub use type_bits::encode_svid;
pub use type_bits::human_readable_to_id;
pub use type_bits::human_readable_to_id_expecting;
pub use type_bits::id_to_human_readable;
pub use type_bits::SvidExt;
pub use type_bits::HUMAN_READABLE_LEN;
pub use type_bits::IDTYPE_BITS;
pub use type_bits::IDTYPE_MASK;
pub use type_bits::IDTYPE_SHIFT;
pub use type_bits::RANDOM_BITS;
pub use type_bits::RANDOM_ID_TAG;
pub use type_bits::RANDOM_MASK;
pub use type_bits::RANDOM_SHIFT;
pub use type_bits::SOURCE_BITS;
pub use type_bits::SOURCE_SHIFT;
pub use type_bits::SVID_EPOCH;
pub use type_bits::TIMESTAMP_BITS;
pub use type_bits::TIMESTAMP_MASK;
pub use type_bits::TIMESTAMP_SHIFT;

Modules§

generator
type_bits
Bit-level helpers for the SVID layout.

Macros§

bridge

Structs§

DecomposedSvid
Decomposed components of an SVID.
SvidGenerator

Derive Macros§

Svid
SvidDomain