{"id":16701205,"url":"https://github.com/eproxus/keysmith","last_synced_at":"2025-03-21T19:33:14.075Z","repository":{"id":257798615,"uuid":"862885287","full_name":"eproxus/keysmith","owner":"eproxus","description":"A Erlang library for generating unique identifiers","archived":false,"fork":false,"pushed_at":"2025-03-05T10:58:39.000Z","size":60,"stargazers_count":8,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T04:42:44.766Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Erlang","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/eproxus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-25T10:59:08.000Z","updated_at":"2025-02-12T21:46:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"c572fcfe-bd5c-49d2-b476-23e7d84134b0","html_url":"https://github.com/eproxus/keysmith","commit_stats":null,"previous_names":["eproxus/keysmith"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eproxus%2Fkeysmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eproxus%2Fkeysmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eproxus%2Fkeysmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eproxus%2Fkeysmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eproxus","download_url":"https://codeload.github.com/eproxus/keysmith/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244855713,"owners_count":20521691,"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":[],"created_at":"2024-10-12T18:43:10.416Z","updated_at":"2025-03-21T19:33:14.057Z","avatar_url":"https://github.com/eproxus.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"# keysmith [![CI Status][ci-img]][ci] [![Lint Status][lint-img]][lint] [![Hex.pm Version][hex-img]][hex] [![Minimum Erlang Version][erlang-img]][erlang] [![License][license-img]][license]\n\nKeySmith is a library for generating unique IDs. It supports two types of\nIDs:\n\n* UUID ([RFC-9562](https://www.rfc-editor.org/rfc/rfc9562.html))\n  * The 'nil' uuid (`00000000-0000-0000-0000-000000000000`)\n  * The 'max' uuid (`ffffffff-ffff-ffff-ffff-ffffffffffff`)\n  * Version 4 (random)\n  * Version 7 (time-based and random)\n* TypeID ([specification](https://github.com/jetify-com/typeid/tree/main/spec))\n  * TypeID's embed a UUID v7 by default, but can be customized with any\n    supported UUID version\n\nKeysmith is a well tested, secure and performant:\n\n* Full test coverage\n* Property-based tests\n* Uses `crypto` for secure random number generation\n* Fast and efficient using binary pattern matching\n\n## Usage\n\nKeySmith provides functions to generate UUIDs and TypeIDs. Here are some basic\nexamples:\n\n### Generating UUIDs\n\nYou can generate UUIDs version 4 (random) and version 7 (time-based):\n\n```erlang\n% Generate a UUID v4\n1\u003e keysmith:uuid(4).\n\u003c\u003c\"79782daf-ff7d-4426-a8f5-e12672e89e32\"\u003e\u003e\n\n% Generate a UUID v7\n2\u003e keysmith:uuid(7).\n\u003c\u003c\"01922919-44d3-779c-84ad-20ab20fc7dbb\"\u003e\u003e\n\n% Generate a UUID v7 with a specific timestamp\n3\u003e keysmith:uuid({7, 1234567890}).\n\u003c\u003c\"00004996-02d2-7bf9-9b68-599f55d37931\"\u003e\u003e\n```\n\nUUIDs can be generated in different formats:\n\n```erlang\n4\u003e keysmith:uuid(4, binary).\n\u003c\u003c193,169,209,27,160,43,73,83,147,64,63,136,127,77,166,39\u003e\u003e\n\n5\u003e keysmith:uuid(4, hex_nodash).\n\u003c\u003c\"01922919d63d7de990a0209e23b50747\"\u003e\u003e\n```\n\n### Generating TypeIDs\n\nTypeIDs are a combination of a type prefix and a UUID. They are useful for\ncreating namespaced unique identifiers:\n\n```erlang\n% Generate a TypeID with default UUID v7\n6\u003e keysmith:type_id(user).\n\u003c\u003c\"user_01j8mhm5vafn8vprb7g6dz4q90\"\u003e\u003e\n\n% Generate a TypeID with a specific UUID\n7\u003e keysmith:type_id(product, 4).\n\u003c\u003c\"product_7fv003jbwg9ptvecwr68p6n5k6\"\u003e\u003e\n```\n\n### Parsing IDs\n\nKeySmith can also parse UUIDs and TypeIDs back into their components:\n\n```erlang\n8\u003e UUID = keysmith:uuid(7).\n\u003c\u003c\"019228d7-b720-7484-ab83-25332e9b0a33\"\u003e\u003e\n9\u003e keysmith:parse(uuid, UUID).\n#{var =\u003e rfc,\n  ver =\u003e 7,\n  bin =\u003e \u003c\u003c1,146,40,215,183,32,116,132,171,131,37,51,46,155,10,51\u003e\u003e,\n  hex =\u003e \u003c\u003c\"019228d7-b720-7484-ab83-25332e9b0a33\"\u003e\u003e,\n  val =\u003e\n      #{rand_a =\u003e \u003c\u003c72,4:4\u003e\u003e,\n        rand_b =\u003e \u003c\u003c174,12,148,204,186,108,40,51:6\u003e\u003e,\n        unix_ts =\u003e {millisecond,1727262078752}}}\n\n10\u003e TypeID = keysmith:type_id(order).\n\u003c\u003c\"order_01j9p6jwxyfzjawx1ksjyzp9gy\"\u003e\u003e\n11\u003e keysmith:parse(type_id, TypeID).\n{type_id,order,\n         #{var =\u003e rfc,\n           ver =\u003e 7,\n           bin =\u003e \u003c\u003c1,146,108,105,115,190,127,228,174,116,51,204,189,251,38,30\u003e\u003e,\n           hex =\u003e \u003c\u003c\"01926c69-73be-7fe4-ae74-33ccbdfb261e\"\u003e\u003e,\n           val =\u003e\n               #{rand_a =\u003e \u003c\u003c254,4:4\u003e\u003e,\n                 rand_b =\u003e \u003c\u003c185,208,207,50,247,236,152,30:6\u003e\u003e,\n                 unix_ts =\u003e {millisecond,1728395703230}}}}\n```\n\nFor more detailed information on available functions and options, please refer\nto the module documentation.\n\n## Changelog\n\nSee [CHANGELOG](https://github.com/eproxus/keysmith/blob/main/CHANGELOG.md) or\nthe [Releases](https://github.com/eproxus/keysmith/releases) page.\n\n## Code of Conduct\n\nFind this project's code of conduct in\n[Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Contributing\n\nFirst of all, thank you for contributing with your time and energy.\n\nIf you want to request a new feature make sure to\n[open a feature request](https://github.com/eproxus/keysmith/issues/new?template=feature_request.yaml)\nso we can discuss it first.\n\nBug reports and questions are also welcome. If you believe you've found a bug,\nfeel free to [report an issue](https://github.com/eproxus/keysmith/issues/new?template=bug_report.yaml).\n\nIf you have a question, search the discussions and issues since it might have\nalready been answered before. If you can't find an answer, you\ncan [open a new discussion](https://github.com/eproxus/keysmith/discussions/new/choose).\n\nContributions will be subject to the MIT License. You will retain the copyright.\n\nFor more information check out [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Security\n\nThis project's security policy is made explicit in [SECURITY.md](SECURITY.md).\n\n## Conventions\n\n### Versions\n\nThis project adheres to\n[Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n### License\n\nThis project uses the [MIT License][license].\n\n[ci]:          https://github.com/eproxus/keysmith/actions/workflows/erlang.yml?query=branch%3Amain\n[ci-img]:      https://img.shields.io/github/actions/workflow/status/eproxus/keysmith/erlang.yml?label=ci\n[lint]:        https://github.com/eproxus/keysmith/actions/workflows/lint.yml\n[lint-img]:    https://img.shields.io/github/actions/workflow/status/eproxus/keysmith/lint.yml?label=lint\n[hex]:         https://hex.pm/packages/keysmith\n[hex-img]:     https://img.shields.io/hexpm/v/keysmith\n[license]:     LICENSE.md\n[license-img]: https://img.shields.io/hexpm/l/keysmith\n[erlang]:      https://github.com/eproxus/keysmith/blob/main/.tool-versions\n[erlang-img]:  https://img.shields.io/badge/erlang-27+-blue.svg?style=flat-square\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feproxus%2Fkeysmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feproxus%2Fkeysmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feproxus%2Fkeysmith/lists"}