sanity-advanced-validators 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eric Jacobsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,474 @@
+# Sanity Advanced Validators
+
+(note: this is a WIP, I don’t know a lot about publishing NPM packages, hopefully coming soon)
+
+This package includes a set of Sanity validators for aggressive and weird edge cases. Please let me know if you find these helpful!
+
+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.
+
+## Tools
+
+- [fileExtension](#fileExtension)
+- [minDimensions](#minDimensions)
+- [maxDimensions](#maxDimensions)
+- [requiredIfPeerEq](#requiredIfPeerEq)
+- [requiredIfPeerNeq](#requiredIfPeerNeq)
+- [requiredIfSlugEq](#requiredIfSlugEq)
+- [requiredIfSlugNeq](#requiredIfSlugNeq)
+- [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 either MP4 or MOV, and have a poster image that's between 1250x800 and 2500x1600 in size.
+
+```typescript
+const Page = defineType({
+  name: "page",
+  type: "document",
+  fields: [
+    defineField({
+      name: 'slug',
+      type: 'slug'
+    }),
+    defineField({
+      name: "someVideoFile",
+      type: "file",
+      validation: (rule) =>
+        rule.requiredIfSlugEq('about')
+          .custom(fileExtension(['mp4', 'mov']))
+    })
+    defineField({
+      name: "posterImage",
+      type: "image",
+      hidden: ({ parent }) => parent.someVideoFile === null,
+      validation: (rule) =>
+        rule.requiredIfPeerNeq('someVideoFile', null)
+          .custom(minDimensions({ x: 1250, y: 800 }))
+          .custom(maxDimensions({ x: 2500, y: 1600 })),
+    })
+  ]
+})
+```
+
+## Examples
+
+### fileType
+
+Enforces that an uploaded file asset is of a certain format.
+
+```typescript
+import { fileExtension } from "sanity-advanced-validation"
+
+const Page = defineType({
+  name: "page",
+  type: "document",
+  fields: [
+    defineField({
+      name: "catalog",
+      type: "file",
+      validation: (rule) => rule.custom(fileType("pdf")),
+    }),
+    defineField({
+      name: "video",
+      type: "file",
+      validation: (rule) => rule.custom(fileExtension(["mp4", "mov", "webm"])),
+    }),
+  ],
+})
+```
+
+### minDimensions
+
+Enforces that an uploaded image asset is at minimum certain dimensions.
+
+```typescript
+import { minDimensions } 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(minDimensions({ x: 100, y: 100 })),
+    }),
+  ],
+})
+```
+
+You can also enforce on only one dimension, or feed a custom error message:
+
+```typescript
+defineField({
+  name: "image",
+  type: "image",
+  description: "At least 100px wide; as tall as you like.",
+  validation: (rule) => rule.custom(
+    minDimensions(
+      { x: 100 }, 
+      "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.
+
+```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 })),
+    }),
+  ],
+})
+```
+
+Chain for min and max dimensions:
+
+```typescript
+defineField({
+  name: "image",
+  type: "image",
+  description: "Min: 100x100, max: 2000x2000.",
+  validation: (rule) =>
+    rule
+      .required()
+      .custom(minDimensions({ x: 1000, y: 1000 }))
+      .custom(maxDimensions({ x: 2000, y: 2000 })),
+})
+```
+
+### requiredIfPeerEq
+
+For a given object that has multiple fields, mark a field as `required` if a peer has a particular value.
+
+_note:_ This does not work for slugs, because they have to match a nested `.current` value. Use the [requiredIfSlugEq validator](#requiredIfSlugEq) instead.
+
+```typescript
+import {requiredIfPeerEq} from 'sanity-advanced-validation'
+
+defineType({
+  name: 'person',
+  type: 'object',
+  fields: [
+    defineField({
+      name: 'name',
+      type: 'string'
+    }),
+    defineField({
+      name: 'occupation',
+      type: 'string',
+      options: {
+        list: ['doctor', 'lawyer', 'software engineer']
+      }
+    })
+    defineField({
+      name: 'favoriteLanguage',
+      type: 'string',
+      options: {
+        list: [
+          'javascript', 'rust', 'python', 'swift'
+        ]
+      }
+      hidden: ({parent}) => parent.occuption !== 'software engineer',
+      validation: rule => rule.custom(requiredIfPeerEq('occupation', 'software engineer'))
+    }),
+  ],
+})
+```
+
+This also works for null. It’s very effective!
+
+```typescript
+defineType({
+  name: 'person',
+  type: 'object',
+  fields: [
+    defineField({
+      name: 'name',
+      type: 'string'
+    }),
+    defineField({
+      name: 'email',
+      type: 'string',
+    })
+    defineField({
+      name: 'phone',
+      type: 'string',
+      validation: rule => rule.custom(requiredIfPeerEq(
+        'email', 
+        null, 
+        "If you don’t have an email address, please provide a phone number."
+      ))
+    })
+  ],
+})
+```
+
+And it even works for arrays.
+
+```typescript
+defineType({
+  name: 'person',
+  type: 'object',
+  fields: [
+    defineField({
+      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(requiredIfPeerEq('occupation', ['doctor', 'lawyer']))
+        })
+      ],
+    })
+  ],
+})
+```
+
+### requiredIfPeerNeq
+
+For a given object that has multiple fields, mark a field as `required` if a peer 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
+import {requiredIfPeerNeq} from 'sanity-advanced-validation'
+
+defineType({
+  name: 'person',
+  type: 'object',
+  fields: [
+    defineField({
+      name: 'name',
+      type: 'string'
+    }),
+    defineField({
+      name: 'occupation',
+      type: 'string',
+      options: {
+        list: ['doctor', 'lawyer', 'software engineer']
+      }
+    })
+    defineField({
+      name: 'why',
+      description: 'Why are you wasting your life this way?',
+      type: 'text',
+      hidden: ({parent}) => parent.occuption === 'software engineer',
+      validation: rule => rule.custom(requiredIfPeerNeq('occupation', 'software engineer'))
+    }),
+  ],
+})
+```
+
+### requiredIfSlugEq
+
+Require for matching slugs.
+
+```typescript
+import {requiredIfSlugEq} from 'sanity-advanced-validation'
+
+defineType({
+  name: 'page',
+  type: 'document',
+  fields: [
+    defineField({
+      name: 'slug',
+      type: 'slug'
+    }),
+    defineField({
+      name: 'questionsAndAnswers',
+      type: 'array',
+      of: [
+        {type: 'qaItem'}
+      ],
+      validation: rule => rule.custom(requiredIfSlugEq('faq'))
+      hidden: ({parent}) => parent.slug.current !== 'faq'
+    })
+  ]
+})
+```
+
+And this can apply to multiple slugs…
+
+```typescript
+defineField({
+  name: "questionsAndAnswers",
+  validation: (rule) => rule.custom(requiredIfSlugEq(["faq", "about"])),
+}),
+```
+
+### requiredIfSlugNeq
+
+Require fields on pages that don't match one or more slugs.
+
+```typescript
+import {requiredIfSlugNeq} from 'sanity-advanced-validation'
+
+defineType({
+  name: 'page',
+  type: 'document',
+  fields: [
+    defineField({
+      name: 'slug',
+      type: 'slug'
+    }),
+    defineField({
+      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'
+    })
+  ]
+})
+```
+
+### 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.
+
+```typescript
+defineField({
+  name: 'refferedArticle',
+  description: 'An article (must include a valid poster image)',
+  type: 'reference',
+  to: [{type: 'article'}],
+  validation: (rule) => rule.custom(referencedDocumentRequires('article', 'poster')),
+}),
+```
+
+### maxDepth
+
+It can be useful to have a nested type. This often comes up when making some kind of navigation tree, like…
+
+```
+- Home
+- About
+- Articles
+  - First Article
+  - Second Article
+  - Articles about Trees
+    - Article about Elm Trees
+    - Article about Willow Trees
+```
+
+Sanity can handle this without breaking a sweat:
+
+```typescript
+const navigation = defineType({
+  name: "navigation",
+  type: "document",
+  fields: [
+    defineField({
+      name: "links",
+      type: "array",
+      of: [{ type: navLink }],
+    }),
+  ],
+})
+
+const navLink = defineType({
+  name: "navLink",
+  type: "object",
+  fields: [
+    defineField({
+      name: "link",
+      type: "url",
+    }),
+    defineField({
+      name: "label",
+      type: "string",
+    }),
+    defineField({
+      name: "subnav",
+      type: "array",
+      of: [{ type: navigation }], // < circular reference
+    }),
+  ],
+})
+```
+
+… but your users might get a little stupid with this, and you may want to enforce navigations only going _n_ layers deep.
+
+```typescript
+import { maxDepth } from "sanity-advanced-validation"
+
+const navLink = defineType({
+  // …
+  fields: [
+    // …
+    defineField({
+      name: "subnav",
+      type: "array",
+      of: [{ type: navigation }],
+      validation: (rule) => rule.custom(maxDepth(3, "subnav")),
+    }),
+  ],
+})
+```
+
+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?
+
+```typescript
+defineField({
+  name: "subnav",
+  type: "array",
+  of: [{ type: navigation }],
+  hidden: ({ path }) => {
+    let regex = new RegExp(String.raw`topLevelItems|subNav`)
+    const paths = context.path.filter((e) => e.match(/topLevelItems|subnav/))
+    return paths.length > 3
+  },
+})
+```
+
+## Extending these and writing your own
+
+Most of these validators rely on a function called `getPeer()`. If you’re thinking about picking this apart and writing your own custom validator, take a close look at how these validators use it.
+
+## 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/dist/fileExtension.cjs

@@ -0,0 +1,41 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/fileExtension.ts
+var fileExtension_exports = {};
+__export(fileExtension_exports, {
+  fileExtension: () => fileExtension
+});
+module.exports = __toCommonJS(fileExtension_exports);
+var import_asset_utils = require("@sanity/asset-utils");
+var fileExtension = (validFileExtension, message = `Image must be of type {validFileExtension}`) => (value) => {
+  if (!value || !value.asset) {
+    return true;
+  }
+  const validExtensions = typeof validFileExtension === "string" ? [validFileExtension] : validFileExtension;
+  const filetype = (0, import_asset_utils.getExtension)(value.asset._ref);
+  if (!validExtensions.includes(filetype)) {
+    return message.replace("{validFileExtension}", validExtensions.join(", or "));
+  }
+  return true;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fileExtension
+});