Add -typederrors flag for typed enum conversion errors

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

Author: samiam2013

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)

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(errs.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)
 }

errs/errs.go

@@ -0,0 +1,8 @@
+package errs
+
+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

@@ -382,7 +382,7 @@ 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, false)
 	got := string(g.format())
 	if got != loadGolden(test.name) {
 		// Use this to help build a golden text when changes are needed

stringer.go

@@ -56,6 +56,7 @@ var (
 	trimPrefix      = flag.String("trimprefix", "", "transform each item name by removing a prefix or comma separated list of prefixes. Default: \"\"")
 	addPrefix       = flag.String("addprefix", "", "transform each item name by adding a prefix. Default: \"\"")
 	linecomment     = flag.Bool("linecomment", false, "use line comment text as printed text when present")
+	typedErrors     = flag.Bool("typederrors", false, "if true, use typed errors for enum string conversion methods. Default: false")
 )
 
 var comments arrayFlags
@@ -119,6 +120,10 @@ func main() {
 	g.Printf("package %s", g.pkg.name)
 	g.Printf("\n")
 	g.Printf("import (\n")
+	if *typedErrors {
+		g.Printf("\t\"errors\"\n")
+		g.Printf("\t\"github.com/dmarkham/enumer/errs\"\n")
+	}
 	g.Printf("\t\"fmt\"\n")
 	g.Printf("\t\"strings\"\n")
 	if *sql {
@@ -135,7 +140,7 @@ func main() {
 
 	// Run generate for each type.
 	for _, typeName := range typs {
-		g.generate(typeName, *json, *yaml, *sql, *text, *gqlgen, *transformMethod, *trimPrefix, *addPrefix, *linecomment, *altValuesFunc)
+		g.generate(typeName, *json, *yaml, *sql, *text, *gqlgen, *transformMethod, *trimPrefix, *addPrefix, *linecomment, *altValuesFunc, *typedErrors)
 	}
 
 	// Format the output.
@@ -415,7 +420,7 @@ func (g *Generator) prefixValueNames(values []Value, prefix string) {
 // generate produces the String method for the named type.
 func (g *Generator) generate(typeName string,
 	includeJSON, includeYAML, includeSQL, includeText, includeGQLGen bool,
-	transformMethod string, trimPrefix string, addPrefix string, lineComment bool, includeValuesMethod bool) {
+	transformMethod string, trimPrefix string, addPrefix string, lineComment bool, includeValuesMethod bool, useTypedErrors bool) {
 	values := make([]Value, 0, 100)
 	for _, file := range g.pkg.files {
 		file.lineComment = lineComment
@@ -468,15 +473,15 @@ func (g *Generator) generate(typeName string,
 
 	g.buildNoOpOrderChangeDetect(runs, typeName)
 
-	g.buildBasicExtras(runs, typeName, runsThreshold)
+	g.buildBasicExtras(runs, typeName, runsThreshold, useTypedErrors)
 	if includeJSON {
-		g.buildJSONMethods(runs, typeName, runsThreshold)
+		g.buildJSONMethods(runs, typeName, runsThreshold, useTypedErrors)
 	}
 	if includeText {
-		g.buildTextMethods(runs, typeName, runsThreshold)
+		g.buildTextMethods(runs, typeName, runsThreshold, useTypedErrors)
 	}
 	if includeYAML {
-		g.buildYAMLMethods(runs, typeName, runsThreshold)
+		g.buildYAMLMethods(runs, typeName, runsThreshold, useTypedErrors)
 	}
 	if includeSQL {
 		g.addValueAndScanMethod(typeName)