docs: update docs for v0.21 #151
Conversation
|
Caution Review failedThe pull request is closed. WalkthroughThe documentation and README were updated to unify and simplify the explanation of data transformations in the Zog validation library. The distinction between pre- and post-transforms was removed in favor of a single, generic Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant ZogSchema
participant PreprocessFunc
participant TransformFunc
participant Validator
User->>ZogSchema: Parse(input)
ZogSchema->>PreprocessFunc: Preprocess(input)
PreprocessFunc-->>ZogSchema: PreprocessedData
ZogSchema->>TransformFunc: Transform(PreprocessedData)
TransformFunc-->>ZogSchema: TransformedData
ZogSchema->>Validator: Validate(TransformedData)
Validator-->>ZogSchema: ValidationResult
ZogSchema-->>User: Result or Errors
Possibly related PRs
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Deploying zog with
|
| Latest commit: |
7307920
|
| Status: | ⚡️ Build in progress... |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (14)
docs/docs/changes-from-zod.md (1)
15-15: Grammar refinement for methods rename: Since you refer to multiple methods, use the plural verb “are renamed” instead of “is renamed.” For example:- The refine & superRefine methods for providing a custom validation function is renamed to `schema.TestFunc` & `schema.Test()` + The refine & superRefine methods for providing a custom validation function are renamed to `schema.TestFunc` & `schema.Test()`docs/docs/core-design-decisions.md (1)
12-12: Grammar refinement for clarity: Consider adding a comma after “For more on this see Errors” and ending the sentence with a period. For example:- For more on this see [Errors](/errors) + For more on this, see [Errors](/errors).🧰 Tools
🪛 LanguageTool
[uncategorized] ~12-~12: Possible missing comma found.
Context: ...raps around an error and adds a message field which is text that can be shown to the ...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~12-~12: Possible missing comma found.
Context: ...t can be shown to the user. For more on this see Errors - You should not ...(AI_HYDRA_LEO_MISSING_COMMA)
README.md (1)
154-161: Include import for strings package.
To make the example self-contained, add:import "strings"before using
strings.Splitin thez.Preprocesssnippet.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
159-159: Hard tabs
Column: 1(MD010, no-hard-tabs)
160-160: Hard tabs
Column: 1(MD010, no-hard-tabs)
docs/docs/preprocess.md (3)
8-9: Specify package qualifier for Ctx.
In the signature, changefunc(data any, ctx Ctx)tofunc(data any, ctx z.Ctx)to match other examples and avoid ambiguity.
14-17: Replace hard tabs with spaces.
Markdown linting flags hard tabs; convert them to spaces in the code block to satisfy MD010.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
15-15: Hard tabs
Column: 1(MD010, no-hard-tabs)
19-19: Fix typo in adverb.
Change “If you blinding typecast” to “If you blindly typecast” to correct the typo.🧰 Tools
🪛 LanguageTool
[grammar] ~19-~19: An auxiliary verb seems to be missing from this progressive structure. Did you mean “you're blinding”, “you are blinding”, or “you were blinding”?
Context: ...the data matches your expected type. If you blinding typecast the data to, for example, an i...(PRP_VBG)
docs/docs/custom-tests.md (3)
16-18: Use spaces instead of hard tabs and acknowledge pointer inference.
The snippet correctly demonstrates Zog infers*stringfor tests, enhancing type safety. Also, replace hard tab indentations in these lines with spaces to fix MD010.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
17-17: Hard tabs
Column: 1(MD010, no-hard-tabs)
26-29: Demonstrate safe type assertions for struct tests.
The example shows castingdataPtr.(*User), highlighting lack of inference for structs. Consider illustrating a safe assertion pattern using:userPtr, ok := dataPtr.(*User) if !ok { return false }to avoid panics.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
27-27: Hard tabs
Column: 1(MD010, no-hard-tabs)
28-28: Hard tabs
Column: 1(MD010, no-hard-tabs)
88-94: Fix typo in descriptive text.
In the prose prior to this snippet, correct “flexbility” to “flexibility” to maintain professionalism.docs/docs/reference.md (2)
18-18: ClarifyTransformmethod signature.
The signaturefunc(valPtr *T or any, ctx z.Ctx) (any, error)may confuse readers. Consider a more idiomatic generic Go signature, e.g.:schema.Transform(func(data any, ctx z.Ctx) (any, error))or document the type parameter explicitly:
schema.Transform[T](func(dataPtr T, ctx z.Ctx) (any, error))
94-95: Improve description ofTrim.
Change// trims the value of whitespaceto// trims leading and trailing whitespace from the stringfor greater precision.docs/docs/core-concepts/1-anatomy-of-schema.md (3)
21-21: Refine comment fortestOrTransformation.
Consider shortening to// test or transformation applied to the dataand adding a comma after “transformation” for clarity.
31-31: Fix missing comma inCatchdescription.
Insert a comma after “ZogIssues” so the sentence reads:If this is set, it will "catch" any errors or ZogIssues, set the destination value to this value, and exit.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~31-~31: A comma might be missing here.
Context: ...(value)` sets a catch value. If this is set it will "catch" any errors or ZogIssues...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~31-~31: Possible missing comma found.
Context: ... code will automatically exit. For more information checkout the [parsing execution structu...(AI_HYDRA_LEO_MISSING_COMMA)
53-58: Correct grammar in Transforms description.
UpdateTransforms is a list of functiontoTransforms are a list of functionsto match plurality, and consider renaming to “Transform functions” for consistency.🧰 Tools
🪛 LanguageTool
[uncategorized] ~53-~53: The verb “is” doesn’t seem to fit in this context, “are” is probably more formally correct.
Context: ...tests) page. ## Transforms Transforms is a list of function that are applied to ...(AI_HYDRA_LEO_CPT_IS_ARE)
[uncategorized] ~53-~53: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ... ## Transforms Transforms is a list of function that are applied to the data at any poi...(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/docs/core-concepts/img/parsing-workflow.pngis excluded by!**/*.png
📒 Files selected for processing (10)
README.md(2 hunks)docs/docs/changes-from-zod.md(1 hunks)docs/docs/core-concepts/1-anatomy-of-schema.md(2 hunks)docs/docs/core-concepts/3-parsing.mdx(1 hunks)docs/docs/core-concepts/parsing-table.tsx(6 hunks)docs/docs/core-design-decisions.md(1 hunks)docs/docs/custom-tests.md(3 hunks)docs/docs/getting-started.md(1 hunks)docs/docs/preprocess.md(1 hunks)docs/docs/reference.md(3 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
README.md
85-85: Hard tabs
Column: 1
(MD010, no-hard-tabs)
159-159: Hard tabs
Column: 1
(MD010, no-hard-tabs)
160-160: Hard tabs
Column: 1
(MD010, no-hard-tabs)
docs/docs/getting-started.md
118-118: Hard tabs
Column: 1
(MD010, no-hard-tabs)
119-119: Hard tabs
Column: 1
(MD010, no-hard-tabs)
docs/docs/preprocess.md
3-3: Link fragments should be valid
null
(MD051, link-fragments)
15-15: Hard tabs
Column: 1
(MD010, no-hard-tabs)
docs/docs/custom-tests.md
17-17: Hard tabs
Column: 1
(MD010, no-hard-tabs)
74-74: Hard tabs
Column: 1
(MD010, no-hard-tabs)
75-75: Hard tabs
Column: 1
(MD010, no-hard-tabs)
76-76: Hard tabs
Column: 1
(MD010, no-hard-tabs)
77-77: Hard tabs
Column: 1
(MD010, no-hard-tabs)
docs/docs/reference.md
84-84: Hard tabs
Column: 1
(MD010, no-hard-tabs)
85-85: Hard tabs
Column: 1
(MD010, no-hard-tabs)
🪛 LanguageTool
docs/docs/preprocess.md
[grammar] ~19-~19: An auxiliary verb seems to be missing from this progressive structure. Did you mean “you're blinding”, “you are blinding”, or “you were blinding”?
Context: ...the data matches your expected type. If you blinding typecast the data to, for example, an i...
(PRP_VBG)
docs/docs/core-concepts/3-parsing.mdx
[style] ~87-~87: As an alternative to the over-used intensifier ‘quite’, consider replacing this phrase.
Context: ...ructure Parsing execution structure is quite simple. It just does roughly this: 1. Check f...
(EN_WEAK_ADJECTIVE)
[style] ~90-~90: ‘take into account’ might be wordy. Consider a shorter alternative.
Context: ...is: 1. Check for nil value - If nil take into account if schema has default value or is requi...
(EN_WORDINESS_PREMIUM_TAKE_INTO_ACCOUNT)
[uncategorized] ~90-~90: You might be missing the article “the” here.
Context: ... value - If nil take into account if schema has default value or is required 2. Coe...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~90-~90: You might be missing the article “a” here.
Context: ... If nil take into account if schema has default value or is required 2. Coerce value to...
(AI_EN_LECTOR_MISSING_DETERMINER_A)
[uncategorized] ~91-~91: Possible missing preposition found.
Context: ...ema has default value or is required 2. Coerce value to the correct type otherwise 3. ...
(AI_HYDRA_LEO_MISSING_TO)
[typographical] ~95-~95: Consider adding a comma here.
Context: ...hat error is returned. - If catch is active any error triggers it and stops the exe...
(IF_THAT_S_NOT_POSSIBLE_COMMA)
docs/docs/core-design-decisions.md
[uncategorized] ~12-~12: Possible missing comma found.
Context: ...raps around an error and adds a message field which is text that can be shown to the ...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~12-~12: Possible missing comma found.
Context: ...t can be shown to the user. For more on this see Errors - You should not ...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/docs/core-concepts/1-anatomy-of-schema.md
[uncategorized] ~27-~27: A comma might be missing here.
Context: ...f it is required and the data is a zero value the schema will return a [ZogIssue](/er...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~31-~31: A comma might be missing here.
Context: ...(value)` sets a catch value. If this is set it will "catch" any errors or ZogIssues...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[uncategorized] ~31-~31: Possible missing comma found.
Context: ... code will automatically exit. For more information checkout the [parsing execution structu...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~53-~53: The verb “is” doesn’t seem to fit in this context, “are” is probably more formally correct.
Context: ...tests) page. ## Transforms Transforms is a list of function that are applied to ...
(AI_HYDRA_LEO_CPT_IS_ARE)
[uncategorized] ~53-~53: The grammatical number of this noun doesn’t look right. Consider replacing it.
Context: ... ## Transforms Transforms is a list of function that are applied to the data at any poi...
(AI_EN_LECTOR_REPLACEMENT_NOUN_NUMBER)
[typographical] ~60-~60: Consider adding a comma here.
Context: ...taPtr T, ctx Ctx) error ``` As you can see the function takes a pointer to the dat...
(AS_YOU_CAN_SEE_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: test (1.22.x, ubuntu-latest)
- GitHub Check: Cloudflare Pages
🔇 Additional comments (11)
docs/docs/core-concepts/parsing-table.tsx (6)
191-202: Updated requiredError behavior for Bool() schema: The entries fordata: '""'(line 191) anddata: '" "'(line 197) now haverequiredError: "no". This accurately reflects that empty or whitespace-only inputs no longer trigger a required error by default.
260-272: Updated requiredError behavior for String() schema: The entries for empty""and" "(lines 261 and 268) are updated torequiredError: "no", aligning with the optional-by-default policy.
309-321: Updated requiredError behavior for Int() schema: The cases fordata: '""'anddata: '" "'(lines 310 and 317) now setrequiredError: "no", correctly reflecting no required error for empty or whitespace-only inputs.
372-384: Updated requiredError behavior for Float() schema: The empty string ("") and whitespace (" ") entries (lines 373 and 380) now haverequiredError: "no", consistent with updated documentation.
420-432: Updated requiredError behavior for Time() schema: Changed the empty""and" "cases (lines 422 and 429) torequiredError: "no", aligning with the new default behavior.
470-482: Updated requiredError behavior for Slice() schema: The cases fordata: '""'anddata: '" "'(lines 471 and 478) now setrequiredError: "no", reflecting no required error for empty or space-only slices.docs/docs/getting-started.md (1)
113-113: Approve updated section title: The new header “7 Transform Data without limits” clearly reflects the unified transformation approach.README.md (1)
85-85: Approved: Clarification maintained for optional fields.
The note explaining that empty strings are skipped and fields are optional by default is clear and consistent with the behavior described later.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
85-85: Hard tabs
Column: 1(MD010, no-hard-tabs)
docs/docs/custom-tests.md (1)
73-82: Approve generic test function signature update.
Updating toz.Test[any]and usingval.(*User)aligns with Go generics and improves clarity on pointer usage.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
74-74: Hard tabs
Column: 1(MD010, no-hard-tabs)
75-75: Hard tabs
Column: 1(MD010, no-hard-tabs)
76-76: Hard tabs
Column: 1(MD010, no-hard-tabs)
77-77: Hard tabs
Column: 1(MD010, no-hard-tabs)
docs/docs/core-concepts/1-anatomy-of-schema.md (2)
10-11: Approve updated method chaining order.
Reordering.Trim()before.Min()and.Required()clarifies the sequence in which transformations and tests run, improving readability.
69-78: Approve unifiedTransformusage example.
The snippet effectively demonstrates both field-level and struct-levelTransformchaining, replacing the earlierPostTransformpattern.
| schema := z.Preprocess(func(data any, ctx z.Ctx) ([]string, error) { | ||
| s := data.(string) // don't do this, actually check the type | ||
| return strings.Split(s, ","), nil | ||
| }).PostTransform(func(destPtr any, ctx z.Ctx) error { | ||
| s := destPtr.(*[]string) | ||
| for i, v := range *s { | ||
| (*s)[i] = strings.TrimSpace(v) | ||
| } | ||
| return nil | ||
| }).Parse("[email protected],[email protected]", &dest) // dest = [[email protected] [email protected]] | ||
| }, z.Slice(z.String().Trim().Email().Required())) |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Guard type assertion to avoid panic: The inline type assertion data.(string) can panic if data isn't a string. Use the comma-ok idiom and remove hard tabs:
- s := data.(string) // don't do this, actually check the type
+ s, ok := data.(string)
+ if !ok {
+ return nil, fmt.Errorf("expected string input, got %T", data)
+ }📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| schema := z.Preprocess(func(data any, ctx z.Ctx) ([]string, error) { | |
| s := data.(string) // don't do this, actually check the type | |
| return strings.Split(s, ","), nil | |
| }).PostTransform(func(destPtr any, ctx z.Ctx) error { | |
| s := destPtr.(*[]string) | |
| for i, v := range *s { | |
| (*s)[i] = strings.TrimSpace(v) | |
| } | |
| return nil | |
| }).Parse("[email protected],[email protected]", &dest) // dest = [[email protected] [email protected]] | |
| }, z.Slice(z.String().Trim().Email().Required())) | |
| schema := z.Preprocess(func(data any, ctx z.Ctx) ([]string, error) { | |
| s, ok := data.(string) | |
| if !ok { | |
| return nil, fmt.Errorf("expected string input, got %T", data) | |
| } | |
| return strings.Split(s, ","), nil | |
| }, z.Slice(z.String().Trim().Email().Required())) |
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
118-118: Hard tabs
Column: 1
(MD010, no-hard-tabs)
119-119: Hard tabs
Column: 1
(MD010, no-hard-tabs)
docs/docs/reference.md
Outdated
| z.Preprocess() | ||
| // Usage: | ||
| z.Preprocess(func(data any, ctx z.Ctx) (any, error) { | ||
| s := data.(string) | ||
| return strings.Split(s, ","), nil | ||
| }, z.Slice(z.String()))) | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Correct parentheses and add import.
The example has an extra closing parenthesis and omits the strings import. Update to:
import "strings"
schema := z.Preprocess(
func(data any, ctx z.Ctx) (any, error) {
s := data.(string)
return strings.Split(s, ","), nil
},
z.Slice(z.String()),
)🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
84-84: Hard tabs
Column: 1
(MD010, no-hard-tabs)
85-85: Hard tabs
Column: 1
(MD010, no-hard-tabs)
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/docs/core-concepts/3-parsing.mdx (2)
87-87: Avoid weak intensifier for clearer tone
Replace “quite simple” with a more precise adjective to strengthen the prose.- Parsing execution structure is quite simple. It just does roughly this: + Parsing execution structure is straightforward. It follows these steps:🧰 Tools
🪛 LanguageTool
[style] ~87-~87: As an alternative to the over-used intensifier ‘quite’, consider replacing this phrase.
Context: ...ructure Parsing execution structure is quite simple. It just does roughly this: 1. Check f...(EN_WEAK_ADJECTIVE)
90-96: Improve clarity and fix grammar in bullet list
- Line 90 is wordy and missing articles; rephrase for readability.
- Line 95 needs a comma after “active” for correct punctuation.
- - If nil take into account if schema has default value or is required + - If nil, check whether the schema has a default value or is marked as required - - If catch is active any error triggers it and stops the execution. + - If catch is active, any error triggers it and stops the execution.🧰 Tools
🪛 LanguageTool
[style] ~90-~90: ‘take into account’ might be wordy. Consider a shorter alternative.
Context: ...is: 1. Check for nil value - If nil take into account if schema has default value or is requi...(EN_WORDINESS_PREMIUM_TAKE_INTO_ACCOUNT)
[uncategorized] ~90-~90: You might be missing the article “the” here.
Context: ... value - If nil take into account if schema has default value or is required 2. Coe...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~90-~90: You might be missing the article “a” here.
Context: ... If nil take into account if schema has default value or is required 2. Coerce value to...(AI_EN_LECTOR_MISSING_DETERMINER_A)
[typographical] ~95-~95: Consider adding a comma here.
Context: ...hat error is returned. - If catch is active any error triggers it and stops the exe...(IF_THAT_S_NOT_POSSIBLE_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/docs/core-concepts/3-parsing.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/docs/core-concepts/3-parsing.mdx
[style] ~87-~87: As an alternative to the over-used intensifier ‘quite’, consider replacing this phrase.
Context: ...ructure Parsing execution structure is quite simple. It just does roughly this: 1. Check f...
(EN_WEAK_ADJECTIVE)
[style] ~90-~90: ‘take into account’ might be wordy. Consider a shorter alternative.
Context: ...is: 1. Check for nil value - If nil take into account if schema has default value or is requi...
(EN_WORDINESS_PREMIUM_TAKE_INTO_ACCOUNT)
[uncategorized] ~90-~90: You might be missing the article “the” here.
Context: ... value - If nil take into account if schema has default value or is required 2. Coe...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~90-~90: You might be missing the article “a” here.
Context: ... If nil take into account if schema has default value or is required 2. Coerce value to...
(AI_EN_LECTOR_MISSING_DETERMINER_A)
[typographical] ~95-~95: Consider adding a comma here.
Context: ...hat error is returned. - If catch is active any error triggers it and stops the exe...
(IF_THAT_S_NOT_POSSIBLE_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Cloudflare Pages
| 7. PostTransforms -> Run all postTransforms on the value. | ||
| - On error you return: aborts and adds your error to the list of [ZogIssues](/errors) | ||
| - Only run on valid values. Won't run if a [ZogIssue](/errors) was created before the postTransforms | ||
|  |
There was a problem hiding this comment.
Fix typo in image alt text
The alt text “Parsig n” is misspelled. Correct it to “Parsing” so the image reference is accurate.
- 
+ 📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
|  | |
|  |
🤖 Prompt for AI Agents (early access)
In docs/docs/core-concepts/3-parsing.mdx at line 97, fix the typo in the image alt text by changing "Parsig n" to "Parsing" to ensure the alt text accurately describes the image.
Summary by CodeRabbit