https://github.com/coolaj86/uuidv7
UUIDv7, written in Zig (and Go, and JS, and Swift - just for good measure, of course)
https://github.com/coolaj86/uuidv7
go golang javascript swift uuid uuid-generator uuidv7 zig ziglang
Last synced: 12 months ago
JSON representation
UUIDv7, written in Zig (and Go, and JS, and Swift - just for good measure, of course)
- Host: GitHub
- URL: https://github.com/coolaj86/uuidv7
- Owner: coolaj86
- License: other
- Created: 2024-09-21T06:58:19.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-10T04:10:23.000Z (over 1 year ago)
- Last Synced: 2025-03-24T16:28:41.022Z (about 1 year ago)
- Topics: go, golang, javascript, swift, uuid, uuid-generator, uuidv7, zig, ziglang
- Language: JavaScript
- Homepage:
- Size: 57.6 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [uuidv7](https://github.com/coolaj86/uuidv7)
Generate UUID v7 strings, like `019212d3-87f4-7d25-902e-b8d39fe07f08`.
```sh
uuidv7 > uuidv7.txt
```
```text
019212d3-87f4-7d25-902e-b8d39fe07f08
```
| 32-bit time | 16-bit time | 4 ver + 12 rnd | 2 var + 14 rnd | 16 rnd + 32 rnd |
| :------------------------: | :---------: | :------------: | :------------: | :----------------------------------------: |
| 01 92 12 d3 | 87 f4 | 7d 25 | 90 2e | b8 d3 9f e0 7f 08 |
# Table of Contents
- [Install](#install)
- [In JavaScript](#javascript-version)
- [UUIDv7 Spec](#uuidv7-spec)
- [By the Characters](#by-the-characters)
- [By the Bits](#by-the-bits)
- [Build](#build)
- [Go Build (and TinyGo)](#go)
- [Swift](#swift)
- [Zig Build](#zig)
- [License](#license)
# Install
Pre-built archives available for Mac, Linux, & Widows. \
Compile from source for FreeBSD, OpenBSD, etc.
1. Download from GitHub Releases:
2. Extract
3. Place in your `PATH`
```sh
b_triplet='x86_64-linux-musl'
curl -L -O https://github.com/coolaj86/uuidv7/releases/download/v1.0.0/uuidv7-v1.0.0-"$b_triplet".tar.gz
tar xvf ./uuidv7-v1.0.0-"$b_triplet".tar.gz
mv ./uuidv7 ~/bin/
```
# JavaScript Version
Supports both `import` and `require`.
Extremely simple implementation that can be tuned for speed or memory
efficiency.
```sh
npm install --save @root/uuidv7
```
High-level API:
```js
import UUIDv7 from "@root/uuidv7";
UUIDv7.uuidv7();
// 01922aa4-88ad-7cae-a517-a298a491d35c
UUIDv7.uuidv7Bytes();
// Uint8Array(16) [ 1, 146, 42, 176, 37, 122, 114, 189
// 172, 240, 1, 146, 42, 176, 37, 122 ]
```
Low-level API:
```js
let buffer = new Uint8Array(4096); // optional, if you need lots of UUIDs, and fast
UUIDv7.setBytesBuffer(buffer);
```
```js
let now = Date.now();
let ms64 = BigInt(now);
let bytes = new Uint8Array(16);
let start = 0;
globalThis.crypto.getRandomValues(bytes);
void UUIDv7.fill(bytes, start, ms64);
console.log(bytes);
// Uint8Array(16) [ 1, 146, 42, 176, 37, 122, 114, 189
// 172, 240, 1, 146, 42, 176, 37, 122 ]
```
```js
let uuidv7 = UUIDv7.format(bytes);
console.log(uuidv7);
// 01922aa4-88ad-7cae-a517-a298a491d35c
```
# UUIDv7 Spec
## By the Characters
There are 36 characters total: 32 hex (`0123456789abcdef`) + 4 dashes (`-`)
```text
8 time 4 time 1v + 3ra ½v + 3½rb 12 random b
019212d3 - 87f4 - 7d25 - 902e - b8d39fe07f08
```
- 8ch hex time high
- `-`
- 4ch hex time low
- `-`
- 4ch hex version + "random a"
- 1ch hex version: `7`
- 3ch hex "random a"
- `-`
- 4ch hex variant + "random b"
- 1ch hex version: `8`, `9`, `a`, `b`
- 3ch hex "random b"
- `-`
- 12ch hex randam a
- 4ch hex random a
- 8ch hex random a
## By the Bits
There are 128 bits total: \
48 time and 80 random, with 4 version and 2 variant bits substituted
```text
48 time 4ver, 12ra 2var, 14rb random b
019212d3-87f4 - 7d25 - 902e - b8d39fe07f08
```
- 48 bits of timestamp
- 32-bit high (minutes to years)
- 16-bit low (seconds & milliseconds)
- 16 bits of version + random
- 4-bit version (`0b0111`)
- 12-bit random
- 64-bits variant + random
- 2-bit variant (`0b10`)
- 62-bit random
# Build
## Go
```sh
curl https://webi.sh/go | sh
source ~/.config/envman/PATH.env
```
For the current platform:
```sh
go build -o uuidv7 ./cmd/.
```
For Linux containers:
```sh
GOOS=linux GOARCH=amd64 GOAMD64=v2 go build -o uuidv7 ./cmd/.
```
The entire build matrix (into `./dist/`):
```sh
goreleaser --snapshot --skip=publish --clean
```
### TinyGo
```sh
curl https://webi.sh/go | sh
source ~/.config/envman/PATH.env
```
```sh
tinygo build -o uuidv7 ./cmd/.
```
```sh
GOOS=linux GOARCH=amd64 GOAMD64=v2 tinygo build -o uuidv7 ./cmd/.
```
## Swift
```sh
swift build --configuration release --show-bin-path
./.build/arm64-apple-macosx/release/uuidv7
```
## Zig
See .
Builds with zig v0.13 and the v0.14 previews so far.
```sh
curl https://webi.sh/zig@0.13 | sh
source ~/.config/envman/PATH.env
```
```sh
zig build-exe ./uuidv7.zig -O ReleaseSmall -femit-bin="uuidv7"
for b_target in x86-linux-musl aarch64-macos-none x86_64-windows-gnu; do
zig build-exe ./uuidv7.zig -O ReleaseSmall \
-target "${b_target}" -femit-bin="uuidv7-${b_target}"
done
```
# License
Copyright 2024 AJ ONeal
This Source Code Form is subject to the terms of the Mozilla Public \
License, v. 2.0. If a copy of the MPL was not distributed with this \
file, You can obtain one at https://mozilla.org/MPL/2.0/.