sqids/sqids-zig

Official Zig port of Sqids. Generate short unique IDs from numbers.

Sqids Zig

Sqids (pronounced "squids") is a small library that lets you generate unique IDs from numbers. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.

Features:

• Encode multiple numbers - generate short IDs from one or several non-negative numbers
• Quick decoding - easily decode IDs back into numbers
• Unique IDs - generate unique IDs by shuffling the alphabet once
• ID padding - provide minimum length to make IDs more uniform
• URL safe - auto-generated IDs do not contain common profanity
• Randomized output - Sequential input provides nonconsecutive IDs
• Many implementations - Support for multiple programming languages

🧰 Use-cases

Good for:

• Generating IDs for public URLs (eg: link shortening)
• Generating IDs for internal systems (eg: event tracking)
• Decoding for quicker database lookups (eg: by primary keys)

Not good for:

• Sensitive data (this is not an encryption library)
• User IDs (can be decoded revealing user count)

🚀 Getting started

To add sqids-zig to your Zig application or library, follow these steps:

1. Fetch the package at the desired commit:

zig fetch --save https://github.com/lvignoli/sqids-zig/archive/<commitID>.tar.gz

2. Declare the dependecy in the build.zig.zon file:

.dependencies = .{
    .sqids = .{
        .url = "https://github.com/lvignoli/sqids-zig/archive/<commitID>.tar.gz",
        .hash = "<hash>",
    },
}

3. Use it your build.zig and add it where needed:

const sqids_dep = b.dependency("sqids", .{});
const sqids_mod = sqids_dep.module("sqids");

[...]
 
exe.addModule("sqids", sqids_mod); // for an executable
lib.addModule("sqids", sqids_mod); // for a library
tests.addModule("sqids", sqids_mod); // for tests

4. Now you can import it in source sode with

const sqids = @import("sqids");

The import string is the one provided in the addModule call.

Tip

Check lvignoli/sqidify for a self-contained Zig executable example.

👩‍💻 Examples

Simple encode & decode:

const s = try sqids.Sqids.init(allocator, .{})
defer s.deinit();

const id = try s.encode(&.{1, 2, 3});
defer allocator.free(id); // Caller owns the memory.

const numbers = try s.decode(id);
defer allocator.free(numbers); // Caller owns the memory.

Note 🚧 Because of the algorithm's design, multiple IDs can decode back into the same sequence of numbers. If it's important to your design that IDs are canonical, you have to manually re-encode decoded numbers and check that the generated ID matches.

The sqids.Options struct is used at initialization to customize the encoder.

Enforce a minimum length for IDs:

const s = try sqids.Sqids.init(allocator, .{.min_length = 10});
const id = try s.encode(&.{1, 2, 3}); // "86Rf07xd4z"

Randomize IDs by providing a custom alphabet:

const s = try sqids.Sqids.init(allocator, .{.alphabet = "FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE"});
const id = try s.encode(&.{1, 2, 3}); // "B4aajs"

Prevent specific words from appearing anywhere in the auto-generated IDs:

const s = try sqids.Sqids.init(allocator, .{.blocklist = &.{"86Rf07"}});
const id = try s.encode(&.{1, 2, 3}); // "se8ojk"

📝 License

MIT