{"id":16578030,"url":"https://github.com/glynnbird/kuuid","last_synced_at":"2025-07-23T14:08:01.615Z","repository":{"id":32751549,"uuid":"141574107","full_name":"glynnbird/kuuid","owner":"glynnbird","description":"Time-sortable UUID - roughly time-sortable unique id generator","archived":false,"fork":false,"pushed_at":"2025-06-18T09:36:54.000Z","size":243,"stargazers_count":22,"open_issues_count":3,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-18T10:33:02.653Z","etag":null,"topics":["cloudant","couchdb","nodejs","uuid"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glynnbird.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2018-07-19T12:08:25.000Z","updated_at":"2025-06-18T09:36:58.000Z","dependencies_parsed_at":"2024-10-26T20:29:02.628Z","dependency_job_id":"3b79dd90-f9cb-4128-8024-ccacd9cfc2d9","html_url":"https://github.com/glynnbird/kuuid","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"6e9c2483a5acb56c8255f807ba00b170b216bc49"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/glynnbird/kuuid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fkuuid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fkuuid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fkuuid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fkuuid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glynnbird","download_url":"https://codeload.github.com/glynnbird/kuuid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glynnbird%2Fkuuid/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266691580,"owners_count":23969182,"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","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cloudant","couchdb","nodejs","uuid"],"created_at":"2024-10-11T22:12:56.464Z","updated_at":"2025-07-23T14:08:01.607Z","avatar_url":"https://github.com/glynnbird.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kuuid\n\nIf you need unique identifiers in your Node.js app for use in a database such as Apache CouchDB or Cloudant, then *kuuid* can generate them. The ids it generates are:\n\n- uniform - all ids are 32 characters long.\n- unique - no two ids will be the same, or at least the likelihood of a clash is vanishingly small.\n- time-sortable - the ids sort into time order (or reverse time order), with one second (or millisecond) precision.\n\nIf a `kuuid`-generated id were used as a database's unique identifier, it would sort roughly in time order (`kuuid.id()`), or reverse time order (`kuuid.idr()`)\n\n## Installation\n\nAdd *kuuid* to your Node.js project with:\n\n```sh\nnpm install --save kuuid\n```\n\nImport the library into your code with:\n\n```js\nimport * as kuuid from 'kuuid'\n```\n\n## Generating an id\n\nSimply call the `kuuid.id()` function to get an id:\n\n```js\nlet id = kuuid.id()\n// 001fgS7k4gJxqY1aXpni3gHuOy0WusLe\n```\n\nYou can use such an id as a unique identifier in your database records:\n\n```js\nlet doc = {\n  _id: kuuid.id(),\n  name: 'Glynn',\n  location: 'UK',\n  verified: true\n}\n// {\"_id\":\"001fgS954GN35e4NJPyK1W9aiE44m2xD\",\"name\":\"Glynn\",\"location\":\"UK\",\"verified\":true}\ndb.insert(doc)\n```\n\n## Parameters\n\nBy default, the `id()` function returns an id made up of a timestamp derived from \"now\" to second precision, 128 bits of data and it will sort in oldest-first order. This can be configured by overriding these defaults:\n\n```js\nconst id = kuuid.id({\n  timestamp: '2000-01-01T10:24:22.000Z', // use a known timestamp\n  random: 1, // use less random data\n  reverse: true, // sort in newest first order\n  millisecond: true // the timestamp should be to millisecond precision\n})\n```\n\n- `timestamp` - an ISO string representing the date/time required or an integer representing the number of milliseconds since 1970. Default \"now\"\n- `random` - the quantity of random data. Between 1 and 4. Default `4`.\n- `reverse` - if true, the id will sort in newest-first order. Default `false`.\n- `millisecond` - if true, the id's time component will be stored with milliecond precision. Default `false`.\n\nFor backwards compatibility, the `id()` function will also accept a string or number parameter representing the timestamp.\n\n```js\n// 'now'\nkuuid.id()\n\n// ISO String \nkuuid.id('2018-07-20T10:10:34.234Z')\n\n// millseconds since 1970\nkuuid.id(1514764800000)\n```\n\n## Shortcut functions\n\n- `idr()` - returns an id that sorts in newest-first order.\n- `idms()` - returns an id with millisecond precision.\n- `ids()` - returns a shorter id (64-bits of random data).\n- `idsr()` - returns a short it in newest-first order.\n- `prefix()` - returns only the time prefix.\n- `prefixReverse()` - returns only the time prefix (reverse order).\n- `prefixms()` - returns only the time prefix with ms precision.\n- `prefixReverseMs()` - returns only the time prefix with ms precision. (reverse order).\n- `rand()` - returns the random portion of the id.\n\n## How does it work?\n\nA `kuuid.id()` string has two parts:\n\n- 8 characters representing the number of seconds since 1st January 1970.\n- 24 characters containing random data (for the default 128-bits)\n\nThe front eight characters allow the string to be sorted by time. Two ids created in the same second will have the same front eight characters. The remaining 24 characters contain 128 bits of random data.\n\nThe strings are encoded in \"base 62\" (i.e using digits and uppercase/lowercase letters) to pack more information into a smaller space.\n\n## Points to note\n\n1) The `kuuid` library can only be used to store dates after the epoch on `1970-01-01`.\n2) The random number is genreated using Node.js's [crypto.randomBytes](https://nodejs.org/dist/latest-v8.x/docs/api/crypto.html#crypto_crypto_randombytes_size_callback) which is a secure, if slow, source of random information.\n3) The character set used by the base-62 encoding algorithm differs from other algorithms I've seen to ensure that it sorts correctly in a CouchDB `_id` field.\n\n## Further reading\n\n- [A Brief History of the UUID](https://segment.com/blog/a-brief-history-of-the-uuid/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglynnbird%2Fkuuid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglynnbird%2Fkuuid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglynnbird%2Fkuuid/lists"}