grain-id 0.14.2

Compact, human-readable unique IDs — grain-sized, yet enough for a lifetime
docs.rs failed to build grain-id-0.14.2
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: grain-id-0.16.0

grain-id

Compact, human-readable unique IDs — grain-sized, yet enough for a lifetime.

For a language agnostic specification of the grain-id format, see SPECS.md

Quick Start

use grain_id::GrainId;

let id = GrainId::random();
println!("{}", id); // e.g. "123abcd"

Why grain-id?

Traditional identifier systems face challenges in distributed environments:

  • Sequential numbers (like GitHub issue numbers) cause collisions in distributed systems
  • UUIDs are too long and not human-friendly
  • Short hashes (like Git commit hashes) lack standardization

grain-id bridges the gap between human readability and technical requirements.

Installation

Add this to your Cargo.toml:

[dependencies]
grain-id = "0.14.1"

# With optional features
grain-id = { version = "0.14.1", features = ["arbitrary", "serde", "rusqlite", "sea-orm", "prost", "redb", "schemars"] }

For no_std Environments

This crate support no_std. For no_std environment, you'll need to disable default features.

[dependencies]
grain-id = { version = "0.14.1", default-features = false }

Features

  • Human-friendly: Easy to read, type, and communicate
  • Collision-resistant: Sufficient entropy for personal distributed systems
  • Compact: Shorter than UUIDs while maintaining uniqueness
  • Type-safe: Rust implementation with strong typing
  • Multiple integrations: Support for serde, rusqlite, sea-orm, and protobuf

Optional Feature Flags

  • arbitrary: arbitrary::Arbitrary support for fuzzing tests.
  • digest: Hash-based GrainId generation via digest::Digest trait.
  • serde: Serialization/deserialization support
  • rusqlite: SQLite database integration
  • sea-orm: SeaORM ORM integration
  • prost: Protocol Buffers support
  • redb: redb integration
  • schemars: JSON Schema support

Examples

use grain_id::GrainId;
// Generate random grain-id
let grain_id = GrainId::random();

// e.g. `123abcd`
println!("'{}'", grain_id);

// Parse from string
let valid_id: GrainId = "012atvw".parse()?;

// When decoding from BASE32, ambiguous characters (1/l/I, 0/o, v/u) are treated as 1, 0 and v respectively, so they do not cause errors.
let also_valid_id: GrainId = "ol2atuw".parse()?;
assert_eq!(valid_id, also_valid_id);

// Convert to/from integer
let num: u64 = valid_id.into();
let id_from_int: GrainId = num.try_into()?;
assert_eq!(valid_id, id_from_int);

// Lossy conversion from oversized int is allowed.
let id_from_overflowed_int = GrainId::from_u64_lossy(GrainId::CAPACITY + num);
assert_eq!(valid_id, id_from_overflowed_int);

License

Licensed under either of:

at your option.