feat(generate): Added UUID V7 generator (#260)

Author: ekkinox

generate/README.md

@@ -9,11 +9,10 @@
 > Generation module based on [Google UUID](https://github.com/google/uuid).
 
 <!-- TOC -->
-
 * [Installation](#installation)
 * [Documentation](#documentation)
-	* [UUID](#uuid)
-
+  * [UUID V4](#uuid-v4)
+  * [UUID V7](#uuid-v7)
 <!-- TOC -->
 
 ## Installation
@@ -24,11 +23,11 @@ go get github.com/ankorstore/yokai/generate
 
 ## Documentation
 
-### UUID
+### UUID V4
 
-This module provides an [UuidGenerator](uuid/generator.go) interface, allowing to generate UUIDs.
+This module provides an [UuidGenerator](uuid/generator.go) interface, allowing to generate UUIDs V4.
 
-The `DefaultUuidGenerator` is based on [Google UUID](https://github.com/google/uuid).
+The `DefaultUuidGenerator` implementing it is based on [Google UUID](https://github.com/google/uuid).
 
 ```go
 package main
@@ -70,4 +69,55 @@ func main() {
 	generator := uuid.NewDefaultUuidGeneratorFactory().Create()
 	fmt.Printf("uuid: %s", generator.Generate()) // uuid: dcb5d8b3-4517-4957-a42c-604d11758561
 }
+```
+
+### UUID V7
+
+This module provides an [UuidV7Generator](uuidv7/generator.go) interface, allowing to generate UUIDs V7.
+
+The `DefaultUuidV7Generator` implementing it  is based on [Google UUID](https://github.com/google/uuid).
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/ankorstore/yokai/generate/uuidv7"
+	uuidv7test "github.com/ankorstore/yokai/generate/generatetest/uuidv7"
+)
+
+func main() {
+	// default UUID V7 generator
+	generator := uuidv7.NewDefaultUuidV7Generator()
+	uuid, _ := generator.Generate()
+	fmt.Printf("uuid: %s", uuid.String()) // uuid: 018fdd68-1b41-7eb0-afad-57f45297c7c1
+
+	// test UUID generator (with deterministic value for testing, requires valid UUID v7)
+	testGenerator, _ := uuidv7test.NewTestUuidV7Generator("018fdd7d-1576-7a21-900e-1399637bd1a1")
+    uuid, _ = testGenerator.Generate()
+	fmt.Printf("uuid: %s", uuid.String()) // uuid: 018fdd7d-1576-7a21-900e-1399637bd1a1
+}
+```
+
+The module also provides a [UuidV7GeneratorFactory](uuidv7/factory.go) interface, to create
+the [UuidV7Generator](uuidv7/generator.go) instances.
+
+The `DefaultUuidV7GeneratorFactory` generates `DefaultUuidV7Generator` instances.
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/ankorstore/yokai/generate/uuidv7"
+)
+
+func main() {
+	// default UUID generator factory
+	generator := uuidv7.NewDefaultUuidV7GeneratorFactory().Create()
+	uuid, _ := generator.Generate()
+	fmt.Printf("uuid: %s", uuid.String()) // uuid: 018fdd68-1b41-7eb0-afad-57f45297c7c1
+}
 ```

generate/generatetest/uuidv7/generator.go

@@ -0,0 +1,39 @@
+package uuid
+
+import googleuuid "github.com/google/uuid"
+
+// TestUuidV7Generator is a [UuidV7Generator] implementation allowing deterministic generations (for testing).
+type TestUuidV7Generator struct {
+	value string
+}
+
+// NewTestUuidV7Generator returns a [TestUuidGenerator], implementing [UuidGenerator].
+//
+// It accepts a value that will be used for deterministic generation results.
+func NewTestUuidV7Generator(value string) (*TestUuidV7Generator, error) {
+	err := googleuuid.Validate(value)
+	if err != nil {
+		return nil, err
+	}
+
+	return &TestUuidV7Generator{
+		value: value,
+	}, nil
+}
+
+// SetValue sets the value to use for deterministic generations.
+func (g *TestUuidV7Generator) SetValue(value string) error {
+	err := googleuuid.Validate(value)
+	if err != nil {
+		return err
+	}
+
+	g.value = value
+
+	return nil
+}
+
+// Generate returns the configured deterministic value.
+func (g *TestUuidV7Generator) Generate() (googleuuid.UUID, error) {
+	return googleuuid.Parse(g.value)
+}

generate/generatetest/uuidv7/generator_test.go

@@ -0,0 +1,68 @@
+package uuid_test
+
+import (
+	"testing"
+
+	uuidv7test "github.com/ankorstore/yokai/generate/generatetest/uuidv7"
+	"github.com/ankorstore/yokai/generate/uuidv7"
+	"github.com/stretchr/testify/assert"
+)
+
+const (
+	uuid1 = "018fdd7d-1576-7a21-900e-1399637bd1a1"
+	uuid2 = "018fdd7d-1576-76ff-944b-39bd474b0ea9"
+	uuid3 = "018fdd7d-1576-7b53-a364-7b96dcc158c9"
+)
+
+func TestNewTestUuidV7Generator(t *testing.T) {
+	t.Parallel()
+
+	generator, err := uuidv7test.NewTestUuidV7Generator(uuid1)
+	assert.NoError(t, err)
+
+	assert.IsType(t, &uuidv7test.TestUuidV7Generator{}, generator)
+	assert.Implements(t, (*uuidv7.UuidV7Generator)(nil), generator)
+}
+
+func TestGenerateSuccess(t *testing.T) {
+	t.Parallel()
+
+	generator, err := uuidv7test.NewTestUuidV7Generator(uuid2)
+	assert.NoError(t, err)
+
+	value1, err := generator.Generate()
+	assert.NoError(t, err)
+
+	value2, err := generator.Generate()
+	assert.NoError(t, err)
+
+	assert.Equal(t, uuid2, value1.String())
+	assert.Equal(t, uuid2, value2.String())
+
+	err = generator.SetValue(uuid3)
+	assert.NoError(t, err)
+
+	value1, err = generator.Generate()
+	assert.NoError(t, err)
+
+	value2, err = generator.Generate()
+	assert.NoError(t, err)
+
+	assert.Equal(t, uuid3, value1.String())
+	assert.Equal(t, uuid3, value2.String())
+}
+
+func TestGenerateFailure(t *testing.T) {
+	t.Parallel()
+
+	_, err := uuidv7test.NewTestUuidV7Generator("invalid")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid UUID length: 7")
+
+	generator, err := uuidv7test.NewTestUuidV7Generator(uuid1)
+	assert.NoError(t, err)
+
+	err = generator.SetValue("invalid")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid UUID length: 7")
+}

generate/uuid/factory.go

@@ -9,7 +9,7 @@ type UuidGeneratorFactory interface {
 type DefaultUuidGeneratorFactory struct{}
 
 // NewDefaultUuidGeneratorFactory returns a [DefaultUuidGeneratorFactory], implementing [UuidGeneratorFactory].
-func NewDefaultUuidGeneratorFactory() UuidGeneratorFactory {
+func NewDefaultUuidGeneratorFactory() *DefaultUuidGeneratorFactory {
 	return &DefaultUuidGeneratorFactory{}
 }
 

generate/uuidv7/factory.go

@@ -0,0 +1,19 @@
+package uuidv7
+
+// UuidV7GeneratorFactory is the interface for [UuidV7Generator] factories.
+type UuidV7GeneratorFactory interface {
+	Create() UuidV7Generator
+}
+
+// DefaultUuidV7GeneratorFactory is the default [UuidV7GeneratorFactory] implementation.
+type DefaultUuidV7GeneratorFactory struct{}
+
+// NewDefaultUuidV7GeneratorFactory returns a [DefaultUuidV7GeneratorFactory], implementing [UuidV7GeneratorFactory].
+func NewDefaultUuidV7GeneratorFactory() UuidV7GeneratorFactory {
+	return &DefaultUuidV7GeneratorFactory{}
+}
+
+// Create returns a new [UuidV7Generator].
+func (g *DefaultUuidV7GeneratorFactory) Create() UuidV7Generator {
+	return NewDefaultUuidV7Generator()
+}

generate/uuidv7/factory_test.go

@@ -0,0 +1,43 @@
+package uuidv7_test
+
+import (
+	"testing"
+
+	"github.com/ankorstore/yokai/generate/uuidv7"
+	googleuuid "github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewDefaultUuidV7GeneratorFactory(t *testing.T) {
+	t.Parallel()
+
+	factory := uuidv7.NewDefaultUuidV7GeneratorFactory()
+
+	assert.IsType(t, &uuidv7.DefaultUuidV7GeneratorFactory{}, factory)
+	assert.Implements(t, (*uuidv7.UuidV7GeneratorFactory)(nil), factory)
+}
+
+func TestCreate(t *testing.T) {
+	t.Parallel()
+
+	generator := uuidv7.NewDefaultUuidV7GeneratorFactory().Create()
+
+	uuid1, err := generator.Generate()
+	assert.NoError(t, err)
+
+	uuid2, err := generator.Generate()
+	assert.NoError(t, err)
+
+	assert.NotEqual(t, uuid1, uuid2)
+
+	parsedValue1, err := googleuuid.Parse(uuid1.String())
+	assert.NoError(t, err)
+
+	parsedValue2, err := googleuuid.Parse(uuid2.String())
+	assert.NoError(t, err)
+
+	assert.NotEqual(t, parsedValue1.String(), parsedValue2.String())
+
+	assert.Equal(t, uuid1.String(), parsedValue1.String())
+	assert.Equal(t, uuid2.String(), parsedValue2.String())
+}

generate/uuidv7/generator.go

@@ -0,0 +1,23 @@
+package uuidv7
+
+import googleuuid "github.com/google/uuid"
+
+// UuidV7Generator is the interface for UUID v7 generators.
+type UuidV7Generator interface {
+	Generate() (googleuuid.UUID, error)
+}
+
+// DefaultUuidV7Generator is the default [UuidGenerator] implementation.
+type DefaultUuidV7Generator struct{}
+
+// NewDefaultUuidV7Generator returns a [DefaultUuidGenerator], implementing [UuidGenerator].
+func NewDefaultUuidV7Generator() *DefaultUuidV7Generator {
+	return &DefaultUuidV7Generator{}
+}
+
+// Generate returns a new UUID V7, using [Google UUID].
+//
+// [Google UUID]: https://github.com/google/uuid
+func (g *DefaultUuidV7Generator) Generate() (googleuuid.UUID, error) {
+	return googleuuid.NewV7()
+}

generate/uuidv7/generator_test.go

@@ -0,0 +1,43 @@
+package uuidv7_test
+
+import (
+	"testing"
+
+	"github.com/ankorstore/yokai/generate/uuidv7"
+	googleuuid "github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewDefaultUuidV7Generator(t *testing.T) {
+	t.Parallel()
+
+	generator := uuidv7.NewDefaultUuidV7Generator()
+
+	assert.IsType(t, &uuidv7.DefaultUuidV7Generator{}, generator)
+	assert.Implements(t, (*uuidv7.UuidV7Generator)(nil), generator)
+}
+
+func TestGenerate(t *testing.T) {
+	t.Parallel()
+
+	generator := uuidv7.NewDefaultUuidV7Generator()
+
+	uuid1, err := generator.Generate()
+	assert.NoError(t, err)
+
+	uuid2, err := generator.Generate()
+	assert.NoError(t, err)
+
+	assert.NotEqual(t, uuid1.String(), uuid2.String())
+
+	parsedUuid1, err := googleuuid.Parse(uuid1.String())
+	assert.NoError(t, err)
+
+	parsedUuid2, err := googleuuid.Parse(uuid2.String())
+	assert.NoError(t, err)
+
+	assert.NotEqual(t, parsedUuid1.String(), parsedUuid2.String())
+
+	assert.Equal(t, uuid1.String(), parsedUuid1.String())
+	assert.Equal(t, uuid2.String(), parsedUuid2.String())
+}