Add -typederrors flag for typed enum conversion errors

Co-authored-by: @bincyber <bincyber@users.noreply.github.com>

Author: samiam2013

.github/workflows/go.yml

@@ -26,3 +26,9 @@ jobs:
 
     - name: Test
       run: go test -v ./...
+
+    - name: Run Golden Tests
+      run: go test -v -run TestGolden
+
+    - name: Run End-to-End Tests  
+      run: go test -v -run TestEndToEnd

README.md

@@ -37,6 +37,8 @@ Flags:
         transform each item name by removing a prefix or comma separated list of prefixes. Default: ""
   -type string
         comma-separated list of type names; must be set
+  -typederrors
+        if true, errors from errs/ will be errors.Join()-ed for errors.Is(...) to simplify invalid value handling. Default: false
   -values
         if true, alternative string values method will be generated. Default: false
   -yaml
@@ -70,6 +72,9 @@ When Enumer is applied to a type, it will generate:
   the enum conform to the `gopkg.in/yaml.v2.Marshaler` and `gopkg.in/yaml.v2.Unmarshaler` interfaces.
 - When the flag `sql` is provided, the methods for implementing the `Scanner` and `Valuer` interfaces.
   Useful when storing the enum in a database.
+- When the flag `typederrors` is provided, the string conversion functions will return errors wrapped with
+  `errors.Join()` containing a typed error from the `errs` package. This allows you to use `errors.Is()` to
+  check for specific enum validation failures.
 
 
 For example, if we have an enum type called `Pill`,
@@ -200,7 +205,7 @@ For a module-aware repo with `enumer` in the `go.mod` file, generation can be ca
 //go:generate go run github.com/dmarkham/enumer -type=YOURTYPE
 ```
 
-There are four boolean flags: `json`, `text`, `yaml` and `sql`. You can use any combination of them (i.e. `enumer -type=Pill -json -text`),
+There are five boolean flags: `json`, `text`, `yaml`, `sql`, and `typederrors`. You can use any combination of them (i.e. `enumer -type=Pill -json -text -typederrors`),
 
 For enum string representation transformation the `transform` and `trimprefix` flags
 were added (i.e. `enumer -type=MyType -json -transform=snake`).
@@ -215,6 +220,28 @@ If a prefix is provided via the `addprefix` flag, it will be added to the start
 
 The boolean flag `values` will additionally create an alternative string values method `Values() []string` to fullfill the `EnumValues` interface of [ent](https://entgo.io/docs/schema-fields/#enum-fields).
 
+## Typed Error Handling
+
+When using the `typederrors` flag, you can handle enum validation errors specifically using `errors.Is()`:
+
+```go
+import (
+    "errors"
+    "github.com/dmarkham/enumer/errs"
+)
+
+// This will return a typed error that can be checked
+pill, err := PillString("InvalidValue")
+if err != nil {
+    if errors.Is(err, errs.ErrValueInvalid) {
+        // Handle invalid enum value specifically
+        fmt.Println("Invalid pill value provided")
+    }
+    // The error also contains a descriptive message
+    fmt.Printf("Error: %v\n", err)
+}
+```
+
 ## Inspiring projects
 
 - [Álvaro López Espinosa](https://github.com/alvaroloes/enumer)

endtoend_test.go

@@ -4,6 +4,7 @@
 
 // go command is not available on android
 
+//go:build !android
 // +build !android
 
 package main
@@ -75,6 +76,7 @@ func TestEndToEnd(t *testing.T) {
 		// Names are known to be ASCII and long enough.
 		var typeName string
 		var transformNameMethod string
+		var useTypedErrors bool
 
 		switch name {
 		case "transform_snake.go":
@@ -110,18 +112,22 @@ func TestEndToEnd(t *testing.T) {
 		case "transform_whitespace.go":
 			typeName = "WhitespaceSeparatedValue"
 			transformNameMethod = "whitespace"
+		case "typedErrors.go":
+			typeName = "TypedErrorsValue"
+			transformNameMethod = "noop"
+			useTypedErrors = true
 		default:
 			typeName = fmt.Sprintf("%c%s", name[0]+'A'-'a', name[1:len(name)-len(".go")])
 			transformNameMethod = "noop"
 		}
 
-		stringerCompileAndRun(t, dir, stringer, typeName, name, transformNameMethod)
+		stringerCompileAndRun(t, dir, stringer, typeName, name, transformNameMethod, useTypedErrors)
 	}
 }
 
 // stringerCompileAndRun runs stringer for the named file and compiles and
 // runs the target binary in directory dir. That binary will panic if the String method is incorrect.
-func stringerCompileAndRun(t *testing.T, dir, stringer, typeName, fileName, transformNameMethod string) {
+func stringerCompileAndRun(t *testing.T, dir, stringer, typeName, fileName, transformNameMethod string, useTypedErrors bool) {
 	t.Logf("run: %s %s\n", fileName, typeName)
 	source := filepath.Join(dir, fileName)
 	err := copy(source, filepath.Join("testdata", fileName))
@@ -130,7 +136,12 @@ func stringerCompileAndRun(t *testing.T, dir, stringer, typeName, fileName, tran
 	}
 	stringSource := filepath.Join(dir, typeName+"_string.go")
 	// Run stringer in temporary directory.
-	err = run(stringer, "-type", typeName, "-output", stringSource, "-transform", transformNameMethod, source)
+	args := []string{"-type", typeName, "-output", stringSource, "-transform", transformNameMethod}
+	if useTypedErrors {
+		args = append(args, "-typederrors", "-values")
+	}
+	args = append(args, source)
+	err = run(stringer, args...)
 	if err != nil {
 		t.Fatal(err)
 	}

enumer.go

@@ -3,7 +3,9 @@ package main
 import "fmt"
 
 // Arguments to format are:
+//
 //	[1]: type name
+//	[2]: complete error expression
 const stringNameToValueMethod = `// %[1]sString retrieves an enum value from the enum constants string name.
 // Throws an error if the param is not part of the enum.
 func %[1]sString(s string) (%[1]s, error) {
@@ -14,11 +16,12 @@ func %[1]sString(s string) (%[1]s, error) {
 	if val, ok := _%[1]sNameToValueMap[strings.ToLower(s)]; ok {
 		return val, nil
 	}
-	return 0, fmt.Errorf("%%s does not belong to %[1]s values", s)
+	return 0, %[2]s
 }
 `
 
 // Arguments to format are:
+//
 //	[1]: type name
 const stringValuesMethod = `// %[1]sValues returns all values of the enum
 func %[1]sValues() []%[1]s {
@@ -27,6 +30,7 @@ func %[1]sValues() []%[1]s {
 `
 
 // Arguments to format are:
+//
 //	[1]: type name
 const stringsMethod = `// %[1]sStrings returns a slice of all String values of the enum
 func %[1]sStrings() []string {
@@ -37,6 +41,7 @@ func %[1]sStrings() []string {
 `
 
 // Arguments to format are:
+//
 //	[1]: type name
 const stringBelongsMethodLoop = `// IsA%[1]s returns "true" if the value is listed in the enum definition. "false" otherwise
 func (i %[1]s) IsA%[1]s() bool {
@@ -50,6 +55,7 @@ func (i %[1]s) IsA%[1]s() bool {
 `
 
 // Arguments to format are:
+//
 //	[1]: type name
 const stringBelongsMethodSet = `// IsA%[1]s returns "true" if the value is listed in the enum definition. "false" otherwise
 func (i %[1]s) IsA%[1]s() bool {
@@ -59,6 +65,7 @@ func (i %[1]s) IsA%[1]s() bool {
 `
 
 // Arguments to format are:
+//
 //	[1]: type name
 const altStringValuesMethod = `func (%[1]s) Values() []string {
 	return %[1]sStrings()
@@ -70,7 +77,9 @@ func (g *Generator) buildAltStringValuesMethod(typeName string) {
 	g.Printf(altStringValuesMethod, typeName)
 }
 
-func (g *Generator) buildBasicExtras(runs [][]Value, typeName string, runsThreshold int) {
+var ErrInvalidValue = fmt.Errorf("invalid enumer value")
+
+func (g *Generator) buildBasicExtras(runs [][]Value, typeName string, runsThreshold int, useTypedErrors bool) {
 	// At this moment, either "g.declareIndexAndNameVars()" or "g.declareNameVars()" has been called
 
 	// Print the slice of values
@@ -89,7 +98,13 @@ func (g *Generator) buildBasicExtras(runs [][]Value, typeName string, runsThresh
 	g.printNamesSlice(runs, typeName, runsThreshold)
 
 	// Print the basic extra methods
-	g.Printf(stringNameToValueMethod, typeName)
+	var errorCode string
+	if useTypedErrors {
+		errorCode = fmt.Sprintf(`errors.Join(enumerrs.ErrValueInvalid, fmt.Errorf("%%s does not belong to %s values", s))`, typeName)
+	} else {
+		errorCode = fmt.Sprintf(`fmt.Errorf("%%s does not belong to %s values", s)`, typeName)
+	}
+	g.Printf(stringNameToValueMethod, typeName, errorCode)
 	g.Printf(stringValuesMethod, typeName)
 	g.Printf(stringsMethod, typeName)
 	if len(runs) <= runsThreshold {
@@ -144,6 +159,7 @@ func (g *Generator) printNamesSlice(runs [][]Value, typeName string, runsThresho
 }
 
 // Arguments to format are:
+//
 //	[1]: type name
 const jsonMethods = `
 // MarshalJSON implements the json.Marshaler interface for %[1]s
@@ -164,11 +180,14 @@ func (i *%[1]s) UnmarshalJSON(data []byte) error {
 }
 `
 
-func (g *Generator) buildJSONMethods(runs [][]Value, typeName string, runsThreshold int) {
+func (g *Generator) buildJSONMethods(runs [][]Value, typeName string, runsThreshold int, useTypedErrors bool) {
+	// For now, just use the standard template
+	// We rely on the %[1]sString method to provide typed errors when enabled
 	g.Printf(jsonMethods, typeName)
 }
 
 // Arguments to format are:
+//
 //	[1]: type name
 const textMethods = `
 // MarshalText implements the encoding.TextMarshaler interface for %[1]s
@@ -184,11 +203,14 @@ func (i *%[1]s) UnmarshalText(text []byte) error {
 }
 `
 
-func (g *Generator) buildTextMethods(runs [][]Value, typeName string, runsThreshold int) {
+func (g *Generator) buildTextMethods(runs [][]Value, typeName string, runsThreshold int, useTypedErrors bool) {
+	// For now, just use the standard template
+	// We rely on the %[1]sString method to provide typed errors when enabled
 	g.Printf(textMethods, typeName)
 }
 
 // Arguments to format are:
+//
 //	[1]: type name
 const yamlMethods = `
 // MarshalYAML implements a YAML Marshaler for %[1]s
@@ -209,6 +231,8 @@ func (i *%[1]s) UnmarshalYAML(unmarshal func(interface{}) error) error {
 }
 `
 
-func (g *Generator) buildYAMLMethods(runs [][]Value, typeName string, runsThreshold int) {
+func (g *Generator) buildYAMLMethods(runs [][]Value, typeName string, runsThreshold int, useTypedErrors bool) {
+	// For now, just use the standard template
+	// We rely on the %[1]sString method to provide typed errors when enabled
 	g.Printf(yamlMethods, typeName)
 }

enumerrs/errors.go

@@ -0,0 +1,8 @@
+package enumerrs
+
+import "errors"
+
+// This package defines custom error types for use in the generated code.
+
+// ErrValueInvalid is returned when a value does not belong to the set of valid values for a type.
+var ErrValueInvalid = errors.New("the input value is not valid for the type")

golden_test.go

@@ -76,6 +76,10 @@ var goldenLinecomment = []Golden{
 	{"dayWithLinecomment", linecommentIn},
 }
 
+var goldenTypedErrors = []Golden{
+	{"typedErrors", typedErrorsIn},
+}
+
 // Each example starts with "type XXX [u]int", with a single space separating them.
 
 // Simple test: enumeration of type int starting at 0.
@@ -313,54 +317,65 @@ const (
 )
 `
 
+const typedErrorsIn = `type TypedErrorsValue int
+const (
+	TypedErrorsValueOne TypedErrorsValue = iota
+	TypedErrorsValueTwo
+	TypedErrorsValueThree
+)
+`
+
 func TestGolden(t *testing.T) {
 	for _, test := range golden {
-		runGoldenTest(t, test, false, false, false, false, false, false, true, "", "")
+		runGoldenTest(t, test, false, false, false, false, false, false, true, "", "", false)
 	}
 	for _, test := range goldenJSON {
-		runGoldenTest(t, test, true, false, false, false, false, false, false, "", "")
+		runGoldenTest(t, test, true, false, false, false, false, false, false, "", "", false)
 	}
 	for _, test := range goldenText {
-		runGoldenTest(t, test, false, false, false, true, false, false, false, "", "")
+		runGoldenTest(t, test, false, false, false, true, false, false, false, "", "", false)
 	}
 	for _, test := range goldenYAML {
-		runGoldenTest(t, test, false, true, false, false, false, false, false, "", "")
+		runGoldenTest(t, test, false, true, false, false, false, false, false, "", "", false)
 	}
 	for _, test := range goldenSQL {
-		runGoldenTest(t, test, false, false, true, false, false, false, false, "", "")
+		runGoldenTest(t, test, false, false, true, false, false, false, false, "", "", false)
 	}
 	for _, test := range goldenJSONAndSQL {
-		runGoldenTest(t, test, true, false, true, false, false, false, false, "", "")
+		runGoldenTest(t, test, true, false, true, false, false, false, false, "", "", false)
 	}
 	for _, test := range goldenGQLGen {
-		runGoldenTest(t, test, false, false, false, false, false, true, false, "", "")
+		runGoldenTest(t, test, false, false, false, false, false, true, false, "", "", false)
 	}
 	for _, test := range goldenTrimPrefix {
-		runGoldenTest(t, test, false, false, false, false, false, false, false, "Day", "")
+		runGoldenTest(t, test, false, false, false, false, false, false, false, "Day", "", false)
 	}
 	for _, test := range goldenTrimPrefixMultiple {
-		runGoldenTest(t, test, false, false, false, false, false, false, false, "Day,Night", "")
+		runGoldenTest(t, test, false, false, false, false, false, false, false, "Day,Night", "", false)
 	}
 	for _, test := range goldenWithPrefix {
-		runGoldenTest(t, test, false, false, false, false, false, false, false, "", "Day")
+		runGoldenTest(t, test, false, false, false, false, false, false, false, "", "Day", false)
 	}
 	for _, test := range goldenTrimAndAddPrefix {
-		runGoldenTest(t, test, false, false, false, false, false, false, false, "Day", "Night")
+		runGoldenTest(t, test, false, false, false, false, false, false, false, "Day", "Night", false)
 	}
 	for _, test := range goldenLinecomment {
-		runGoldenTest(t, test, false, false, false, false, true, false, false, "", "")
+		runGoldenTest(t, test, false, false, false, false, true, false, false, "", "", false)
+	}
+	for _, test := range goldenTypedErrors {
+		runGoldenTest(t, test, false, false, false, false, false, false, false, "", "", true)
 	}
 }
 
 func runGoldenTest(t *testing.T, test Golden,
 	generateJSON, generateYAML, generateSQL, generateText, linecomment, generateGQLGen, generateValuesMethod bool,
-	trimPrefix string, prefix string) {
+	trimPrefix string, prefix string, useTypedErrors bool) {
 
 	var g Generator
 	file := test.name + ".go"
 	input := "package test\n" + test.input
 
-	dir, err := ioutil.TempDir("", "stringer")
+	dir, err := os.MkdirTemp("", "stringer")
 	if err != nil {
 		t.Error(err)
 	}
@@ -372,7 +387,7 @@ func runGoldenTest(t *testing.T, test Golden,
 	}()
 
 	absFile := filepath.Join(dir, file)
-	err = ioutil.WriteFile(absFile, []byte(input), 0644)
+	err = os.WriteFile(absFile, []byte(input), 0644)
 	if err != nil {
 		t.Error(err)
 	}
@@ -382,15 +397,15 @@ func runGoldenTest(t *testing.T, test Golden,
 	if len(tokens) != 3 {
 		t.Fatalf("%s: need type declaration on first line", test.name)
 	}
-	g.generate(tokens[1], generateJSON, generateYAML, generateSQL, generateText, generateGQLGen, "noop", trimPrefix, prefix, linecomment, generateValuesMethod)
+	g.generate(tokens[1], generateJSON, generateYAML, generateSQL, generateText, generateGQLGen, "noop", trimPrefix, prefix, linecomment, generateValuesMethod, useTypedErrors)
 	got := string(g.format())
 	if got != loadGolden(test.name) {
 		// Use this to help build a golden text when changes are needed
-		//goldenFile := fmt.Sprintf("./testdata/%v.golden", test.name)
-		//err = ioutil.WriteFile(goldenFile, []byte(got), 0644)
-		//if err != nil {
-		//	t.Error(err)
-		//}
+		// goldenFile := fmt.Sprintf("./testdata/%v.golden", test.name)
+		// err = os.WriteFile(goldenFile, []byte(got), 0644)
+		// if err != nil {
+		// 	t.Error(err)
+		// }
 		t.Errorf("%s: got\n====\n%s====\nexpected\n====%s", test.name, got, loadGolden(test.name))
 	}
 }