{"id":13431373,"url":"https://github.com/ulid/javascript","last_synced_at":"2025-05-14T11:08:27.411Z","repository":{"id":39787876,"uuid":"61051155","full_name":"ulid/javascript","owner":"ulid","description":"Universally Unique Lexicographically Sortable Identifier","archived":false,"fork":false,"pushed_at":"2025-03-24T20:28:17.000Z","size":275,"stargazers_count":3163,"open_issues_count":2,"forks_count":109,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-05-07T10:52:37.530Z","etag":null,"topics":["javascript","ulid","uuid"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/ulid.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,"zenodo":null}},"created_at":"2016-06-13T16:14:51.000Z","updated_at":"2025-05-07T06:53:16.000Z","dependencies_parsed_at":"2024-11-25T16:03:00.393Z","dependency_job_id":"18012e2d-317f-410e-b7d8-f1e407c0acae","html_url":"https://github.com/ulid/javascript","commit_stats":{"total_commits":129,"total_committers":35,"mean_commits":"3.6857142857142855","dds":"0.31007751937984496","last_synced_commit":"a5831206a11636c94d4657b9e1a1354c529ee4e9"},"previous_names":["alizain/ulid","ulid/ulid"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulid%2Fjavascript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulid%2Fjavascript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulid%2Fjavascript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulid%2Fjavascript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ulid","download_url":"https://codeload.github.com/ulid/javascript/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129481,"owners_count":22019628,"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":["javascript","ulid","uuid"],"created_at":"2024-07-31T02:01:02.602Z","updated_at":"2025-05-14T11:08:27.382Z","avatar_url":"https://github.com/ulid.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\t\u003cimg width=\"360\" src=\"logo.png\" alt=\"ulid\"\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\u003c/h1\u003e\n\n# Universally Unique Lexicographically Sortable Identifier\n\n[![Tests](https://github.com/ulid/javascript/actions/workflows/test.yml/badge.svg)](https://github.com/ulid/javascript/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/ulid/javascript/branch/master/graph/badge.svg)](https://codecov.io/gh/ulid/javascript)\n[![npm](https://img.shields.io/npm/dm/ulid.svg)](https://www.npmjs.com/package/ulid) [![npm](https://img.shields.io/npm/dy/ulid)](https://www.npmjs.com/package/ulid)\n\nULIDs are unique, sortable identifiers that work much in the same way as UUIDs, though with some improvements:\n\n * Lexicographically sortable\n * Canonically encoded as a 26 character string, as opposed to the 36 character UUID\n * Uses Crockford's base32 for better efficiency and readability (5 bits per character)\n * Monotonic sort order (correctly detects and handles the same millisecond)\n\nULIDs also provide:\n\n * 128-bit compatibility with UUID\n * 1.21e+24 unique IDs per millisecond\n * Case insensitivity\n * No special characters (URL safe)\n\nUUID can be suboptimal for many uses-cases because:\n\n- It isn't the most character efficient way of encoding 128 bits of randomness\n- UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address\n- UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures\n- UUID v4 provides no other information than randomness which can cause fragmentation in many data structures\n\n## Installation\n\nInstall using NPM:\n\n```shell\nnpm install ulid --save\n```\n\n### Compatibility\n\nULID supports the following environments:\n\n| Version   | NodeJS    | Browsers      | React-Native  | Web Workers   | Edge Functions    |\n|-----------|-----------|---------------|---------------|---------------|-------------------|\n| v3        | v18+      | Yes           | Yes           | Yes           | ?                 |\n| v2        | v16+      | Yes           | No            | No            | No                |\n\nAdditionally, both ESM and CommonJS entrypoints are provided.\n\n## Usage\n\nTo quickly generate a ULID, you can simply import the `ulid` function:\n\n```typescript\nimport { ulid } from \"ulid\";\n\nulid(); // \"01ARZ3NDEKTSV4RRFFQ69G5FAV\"\n```\n\n### Seed Time\n\nYou can also input a seed time which will consistently give you the same string for the time component. This is useful for migrating to ulid.\n\n```typescript\nulid(1469918176385) // \"01ARYZ6S41TSV4RRFFQ69G5FAV\"\n```\n\n### Monotonic ULIDs\n\nTo generate monotonically increasing ULIDs, create a monotonic counter with `monotonicFactory`.\n\n\u003e Note that the same seed time is being passed in for this example to demonstrate its behaviour when generating multiple ULIDs within the same millisecond\n\n```typescript\nimport { monotonicFactory } from \"ulid\";\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### Pseudo-Random Number Generators\n\n`ulid` automatically detects a suitable (cryptographically-secure) PRNG. In the browser it will use `crypto.getRandomValues` and on NodeJS it will use `crypto.randomBytes`.\n\n#### Using `Math.random` (insecure)\n\nBy default, `ulid` will not use `Math.random` to generate random values. You can bypass this limitation by overriding the PRNG:\n\n```typescript\nconst ulid = monotonicFactory(() =\u003e Math.random());\n\nulid(); // \"01BXAVRG61YJ5YSBRM51702F6M\"\n```\n\n### Validity\n\nYou can verify if a value is a valid ULID by using `isValid`:\n\n```typescript\nimport { isValid } from \"ulid\";\n\nisValid(\"01ARYZ6S41TSV4RRFFQ69G5FAV\"); // true\nisValid(\"01ARYZ6S41TSV4RRFFQ69G5FA\"); // false\n```\n\n### ULID Time\n\nYou can encode and decode ULID timestamps by using `encodeTime` and `decodeTime` respectively:\n\n```typescript\nimport { decodeTime } from \"ulid\";\n\ndecodeTime(\"01ARYZ6S41TSV4RRFFQ69G5FAV\"); // 1469918176385\n```\n\nNote that while `decodeTime` works on full ULIDs, `encodeTime` encodes only the _time portion_ of ULIDs:\n\n```typescript\nimport { encodeTime } from \"ulid\";\n\nencodeTime(1469918176385); // \"01ARYZ6S41\"\n```\n\n### Tests\n\nInstall dependencies using `npm install` first, and then simply run `npm test` to run the test suite.\n\n### CLI\n\n`ulid` can be used on the command line, either via global install:\n\n```shell\nnpm install -g ulid\nulid\n```\n\nOr via `npx`:\n\n```shell\nnpx ulid\n```\n\nYou can also generate multiple IDs at the same time:\n\n```shell\nulid --count 15\n```\n\n## Specification\n\nYou can find the full specification, as well as information regarding implementations in other languages, over at [ulid/spec](https://github.com/ulid/spec).\n\n## Performance\n\nYou can test `ulid`'s performance by running `npm run bench`:\n\n```\nSimple ulid x 56,782 ops/sec ±2.50% (86 runs sampled)\nulid with timestamp x 58,574 ops/sec ±1.80% (87 runs sampled)\nDone!\n```\n","funding_links":[],"categories":["TypeScript","Repository","JavaScript"],"sub_categories":["Text/String"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulid%2Fjavascript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fulid%2Fjavascript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulid%2Fjavascript/lists"}