ui7

ui7
===

![npm][npm]
![deno.land][deno]
![CI][build]
![includes TypeScript types][typescript]
!node-current
![MIT license][license]

[npm]: https://www.npmjs.com/package/ui7
[deno]: https://deno.land/x/ui7
[build]: https://github.com/silverlyra/ui7/actions/workflows/ci.yml?query=branch%3Amain
[typescript]: https://deno.land/x/ui7/mod.ts
[license]: ./LICENSE

A small [UUIDv7][] generator, targeting a [proposed][bis] update to [RFC 4122][]. v7 UUID’s are lexically sortable by their included timestamp.

[UUIDV7]: https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-11#name-uuid-version-7
[bis]: https://datatracker.ietf.org/doc/draft-ietf-uuidrev-rfc4122bis/
[RFC 4122]: https://datatracker.ietf.org/doc/html/rfc4122

``js
import uuid, { timestamp } from "ui7";

const id = uuid();
// ==> "01836531-a895-7a2d-a70d-504ea62b40e2"

const when = new Date(timestamp(id));
// ==> 2022-09-22T12:34:56.789Z
`

Installation

ui7 is available on [NPM][npm] and [deno.land][deno]:

#### npm

`sh
npm install --save ui7
`

Node.js versions 12.0 and up are supported, and _ui7_ includes an ESM build. It has no runtime dependencies.

#### deno

`ts
import uuid from "https://deno.land/x/ui7@v0.2.3/mod.ts";
`

Usage

$3

The default UUIDv7 generator is available as both a default export and a named v7 function:

`js
import uuid from "ui7";

console.log(uuid());
// ==> "01836d65-3ec5-789f-b509-9ebd1d5ac2d3"
`

`js
import { v7 } from "ui7";

console.log(v7());
// ==> "01836d65-4a33-7aeb-aceb-8bfe42901787"
`

$3

Version 7 UUID’s include a millisecond-precision timestamp part and a random part. By default, _ui7_ will fully populate the random part with random bits. This means that ID’s generated during the same millisecond will sort in an arbitrary order:

`js
import uuid from "ui7";

const ids = [uuid(), uuid(), uuid()];
// [
// "01836d99-1b31-75c7-bb83-aa52c651b085",
// "01836d99-1b31-7b6a-8010-98fe59822b40",
// "01836d99-1b31-71c4-bed3-6d3111c2de7d"
// ]

[...ids].sort().map(id => ids.indexOf(id))
// [ 2, 0, 1 ]
`

If you want UUID’s generated in the same process to sort in the order they were generated, you can instead create a _monotonic_ generator:

`js
import { generator } from "ui7";

// generator uses a monotonic entropy source by default.
const uuid = generator();

const ids = [uuid(), uuid(), uuid()];
// [
// "01836da2-8a0d-7429-812d-f23f4d3d14c1",
// "01836da2-8a0d-742a-89a3-0442ac613d11",
// "01836da2-8a0d-742b-85e0-476f85ee36d9"
// ]

[...ids].sort().map(id => ids.indexOf(id))
// [ 0, 1, 2 ]
`

This uses the 12-bit rand_a field of UUIDv7 as a counter. For the first timestamp generated in a particular millisecond, the high bit is set to 0, so that there are always at least 2¹¹ (2,048) sequential counter values available before the field overflows (and wraps back to 0).

$3

Use the timestamp function to read the timestamp field of a UUIDv7:

`js
import { timestamp } from "ui7";

const when = timestamp("01836db9-3d80-7df2-9c5e-d66442a3cf21");
// 1663993200000

const date = new Date(when);
// 2022-09-24T04:20:00.000Z
`

If the input to timestamp is not a UUIDv7, it throws a ParseError exception.

$3

The default uuid function, the generator factory function, and the functions returned by generator all accept some options to customize their behavior.

#### Setting the time

You can pass a numeric timestamp, Date object, or custom clock function to a UUID generator or factory:

`js
import uuid from "ui7";

const id1 = uuid(0);
// "00000000-0000-7e2f-898b-a1f288a85661"

const id2 = uuid(new Date("2009-08-23T03:58:16.491Z"));
// "01234567-89ab-772e-9998-11f7395091b3"

const id3 = uuid(() => Date.now() * 2);
// "0306db58-42bc-722f-b2a5-4b13763cc462"

// Pass an object with a time property to combine with other options:
const id4 = uuid({ time: 1663993200000 });
// "01836db9-3d80-74a3-8b2a-8bf75bae40d5"
`

#### Controlling the format

You can omit dashes from the generated UUID’s, or use upper-case hex characters:

`js
import uuid from "ui7";

const id1 = uuid({ dashes: false });
// "01836db3b12d7f4e88c9fdc29019862e"

const id2 = uuid({ upper: true });
// "01836DB3-E2C7-7C84-8EB7-5CBE9205615B"

const id3 = uuid({ dashes: false, upper: true });
// "01836DB44DEF7836B69838F38A0A2A2A"
`

#### Using a different entropy source

By default, _ui7_ uses [crypto.getRandomValues][webcrypto] to populate the random part of the UUID (or [crypto.randomFillSync][fillsync] on Node.js versions that don't support Web-compatible crypto).

To instead set the "random" bits to either all 0 or all 1, pass a literal 0 or 0xff as the entropy option:

`js
import uuid from "ui7";

const id1 = uuid({ entropy: 0 });
// "018abdfe-4693-7000-8000-000000000000"

const id2 = uuid({ entropy: 0xff });
// "18abfe1-984b-7fff-bfff-ffffffffffff"
`

Full control is available by providing an entropy function, which must return a [Uint8Array][u8a] with the requested byteLength:

`js
import uuid from "ui7";

const id1 = uuid({ entropy: (n) => new Uint8Array(n) });
// "01836db8-4831-7000-8000-000000000000"

const id2 = uuid({ entropy: (n) => new Uint8Array(n).map((_, i) => i) })
// "01836dbb-bd3d-7001-8203-040506070809"

// The entropy function receives the timestamp of the ID being generated:
const id4 = uuid({
entropy(n, time) {
const b = new Uint8Array(n);
new DataView(b.buffer).setBigUint64(0, BigInt(time));
return b;
}
});
// "01836dbd-448c-7000-8183-6dbd448c0000"
`

Note that the default implementation avoids making a getRandomValues call every time entropy() is called; it makes larger, less infrequent reads to improve performance when many UUID's are being generated.

[webcrypto]: https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues
[fillsync]: https://nodejs.org/api/crypto.html#cryptorandomfillsyncbuffer-offset-size
[u8a]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array

#### Creating a preset

In addition to providing options to the default generator, you can pass them to the generator factory function, which will return a generator that uses those options as its defaults:

`ts
import { generator } from "ui7";

const uuid = generator({
time: () => Math.trunc(Date.now() / 1000),
entropy: 0xff,
upper: true,
});

const id1 = uuid();
// "0000632F-3ACC-7FFF-BFFF-FFFFFFFFFFFF"

// Options can still be set for each individual ID:
const id2 = uuid({ dashes: false, time: 0 }):
// "0000000000007FFFBFFFFFFFFFFFFFFF"
`

$3

_ui7_ is written in TypeScript and ships with type definitions.

Should I use this?

UUID’s are currently defined by [RFC 4122][] (2005), which specifies three UUID versions in common use: 1, 4, and 5. The “UUIDv7” identifiers generated by this package conform to [a proposed update][ietf tracker] to that standard, but as of this writing (September 2023) it has not yet obsoleted the 2005 edition.

UUIDv7 – a sortable UUID containing a UNIX timestamp – was first proposed in the second draft from April 2021. Originally, UUIDv7 held a variable-precision timestamp, but this was simplified to millisecond precision only in the fourth draft from March 2022. This implementation originally targeted a [June 2022][dcl] draft.

There are advantages to the UUIDv7 format: they encode a timestamp, while still being collision-resistant with up to 74 bits of entropy per UUID. Their natural sortability by putting the timestamp field first is convenient for display and efficient for insertion into the [B-tree][] structures that underlie many databases. And they're still UUID's, and can be used directly in (e.g.) a Postgres uuid` column without conversion.

But you might reasonably decide to say “no” or “not yet” to UUIDv7 until it is specified in an accepted RFC, or to use a different unique identifier format like [ULID][].

$3

_ui7_ is a compact, zero-dependency implementation of UUIDv7, using a cryptographic PRNG provided by its host environment. It is one of the simplest, but neither the fastest nor the slowest implementation; [a few others][others] can be found on NPM.

[ietf tracker]: https://datatracker.ietf.org/doc/draft-ietf-uuidrev-rfc4122bis/
[dcl]: https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#section-3.1-2
[B-tree]: https://www.cs.cornell.edu/courses/cs3110/2012sp/recitations/rec25-B-trees/rec25.html
[ULID]: https://github.com/ulid/spec#readme
[others]: https://www.npmjs.com/search?q=uuidv7