Refactoring, restructuring, new tests, sequential guids

Author: sdrapkin

README.md

@@ -35,7 +35,7 @@ gxOQRIVR4B_uGHD6OP76XA
 Zo_hpnDxkOsAWLk1tIS6DA
 ```
 ---
-## Guid is ~10x faster than `github.com/google/uuid`
+## Guid is ~10x faster than `github.com/google/uuid` 🔥
 
 * `guid.New()` is  6~10 ns 
 * `guid.NewString()` is 40~60 ns
@@ -47,14 +47,78 @@ Zo_hpnDxkOsAWLk1tIS6DA
 | Function | Description |
 |---|---|
 | `guid.New()`         | Generate a new Guid |
-| `guid.NewString()`   | Generate a new Guid as Base64Url string |
+| `guid.NewString()`   | Generate a new Guid as q Base64Url string |
 | `guid.Parse(s)`      | Parse Base64Url string to Guid |
 | `guid.ParseBytes(b)` | Parse Base64Url bytes to Guid |
 | `guid.FromBytes(b)`  | Parse 16-byte slice to Guid |
-| `guid.Read()` 🔥       | Faster alternative to `crypto/rand` |
+| `guid.Read()` 🔥     | Faster alternative to `crypto/rand` |
 | `guid.Nil`           | The zero-value Guid |
 
-## Benchmarks
+## Sequential Guids 🔥
+`guid` includes two special types `GuidPG` and `GuidSS` optimized for use as database primary keys (PostgreSQL and SQL Server). Their time-ordered composition helps prevent index fragmentation and improves `INSERT` performance compared to fully random Guids. Note that sequential sorting is only across `time.Now()` timestamp presision.
+
+* **`guid.NewPG()`**: Generates a `GuidPG`, which is sortable in **PostgreSQL**. It is structured as `[8-byte timestamp][8 random bytes]`.
+* **`guid.NewSS()`**: Generates a `GuidSS`, which is sortable in **SQL Server**. It is structured as `[8 random bytes][8-byte SQL Server-ordered timestamp]`.
+* `.Timestamp()` on `GuidPG`/`GuidSS` returns Guid creation time as UTC `time.Time`.
+
+Both `GuidPG` and `GuidSS` are nearly as fast as `guid.New()`. They can be used as a standard `Guid` and support the same interfaces.
+
+***
+
+### Sequential Guid Example:
+
+```go
+fmt.Printf("%s\t       %s\t\t\t\t%s\t       %s\n",
+	"gpg.String()", "hex(gpg)", "gss.String()", "hex(gss)")
+for range 10 {
+	gpg := guid.NewPG()
+	gss := guid.NewSS()
+	fmt.Println(&gpg, hex.EncodeToString(gpg.Guid[:]), &gss, hex.EncodeToString(gss.Guid[:]))
+}
+
+gpg := guid.NewPG()
+gss := guid.NewSS()
+fmt.Println(gpg.Timestamp()) // time.Time
+fmt.Println(gss.Timestamp()) // time.Time
+```
+```
+gpg.String()           hex(gpg)                         gss.String()           hex(gss)
+GFEU88wgQvDlahOowSGTKA 185114f3cc2042f0e56a13a8c1219328 9SurLKL6ti2l0BhRFPPMKA f52bab2ca2fab62da5d0185114f3cc28
+GFEU88wopdChlFba89-4yg 185114f3cc28a5d0a19456daf3dfb8ca yTRE6Rr1gISl0BhRFPPMKA c93444e91af58084a5d0185114f3cc28
+GFEU88ww9fA01GntVDQ_4w 185114f3cc30f5f034d469ed54343fe3 8SaILyee6q718BhRFPPMMA f126882f279eeaaef5f0185114f3cc30
+GFEU88ww9fASNFzZQJpv7Q 185114f3cc30f5f012345cd9409a6fed xZ3KYLzqJ0f18BhRFPPMMA c59dca60bcea2747f5f0185114f3cc30
+GFEU88ww9fAHgWvjAmkQJw 185114f3cc30f5f007816be302691027 yEif2kTQBcD18BhRFPPMMA c8489fda44d005c0f5f0185114f3cc30
+GFEU88ww9fD4_Vm3PG5Vuw 185114f3cc30f5f0f8fd59b73c6e55bb SRKgSiCc-gL18BhRFPPMMA 4912a04a209cfa02f5f0185114f3cc30
+GFEU88ww9fDzO_One7T6BA 185114f3cc30f5f0f33bf3a77bb4fa04 rGr2czgQcmr18BhRFPPMMA ac6af6733810726af5f0185114f3cc30
+GFEU88w5PqQAifEi5tqoWQ 185114f3cc393ea40089f122e6daa859 5YYbiI3p7P4-pBhRFPPMOQ e5861b888de9ecfe3ea4185114f3cc39
+GFEU88w5PqSFkX4bmxSvMQ 185114f3cc393ea485917e1b9b14af31 PqUPeiyessU-pBhRFPPMOQ 3ea50f7a2c9eb2c53ea4185114f3cc39
+GFEU88w5PqTsYX0kcZzL6Q 185114f3cc393ea4ec617d24719ccbe9 yFIlRwKZJNo-pBhRFPPMOQ c8522547029924da3ea4185114f3cc39
+2025-07-11 03:32:47.3597457 +0000 UTC
+2025-07-11 03:32:47.3597457 +0000 UTC
+```
+
+## Interoperability with `google/uuid` 🔥
+* If you must keep using `google/uuid`, use `guid` to increase performance by **2~4x**:
+```go
+// do this before using google/uuid
+uuid.SetRand(guid.Reader);
+```
+
+## uuid Benchmarks with and without `guid.Reader`
+
+| Benchmark Name | Time per Op | Bytes per Op  | Allocs per Op  |
+|---|---|---|---|
+| Benchmark_uuid_New_x10-8                                   | 3031 ns/op  | 160 B/op      | 10 allocs/op   |
+| Benchmark_uuid_New_**guidRand**_x10-8 🔥                   | 862.0 ns/op | 160 B/op      | 10 allocs/op   |
+| Benchmark_uuid_New_RandPool_x10-8                          | 747.6 ns/op | 0 B/op        | 0 allocs/op    |
+| Benchmark_uuid_New_RandPool_**guidRand**_x10-8 🔥          | 516.8 ns/op | 0 B/op        | 0 allocs/op    |
+| Benchmark_uuid_New_Parallel_x10-8                          | 1230 ns/op  | 160 B/op      | 10 allocs/op   |
+| Benchmark_uuid_New_Parallel_**guidRand**_x10-8 🔥          | 510.0 ns/op | 160 B/op      | 10 allocs/op   |
+| Benchmark_uuid_New_Parallel_RandPool_x10-8                 | 1430 ns/op  | 0 B/op        | 0 allocs/op    |
+| Benchmark_uuid_New_Parallel_RandPool_**guidRand**_x10-8 🔥 | 1185 ns/op  | 0 B/op        | 0 allocs/op    |
+
+
+## Guid Benchmarks
 ```
 go test -bench=.* -benchtime=4s
 goos: windows
@@ -67,7 +131,7 @@ cpu: Intel(R) Core(TM) i7-10510U CPU @ 1.80GHz
 | guid_New_x10-8                          |  203.4 ns/op  |   0 B/op |  0 allocs/op | |
 | guid_NewString_x10-8                    |  582.4 ns/op  | 240 B/op | 10 allocs/op | |
 | guid_String_x10-8                       |  388.9 ns/op  | 240 B/op | 10 allocs/op | |
-| guid_New_Parallel_x10-8                 |  62.45 ns/op  |   0 B/op |  0 allocs/op | |
+| guid_New_Parallel_x10-8 🔥               |  62.45 ns/op  |   0 B/op |  0 allocs/op | |
 | guid_NewString_Parallel_x10-8           |  374.2 ns/op  | 240 B/op | 10 allocs/op | |
 
 ### Alternative library benchmarks:

go.mod

@@ -1,3 +1,5 @@
 module github.com/sdrapkin/guid
 
 go 1.24
+
+require golang.org/x/sys v0.34.0

go.sum

@@ -0,0 +1,2 @@
+golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA=
+golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=

guid.go

@@ -9,8 +9,12 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"math/bits"
 	"sync"
+	"time"
 	"unsafe"
+
+	"golang.org/x/sys/cpu"
 )
 
 //==============================================
@@ -45,6 +49,8 @@ var (
 	ErrInvalidBase64UrlGuidEncoding = errors.New("invalid Base64Url Guid encoding (invalid characters, or length != 22)")
 	// ErrInvalidGuidSlice is returned when a byte slice cannot represent a valid Guid (length < 16 bytes).
 	ErrInvalidGuidSlice = errors.New("invalid Guid slice (length < 16 bytes)")
+	// ErrBufferTooSmallBase64Url is returned when a destination slice is too small to receive the text-encoded Guid.
+	ErrBufferTooSmallBase64Url = fmt.Errorf("buffer is too small (length < %d bytes)", GuidBase64UrlByteSize)
 )
 
 //==============================================
@@ -66,6 +72,19 @@ var (
 
 // Guid is a 16-byte (128-bit) cryptographically random value.
 type Guid [GuidByteSize]byte
+
+// GuidPG is a 16-byte (128-bit) PostgreSQL sortable Guid formed as [8-byte time.Now() timestamp][8 random bytes]
+// GuidPG is optimized for use as a PostgreSQL index key.
+type GuidPG struct {
+	Guid // embedded
+}
+
+// GuidSS is a 16-byte (128-bit) SQL Server sortable Guid formed as [8 random bytes][8 bytes of SQL Server ordered time.Now() timestamp]
+// GuidSS is optimized for use as a SQL Server index or clustered key.
+type GuidSS struct {
+	Guid // embedded
+}
+
 type reader struct{}
 
 //==============================================
@@ -74,9 +93,9 @@ type reader struct{}
 
 // guidCache holds a 4096-byte buffer and a byte index for Guid allocation.
 type guidCache struct {
-	buffer [guidCacheByteSize]byte
+	buffer []byte //buffer [guidCacheByteSize]byte
 	index  uint8
-	_      [63]byte // pad ensures each index is on its own cache line
+	_      [32]byte // pad ensures each index is on its own cache line
 
 }
 
@@ -109,7 +128,7 @@ func (guid *Guid) UnmarshalText(data []byte) error {
 // MarshalText implements encoding.TextMarshaler.
 func (guid *Guid) MarshalText() ([]byte, error) {
 	buffer := make([]byte, GuidBase64UrlByteSize)
-	guid.EncodeBase64URL(buffer)
+	guid.encodeBase64URL(buffer)
 	return buffer, nil
 }
 
@@ -158,7 +177,16 @@ func (guid *Guid) String() string {
 }
 
 // EncodeBase64URL encodes the Guid into the provided dst as Base64Url.
-func (guid *Guid) EncodeBase64URL(dst []byte) {
+func (guid *Guid) EncodeBase64URL(dst []byte) error {
+	if len(dst) < GuidBase64UrlByteSize {
+		return ErrBufferTooSmallBase64Url
+	}
+	guid.encodeBase64URL(dst)
+	return nil
+}
+
+// private - panics on undersized buffer
+func (guid *Guid) encodeBase64URL(dst []byte) {
 	const lengthMod3 = 1                    // 16 % 3 = 1
 	const limit = GuidByteSize - lengthMod3 // 15 bytes can be processed in groups of 3 bytes, leaving 1 byte at the end.
 
@@ -190,7 +218,7 @@ func (guid *Guid) EncodeBase64URL(dst []byte) {
 // It always fills b entirely, and returns len(b) and nil error.
 // guid.Read() is up to 7x faster than crypto/rand.Read() for small slices.
 // if b is > 512 bytes, it simply calls crypto/rand.Read().
-func (r *reader) Read(b []byte) (n int, err error) {
+func (r reader) Read(b []byte) (n int, err error) {
 	const MaxBytesToFillViaGuids = 512
 	n = len(b)
 
@@ -206,7 +234,7 @@ func (r *reader) Read(b []byte) (n int, err error) {
 
 	if guidCacheRef.index == 0 {
 		// Refill buffer if index wraps (Go 1.24+: cryptoRand.Read is guaranteed to succeed)
-		cryptoRand.Read(guidCacheRef.buffer[:])
+		cryptoRand.Read(guidCacheRef.buffer)
 	}
 
 	n1 := copy(b, guidCacheRef.buffer[int(guidCacheRef.index)*GuidByteSize:])
@@ -219,8 +247,8 @@ func (r *reader) Read(b []byte) (n int, err error) {
 	}
 
 	// Case 2: Need to refill for remainder
-	cryptoRand.Read(guidCacheRef.buffer[:])
-	n2 := copy(b[n1:], guidCacheRef.buffer[:])
+	cryptoRand.Read(guidCacheRef.buffer)
+	n2 := copy(b[n1:], guidCacheRef.buffer)
 
 	if n1+n2 != n {
 		panic("guid: internal panic in reader.Read(); should never happen")
@@ -230,6 +258,35 @@ func (r *reader) Read(b []byte) (n int, err error) {
 	return
 } //func (r *reader) Read
 
+//==============================================
+// GuidPG Extension Methods
+//==============================================
+
+// Timestamp extracts the timestamp from the PostgreSQL Guid.
+// The timestamp is stored in the first 8 bytes as nanoseconds since Unix epoch.
+// Returns the time.Time representation of when the Guid was created.
+func (g *GuidPG) Timestamp() time.Time {
+	timestamp := *(*int64)(unsafe.Pointer(&g.Guid[0])) // Extract timestamp from first 8 bytes
+
+	if !cpu.IsBigEndian {
+		timestamp = int64(bits.ReverseBytes64(uint64(timestamp)))
+	}
+	return time.Unix(0, timestamp).UTC()
+}
+
+//==============================================
+// GuidSS Extension Methods
+//==============================================
+
+// Timestamp extracts the timestamp from the SQL Server Guid.
+// The timestamp is stored in the last 8 bytes using SQL Server's Guid ordering rules.
+// Returns the time.Time representation of when the Guid was created.
+func (g *GuidSS) Timestamp() time.Time {
+	encoded := *(*uint64)(unsafe.Pointer(&g.Guid[8])) // Extract timestamp from last 8 bytes (SQL Server format)
+	timestamp := int64(bits.RotateLeft64(bits.ReverseBytes64(encoded), 16))
+	return time.Unix(0, timestamp).UTC()
+}
+
 //==============================================
 // Standalone Functions
 //==============================================
@@ -240,7 +297,7 @@ func New() (g Guid) {
 
 	if guidCacheRef.index == 0 {
 		// Refill buffer if index wraps (Go 1.24+: cryptoRand.Read is guaranteed to succeed)
-		cryptoRand.Read(guidCacheRef.buffer[:])
+		cryptoRand.Read(guidCacheRef.buffer)
 	}
 
 	// Extract GUID at current index
@@ -252,6 +309,34 @@ func New() (g Guid) {
 	return
 }
 
+// NewPG generates a new PostgreSQL sortable Guid as [8-byte time.Now() timestamp][8 random bytes]
+func NewPG() GuidPG {
+	return newPG(time.Now().UnixNano())
+}
+
+func newPG(ts int64) (gpg GuidPG) {
+	gpg.Guid = New()
+	if !cpu.IsBigEndian {
+		ts = int64(bits.ReverseBytes64(uint64(ts)))
+	}
+	*(*uint64)(unsafe.Pointer(&gpg.Guid[0])) = uint64(ts)
+	return
+}
+
+// NewSS generates a new SQL Server sortable Guid as [8 random bytes][8 bytes of SQL Server ordered time.Now() timestamp]
+func NewSS() GuidSS {
+	return newSS(time.Now().UnixNano())
+}
+
+func newSS(ts int64) (gss GuidSS) {
+	// based on Microsoft SqlGuid.cs
+	// https://github.com/microsoft/referencesource/blob/5697c29004a34d80acdaf5742d7e699022c64ecd/System.Data/System/Data/SQLTypes/SQLGuid.cs
+	gss.Guid = New()
+	// we don't worry about big-endian, because SQL Server does not run on big-endian
+	*(*uint64)(unsafe.Pointer(&gss.Guid[8])) = bits.ReverseBytes64(bits.RotateLeft64(uint64(ts), -16))
+	return
+}
+
 // NewString generates a new cryptographically secure Guid, and returns it as a Base64Url string.
 // NewString is equivalent to "g := guid.New(); return g.String();".
 func NewString() string {
@@ -357,7 +442,7 @@ func Read(b []byte) (n int, err error) {
 // guidCachePool is a sync.Pool that holds guidCache instances.
 var guidCachePool = sync.Pool{
 	New: func() any {
-		return &guidCache{}
+		return &guidCache{buffer: make([]byte, guidCacheByteSize)}
 	},
 }