feat: provide better panic msgs and docs (#153)

* feat: provide better panic msgs and docs

* fix: docs link

Author: Oudwins

custom.go

@@ -48,7 +48,10 @@ func (c *Custom[T]) process(ctx *p.SchemaCtx) {
 		ctx.AddIssue(ctx.IssueFromCoerce(fmt.Errorf("expected %T, got %T", new(T), ctx.Data)))
 		return
 	}
-	ptr := ctx.ValPtr.(*T)
+	ptr, ok := ctx.ValPtr.(*T)
+	if !ok {
+		p.Panicf(p.PanicTypeCast, ctx.String(), ctx.DType, ctx.ValPtr)
+	}
 	*ptr = d
 
 	// run the test
@@ -73,7 +76,11 @@ func (c *Custom[T]) Validate(dataPtr *T, options ...ExecOption) ZogIssueList {
 
 func (c *Custom[T]) validate(ctx *p.SchemaCtx) {
 	ctx.Processor = &c.test
-	c.test.Func(ctx.ValPtr.(*T), ctx)
+	ptr, ok := ctx.ValPtr.(*T)
+	if !ok {
+		p.Panicf(p.PanicTypeCast, ctx.String(), ctx.DType, ctx.ValPtr)
+	}
+	c.test.Func(ptr, ctx)
 }
 
 func (c *Custom[T]) setCoercer(coercer CoercerFunc) {

docs/docs/core-design-decisions.md

@@ -12,7 +12,7 @@ toc_max_heading_level: 4
 - Errors returned by you (for example in a `Preprocess` or `Transform` function) can be the ZogIssue interface or an error. If you return an error, it will be wrapped in a ZogIssue. ZogIssue is just a struct that wraps around an error and adds a message field which is text that can be shown to the user. For more on this see [Errors](/errors)
 - You should not depend on test execution order. They might run in parallel in the future
 
-> **A WORD OF CAUTION. ZOG & PANICS**
+> **A WORD OF CAUTION. [ZOG & PANICS](/panics)**
 > In general Zog will never panic if the input data is wrong but it will panic if you configure it wrong. For example:
 >
 > - In parse mode Zog will never panic due to invalid input data but will always panic if invalid destination is passed to the `Parse` function. if the destination does not match the schema in terms of types or fields.

docs/docs/panics.md

@@ -0,0 +1,139 @@
+---
+sidebar_position: 199
+hide_table_of_contents: false
+toc_min_heading_level: 2
+toc_max_heading_level: 4
+---
+
+# Zog Panics
+
+## When does Zog panic?
+
+Zog follows [TigerStyle](https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/TIGER_STYLE.md) asserts. It panics when something in its fundamental assumptions is broken.
+
+In practice this means that Zog will never panic if the input data is wrong but it will panic if you configure it wrong. Most of the time "configured it wrong" means that you have made a mistake in your schema definition which puts Zog into an invalid state and results in a schema that can never succeed.
+
+## Types of Panics
+
+> If you find a panic that is not listed here, please report it as a bug!
+
+### Schema Definition Errors
+
+```go
+var schema = z.Struct(z.Schema{
+	"name": z.String().Required(),
+})
+
+// This struct is a valid destination for the schema
+type User struct {
+	Name string
+	Age  int // age will be ignored since it is not a field in the schema
+}
+
+// this struct is not a valid structure for the schema. It is missing the name field.
+// This will cause Zog to panic in both Parse and Validate mode
+type User2 struct {
+	Email string `zog:"name"` // using struct tag here DOES NOT WORK. This is not the purpose of the struct tag.
+	Age   int
+}
+schema.Parse(map[string]any{"name": "zog"}, &User{}) // this will panic even if input data is valid. Because the destination is not a valid structure for the schema
+schema.Validate(&User2{})                            // This will panic because the structure does not match the schema
+```
+
+### Type Cast Errors
+
+There are multiple ways in which a type cast error can occur. For example:
+
+###### 1 Destination/Validation value is not a pointer
+
+```go
+var schema = z.Struct(z.Schema{
+	"name": z.String().Required(),
+})
+
+var dest User
+schema.Parse(map[string]any{"name": "zog"}, dest) // This will panic because dest is not a pointer
+schema.Validate(dest)                             // This will panic because dest is not a pointer
+// Fix this by using a pointer
+schema.Parse(map[string]any{"name": "zog"}, &dest)
+schema.Validate(&dest)
+```
+
+> This can only really happen on complex schemas since those are not fully typesafe. Primitive schemas are typesafe and won't let you pass a non-pointer value.
+
+###### 2 Destination/Validation value is not a valid type for the schema
+
+```go
+type MyString string
+type User struct {
+	Age MyString
+}
+var schema = z.Struct(z.Schema{
+	"age": z.String().Required(),
+})
+
+val := User{
+	Age: MyString("1"),
+}
+schema.Validate(&val) // This will panic because the schema is expecting a string but the value is of type MyString
+```
+
+Same thing will happen if you incorrectly set the type in a z.Custom schema:
+
+```go
+
+type User struct {
+	ID uuid.UUID
+}
+
+var schema = z.Struct(z.Schema{
+	"id": z.Custom(func (ptr *string, ctx z.Ctx) bool { // Zog can't convert a UUID to a string so this will panic
+		return true
+	}),
+})
+
+val := User{
+	ID: uuid.New(),
+}
+
+schema.Validate(&val) // This will panic because the schema is expecting a string but the value is of type uuid.UUID
+```
+
+Another common example is when you forget to use z.Ptr.
+
+```go
+type User struct {
+	Friends *[]Friend
+}
+
+// This is incorrect!
+var schema = z.Struct(z.Schema{
+	"friends": z.Slice(z.Struct(z.Schema{
+		"name": z.String().Required(),
+	})),
+})
+
+// This is correct!
+var schema2 = z.Struct(z.Schema{
+	"friends": z.Ptr(z.Slice(z.Struct(z.Schema{
+		"name": z.String().Required(),
+	}))),
+})
+```
+
+###### 3 The coercer returns a value of the wrong type
+
+> Only applicable to `schema.Parse()`
+
+```go
+var schema = z.Struct(z.Schema{
+	"name": z.String(z.WithCoercer(func (v any, ctx z.Ctx) (any, error) {
+		return 1, nil // we are returning an int but the schema is expecting a string
+	})).Required(),
+})
+
+val := User{
+	Name: "zog",
+}
+schema.Parse(map[string]any{"name": "zog"}, &val) // This will panic because the coercer is returning an int but the schema is expecting a string
+```

internals/contexts.go

@@ -1,6 +1,8 @@
 package internals
 
 import (
+	"fmt"
+
 	zconst "github.com/Oudwins/zog/zconst"
 )
 
@@ -208,6 +210,10 @@ func (c *SchemaCtx) Free() {
 	SchemaCtxPool.Put(c)
 }
 
+func (c *SchemaCtx) String() string {
+	return fmt.Sprintf("z.Ctx{Data: %v, ValPtr: %v, Path: %v, DType: %v, CanCatch: %v, Exit: %v, HasCaught: %v }", SafeString(c.Data), SafeString(c.ValPtr), c.Path, c.DType, c.CanCatch, c.Exit, c.HasCaught)
+}
+
 // func (c *TestCtx) Issue() *ZogIssue {
 // 	// TODO handle catch here
 // 	zerr := ZogIssuePool.Get().(*ZogIssue)

internals/panics.go

@@ -0,0 +1,13 @@
+package internals
+
+import "fmt"
+
+const (
+	PanicTypeCast           = "Zog Panic: Type Cast Error\n Current context: %s\n Expected valPtr type to correspond with type defined in schema. But it does not. Expected type: *%T, got: %T\nFor more information see: https://zog.dev/panics#type-cast-errors"
+	PanicTypeCastCoercer    = "Zog Panic: Type Cast Error\n Current context: %s\n Expected coercer return value to correspond with type defined in schema. But it does not. Expected type: *%T, got: %T\nFor more information see: https://zog.dev/panics#type-cast-errors"
+	PanicMissingStructField = "Zog Panic: Struct Schema Definition Error\n Current context: %s\n Provided struct is missing expected schema key: %s.\n This means you have made a mistake in your schema definition.\nFor more information see: https://zog.dev/panics#schema-definition-errors"
+)
+
+func Panicf(format string, args ...any) {
+	panic(fmt.Sprintf(format, args...))
+}

internals/utils.go

@@ -11,7 +11,14 @@ func SafeString(x any) string {
 	if x == nil {
 		return defaultString
 	}
-	return fmt.Sprintf("%v", x)
+	refVal := reflect.ValueOf(x)
+	for refVal.Kind() == reflect.Ptr {
+		if refVal.IsNil() {
+			return defaultString
+		}
+		refVal = refVal.Elem()
+	}
+	return fmt.Sprintf("%v", refVal.Interface())
 }
 
 func SafeError(x error) string {

preprocess.go

@@ -34,7 +34,11 @@ func (s *PreprocessSchema[F, T]) process(ctx *p.SchemaCtx) {
 }
 
 func (s *PreprocessSchema[F, T]) validate(ctx *p.SchemaCtx) {
-	out, err := s.fn(ctx.ValPtr.(F), ctx)
+	v, ok := ctx.ValPtr.(F)
+	if !ok {
+		p.Panicf(p.PanicTypeCast, ctx.String(), new(F), ctx.ValPtr)
+	}
+	out, err := s.fn(v, ctx)
 	if err != nil {
 		ctx.AddIssue(ctx.Issue().SetMessage(err.Error()))
 		return

struct.go

@@ -100,7 +100,7 @@ func (v *StructSchema) process(ctx *p.SchemaCtx) {
 
 		fieldMeta, ok := structVal.Type().FieldByName(key)
 		if !ok {
-			panic(fmt.Sprintf("Struct is missing expected schema key: %s\n see the zog FAQ for more info", key))
+			p.Panicf(p.PanicMissingStructField, ctx.String(), key)
 		}
 		destPtr := structVal.FieldByName(key).Addr().Interface()
 

struct_validate_test.go

@@ -215,3 +215,18 @@ func TestValidateStructGetType(t *testing.T) {
 	})
 	assert.Equal(t, zconst.TypeStruct, s.getType())
 }
+
+func TestValidateStructInvalidSchema(t *testing.T) {
+	schema := Struct(Shape{
+		"field": String(),
+	})
+
+	type TestStruct struct {
+		Field int
+	}
+
+	var dest TestStruct
+	assert.Panics(t, func() {
+		schema.Validate(&dest)
+	})
+}

zogSchema.go

@@ -53,7 +53,10 @@ func TestFunc[T any](IssueCode zconst.ZogIssueCode, fn BoolTFunc[T], options ...
 func primitiveParsing[T p.ZogPrimitive](ctx *p.SchemaCtx, processors []p.ZProcessor[*T], defaultVal *T, required *p.Test[*T], catch *T, coercer CoercerFunc, isZeroFunc p.IsZeroValueFunc) {
 	ctx.CanCatch = catch != nil
 
-	destPtr := ctx.ValPtr.(*T)
+	destPtr, ok := ctx.ValPtr.(*T)
+	if !ok {
+		p.Panicf(p.PanicTypeCast, ctx.String(), ctx.DType, ctx.ValPtr)
+	}
 
 	// 2. cast data to string & handle default/required
 	isZeroVal := isZeroFunc(ctx.Data, ctx)
@@ -84,7 +87,11 @@ func primitiveParsing[T p.ZogPrimitive](ctx *p.SchemaCtx, processors []p.ZProces
 			ctx.AddIssue(ctx.IssueFromCoerce(err))
 			return
 		}
-		*destPtr = v.(T)
+		x, ok := v.(T)
+		if !ok {
+			p.Panicf(p.PanicTypeCastCoercer, ctx.String(), ctx.DType, v)
+		}
+		*destPtr = x
 	}
 
 	for _, processor := range processors {
@@ -103,7 +110,10 @@ func primitiveParsing[T p.ZogPrimitive](ctx *p.SchemaCtx, processors []p.ZProces
 func primitiveValidation[T p.ZogPrimitive](ctx *p.SchemaCtx, processors []p.ZProcessor[*T], defaultVal *T, required *p.Test[*T], catch *T) {
 	ctx.CanCatch = catch != nil
 
-	valPtr := ctx.ValPtr.(*T)
+	valPtr, ok := ctx.ValPtr.(*T)
+	if !ok {
+		p.Panicf(p.PanicTypeCast, ctx.String(), ctx.DType, ctx.ValPtr)
+	}
 
 	// 2. cast data to string & handle default/required
 	// Warning. This uses generic IsZeroValue because for Validate we treat zero values as invalid for required fields. This is different from Parse.