https://github.com/kripod/uuidv7

UUIDv7 generator with millisecond precision
https://github.com/kripod/uuidv7

collision-resistance id-generator k-sortable

Last synced: 6 months ago
JSON representation

UUIDv7 generator with millisecond precision

• Host: GitHub
• URL: https://github.com/kripod/uuidv7
• Owner: kripod
• License: mit
• Created: 2021-09-21T11:31:50.000Z (about 4 years ago)
• Default Branch: main
• Last Pushed: 2022-08-25T05:51:00.000Z (about 3 years ago)
• Last Synced: 2025-03-27T00:13:29.497Z (6 months ago)
• Topics: collision-resistance, id-generator, k-sortable
• Language: TypeScript
• Homepage:
• Size: 556 KB
• Stars: 109
• Watchers: 2
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

          
# UUIDv7

UUIDv7 generator based on the [RFC4122 update proposal (draft-04)](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html)

[![npm (scoped)](https://img.shields.io/npm/v/@kripod/uuidv7)](https://www.npmjs.com/package/@kripod/uuidv7)

[![npm bundle size (scoped)](https://img.shields.io/bundlephobia/minzip/@kripod/uuidv7)](https://bundlephobia.com/package/@kripod/uuidv7)

[![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/kripod/uuidv7/Node.js%20CI/main)](https://github.com/kripod/uuidv7/actions/workflows/node-ci.yaml)

[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](./CODE_OF_CONDUCT.md)

## Usage

```js

import { uuidv7 } from "@kripod/uuidv7";

let id = uuidv7();

console.log(id); // Example: 00ccebbc-13e0-7000-8b18-6150ad2d0c05

```

## Key features

- K-sortable with 1ms precision _(Safari disallows sub-ms timing [to defend against Spectre](https://webkit.org/blog/8048/what-spectre-and-meltdown-mean-for-webkit/))_

- Time-ordered when sorted lexicographically

- Collision-resistant with distributed systems in mind

- Works until the year 10889, after which timestamps would overflow

## Compatibility

| Chrome | Safari | Firefox |         IE          | Node.js | Deno |

| :----: | :----: | :-----: | :-----------------: | :-----: | :--: |

|  ≥57   |  ≥10   |   ≥48   | No _(polyfillable)_ |   ≥8    |  ≥1  |

### Supporting additional runtimes

- [`String.prototype.padStart`](https://caniuse.com/pad-start-end)

  - Included in popular frameworks:

    - Next.js

    - Nuxt

    - Gatsby

  - Polyfillable using [core-js](https://github.com/zloirock/core-js), preferably [within ``](https://3perf.com/blog/polyfills/#modulenomodule):

    ```js

    import "core-js/features/string/pad-start";

    ```

- [`crypto.getRandomValues()`](https://caniuse.com/getrandomvalues)

  - IE 11:

    ```js

    if (typeof window !== "undefined" && !window.crypto && window.msCrypto) {

      window.crypto = window.msCrypto;

    }

    ```

## Binary structure

- `unix_ts_ms`: Milliseconds elapsed since the Unix epoch – 48 bits

- `ver`: UUID version (`7`) – 4 bits

- `rand_a`: Monotonic sequence counter for more precise sorting – 12 bits

- `var`: UUID variant (`0b10`) – 2 bits

- `rand_b`: Cryptographically strong random data – 62 bits

<div aria-hidden="true">

```

 0                   1                   2                   3

 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1

┌─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┐

│                          unix_ts_ms                           │

├─┴─┴─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┼─┴─┴─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤

│          unix_ts_ms           │  ver  │        rand_a         │

├─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤

│var│                        rand_b                             │

├─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤

│                            rand_b                             │

└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

```

</div>