sanity-advanced-validators 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,10 @@
+*🚓 Never trust a user! 👮*
+
 # Sanity Advanced Validators
 
-This package includes a set of Sanity validators for aggressive and weird edge cases. Please let me know if you find these helpful!
+This package includes a set of Sanity validators for aggressive and weird edge cases. *Maintain sanity with micro-managed validation.*
 
-Note that every validator can accept an optional custom error message as its last parameter. `minDimensions` lists one example; all the others work the same way.
+Note: Every validator can accept an optional custom error message as its last parameter. See [minDimensions](#minDimensions) for an example.
 
 ## Tools
 
@@ -18,7 +20,10 @@ Note that every validator can accept an optional custom error message as its las
 
 ## 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 either MP4 or MOV, and have a poster image that's between 1250x800 and 2500x1600 in size.
+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
 
 ```typescript
 const Page = defineType({
@@ -51,7 +56,7 @@ const Page = defineType({
 
 ## Examples
 
-### fileType
+### fileExtension
 
 Enforces that an uploaded file asset is of a certain format.
 
@@ -65,7 +70,7 @@ const Page = defineType({
     defineField({
       name: "catalog",
       type: "file",
-      validation: (rule) => rule.custom(fileType("pdf")),
+      validation: (rule) => rule.custom(fileExtension("pdf")),
     }),
     defineField({
       name: "video",
@@ -76,6 +81,14 @@ 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.
@@ -84,17 +97,14 @@ Enforces that an uploaded image asset is at minimum certain dimensions.
 import { minDimensions } from "sanity-advanced-validation"
 
 const ImageWithCaption = defineType({
-  name: "imageWithCaption",
+  name: "article",
   type: "object",
   fields: [
+    // …
     defineField({
-      name: "caption",
-      type: "string",
-    }),
-    defineField({
-      name: "image",
+      name: "heroImage",
       type: "image",
-      validation: (rule) => rule.custom(minDimensions({ x: 100, y: 100 })),
+      validation: (rule) => rule.custom(minDimensions({ x: 1200, y: 800 })),
     }),
   ],
 })
@@ -104,60 +114,68 @@ You can also enforce on only one dimension, or feed a custom error message:
 
 ```typescript
 defineField({
-  name: "image",
+  name: "heroImage",
   type: "image",
-  description: "At least 100px wide; as tall as you like.",
+  description: "At least 1200px wide; as tall as you like.",
   validation: (rule) => rule.custom(
     minDimensions(
-      { x: 100 }, 
+      { x: 1200 }, 
       "Uh oh, your image is {width} pixels wide. That’s less than {x}!"
     )
   ),
 })
 ```
 
+#### 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
+```
+
+---
+
+
 ### maxDimensions
 
 Enforces that an uploaded image asset is at most certain dimensions.
 
 ```typescript
-import { maxDimensions } from "sanity-advanced-validation"
-
-const ImageWithCaption = defineType({
-  name: "imageWithCaption",
-  type: "object",
-  fields: [
-    defineField({
-      name: "caption",
-      type: "string",
-    }),
-    defineField({
-      name: "image",
-      type: "image",
-      validation: (rule) => rule.custom(maxDimensions({ x: 2000, y: 2000 })),
-    }),
-  ],
-})
+defineField({
+  name: "heroImage",
+  type: "image",
+  validation: (rule) => rule.custom(maxDimensions({ x: 2400, y: 1600 })),
+}),
 ```
 
 Chain for min and max dimensions:
 
 ```typescript
 defineField({
-  name: "image",
+  name: "heroImage",
   type: "image",
-  description: "Min: 100x100, max: 2000x2000.",
+  description: "Min: 1200x800, max: 2400x1600.",
   validation: (rule) =>
     rule
       .required()
-      .custom(minDimensions({ x: 1000, y: 1000 }))
-      .custom(maxDimensions({ x: 2000, y: 2000 })),
+      .custom(minDimensions({ x: 1200, y: 800 }))
+      .custom(maxDimensions({ x: 2400, y: 1600 })),
 })
 ```
 
+#### 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
 
-For a given object that has multiple fields, mark a field as `required` if a sibling has a particular value.
+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. 
 
 _note:_ This does not work for slugs, because they have to match a nested `.current` value. Use the [requiredIfSlugEq validator](#requiredIfSlugEq) instead.
 
@@ -186,15 +204,15 @@ defineType({
         list: [
           'javascript', 'rust', 'python', 'swift'
         ]
-      }
+      },
+      validation: rule => rule.custom(requiredIfSiblingEq('occupation', 'software engineer')),
       hidden: ({parent}) => parent.occuption !== 'software engineer',
-      validation: rule => rule.custom(requiredIfSiblingEq('occupation', 'software engineer'))
     }),
   ],
 })
 ```
 
-This also works for null. It’s very effective!
+“If not that, then this.” This also works for null.
 
 ```typescript
 defineType({
@@ -215,7 +233,7 @@ defineType({
       validation: rule => rule.custom(requiredIfSiblingEq(
         'email', 
         null, 
-        "If you don’t have an email address, please provide a phone number."
+        "If you don’t have an email address, a phone number is required."
       ))
     })
   ],
@@ -233,34 +251,38 @@ defineType({
       name: 'name',
       type: 'string'
     }),
-    defineType({
-      name: 'person',
-      type: 'object',
-      fields: [
-        defineField({
-          name: 'name',
-          type: 'string'
-        }),
-        defineField({
-          name: 'occupation',
-          type: 'string',
-          options: {
-            list: ['doctor', 'lawyer', 'software engineer']
-          }
-        }),
-        defineField({
-          name: 'explanation',
-          description: 'Why are you wasting your life this way?',
-          type: 'text',
-          hidden: ({parent}) => parent.occuption === 'software engineer',
-          validation: rule => rule.custom(requiredIfSiblingEq('occupation', ['doctor', 'lawyer']))
-        })
-      ],
+    defineField({
+      name: 'name',
+      type: 'string'
+    }),
+    defineField({
+      name: 'occupation',
+      type: 'string',
+      options: {
+        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',
     })
   ],
 })
 ```
 
+#### 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.
@@ -287,15 +309,24 @@ defineType({
     })
     defineField({
       name: 'why',
-      description: 'Why are you wasting your life this way?',
-      type: 'text',
-      hidden: ({parent}) => parent.occuption === 'software engineer',
+      description: 'How many years will you spend paying off your degree?',
+      type: 'number',
       validation: rule => rule.custom(requiredIfSiblingNeq('occupation', '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.
+```
+
+---
+
+
 ### requiredIfSlugEq
 
 Require for matching slugs.
@@ -317,7 +348,7 @@ defineType({
       of: [
         {type: 'qaItem'}
       ],
-      validation: rule => rule.custom(requiredIfSlugEq('faq'))
+      validation: rule => rule.custom(requiredIfSlugEq('faq')),
       hidden: ({parent}) => parent.slug.current !== 'faq'
     })
   ]
@@ -333,6 +364,16 @@ 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.
@@ -350,25 +391,35 @@ defineType({
     }),
     defineField({
       name: 'subnav',
-      description: 'Subnav is required on documents that aren't '/home'`,
+      description: `Subnav is required on documents that aren’t '/home'`,
       type: 'array',
       of: [
         {type: 'navLink'}
       ],
-      validation: rule => rule.custom(requiredIfSlugNeq('home'))
+      validation: rule => rule.custom(requiredIfSlugNeq('home')),
       hidden: ({parent}) => parent.slug.current !== 'home'
     })
   ]
 })
 ```
 
+#### 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.
+```
+
+---
+
+
 ### referencedDocumentRequires
 
-You might want to enforce some validation on a referred document. This validator enforces that a given value is not null in the referenced document.
+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
 defineField({
-  name: 'refferedArticle',
+  name: 'referredArticle',
   description: 'An article (must include a valid poster image)',
   type: 'reference',
   to: [{type: 'article'}],
@@ -376,6 +427,16 @@ 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…
@@ -448,7 +509,20 @@ 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.
 
-_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 the `hidden` context that’s similar to the one fed to the `ValidationContext` (todo: type this correctly). Wouldn’t this be cool?
+
+#### 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?
 
 ```typescript
 defineField({
@@ -463,18 +537,37 @@ defineField({
 })
 ```
 
+---
+
 ## Extending these and writing your own
 
 Most of these validators rely on a function called `getSibling()`. If you’re thinking about picking this apart and writing your own custom validator, take a close look at how these validators use it.
 
 ## Upcoming
 
+### Nested pathfinders
+
 Since building these validator, I took to putting my slugs in a metadata object. I need to update `requiredIfSlugEq` to accept a path, like `requiredIfSlugEq('metadata.slug', 'some-values')`.
 
 This pathfinding should be added to any validator that takes a sibling, like `requiredIfSiblingEq`. It can probably be snapped into `getSibling`.
 
 While I’m at it, there’s a possibility that `getSibling` could detect the target type. If that type is `slug`, then it could add `current` to the path, and then I can deprecate `requiredIfSlugEq` altogether.
 
+### Image and File checks
+
+`minDimensions`, `maxDimensions`, and `fileExtension` should check to see if the field is of type `image` or `file`.
+
+Some of the other checks should probably make sure the field is _not_ `image` or `file`.
+
+### new referencedDocumentFieldEq validator
+
+```
+// only articles by Jimmy Olsen
+rule => rule.custom(referencedDocumentFieldEq('article', 'author', 'Jimmy Olsen'))
+// only articles whose authors are not null. replaces  `referencedDocumentRequires`.
+rule => rule.custom(referencedDocumentFieldNeq('article', 'author', null))
+```
+
 ## MOAR
 
 Do you have any ideas or edge cases that these validators don’t cover? Leave an issue, maybe I can hack it out.

package/package.json

@@ -1,6 +1,6 @@
 {
   "package-name": "sanity-advanced-validators",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Advanced input validation tools for Sanity CMS.",
   "author": "Eric_WVGG",
   "license": "MIT",