{"id":13837573,"url":"https://github.com/perry-mitchell/ulidx","last_synced_at":"2025-04-08T14:03:36.118Z","repository":{"id":45198804,"uuid":"373811756","full_name":"perry-mitchell/ulidx","owner":"perry-mitchell","description":"ULID generator for NodeJS and the browser","archived":false,"fork":false,"pushed_at":"2024-08-25T18:43:31.000Z","size":650,"stargazers_count":284,"open_issues_count":3,"forks_count":17,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-10-29T23:22:57.850Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/perry-mitchell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["perry-mitchell"]}},"created_at":"2021-06-04T10:55:11.000Z","updated_at":"2024-10-28T22:05:16.000Z","dependencies_parsed_at":"2024-05-30T05:09:59.348Z","dependency_job_id":"443121e8-f82d-4b0c-a947-615e31948991","html_url":"https://github.com/perry-mitchell/ulidx","commit_stats":{"total_commits":111,"total_committers":13,"mean_commits":8.538461538461538,"dds":"0.18918918918918914","last_synced_commit":"bb685bac8d062bc168d231e97ebffff0dc389963"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fulidx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fulidx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fulidx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fulidx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perry-mitchell","download_url":"https://codeload.github.com/perry-mitchell/ulidx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247856541,"owners_count":21007620,"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-08-04T15:01:15.000Z","updated_at":"2025-04-08T14:03:36.079Z","avatar_url":"https://github.com/perry-mitchell.png","language":"JavaScript","funding_links":["https://github.com/sponsors/perry-mitchell"],"categories":["JavaScript"],"sub_categories":[],"readme":"# ulidx\n\u003e ULID generator for NodeJS and the browser\n\n[![ulidx](https://img.shields.io/npm/v/ulidx?color=blue\u0026label=ulidx\u0026logo=npm\u0026style=flat-square)](https://www.npmjs.com/package/ulidx) ![Tests status](https://github.com/perry-mitchell/ulidx/actions/workflows/test.yml/badge.svg) ![GitHub](https://img.shields.io/github/license/perry-mitchell/ulidx) ![Dependents (via libraries.io)](https://img.shields.io/librariesio/dependents/npm/ulidx) [![monthly downloads](https://img.shields.io/npm/dm/ulidx.svg)](https://www.npmjs.com/package/ulidx) [![total downloads](https://img.shields.io/npm/dt/ulidx.svg?label=total%20downloads)](https://www.npmjs.com/package/ulidx)\n\nULID generator library, based off of the original [ulid](https://github.com/ulid/javascript) for NodeJS and the browser. ULIDs are Universally Unique Lexicographically Sortable Identifiers. This library adheres to [this specification](https://github.com/ulid/spec).\n\n\u003e The original [ulid](https://github.com/ulid/javascript) is no longer maintained, and has several outstanding compatibility-related issues that were never addressed. This library aims to address those and remain compatible in a larger range of environments.\n\n## Installation\n\nInstall using npm by running: `npm install ulidx --save`.\n\n`ulidx` provides types and is written entirely in Typescript. It provides both ESM and CommonJS outputs.\n\n## Usage\n\nImport `ulid` to generate new ULIDs:\n\n```typescript\nimport { ulid } from \"ulidx\";\n\nulid(); // 01F7DKCVCVDZN1Z5Q4FWANHHCC\n```\n\n### Time seed\n\nYou can also provide a time seed which will consistently give you the same string for the time component.\n\n\u003e This is useful for migrating to ulid.\n\n```typescript\nulid(1469918176385); // 01ARYZ6S41TSV4RRFFQ69G5FAV\n```\n\n### Monotonic ULID factory\n\nTo generate monotonically increasing ULIDs, create a monotonic counter using the factory:\n\n```typescript\nimport { monotonicFactory } from \"ulidx\";\n\nconst ulid = monotonicFactory();\n\n// Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1\nulid(150000); // 000XAL6S41ACTAV9WEVGEMMVR8\nulid(150000); // 000XAL6S41ACTAV9WEVGEMMVR9\nulid(150000); // 000XAL6S41ACTAV9WEVGEMMVRA\nulid(150000); // 000XAL6S41ACTAV9WEVGEMMVRB\nulid(150000); // 000XAL6S41ACTAV9WEVGEMMVRC\n\n// Even if a lower timestamp is passed (or generated), it will preserve sort order\nulid(100000); // 000XAL6S41ACTAV9WEVGEMMVRD\n```\n\n### Decode ULID Time\n\nImport `decodeTime` to extract the timestamp embedded in a ULID:\n\n```typescript\nimport { decodeTime } from \"ulidx\";\n\n// Extract milliseconds since UNIX Epoch from ULID\ndecodeTime(\"01ARYZ6S41TSV4RRFFQ69G5FAV\"); // 1469918176385\n```\n\n### Validate ULID\n\nImport `isValid` to check if a string is a valid ULID:\n\n```typescript\nimport { isValid } from \"ulidx\";\n\nisValid(\"01ARYZ6S41TSV4RRFFQ69G5FAV\"); // true\nisValid(\"01ARYZ6S41TSV4RRFFQ69G5FA\"); // false\n```\n\n### Crockford's Base32 (Typos tolerance and Hyphened ULIDs)\n\nImport `fixULIDBase32` to fix typos and remove hyphens in a ULID:\n\n```typescript\nimport { fixULIDBase32 } from \"ulidx\";\n\nfixULIDBase32(\"oLARYZ6-S41TSV4RRF-FQ69G5FAV\"); // 01ARYZ6S41TSV4RRFFQ69G5FAV\n```\n\n## Pseudo-Random Number Generation (PRNG)\n\n`ulidx` will attempt to locate a suitable cryptographically-secure random number generator in the environment where it's loaded. On NodeJS this will be `crypto.randomBytes` and in the browser it will be `crypto.getRandomValues`.\n\n`Math.random()` is **not supported**: The environment _must_ have a suitable crypto random number generator.\n\n## Compatibility\n\n`ulidx` is compatible with the following environments:\n\n * NodeJS 16 and up\n   * Node REPL\n * Browsers with working `crypto` / `msCrypto` libraries\n   * Web workers\n * React-Native ¹\n * Edge compute\n   * Cloudflare Workers ²\n   * Vercel Edge\n\n ¹ React-Native is supported if `crypto.getRandomValues()` is polyfilled. [`react-native-get-random-values`](https://github.com/LinusU/react-native-get-random-values) is one such library that should work well with `ulidx`. It should be imported before `ulidx` is used.\n\n ² `ulidx` is not _fully_ compatible with Cloudflare Workers due to their [problematic stance on getting the current time](https://developers.cloudflare.com/workers/learning/security-model#step-1-disallow-timers-and-multi-threading). It is recommended to only use monotonic factories in this runtime.\n\n### Browser\n\n`ulidx` provides browser bundles in both ESM and CommonJS varieties. Importing should be automatic, but you can import them directly:\n\n * `dist/browser/index.js` - Browser ESM build\n * `dist/browser/index.cjs` - Browser CommonJS build\n\nUnlike version 1.x, these browser builds cannot simply be injected into the browser. They must be included in a build system of some kind, like Rollup or Webpack.\n\nNote that you can use the Node-based builds in the browser if you use such an aforementioned tool, but you will need to stub `node:crypto` to do so. Consider the following example in Webpack using a plugin:\n\n```javascript\n{\n    // ...\n\n    plugins: [\n        new NormalModuleReplacementPlugin(/node:/, (resource) =\u003e {\n            resource.request = resource.request.replace(/^node:/, \"\");\n        })\n    ]\n\n    // ...\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fulidx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperry-mitchell%2Fulidx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fulidx/lists"}