KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #dsh #dsh-plugin #ai-agent #codex #ai-agents #deepseek-harness #claude-code #cli #react #mcp

sparkid

★ 37 Open GitHub ↗

⚡ Fast, sortable, 21-char Base58 unique ID generator

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ⚡ sparkid

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/youssefm/sparkid/main/LICENSE)
[![Test](https://github.com/youssefm/sparkid/actions/workflows/test.yml/badge.svg)](https://github.com/youssefm/sparkid/actions/workflows/test.yml)
[![npm](https://img.shields.io/npm/v/sparkid)](https://www.npmjs.com/package/sparkid)
[![PyPI](https://img.shields.io/pypi/v/sparkid)](https://pypi.org/project/sparkid/)
[![crates.io](https://img.shields.io/crates/v/sparkid)](https://crates.io/crates/sparkid)

Fast, monotonic, time-sortable, 21-char Base58 unique ID generator. Zero dependencies.

```
1ocmpHE1bFnygEBAPTzMK
1ocmpHE1bFnygFv4Wp4dL
1ocmpHE1bFnygGoUXUL7X
```

Available for [JavaScript/TypeScript](#javascript), [Python](#python), and [Rust](#rust).

## Why sparkid?

| | sparkid | UUID v4 | UUID v7 | ULID | nanoid |
|---|---|---|---|---|---|
| **Length** | 21 | 36 | 36 | 26 | 21 |
| **Sortable** | Yes | No | Yes | Yes | No |
| **Monotonic** | Yes | No | Opt-in | Opt-in | No |
| **Alphabet** | Base58 | Hex | Hex | Crockford32 | Mixed |
| **Binary** | 16 bytes | 16 bytes | 16 bytes | 16 bytes | None |
| **Performance** | Fastest | Medium | Slow | Medium | Medium |

sparkid gives you compact, readable IDs that sort by creation time and are strictly monotonically increasing — no two IDs from the same generator will ever compare equal or out of order.

It's also the fastest option across all three languages:

![Benchmark comparison — sparkid vs. UUID v4, UUID v7, nanoid, and ulid across Python, JavaScript, and Rust](https://raw.githubusercontent.com/youssefm/sparkid/main/benchmark_comparison.png)

## How it works

Each ID is 21 characters built from three parts:

```
[8-char timestamp][6-char counter][7-char random]
```

- **Timestamp** — current millisecond, Base58-encoded. IDs from a later millisecond always sort after earlier ones.
- **Counter** — randomly seeded each new millisecond, then incremented for each ID within that millisecond. Guarantees strict monotonic ordering even at high throughput.
- **Random** — 7 characters of cryptographically secure randomness per ID, rejection-sampled to avoid modulo bias. Provides ~58^13 (~8.4 x 10^22) combinations per millisecond for collision resistance.

The Base58 alphabet (`123456789ABC...xyz`) excludes visually ambiguous characters (`0`, `O`, `I`, `l`), making IDs safe to copy, paste, and read aloud.

### Binary format

IDs can be packed into a 16-byte binary representation (6 bits per Base58 character, 126 data bits + 2 padding bits). Sort order is preserved — byte-wise comparison on the binary form gives the same ordering as string comparison. All three language implementations provide `toBytes`/`fromBytes` (or `to_bytes`/`from_bytes`) for this conversion.

## JavaScript

```bash
npm install sparkid
```

```typescript
import { generateId } from "sparkid";

const id = generateId();
```

Works in Node >= 19, browsers, Deno, Bun, and Cloudflare Workers.

All IDs from `generateId()` are strictly monotonically increasing within the process. Since JavaScript is single-threaded, this means process-wide ordering with no coordination needed.

See [js/README.md](js/README.md) for full documentation.

## Python

```bash
pip install sparkid
```

```python
from sparkid import generate_id

id = generate_id()
```

Thread-safe via `threading.local` (one generator per thread). Fork-safe via `os.register_at_fork`.

IDs from a single thread are strictly monotonically increasing. Across threads, IDs are unique but unordered. For process-wide monotonic ordering, wrap an `IdGenerator` in a lock — see [python/README.md](python/README.md) for details.

## Rust

```bash
cargo add sparkid
```

```rust
use sparkid::SparkId;

let id = SparkId::new();
```

`SparkId` is a stack-allocated, `Copy` type — no heap allocation. Thread-safe via `thread_local!` (one generator per thread). Only dependency is `rand` (userspace CSPRNG).

IDs from a single thread are strictly monotonically increasing. Across threads, IDs are unique but unordered. For manual control, use `IdGenerator` directly — see [rust/README.md](rust/README.md) for details.

## License

MIT

sparkid

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README