You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/docs/changes-from-zod.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ toc_max_heading_level: 4
12
12
2. I have chosen to make Zog prioritize idiomatic Golang over the Zod API. Meaning some of the schemas & tests (validation rules) have changed names, `z.Array()` is `z.Slice()`, `z.String().StartsWith()` is `z.String().HasPrefix` (to follow the std lib). Etc.
13
13
3. When I felt like a Zod method name would be confusing for Golang devs I changed it
14
14
- Some other changes:
15
-
- The refine method for providing a custom validation function is renamed to `schema.Test()`
15
+
- The refine & superRefine methods for providing a custom validation function is renamed to`schema.TestFunc` &`schema.Test()`
16
16
- schemas are optional by default (in zod they are required)
17
17
- The `z.Enum()` type from zod is removed in favor of `z.String().OneOf()` and is only supported for strings and numbers
18
18
-`string().regex` is renamed to `z.String().Match()` as that is in line with the regexp methods from the standard library (i.e `regexp.Match` and `regexp.MatchString()`)
Copy file name to clipboardExpand all lines: docs/docs/core-concepts/1-anatomy-of-schema.md
+12-34Lines changed: 12 additions & 34 deletions
Original file line number
Diff line number
Diff line change
@@ -7,51 +7,28 @@ sidebar_position: 1
7
7
A zog schema is an interface implemented by multiple custom structs that represent a set of `validation` and `transformation` logic for a variable of a given type. For example:
8
8
9
9
```go
10
-
stringSchema:= z.String().Min(3).Required().Trim()// A zog schema that represents a required string of minimum 3 characters and will be trimmed for white space
10
+
stringSchema:= z.String().Trim().Min(3).Required() // A zog schema that represents a required string which will first be trimmed then a test to ensure it has 3+ characters will be ran.
11
11
userSchema:= z.Struct(z.Schema{"name": stringSchema}) // a zog schema that represents a user struct. Also yes I know that z.Schema might be confusing but think of it as the schema for the struct not a ZogSchema
12
12
```
13
13
14
14
**The string schema, for example, looks something like this:**
15
15
16
16
```go
17
17
type stringSchema struct {
18
-
preTransforms []PreTransforms// transformations executed before the validation. For example trimming the string
19
18
isRequired bool// optional. Defaults to FALSE
20
19
defaultValue string// optional. if the input value is a "zero value" it will be replaced with this. Tests will still run on this value.
21
20
catchValue string// optional. If this is set it will "catch" any errors, set the destination value to this value and exit
22
-
tests []Test// These are your validation checks. Such as .Min(), .Contains(), etc
23
-
postTransforms []PostTransform// transformations executed after the validation.
21
+
testOrTransformation TestOrTransformation// This is the test or transformation that will be applied to the data.
24
22
}
25
23
```
26
24
27
-
## PreTransforms
28
-
29
-
Pretransforms is a list of function that are applied to the data before the [tests](#tests) are run. You can think of it like a `pipeline` of pre validation transformations for a specific schema. These are similar to preprocess functions in zod. **PreTransforms are PURE functions**. They take in data and return new data. This is the function signature:
30
-
31
-
```go
32
-
// takes the data as input and returns the new data which will then be passed onto the next functions.
33
-
// The function may return an error or a ZogIssue. In this case all validation will be skipped and the error will be wrapped into a ZogIssue and entire execution will return.
You can use pretransforms for things like trimming whitespace, splitting strings, etc. Here is an example of splitting a string into a slice of strings:
> **FOOTGUNS** > _Type Coercion_: Please note that pretransforms are executed before type coercion (if using `schema.Parse()`). This means that if you are responsible for checking that the data matches your expected type. If you blinding typecast the data to, for example, an int and your user provides a string as input you will cause a panic.
46
-
> _Pure Functions_: Since pretransforms are pure functions. A copy of the data is passed in. So if you place a preTransform on a large struct it will copy the entire struct which is not efficient. Be careful!
47
-
48
25
## Required, Default and Catch
49
26
50
27
`schema.Required()` is a boolean that indicates if the field is required. If it is required and the data is a zero value the schema will return a [ZogIssue](/errors).
51
28
52
29
`schema.Default(value)` sets a default value for the field. If the data is a zero value it will be replaced with this value, this takes priority over required. Tests will still run on this value.
53
30
54
-
`schema.Catch(value)` sets a catch value. If this is set it will "catch" any errors or ZogIssues with the catch value. Meaning it will set the destination value to the catch value and exit. When this is triggered, no matter what error triggers it code will automatically jump to the [PostTransforms](#posttransforms). For more information checkout the [parsing execution structure](/core-concepts/parsing#parsing-execution-structure).
31
+
`schema.Catch(value)` sets a catch value. If this is set it will "catch" any errors or ZogIssues with the catch value. Meaning it will set the destination value to the catch value and exit. When this is triggered, no matter what error triggers it code will automatically exit. For more information checkout the [parsing execution structure](/core-concepts/parsing#parsing-execution-structure).
You are also free to create custom tests and pass them to the `schema.Test()` and `schema.TestFunc()` methods. For more details on this checkout the [Creating Custom Tests](/custom-tests) page.
73
50
74
-
## PostTransforms
51
+
## Transforms
75
52
76
-
PostTransforms is a list of function that are applied to the data after the [tests](#tests) are run. You can think of it like a `pipeline` of transformations for a specific schema. This is the function signature:
53
+
Transforms is a list of function that are applied to the data at any point. You can think of it like a `pipeline` of transformations for a specific schema. This is the function signature:
77
54
78
55
```go
79
-
//type for functions called after validation & parsing is done
//Transforms are generic functions that take a pointer to the data as input. For primitive types you won't have to typecast but for complex types it will just be a any type and you will have to manually typecast it.
As you can see the function takes a pointer to the data as input. This is to allow the function to modify the data.
84
61
85
-
You can use posttransforms for any transformation you want to do but don't want it to affect the validation process. For example imagine you want to validate a phone number and afterwards separate the string into the area code and the rest of the number.
Parsing execution structure is quite simple. It just does roughly this:
88
+
89
+
1. Check for nil value
90
+
- If nil take into account if schema has default value or is required
91
+
2. Coerce value to the correct type otherwise
92
+
3. Run validation loop
93
+
- If a test fails, an issue is added
94
+
- If you return an error from a transform, the execution stops and that error is returned.
95
+
- If catch is active any error triggers it and stops the execution.
88
96
89
-
1. Pretransforms
90
-
- On error all parsing and validation stops and [ZogIssues](/errors) are returned.
91
-
- Can be caught by catch
92
-
2. Default Check -> Assigns default value if the value is nil value
93
-
3. Optional Check -> Stops validation if the value is nil value
94
-
4. Casting -> Attempts to cast the value to the correct type
95
-
- On error all parsing and validation stops and [ZogIssues](/errors) are returned
96
-
- Can be caught by catch
97
-
5. Required check ->
98
-
- On error: aborts if the value is its nil value and returns a required [ZogIssue](/errors).
99
-
- Can be caught by catch
100
-
6. Tests -> Run all tests on the value (including required)
101
-
- On error: validation [ZogIssues](/errors) are added to the [ZogIssueList](/errors#zogissuelist) or [ZogIssueMap](/errors#zogissuelist). All validation functions are run even if one of them fails.
102
-
- Can be caught by catch
103
-
7. PostTransforms -> Run all postTransforms on the value.
104
-
- On error you return: aborts and adds your error to the list of [ZogIssues](/errors)
105
-
- Only run on valid values. Won't run if a [ZogIssue](/errors) was created before the postTransforms
Copy file name to clipboardExpand all lines: docs/docs/core-design-decisions.md
+1-4Lines changed: 1 addition & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -9,8 +9,7 @@ toc_max_heading_level: 4
9
9
10
10
- All fields optional by default. Same as graphql
11
11
- When parsing into structs, private fields are ignored (same as stdlib json.Unmarshal)
12
-
- The struct parser expects a `DataProvider` (although if you pass something else to the data field it will try to coerce it into a `DataProvider`), which is an interface that wraps around an input like a map. This is less efficient than doing it directly but allows us to reuse the same code for all kinds of data sources (i.e json, query params, forms, etc). Generally as a normal user you should ignore that `DataProviders` exist. So forget you ever read this.
13
-
- Errors returned by you (for example in a `PreTransform` or `PostTransform` 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)
12
+
- 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)
14
13
- You should not depend on test execution order. They might run in parallel in the future
15
14
16
15
> **A WORD OF CAUTION. ZOG & PANICS**
@@ -47,8 +46,6 @@ Most of these things are issues we would like to address in future versions.
47
46
- Unsupported schemas:
48
47
49
48
-`z.Map()`
50
-
- custom types -> i.e `type MyString string`
51
-
- custom interfaces as types -> i.e the `Valuer` interface
52
49
53
50
-`zhttp` does not support parsing into any data type that is not a struct
54
51
- Schema & pick, omit, etc are not really typesafe. i.e `z.Struct(z.Schema{"name"})` name is not typesafe
Copy file name to clipboardExpand all lines: docs/docs/custom-tests.md
+9-8Lines changed: 9 additions & 8 deletions
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
sidebar_position: 4
2
+
sidebar_position: 5
3
3
toc_min_heading_level: 2
4
4
toc_max_heading_level: 4
5
5
---
@@ -13,8 +13,8 @@ toc_max_heading_level: 4
13
13
All schemas contain the `TestFunc()` method which can be used to create a simple custom test in a similar way to Zod's `refine` method. The `TestFunc()` method takes a `ValidateFunc` as an argument. This is a function that takes the data as input and returns a boolean indicating if it is valid or not. If you return `false` from the function Zog will create a [ZogIssue](/errors). For example:
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?v=4&size=40){kind=avatar}
0 commit comments