feat(fxgenerate): Provided module

ankorstore · Jan 11, 2024 · 619a24d · 619a24d
1 parent 95f6600
commit 619a24d
Show file tree

Hide file tree

Showing 13 changed files with 490 additions and 6 deletions.
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -30,6 +30,7 @@ jobs:
         - "orm"
         - "trace"
         - "fxconfig"
+        - "fxgenerate"
     steps:
       - name: Checkout
         uses: actions/checkout@v3

diff --git a/.github/workflows/fxgenerate-ci.yml b/.github/workflows/fxgenerate-ci.yml
@@ -0,0 +1,31 @@
+name: "fxgenerate-ci"
+
+on:
+    push:
+        branches:
+            - "feat**"
+            - "fix**"
+            - "hotfix**"
+            - "chore**"
+        paths:
+            - "fxgenerate/**.go"
+            - "fxgenerate/go.mod"
+            - "fxgenerate/go.sum"
+    pull_request:
+        types:
+            - opened
+            - synchronize
+            - reopened
+        branches:
+            - main
+        paths:
+            - "fxgenerate/**.go"
+            - "fxgenerate/go.mod"
+            - "fxgenerate/go.sum"
+
+jobs:
+    ci:
+        uses: ./.github/workflows/common-ci.yml
+        secrets: inherit
+        with:
+            module: "fxgenerate"
diff --git a/README.md b/README.md
@@ -16,18 +16,20 @@ Yokai's documentation will be available soon.
 
 ## Fx Modules
 
-Yokai is using [Fx](https://github.com/uber-go/fx) for its plugin system.
+Yokai's `Fx modules` are the plugins for your Yokai application.
 
-`Yokai's Fx modules` are the plugins for your Yokai application, but they can be used in any [Fx](https://github.com/uber-go/fx) based Go application.
+Yokai is using [Fx](https://github.com/uber-go/fx) for its plugin system.
 
-| Fx Module            | Description                    |
-|----------------------|--------------------------------|
-| [fxconfig](fxconfig) | Fx module for [config](config) |
+| Fx Module                | Description                        |
+|--------------------------|------------------------------------|
+| [fxconfig](fxconfig)     | Fx module for [config](config)     |
+| [fxgenerate](fxgenerate) | Fx module for [generate](generate) |
 
+They can also be used in any [Fx](https://github.com/uber-go/fx) based Go application.
 
 ## Modules
 
-`Yokai's modules` are the foundation of the framework, but they can be used in any Go application (no Yokai dependencies).
+Yokai's `modules` are the foundation of the framework.
 
 | Module                     | Description                                                                                                                                             |
 |----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -40,6 +42,8 @@ Yokai is using [Fx](https://github.com/uber-go/fx) for its plugin system.
 | [orm](orm)                 | ORM module based on [Gorm](https://gorm.io/)                                                                                                            |
 | [trace](trace)             | Tracing module based on [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-go)                                                             |
 
+They can also be used in any Go application (no Yokai or [Fx](https://github.com/uber-go/fx) dependencies).
+
 ## Contributing
 
 This repository uses [release-please](https://github.com/googleapis/release-please) to automate Yokai's modules release process.

diff --git a/fxgenerate/.golangci.yml b/fxgenerate/.golangci.yml
@@ -0,0 +1,66 @@
+run:
+  timeout: 5m
+  concurrency: 8
+
+linters:
+  enable:
+    - asasalint
+    - asciicheck
+    - bidichk
+    - bodyclose
+    - containedctx
+    - contextcheck
+    - cyclop
+    - decorder
+    - dogsled
+    - dupl
+    - durationcheck
+    - errcheck
+    - errchkjson
+    - errname
+    - errorlint
+    - exhaustive
+    - forbidigo
+    - forcetypeassert
+    - gocognit
+    - goconst
+    - gocritic
+    - gocyclo
+    - godot
+    - godox
+    - gofmt
+    - goheader
+    - gomoddirectives
+    - gomodguard
+    - goprintffuncname
+    - gosec
+    - gosimple
+    - govet
+    - grouper
+    - importas
+    - ineffassign
+    - interfacebloat
+    - logrlint
+    - maintidx
+    - makezero
+    - misspell
+    - nestif
+    - nilerr
+    - nilnil
+    - nlreturn
+    - nolintlint
+    - nosprintfhostport
+    - prealloc
+    - predeclared
+    - promlinter
+    - reassign
+    - staticcheck
+    - tenv
+    - thelper
+    - tparallel
+    - typecheck
+    - unconvert
+    - unparam
+    - unused
+    - usestdlibvars
+    - whitespace
diff --git a/fxgenerate/README.md b/fxgenerate/README.md
@@ -0,0 +1,143 @@
+# Fx Generate Module
+
+[![ci](https://github.com/ankorstore/yokai/actions/workflows/fxgenerate-ci.yml/badge.svg)](https://github.com/ankorstore/yokai/actions/workflows/fxgenerate-ci.yml)
+[![go report](https://goreportcard.com/badge/github.com/ankorstore/yokai/fxgenerate)](https://goreportcard.com/report/github.com/ankorstore/yokai/fxgenerate)
+[![codecov](https://codecov.io/gh/ankorstore/yokai/graph/badge.svg?token=ghUBlFsjhR&flag=fxgenerate)](https://app.codecov.io/gh/ankorstore/yokai/tree/main/fxgenerate)
+[![Deps](https://img.shields.io/badge/osi-deps-blue)](https://deps.dev/go/github.com%2Fankorstore%2Fyokai%2Ffxgenerate)
+[![PkgGoDev](https://pkg.go.dev/badge/github.com/ankorstore/yokai/fxgenerate)](https://pkg.go.dev/github.com/ankorstore/yokai/fxgenerate)
+
+> [Fx](https://uber-go.github.io/fx/) module for [generate](https://github.com/ankorstore/yokai/tree/main/generate).
+
+<!-- TOC -->
+* [Installation](#installation)
+* [Documentation](#documentation)
+	* [Loading](#loading)
+	* [Generators](#generators)
+		* [UUID](#uuid)
+			* [Usage](#usage)
+			* [Testing](#testing)
+	* [Override](#override)
+<!-- TOC -->
+
+## Installation
+
+```shell
+go get github.com/ankorstore/yokai/fxgenerate
+```
+
+## Documentation
+
+### Loading
+
+To load the module in your Fx application:
+
+```go
+package main
+
+import (
+	"github.com/ankorstore/yokai/fxgenerate"
+	"go.uber.org/fx"
+)
+
+func main() {
+	fx.New(fxgenerate.FxGenerateModule).Run()
+}
+```
+
+### Generators
+
+#### UUID
+
+##### Usage
+
+This module provides a [UuidGenerator](https://github.com/ankorstore/yokai/blob/main/generate/uuid/generator.go), made available into the Fx container.
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/ankorstore/yokai/generate/uuid"
+	"github.com/ankorstore/yokai/fxgenerate"
+	"go.uber.org/fx"
+)
+
+func main() {
+	fx.New(
+		fxgenerate.FxGenerateModule, // load the module
+		fx.Invoke(func(generator *uuid.UuidGenerator) { // invoke the uuid generator
+			fmt.Printf("uuid: %s", generator.Generate()) // uuid: dcb5d8b3-4517-4957-a42c-604d11758561
+		}),
+	).Run()
+}
+```
+
+##### Testing
+
+This module provides the possibility to make your [UuidGenerator](https://github.com/ankorstore/yokai/blob/main/generate/uuid/generator.go) generate deterministic values, for testing purposes.
+
+You need to:
+
+- first provide into the Fx container the deterministic value to be used for generation, annotated with `name:"generate-test-uuid-value"`
+- then decorate into the Fx container the `UuidGeneratorFactory` with the provided [TestUuidGeneratorFactory](fxgeneratetest/uuid/factory.go)
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/ankorstore/yokai/fxgenerate"
+	fxtestuuid "github.com/ankorstore/yokai/fxgenerate/fxgeneratetest/uuid"
+	"github.com/ankorstore/yokai/generate/uuid"
+	"go.uber.org/fx"
+)
+
+func main() {
+	fx.New(
+		fxgenerate.FxGenerateModule, // load the module
+		fx.Provide(                  // provide and annotate the deterministic value
+			fx.Annotate(
+				func() string {
+					return "some deterministic value"
+				},
+				fx.ResultTags(`name:"generate-test-uuid-value"`),
+			),
+		),
+		fx.Decorate(fxtestuuid.NewFxTestUuidGeneratorFactory), // override the module with the TestUuidGeneratorFactory
+		fx.Invoke(func(generator *uuid.UuidGenerator) {        // invoke the generator
+			fmt.Printf("uuid: %s", generator.Generate())       // uuid: some deterministic value
+		}),
+	).Run()
+}
+```
+
+### Override
+
+By default, the `uuid.UuidGenerator` is created by the [DefaultUuidGeneratorFactory](https://github.com/ankorstore/yokai/blob/main/generate/uuid/factory.go).
+
+If needed, you can provide your own factory and override the module:
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/ankorstore/yokai/fxgenerate"
+	testuuid "github.com/ankorstore/yokai/fxgenerate/testdata/uuid"
+	"github.com/ankorstore/yokai/generate/uuid"
+	"go.uber.org/fx"
+)
+
+func main() {
+	fx.New(
+		fxgenerate.FxGenerateModule,                             // load the module
+		fx.Decorate(testuuid.NewTestStaticUuidGeneratorFactory), // override the module with a custom factory
+		fx.Invoke(func(generator *uuid.UuidGenerator) {          // invoke the custom generator
+			fmt.Printf("uuid: %s", generator.Generate())         // uuid: static
+		}),
+	).Run()
+}
+```
diff --git a/fxgenerate/fxgeneratetest/uuid/factory.go b/fxgenerate/fxgeneratetest/uuid/factory.go
@@ -0,0 +1,30 @@
+package uuid
+
+import (
+	uuidtest "github.com/ankorstore/yokai/generate/generatetest/uuid"
+	"github.com/ankorstore/yokai/generate/uuid"
+	"go.uber.org/fx"
+)
+
+// FxTestUuidGeneratorFactoryParam is used to retrieve the provided generate-test-uuid-value from Fx.
+type FxTestUuidGeneratorFactoryParam struct {
+	fx.In
+	Value string `name:"generate-test-uuid-value"`
+}
+
+// TestUuidGeneratorFactory is a [uuid.UuidGeneratorFactory] implementation.
+type TestUuidGeneratorFactory struct {
+	value string
+}
+
+// NewFxTestUuidGeneratorFactory returns a new [TestUuidGeneratorFactory], implementing [uuid.UuidGeneratorFactory].
+func NewFxTestUuidGeneratorFactory(p FxTestUuidGeneratorFactoryParam) uuid.UuidGeneratorFactory {
+	return &TestUuidGeneratorFactory{
+		value: p.Value,
+	}
+}
+
+// Create returns a new [uuid.UuidGenerator].
+func (f *TestUuidGeneratorFactory) Create() uuid.UuidGenerator {
+	return uuidtest.NewTestUuidGenerator(f.value)
+}
diff --git a/fxgenerate/fxgeneratetest/uuid/factory_test.go b/fxgenerate/fxgeneratetest/uuid/factory_test.go
@@ -0,0 +1,36 @@
+package uuid_test
+
+import (
+	"testing"
+
+	"github.com/ankorstore/yokai/fxgenerate"
+	fxgeneratetestuuid "github.com/ankorstore/yokai/fxgenerate/fxgeneratetest/uuid"
+	"github.com/ankorstore/yokai/generate/uuid"
+	"github.com/stretchr/testify/assert"
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxtest"
+)
+
+func TestTestUuidGenerator(t *testing.T) {
+	t.Parallel()
+
+	var generator uuid.UuidGenerator
+
+	fxtest.New(
+		t,
+		fx.NopLogger,
+		fxgenerate.FxGenerateModule,
+		fx.Provide(
+			fx.Annotate(
+				func() string {
+					return "some test value"
+				},
+				fx.ResultTags(`name:"generate-test-uuid-value"`),
+			),
+		),
+		fx.Decorate(fxgeneratetestuuid.NewFxTestUuidGeneratorFactory),
+		fx.Populate(&generator),
+	).RequireStart().RequireStop()
+
+	assert.Equal(t, "some test value", generator.Generate())
+}
diff --git a/fxgenerate/go.mod b/fxgenerate/go.mod
@@ -0,0 +1,22 @@
+module github.com/ankorstore/yokai/fxgenerate
+
+go 1.20
+
+require (
+	github.com/ankorstore/yokai/generate v1.0.0
+	github.com/google/uuid v1.5.0
+	github.com/stretchr/testify v1.8.4
+	go.uber.org/fx v1.20.1
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	go.uber.org/atomic v1.9.0 // indirect
+	go.uber.org/dig v1.17.0 // indirect
+	go.uber.org/multierr v1.8.0 // indirect
+	go.uber.org/zap v1.23.0 // indirect
+	golang.org/x/sys v0.8.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)