sanity-advanced-validators 0.3.1 → 0.4.0

package/README.md

@@ -1,10 +1,8 @@
-*🚓 Never trust a user! 👮*
+_🚓 Never trust a user! 👮_
 
 # Sanity Advanced Validators
 
-This package includes a set of Sanity validators for aggressive and weird edge cases. *Maintain sanity with micro-managed validation.*
-
-Note: Every validator can accept an optional custom error message as its last parameter. See [minDimensions](#minDimensions) for an example.
+This package includes a set of Sanity validators for aggressive and weird edge cases. _Maintain sanity with micro-managed validation._
 
 ## Tools
 
@@ -15,12 +13,14 @@ Note: Every validator can accept an optional custom error message as its last pa
 - [requiredIfSiblingNeq](#requiredIfSiblingNeq)
 - [requiredIfSlugEq](#requiredIfSlugEq)
 - [requiredIfSlugNeq](#requiredIfSlugNeq)
+- [regex](#regex) 🆕
 - [referencedDocumentRequires](#referencedDocumentRequires)
 - [maxDepth](#maxDepth)
 
 ## Mega-example
 
 Imagine that you’ve got a document that has an optional video file, but…
+
 - it’s required on the `/about` page
 - if the video exists, it must be either **MP4** or **MOV**
 - and there must be a poster image that's between **1250x800** and **2500x1600** pixels in size
@@ -38,7 +38,7 @@ const Page = defineType({
       name: "someVideoFile",
       type: "file",
       validation: (rule) =>
-        rule.custom(requiredIfSlugEq('about'))
+        rule.custom(requiredIfSlugEq('about', 'A video is required if {slugKey} is {operand}.'))
           .custom(fileExtension(['mp4', 'mov']))
     })
     defineField({
@@ -60,6 +60,11 @@ const Page = defineType({
 
 Enforces that an uploaded file asset is of a certain format.
 
+```typescript
+fileType: string | Array<string>,
+message?: string // optional custom error message; replaces {validFileExtension} with fileType (flattened)
+```
+
 ```typescript
 import { fileExtension } from "sanity-advanced-validation"
 
@@ -81,17 +86,16 @@ const Page = defineType({
 })
 ```
 
-#### parameters
-```typescript
-fileType: string | Array<string>, 
-message?: string // optional custom error message; replaces {validFileExtension} with fileType (flattened)
-```
-
 ---
 
 ### minDimensions
 
-Enforces that an uploaded image asset is at minimum certain dimensions.
+Enforces that an uploaded image asset is at minimum certain dimensions. You can test on both, just x, or just y.
+
+```typescript
+dimensions: {x?: number, y?: number},
+message?: string // optional custom error message; replaces {x} and {y} with your dimension requirements, and {width} and {height} with submitted image dimensions
+```
 
 ```typescript
 import { minDimensions } from "sanity-advanced-validation"
@@ -110,35 +114,17 @@ const ImageWithCaption = defineType({
 })
 ```
 
-You can also enforce on only one dimension, or feed a custom error message:
+---
 
-```typescript
-defineField({
-  name: "heroImage",
-  type: "image",
-  description: "At least 1200px wide; as tall as you like.",
-  validation: (rule) => rule.custom(
-    minDimensions(
-      { x: 1200 }, 
-      "Uh oh, your image is {width} pixels wide. That’s less than {x}!"
-    )
-  ),
-})
-```
+### maxDimensions
+
+Enforces that an uploaded image asset is at most certain dimensions. You can test on both, just x, or just y.
 
-#### parameters
 ```typescript
-dimensions: {x?: number, y?: number}, 
+dimensions: {x?: number, y?: number},
 message?: string // optional custom error message; replaces {x} and {y} with your dimension requirements, and {width} and {height} with submitted image dimensions
 ```
 
----
-
-
-### maxDimensions
-
-Enforces that an uploaded image asset is at most certain dimensions.
-
 ```typescript
 defineField({
   name: "heroImage",
@@ -162,23 +148,22 @@ defineField({
 })
 ```
 
-#### parameters
-```typescript
-dimensions: {x?: number, y?: number}, 
-message?: string // optional custom error message; replaces {x} and {y} with your dimension requirements, and {width} and {height} with submitted image dimensions
-```
-
 ---
 
-
 ### requiredIfSiblingEq
 
-Mark a field as `required` if a sibling field has a particular value. This is the validator we use most. *It’s super effective!*
+Mark a field as `required` if a sibling field has a particular value. This is the validator we use most. _It’s super effective!_
 
-This is handy if you have a field that is hidden under some circumstances, but is `required()` when it’s visible. 
+This is handy if you have a field that is hidden under some circumstances, but is `required()` when it’s visible.
 
 _note:_ This does not work for slugs, because they have to match a nested `.current` value. Use the [requiredIfSlugEq validator](#requiredIfSlugEq) instead.
 
+```typescript
+key: string, // name of sibling
+operand: string | number | null | Array<string, number, null> // value that you’re testing for (i.e. if 'name' === operand)
+message?: string // optional custom error message; replaces {key} and {operand} with your input, and {siblingValue} with the value of the sibling you’re testing against.
+```
+
 ```typescript
 import {requiredIfSiblingEq} from 'sanity-advanced-validation'
 
@@ -231,8 +216,8 @@ defineType({
       name: 'phone',
       type: 'string',
       validation: rule => rule.custom(requiredIfSiblingEq(
-        'email', 
-        null, 
+        'email',
+        null,
         "If you don’t have an email address, a phone number is required."
       ))
     })
@@ -244,51 +229,49 @@ And it even works for arrays.
 
 ```typescript
 defineType({
-  name: 'person',
-  type: 'object',
+  name: "person",
+  type: "object",
   fields: [
     defineField({
-      name: 'name',
-      type: 'string'
+      name: "name",
+      type: "string",
     }),
     defineField({
-      name: 'name',
-      type: 'string'
+      name: "name",
+      type: "string",
     }),
     defineField({
-      name: 'occupation',
-      type: 'string',
+      name: "occupation",
+      type: "string",
       options: {
-        list: ['doctor', 'lawyer', 'software engineer']
-      }
+        list: ["doctor", "lawyer", "software engineer"],
+      },
     }),
     defineField({
-      name: 'explanation',
-      description: 'Why are you wasting your life this way?',
-      type: 'text',
-      validation: rule => rule.custom(requiredIfSiblingEq('occupation', ['doctor', 'lawyer'])),
-      hidden: ({parent}) => parent.occuption === 'software engineer',
-    })
+      name: "explanation",
+      description: "Why are you wasting your life this way?",
+      type: "text",
+      validation: (rule) => rule.custom(requiredIfSiblingEq("occupation", ["doctor", "lawyer"])),
+      hidden: ({ parent }) => parent.occuption === "software engineer",
+    }),
   ],
 })
 ```
 
-#### parameters
-```typescript
-key: string, // name of sibling
-operand: string | number | null | Array<string, number, null> // value that you’re testing for (i.e. if 'name' === operand)
-message?: string // optional custom error message; replaces {key} and {operand} with your input, and {siblingValue} with the value of the sibling you’re testing against.
-```
-
 ---
 
-
 ### requiredIfSiblingNeq
 
 For a given object that has multiple fields, mark a field as `required` if a sibling does _not_ have a particular value.
 
 _note:_ This does not work for slugs, because they have to match a nested `.current` value. Use the [requiredIfSlugNeq validator](#requiredIfSlugNeq) instead.
 
+```typescript
+key: string, // name of sibling
+operand: string | number | null | Array<string, number, null> // value that you’re testing for (i.e. if 'name' === operand)
+message?: string // optional custom error message; replaces {key} and {operand} with your input, and {siblingValue} with the value of the sibling you’re testing against.
+```
+
 ```typescript
 import {requiredIfSiblingNeq} from 'sanity-advanced-validation'
 
@@ -317,41 +300,37 @@ defineType({
 })
 ```
 
-#### parameters
-```typescript
-key: string, // name of sibling
-operand: string | number | null | Array<string, number, null> // value that you’re testing for (i.e. if 'name' === operand)
-message?: string // optional custom error message; replaces {key} and {operand} with your input, and {siblingValue} with the value of the sibling you’re testing against.
-```
-
 ---
 
-
 ### requiredIfSlugEq
 
-Require for matching slugs.
+Mark a field as `required` for documents with matching slugs.
 
 ```typescript
-import {requiredIfSlugEq} from 'sanity-advanced-validation'
+operand: string | number | null | Array<string, number, null> // possible slug or slugs you’re testing
+key?: string, // name of sibling if not "slug"
+message?: string // optional custom error message; replaces {slugKey} and {operand} with your input, and {siblingSlugValue} with the value of the sibling you’re testing against.
+```
+
+```typescript
+import { requiredIfSlugEq } from "sanity-advanced-validation"
 
 defineType({
-  name: 'page',
-  type: 'document',
+  name: "page",
+  type: "document",
   fields: [
     defineField({
-      name: 'slug',
-      type: 'slug'
+      name: "slug",
+      type: "slug",
     }),
     defineField({
-      name: 'questionsAndAnswers',
-      type: 'array',
-      of: [
-        {type: 'qaItem'}
-      ],
-      validation: rule => rule.custom(requiredIfSlugEq('faq')),
-      hidden: ({parent}) => parent.slug.current !== 'faq'
-    })
-  ]
+      name: "questionsAndAnswers",
+      type: "array",
+      of: [{ type: "qaItem" }],
+      validation: (rule) => rule.custom(requiredIfSlugEq("faq")),
+      hidden: ({ parent }) => parent.slug.current !== "faq",
+    }),
+  ],
 })
 ```
 
@@ -364,59 +343,84 @@ defineField({
 }),
 ```
 
-#### parameters
-```typescript
-operand: string | number | null | Array<string, number, null> // possible slug or slugs you’re testing
-key?: string, // name of sibling if not "slug"
-message?: string // optional custom error message; replaces {slugKey} and {operand} with your input, and {siblingSlugValue} with the value of the sibling you’re testing against.
-```
-
 ---
 
-
 ### requiredIfSlugNeq
 
 Require fields on pages that don't match one or more slugs.
 
 ```typescript
-import {requiredIfSlugNeq} from 'sanity-advanced-validation'
+operand: string | number | null | Array<string, number, null> // possible slug or slugs you’re testing
+key?: string, // name of sibling if not "slug"
+message?: string // optional custom error message; replaces {slugKey} and {operand} with your input, and {siblingSlugValue} with the value of the sibling you’re testing against.
+```
+
+```typescript
+import { requiredIfSlugNeq } from "sanity-advanced-validation"
 
 defineType({
-  name: 'page',
-  type: 'document',
+  name: "page",
+  type: "document",
   fields: [
     defineField({
-      name: 'slug',
-      type: 'slug'
+      name: "slug",
+      type: "slug",
     }),
     defineField({
-      name: 'subnav',
+      name: "subnav",
       description: `Subnav is required on documents that aren’t '/home'`,
-      type: 'array',
-      of: [
-        {type: 'navLink'}
-      ],
-      validation: rule => rule.custom(requiredIfSlugNeq('home')),
-      hidden: ({parent}) => parent.slug.current !== 'home'
-    })
-  ]
+      type: "array",
+      of: [{ type: "navLink" }],
+      validation: (rule) => rule.custom(requiredIfSlugNeq("home")),
+      hidden: ({ parent }) => parent.slug.current !== "home",
+    }),
+  ],
 })
 ```
 
-#### parameters
+---
+
+### regex
+
+Easily test any value against a regular expression.
+
+Values can be of type string, number, boolean… even objects!
+
 ```typescript
-operand: string | number | null | Array<string, number, null> // possible slug or slugs you’re testing
-key?: string, // name of sibling if not "slug"
-message?: string // optional custom error message; replaces {slugKey} and {operand} with your input, and {siblingSlugValue} with the value of the sibling you’re testing against.
+pattern: RegExp // regular expression
+message?: string // optional custom error message; replaces {pattern} with your input and {value} as submitted field value
 ```
 
----
+```typescript
+defineField({
+  name: 'email',
+  type: 'string',
+  validation: (rule) => rule.custom(
+    regex(
+      /^([a-zA-Z0-9._%-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6})*$/, 
+      "“{value}” is not a valid email address."
+    )
+  ),
+}),
+```
 
+**Custom error messages are highly recommended here.** Without the custom message above, the default response would be:
+```
+“me@googlecom” does not match the pattern /^([a-zA-Z0-9._%-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6})*$/.
+```
+
+---
 
 ### referencedDocumentRequires
 
 You might want to enforce some validation on a referenced document. This validator enforces that a given value is not null in the referenced document.
 
+```typescript
+documentType: string // type of document you’re referring to
+field: string, // name of document field that is required
+message?: string // optional custom error message; replaces {documentType} and {field} with your input
+```
+
 ```typescript
 defineField({
   name: 'referredArticle',
@@ -427,16 +431,8 @@ defineField({
 }),
 ```
 
-#### parameters
-```typescript
-documentType: string // type of document you’re referring to
-field: string, // name of document field that is required
-message?: string // optional custom error message; replaces {documentType} and {field} with your input
-```
-
 ---
 
-
 ### maxDepth
 
 It can be useful to have a nested type. This often comes up when making some kind of navigation tree, like…
@@ -490,6 +486,12 @@ const navLink = defineType({
 
 … but your users might get a little stupid with this, and you may want to enforce navigations only going _n_ layers deep.
 
+```typescript
+maxDepth: number // maximum "depth" of embedding (including parent)
+key: string, // name of the field that includes the cursive value (i.e. the field’s own name)
+message?: string // optional custom error message; replaces {maxDepth} and {key} with your input
+```
+
 ```typescript
 import { maxDepth } from "sanity-advanced-validation"
 
@@ -509,17 +511,8 @@ const navLink = defineType({
 
 This will enforce that a subnav list can embed in a subnav, which can also be embedded in a subnav — but no further.
 
-
-#### parameters
-```typescript
-maxDepth: number // maximum "depth" of embedding (including parent)
-key: string, // name of the field that includes the cursive value (i.e. the field’s own name)
-message?: string // optional custom error message; replaces {maxDepth} and {key} with your input
-```
-
 ---
 
-
 #### Note to any Sanity dev who looks at this
 
 I’d love to include similar logic on my `hidden:` attribute, but I don’t think that’t possible without a `path` array in `hidden`’s `ConditionalPropertyCallbackContext` that’s similar to the one fed to the `ValidationContext` (todo: type this correctly). Wouldn’t this be cool?

package/package.json

@@ -1,6 +1,6 @@
 {
   "package-name": "sanity-advanced-validators",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Advanced input validation tools for Sanity CMS.",
   "author": "Eric_WVGG",
   "license": "MIT",
@@ -18,8 +18,8 @@
   "module": "./dist/index.cjs",
   "types": "./dist/index.d.ts",
   "files": [
-      "dist"
-   ],
+    "dist"
+  ],
   "dependencies": {
     "@sanity/asset-utils": "^2.2.1",
     "lodash-es": "^4.0.0",