{"id":13742000,"url":"https://github.com/SasLuca/zig-nanoid","last_synced_at":"2025-05-08T22:32:53.179Z","repository":{"id":46170687,"uuid":"483016950","full_name":"SasLuca/zig-nanoid","owner":"SasLuca","description":"A tiny, secure, URL-friendly, unique string ID generator. Now available in pure Zig.","archived":false,"fork":false,"pushed_at":"2024-12-24T12:43:38.000Z","size":59,"stargazers_count":30,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-14T22:45:28.939Z","etag":null,"topics":["id","nanoid","random","unique-id","unique-identifier","uniqueid","url","uuid","uuid-generator","zig","zig-package","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SasLuca.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-04-18T22:32:31.000Z","updated_at":"2025-03-27T18:32:48.000Z","dependencies_parsed_at":"2025-04-16T04:01:17.017Z","dependency_job_id":null,"html_url":"https://github.com/SasLuca/zig-nanoid","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SasLuca%2Fzig-nanoid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SasLuca%2Fzig-nanoid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SasLuca%2Fzig-nanoid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SasLuca%2Fzig-nanoid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SasLuca","download_url":"https://codeload.github.com/SasLuca/zig-nanoid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253158634,"owners_count":21863344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["id","nanoid","random","unique-id","unique-identifier","uniqueid","url","uuid","uuid-generator","zig","zig-package","ziglang"],"created_at":"2024-08-03T04:01:05.077Z","updated_at":"2025-05-08T22:32:52.913Z","avatar_url":"https://github.com/SasLuca.png","language":"Zig","funding_links":[],"categories":["Libraries"],"sub_categories":[],"readme":"# Nano ID in Zig\n\n[![License](https://img.shields.io/badge/license-MIT%20License-blue.svg)](https://github.com/SasLuca/nanoid-zig/master/LICENSE)\n[![cross build tests](https://github.com/SasLuca/zig-nanoid/actions/workflows/cross-build.yml/badge.svg)](https://github.com/SasLuca/zig-nanoid/actions/workflows/cross-build.yml)\n![Maintenance intention for this crate](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)\n\n\u003cimg src=\"https://raw.githubusercontent.com/SasLuca/zig-nanoid/main/logo.svg\" align=\"right\" alt=\"Nano ID x Zig logo by Anton Lovchikov, adapted by Luca Sas\" width=\"180\" height=\"94\"\u003e\n\nA battle-tested, tiny, secure, URL-friendly, unique string ID generator. Now available in pure Zig.\n\n* **Freestanding.** zig-nanoid is entirely freestanding.\n* **Fast.** The algorithm is very fast and relies just on basic math, speed will mostly depend on your choice of RNG.\n* **Safe.** It can use any random generator you want and the library has no errors to handle.\n* **Short IDs.** It uses a larger alphabet than UUID (`A-Za-z0-9_-`). So ID length was reduced from 36 to 21 symbols and it is URL friendly.\n* **Battle Tested.** Original implementation has over 18 million weekly downloads on [npm](https://www.npmjs.com/package/nanoid).\n* **Portable.** Nano ID was ported to [20+ programming languages](https://github.com/ai/nanoid#other-programming-languages).\n\n## Example\n\nBasic usage with `std.crypto.random`:\n```zig\nconst std = @import(\"std\");\nconst nanoid = @import(\"nanoid\");\n\npub fn main() !void\n{   \n    const result = nanoid.generate(std.crypto.random);\n\n    std.log.info(\"Nanoid: {s}\", .{result});\n}\n```\n\n## Comparison to UUID\n\nNano ID is quite comparable to UUID v4 (random-based).\n\nIt has a similar number of random bits in the ID (126 in Nano ID and 122 in UUID), so it has a similar collision probability.\n\nIt also uses a bigger alphabet, so a similar number of random bits are packed in just 21 symbols instead of 36.\n\nFor there to be a one in a billion chance of duplication, 103 trillion version 4 IDs must be generated.\n\n## How to use\n\n### Generating an id with the default size\n\nThe simplest way to generate an id with the default alphabet and length is by using the function `generate` like so:\n\n```zig\nconst result = nanoid.generate(std.crypto.random);\n```\n\nIf you want a custom alphabet you can use `generateWithAlphabet` and pass either a custom alphabet or one from `nanoid.alphabets`:\n```zig\nconst result = nanoid.generateWithAlphabet(std.crypto.random, nanoid.alphabets.numbers); // This id will only contain numbers\n```\n\nYou can find a variety of other useful alphabets inside of `nanoid.alphabets`.\n\nThe result is an array of size `default_id_len` which happens to be 21 which is returned by value.\n\nThere are no errors to handle, assuming your rng object is valid everything will work.\nThe default alphabet includes the symbols \"-_\", numbers and English lowercase and uppercase letters.\n\n### Generating an id with a custom size\n\nIf you want a custom alphabet and length use `generateEx` or `generateExWithIterativeRng`.\n\nThe function `generateEx` takes an rng, an `alphabet`, a `result_buffer` that it will write the id to, and a `step_buffer`.\nThe `step_buffer` is used by the algorithm to store a random bytes so it has to do less calls to the rng and `step_buffer.len` must be at \nleast `computeRngStepBufferLength(computeMask(@truncate(u8, alphabet.len)), result_buffer.len, alphabet.len)`.\n\nThe function `generateExWithIterativeRng` is the same as `generateEx` except it doesn't need a `step_buffer`. It will use `Random.int(u8)` \ninstead of `Random.bytes()` to get a random byte at a time thus avoiding the need for a rng step buffer. Normally this will be slower but \ndepending on your rng algorithm or other requirements it might not be, so the option is there in case you need but normally it is \nrecommended you use `generateEx` which requires a temporary buffer that will be filled using `Random.bytes()` in order to get the best\nperformance.\n\nAdditionally you can precompute a sufficient length for the `step_buffer` and pre-allocate it as an optimization using \n`computeSufficientRngStepBufferLengthFor` which simply asks for the largest possible id length you want to generate.\n\nIf you intend to use the `default_id_len`, you can use the constant `nanoid.rng_step_buffer_len_sufficient_for_default_length_ids`.\n\n### Regarding RNGs\n\nYou will need to provide an random number generator (rng) yourself. You can use the zig standard library ones, either `std.rand.DefaultPrng`\nor if you have stricter security requirements use `std.rand.DefaultCsprng` or `std.crypto.random`.\n\nWhen you initialize them you need to provide a seed, providing the same one every time will result in the same ids being generated every \ntime you run the program, except for `std.crypto.random`.\n\nIf you want a good secure seed you can generate one using `std.crypto.random.bytes`. \n\nHere is an example of how you would initialize and seed `std.rand.DefaultCsprng` and use it:\n\n```zig\n// Generate seed\nvar seed: [std.rand.DefaultCsprng.secret_seed_length]u8 = undefined;\nstd.crypto.random.bytes(\u0026seed);\n\n// Initialize the rng and allocator\nvar rng = std.rand.DefaultCsprng.init(seed);\n\n// Generate id\nvar id = nanoid.generate(rng.random());\n```\n\n## Add zig-nanoid to your project\n\n### Manually\n\nTo add the library as a package to your zig project:\n1. Download the repo and put it in a folder (eg: `thirdparty`) in your project.\n2. Import the library's `build.zig` in your build script (eg: `const nanoid = @import(\"thirdparty/nanoid-zig/build.zig\");`)\n3. Add the library as a package to your steps (eg: `exe.addPackage(nanoid.getPackage(\"nanoid\"));`)\n\nFull example:\n```zig\n// build.zig\nconst std = @import(\"std\");\nconst nanoid = @import(\"thirdparty/zig-nanoid/build.zig\");\n\npub fn build(b: *std.build.Builder) void \n{\n    const target = b.standardTargetOptions(.{});\n    const mode = b.standardReleaseOptions();\n\n    const exe = b.addExecutable(\"zig-nanoid-test\", \"src/main.zig\");\n    exe.setTarget(target);\n    exe.setBuildMode(mode);\n    exe.addPackage(nanoid.getPackage(\"nanoid\"));\n    exe.install();\n}\n```\n\n### Using the gyro package manager\n\nWe support the zig [gyro package manager](https://github.com/mattnite/gyro).\nHere is how to use it:\n\n1. From your terminal initialize a gyro project and add the package `SasLuca/nanoid`.\n    ```\n    gyro init\n    gyro add SasLuca/nanoid\n    ```\n\n2. In your `build.zig` do an import like so `const pkgs = @import(\"deps.zig\").pkgs;` and call `pkgs.addAllTo(exe);` to add all libraries to your executable (or some other target).\n\n3. Import `const nanoid = @import(\"nanoid\");` in your `main.zig` and use it.\n\n4. Invoke `gyro build run` which will generate `deps.zig` and other files as well as building and running your project.\n\n## Useful links\n\n- Original implementation: https://github.com/ai/nanoid\n\n- Online Tool: https://zelark.github.io/nano-id-cc/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSasLuca%2Fzig-nanoid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSasLuca%2Fzig-nanoid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSasLuca%2Fzig-nanoid/lists"}