@cqrs-ddd/uuidv7 0.4.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -85
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,9 +4,7 @@ Generates and validates UUID version 7 identifiers as defined by
|
|
|
4
4
|
[RFC 9562](https://www.rfc-editor.org/rfc/rfc9562). It has no runtime dependencies and
|
|
5
5
|
no framework: it uses Node's built-in `crypto.randomBytes()` only.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
different milliseconds sort by creation time as plain strings. That makes them a good
|
|
9
|
-
fit for database primary keys, event identifiers and correlation IDs.
|
|
7
|
+
**Documentation:** [guide](https://aristoteliss.github.io/nestjs-pipeline/packages/cqrs-ddd/uuidv7/) · [API reference](https://aristoteliss.github.io/nestjs-pipeline/api/cqrs-ddd/uuidv7/) · [all packages](https://aristoteliss.github.io/nestjs-pipeline/)
|
|
10
8
|
|
|
11
9
|
## Installation
|
|
12
10
|
|
|
@@ -18,88 +16,7 @@ pnpm add @cqrs-ddd/uuidv7
|
|
|
18
16
|
|
|
19
17
|
Requires Node.js 22.12 or later.
|
|
20
18
|
|
|
21
|
-
Published as an ES module; a CommonJS application loads it with `require()`. Coming from
|
|
22
|
-
0.3.x, see [Upgrading from 0.3.x](https://github.com/aristoteliss/nestjs-pipeline#upgrading-from-03x).
|
|
23
|
-
|
|
24
|
-
## API
|
|
25
|
-
|
|
26
|
-
```typescript
|
|
27
|
-
import { isUuidV7, uuidv7 } from '@cqrs-ddd/uuidv7';
|
|
28
|
-
|
|
29
|
-
const id = uuidv7(); // e.g. '01923456-789a-7c3d-9e4f-0123456789ab'
|
|
30
|
-
|
|
31
|
-
isUuidV7(id); // true
|
|
32
|
-
isUuidV7(` ${id}\n`); // true: surrounding whitespace is ignored
|
|
33
|
-
isUuidV7('00000000-0000-4000-8000-000000000000'); // false: version 4
|
|
34
|
-
isUuidV7(42); // false
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
| Export | Signature | Description |
|
|
38
|
-
| --- | --- | --- |
|
|
39
|
-
| `uuidv7` | `() => string` | A new UUIDv7 in the canonical lowercase 8-4-4-4-12 form |
|
|
40
|
-
| `isUuidV7` | `(value: unknown) => value is string` | `true` for a string that is a UUIDv7 once trimmed, in either case |
|
|
41
|
-
|
|
42
|
-
## Format guarantees
|
|
43
|
-
|
|
44
|
-
Each identifier is 128 bits, written as 36 lowercase hexadecimal characters and hyphens:
|
|
45
|
-
|
|
46
|
-
| Bits | Field | Content |
|
|
47
|
-
| --- | --- | --- |
|
|
48
|
-
| 0–47 | `unix_ts_ms` | `Date.now()`, the Unix time in milliseconds |
|
|
49
|
-
| 48–51 | `ver` | `0111` (version 7) |
|
|
50
|
-
| 52–63 | `rand_a` | cryptographically random |
|
|
51
|
-
| 64–65 | `var` | `10` (the RFC 9562 variant) |
|
|
52
|
-
| 66–127 | `rand_b` | cryptographically random |
|
|
53
|
-
|
|
54
|
-
- Identifiers from different milliseconds sort by creation time when compared as strings.
|
|
55
|
-
- Identifiers from the same millisecond differ only in their random bits, so their order
|
|
56
|
-
is random: this implementation does not add a monotonic counter.
|
|
57
|
-
- The timestamp comes from the system clock. If the clock moves backwards, later
|
|
58
|
-
identifiers sort before earlier ones.
|
|
59
|
-
- `isUuidV7` checks the textual form, the version and the variant. It does not check that
|
|
60
|
-
the timestamp is plausible.
|
|
61
|
-
|
|
62
|
-
## Examples
|
|
63
|
-
|
|
64
|
-
Validate an incoming identifier before using it, and generate one otherwise:
|
|
65
|
-
|
|
66
|
-
```typescript
|
|
67
|
-
import { isUuidV7, uuidv7 } from '@cqrs-ddd/uuidv7';
|
|
68
|
-
|
|
69
|
-
function requestId(header: string | undefined): string {
|
|
70
|
-
return isUuidV7(header) ? header.trim().toLowerCase() : uuidv7();
|
|
71
|
-
}
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
`isUuidV7` accepts surrounding whitespace and uppercase, so normalize an accepted value
|
|
75
|
-
before storing it if you compare identifiers as strings.
|
|
76
|
-
|
|
77
|
-
Read the creation time back from the first 48 bits:
|
|
78
|
-
|
|
79
|
-
```typescript
|
|
80
|
-
import { uuidv7 } from '@cqrs-ddd/uuidv7';
|
|
81
|
-
|
|
82
|
-
const id = uuidv7();
|
|
83
|
-
const createdAt = new Date(Number.parseInt(id.replace(/-/g, '').slice(0, 12), 16));
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
## Migrating from @nestjs-pipeline/core 0.1.x
|
|
87
|
-
|
|
88
|
-
`uuidv7` and `isUuidV7` were exported by `@nestjs-pipeline/core` 0.1.x, and `uuidv7`
|
|
89
|
-
also by `@nestjs-pipeline/correlation` 0.1.x. Neither package exports them in 0.2.0.
|
|
90
|
-
|
|
91
|
-
```typescript
|
|
92
|
-
// Before (0.1.x)
|
|
93
|
-
import { isUuidV7, uuidv7 } from '@nestjs-pipeline/core';
|
|
94
|
-
import { uuidv7 } from '@nestjs-pipeline/correlation';
|
|
95
|
-
|
|
96
|
-
// After (0.2.0)
|
|
97
|
-
import { isUuidV7, uuidv7 } from '@cqrs-ddd/uuidv7';
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
The signatures and the output format are unchanged. Add `@cqrs-ddd/uuidv7` to your own
|
|
101
|
-
`dependencies`: it is a dependency of the pipeline packages, not a re-export.
|
|
102
|
-
|
|
19
|
+
Published as an ES module; a CommonJS application loads it with `require()`. Coming from 0.3.x, see [Upgrading from 0.3.x](https://aristoteliss.github.io/nestjs-pipeline/upgrading/from-0-3/).
|
|
103
20
|
|
|
104
21
|
## License
|
|
105
22
|
|
package/package.json
CHANGED