@sanity/validation 6.12.0 → 6.13.0-next.17

package/README.md

@@ -5,9 +5,9 @@ Validates complete Sanity documents against a compiled Sanity schema.
 ```ts
 import {validateDocument, validationMarkerCodes} from '@sanity/validation'
 
-const markers = await validateDocument({document, schema, client})
+const result = await validateDocument({document, schema, client})
 
-for (const marker of markers) {
+for (const marker of result.markers) {
   if (marker.code === validationMarkerCodes.stringMinimumLength) {
     const {actualLength, minimumLength} = marker.details || {}
     if (typeof actualLength === 'number' && typeof minimumLength === 'number') {
@@ -16,7 +16,7 @@ for (const marker of markers) {
   }
 }
 
-const summary = markers
+const summary = result.markers
   .map((marker) => {
     const path = marker.path
       .map((segment) => (typeof segment === 'object' ? segment._key : segment))
@@ -27,26 +27,50 @@ const summary = markers
   .join('\n')
 ```
 
-Every returned marker includes a stable machine-readable `code` alongside its localized `message`,
+Every failed marker includes a stable machine-readable `code` alongside its localized `message`,
 `level`, and `path`. Built-in failures may also include structured `details`. Custom validators can
 return their own `code` and `details`; custom codes should be namespaced, for example
 `custom.seo-title`.
 
+When a check cannot run, `result.status` is `notEvaluated`. Omitting `client` disables custom
+callbacks and skips network checks. Pass `customValidation: false` to disable custom callbacks while
+still providing a client.
+
+Pass one `AbortSignal` to cancel validation and its pending network work. Built-in checks and client
+requests made through a custom validator's `context.getClient()` inherit this signal. A custom
+`getDocumentExists` callback receives it as an argument; custom work using another API should pass
+`context.signal` to that API. Cancellation rejects with the signal's reason (an `AbortError` when
+no custom reason was supplied). Work that does not accept an abort signal cannot be stopped, even
+though validation itself rejects immediately.
+
+```ts
+const controller = new AbortController()
+const validation = validateDocument({document, schema, client, signal: controller.signal})
+const reason = new Error('Validation cancelled')
+
+controller.abort(reason)
+try {
+  await validation
+} catch (error) {
+  if (error !== reason) throw error
+}
+```
+
 The package does not apply mutations or decide whether a document may be edited or published.
 
 ## Migrating from `sanity`
 
 Add `@sanity/validation` as a direct dependency. The workspace-based API is available as a
-compatibility overload, so call sites that only import `validateDocument` can migrate by changing
-the import:
+deprecated compatibility helper, so call sites that only import the validation function can
+migrate by changing the imported symbol:
 
 ```ts
-import {validateDocument} from '@sanity/validation'
+import {validateDocumentWithWorkspace} from '@sanity/validation'
 
-const markers = await validateDocument({document, workspace})
+const markers = await validateDocumentWithWorkspace({document, workspace})
 ```
 
 Call sites that also import `ValidateDocumentOptions` from `sanity` should use
 `ValidateDocumentWorkspaceOptions` for the workspace-shaped options.
 
-Prefer the `{document, schema, client}` API for new code.
+Prefer `validateDocument({document, schema, client})` for new code.

package/lib/_internal.d.ts

@@ -1,4 +1,4 @@
-import { c as resolveTypeForArrayItem, d as validateDocumentObservable, g as ValidationMarkerCode, n as ValidateDocumentObservableOptions, p as validateItem, t as ValidateDocumentInternalOptions, u as validateDocumentInternal, v as ValidationContext, y as LocaleSource } from "./validateDocument-6pLTIHIn.js";
+import { C as LocaleSource, S as ValidationContext, _ as validateItem, b as ValidationMarkerCode, d as evaluateDocumentObservable, f as resolveTypeForArrayItem, h as validateDocumentObservable, m as validateDocumentInternal, n as ValidateDocumentInternalOptions, o as ValidateItemOptions, r as ValidateDocumentObservableOptions, u as evaluateDocumentInternal } from "./validateDocument-CdvFjlAk.js";
 import { Path, Rule as Rule$1, RuleClass, Schema, SchemaType, SchemaValidationValue, ValidationContext as ValidationContext$1, ValidationError, ValidationMarker } from "@sanity/types";
 declare function getFallbackLocaleSource(): LocaleSource;
 declare const validationLocaleStrings: {
@@ -92,5 +92,5 @@ declare function getTypeChain(type: SchemaType | undefined, visited?: Set<Schema
 declare function normalizeValidationRules(typeDef: SchemaType | undefined, context?: ValidationContext$1): Rule$1[];
 declare function pathToString(path?: Path | undefined): string;
 declare function typeString(obj: unknown): string;
-export { type LocaleSource, Rule, type ValidateDocumentInternalOptions, type ValidateDocumentObservableOptions, type ValidationContext, convertToValidationMarker, getFallbackLocaleSource, getTypeChain, hasValidationContext, inferFromSchema, inferFromSchemaType, normalizeValidationRules, pathToString, resolveTypeForArrayItem, typeString, validateDocumentInternal, validateDocumentObservable, validateItem, validationLocaleStrings };
+export { type LocaleSource, Rule, type ValidateDocumentInternalOptions, type ValidateDocumentObservableOptions, type ValidateItemOptions, type ValidationContext, convertToValidationMarker, evaluateDocumentInternal, evaluateDocumentObservable, getFallbackLocaleSource, getTypeChain, hasValidationContext, inferFromSchema, inferFromSchemaType, normalizeValidationRules, pathToString, resolveTypeForArrayItem, typeString, validateDocumentInternal, validateDocumentObservable, validateItem, validationLocaleStrings };
 //# sourceMappingURL=_internal.d.ts.map

package/lib/_internal.js

@@ -1,4 +1,4 @@
-import { c as normalizeValidationRules, d as convertToValidationMarker, f as pathToString, i as validateDocumentObservable, l as Rule, m as validationLocaleStrings, o as validateItem, p as getFallbackLocaleSource, r as validateDocumentInternal, s as getTypeChain, t as resolveTypeForArrayItem, u as typeString } from "./validateDocument-Cq33kUmN.js";
+import { a as validateDocumentInternal, c as validateItem, d as Rule, f as typeString, g as validationLocaleStrings, h as getFallbackLocaleSource, l as getTypeChain, m as pathToString, n as evaluateDocumentObservable, o as validateDocumentObservable, p as convertToValidationMarker, r as resolveTypeForArrayItem, t as evaluateDocumentInternal, u as normalizeValidationRules } from "./validateDocument-DtBbNOGc.js";
 function inferFromSchemaType(typeDef) {
 	return traverse(typeDef, /* @__PURE__ */ new Set()), typeDef;
 }
@@ -34,6 +34,6 @@ function inferFromSchema(schema) {
 		schemaType && inferFromSchemaType(schemaType);
 	}), schema;
 }
-export { Rule, convertToValidationMarker, getFallbackLocaleSource, getTypeChain, hasValidationContext, inferFromSchema, inferFromSchemaType, normalizeValidationRules, pathToString, resolveTypeForArrayItem, typeString, validateDocumentInternal, validateDocumentObservable, validateItem, validationLocaleStrings };
+export { Rule, convertToValidationMarker, evaluateDocumentInternal, evaluateDocumentObservable, getFallbackLocaleSource, getTypeChain, hasValidationContext, inferFromSchema, inferFromSchemaType, normalizeValidationRules, pathToString, resolveTypeForArrayItem, typeString, validateDocumentInternal, validateDocumentObservable, validateItem, validationLocaleStrings };
 
 //# sourceMappingURL=_internal.js.map

package/lib/index.d.ts

@@ -1,2 +1,2 @@
-import { _ as validationMarkerCodes, a as ValidationClient, f as validateDocumentWithWorkspace, g as ValidationMarkerCode, h as DocumentValidationMarker, i as ValidateDocumentWorkspaceOptions, l as validateDocument, m as BuiltInValidationMarkerCode, o as ValidationSchema, r as ValidateDocumentOptions, s as ValidationSource } from "./validateDocument-6pLTIHIn.js";
-export { type BuiltInValidationMarkerCode, type DocumentValidationMarker, type ValidateDocumentOptions, type ValidateDocumentWorkspaceOptions, type ValidationClient, type ValidationMarkerCode, type ValidationSchema, type ValidationSource, validateDocument, validateDocumentWithWorkspace, validationMarkerCodes };
+import { a as ValidateDocumentWorkspaceOptions, b as ValidationMarkerCode, c as ValidationSchema, g as validateDocumentWithWorkspace, i as ValidateDocumentOptions, l as ValidationSource, p as validateDocument, s as ValidationClient, t as DocumentValidationResult, v as BuiltInValidationMarkerCode, x as validationMarkerCodes, y as DocumentValidationMarker } from "./validateDocument-CdvFjlAk.js";
+export { type BuiltInValidationMarkerCode, type DocumentValidationMarker, type DocumentValidationResult, type ValidateDocumentOptions, type ValidateDocumentWorkspaceOptions, type ValidationClient, type ValidationMarkerCode, type ValidationSchema, type ValidationSource, validateDocument, validateDocumentWithWorkspace, validationMarkerCodes };

package/lib/index.js

@@ -1,2 +1,2 @@
-import { a as validateDocumentWithWorkspace, h as validationMarkerCodes, n as validateDocument } from "./validateDocument-Cq33kUmN.js";
+import { _ as validationMarkerCodes, i as validateDocument, s as validateDocumentWithWorkspace } from "./validateDocument-DtBbNOGc.js";
 export { validateDocument, validateDocumentWithWorkspace, validationMarkerCodes };

package/lib/{validateDocument-6pLTIHIn.d.ts → validateDocument-CdvFjlAk.d.ts}

@@ -1,4 +1,4 @@
-import { CurrentUser, SanityDocument, Schema, SchemaType, ValidationContext as ValidationContext$1, ValidationMarker } from "@sanity/types";
+import { CurrentUser, SanityDocument, Schema, SchemaType, ValidationContext, ValidationContext as ValidationContext$1, ValidationMarker } from "@sanity/types";
 import { ConcurrencyLimiter } from "@sanity/util/concurrency-limiter";
 import { Observable } from "rxjs";
 import { TFunction } from "i18next";
@@ -34,6 +34,17 @@ declare module '@sanity/types' {
     i18n: LocaleSource;
   }
 }
+interface InternalValidationContext extends ValidationContext {
+  __internal?: {
+    customValidation?: boolean;
+    customValidationConcurrencyLimiter?: {
+      ready: (signal?: AbortSignal) => Promise<void>;
+      release: () => void;
+      run: <T>(work: () => PromiseLike<T> | T, signal?: AbortSignal) => Promise<T>;
+    };
+    markIncomplete?: () => void;
+  };
+}
 /** Machine-readable codes emitted by built-in document validation. @beta */
 declare const validationMarkerCodes: {
   readonly arrayDuplicateItem: 'array.duplicate-item';
@@ -98,18 +109,15 @@ type DocumentValidationMarker = Omit<ValidationMarker, 'code'> & {
  * @internal
  */
 declare function resolveTypeForArrayItem(item: unknown, candidates: SchemaType[]): SchemaType | undefined;
-/**
- * @beta
- */
-interface ValidateDocumentOptions {
+interface ValidateDocumentBaseOptions {
   /**
    * The document to be validated
    */
   document: SanityDocument;
   /** The compiled schema to validate against. */
   schema: ValidationSchema;
-  /** A configured client used for reference checks and custom validators. */
-  client: ValidationClient;
+  /** Signal used to cancel validation and any work it starts. */
+  signal?: AbortSignal;
   /**
    * Function used to check if referenced documents exists (and is published).
    *
@@ -121,6 +129,7 @@ interface ValidateDocumentOptions {
    */
   getDocumentExists?: (options: {
     id: string;
+    signal?: AbortSignal;
   }) => Promise<boolean>;
   /**
    * The maximum amount of custom validation functions to be running
@@ -149,6 +158,21 @@ interface ValidateDocumentOptions {
    */
   currentUser?: Omit<CurrentUser, 'role'> | null;
 }
+/**
+ * Options for validating a document. Custom validation is disabled when no client is provided.
+ *
+ * @beta
+ */
+type ValidateDocumentOptions = ValidateDocumentBaseOptions & ({
+  /** A configured client used for reference checks and custom validators. */
+  client: ValidationClient;
+  /** Whether to run custom validation callbacks. Defaults to `true`. */
+  customValidation?: boolean;
+} | {
+  /** Omit the client to perform local validation without custom callbacks. */
+  client?: undefined;
+  customValidation?: false;
+});
 /** A compiled schema accepted across compatible `@sanity/types` versions. @beta */
 interface ValidationSchema {
   get(name: string): unknown;
@@ -167,6 +191,13 @@ interface ValidationClient {
   observable: Pick<SanityClient['observable'], 'fetch' | 'request'>;
   withConfig(config: Parameters<SanityClient['withConfig']>[0]): ValidationClient;
 }
+/** The result of validating a complete document. @beta */
+interface DocumentValidationResult {
+  /** Whether validation passed, failed, or could not be fully evaluated. */
+  status: 'passed' | 'failed' | 'notEvaluated';
+  /** Validation rules that failed. */
+  markers: DocumentValidationMarker[];
+}
 /**
  * The validation capabilities required from a resolved Studio source or workspace.
  *
@@ -187,7 +218,7 @@ interface ValidationSource {
  *
  * @beta
  */
-interface ValidateDocumentWorkspaceOptions extends Omit<ValidateDocumentOptions, 'client' | 'schema'> {
+interface ValidateDocumentWorkspaceOptions extends Omit<ValidateDocumentBaseOptions, 'schema'> {
   /** The resolved Studio workspace or source used for validation. */
   workspace: ValidationSource;
   /**
@@ -198,6 +229,8 @@ interface ValidateDocumentWorkspaceOptions extends Omit<ValidateDocumentOptions,
   getClient?: ValidationSource['getClient'];
   /** Validation environment exposed to custom validators. */
   environment?: 'cli' | 'studio';
+  /** Whether to run custom validation callbacks. Defaults to `true`. */
+  customValidation?: boolean;
 }
 /**
  * Validates a document against the schema in a resolved Studio workspace or source.
@@ -205,23 +238,15 @@ interface ValidateDocumentWorkspaceOptions extends Omit<ValidateDocumentOptions,
  * @beta
  * @deprecated Prefer {@link validateDocument} with `{document, schema, client}` for new code.
  */
-declare function validateDocumentWithWorkspace({ document, workspace, getClient, getDocumentExists, environment, maxCustomValidationConcurrency, maxFetchConcurrency, currentUser }: ValidateDocumentWorkspaceOptions): Promise<DocumentValidationMarker[]>;
-/**
- * Validates a document against the schema in a resolved Studio workspace or source.
- *
- * This compatibility overload preserves the existing `sanity` API. Prefer the
- * `{document, schema, client}` overload for new code.
- *
- * @beta
- */
-declare function validateDocument(options: ValidateDocumentWorkspaceOptions): Promise<DocumentValidationMarker[]>;
+declare function validateDocumentWithWorkspace({ document, workspace, getClient, getDocumentExists, environment, maxCustomValidationConcurrency, maxFetchConcurrency, currentUser, customValidation, signal }: ValidateDocumentWorkspaceOptions): Promise<DocumentValidationMarker[]>;
 /**
- * Validates a document against a compiled schema. Returns validation markers
+ * Validates a document against a compiled schema. Returns failures and whether
+ * validation completed
  * without deciding whether the document may be edited or published.
  *
  * @beta
  */
-declare function validateDocument(options: ValidateDocumentOptions): Promise<DocumentValidationMarker[]>;
+declare function validateDocument(options: ValidateDocumentOptions): Promise<DocumentValidationResult>;
 /** @internal */
 interface ValidateDocumentInternalOptions {
   document: SanityDocument;
@@ -231,19 +256,24 @@ interface ValidateDocumentInternalOptions {
   }) => SanityClient;
   getDocumentExists?: (options: {
     id: string;
+    signal?: AbortSignal;
   }) => Promise<boolean>;
   i18n?: LocaleSource;
   environment: 'cli' | 'studio';
   maxCustomValidationConcurrency?: number;
   maxFetchConcurrency?: number;
   currentUser?: Omit<CurrentUser, 'role'> | null;
+  customValidation?: boolean;
+  signal?: AbortSignal;
 }
 /** @internal */
-declare function validateDocumentInternal({ document, schema, getClient, getDocumentExists, i18n, environment, maxCustomValidationConcurrency, maxFetchConcurrency, currentUser }: ValidateDocumentInternalOptions): Promise<DocumentValidationMarker[]>;
+declare function validateDocumentInternal(options: ValidateDocumentInternalOptions): Promise<DocumentValidationMarker[]>;
+/** @internal */
+declare function evaluateDocumentInternal({ document, schema, getClient, getDocumentExists, i18n, environment, maxCustomValidationConcurrency, maxFetchConcurrency, currentUser, customValidation, signal }: ValidateDocumentInternalOptions): Promise<DocumentValidationResult>;
 /**
  * @internal
  */
-interface ValidateDocumentObservableOptions extends Pick<ValidationContext$1, 'getDocumentExists' | 'i18n'> {
+interface ValidateDocumentObservableOptions extends Pick<ValidationContext$1, 'getDocumentExists' | 'i18n' | 'signal'> {
   getClient: (options: {
     apiVersion: string;
   }) => SanityClient;
@@ -252,12 +282,18 @@ interface ValidateDocumentObservableOptions extends Pick<ValidationContext$1, 'g
   environment: 'cli' | 'studio';
   maxCustomValidationConcurrency?: number;
   currentUser?: Omit<CurrentUser, 'role'> | null;
+  customValidation?: boolean;
 }
 /**
  * Validates a document against the given schema, returning an Observable
  * @internal
  */
-declare function validateDocumentObservable({ document, getClient, i18n, schema, getDocumentExists, environment, maxCustomValidationConcurrency, currentUser }: ValidateDocumentObservableOptions): Observable<DocumentValidationMarker[]>;
+declare function validateDocumentObservable(options: ValidateDocumentObservableOptions): Observable<DocumentValidationMarker[]>;
+/**
+ * Validates a document against the given schema, including completion status.
+ * @internal
+ */
+declare function evaluateDocumentObservable(options: ValidateDocumentObservableOptions): Observable<DocumentValidationResult>;
 /**
  * this is used make optional properties required by replacing optionals with
  * `T[P] | undefined`. this is used to prevent errors in `validateItem` where
@@ -271,7 +307,10 @@ type ValidateItemOptions = {
   customValidationConcurrencyLimiter?: ConcurrencyLimiter;
   hidden?: boolean;
   currentUser?: Omit<CurrentUser, 'role'> | null;
-} & ExplicitUndefined<Omit<ValidationContext$1, 'hidden'>>;
+  customValidation?: boolean;
+  signal?: AbortSignal;
+  __internal?: InternalValidationContext['__internal'];
+} & ExplicitUndefined<Omit<ValidationContext$1, 'hidden' | 'signal'>>;
 declare function validateItem(opts: ValidateItemOptions): Promise<ValidationMarker[]>;
-export { validationMarkerCodes as _, ValidationClient as a, resolveTypeForArrayItem as c, validateDocumentObservable as d, validateDocumentWithWorkspace as f, ValidationMarkerCode as g, DocumentValidationMarker as h, ValidateDocumentWorkspaceOptions as i, validateDocument as l, BuiltInValidationMarkerCode as m, ValidateDocumentObservableOptions as n, ValidationSchema as o, validateItem as p, ValidateDocumentOptions as r, ValidationSource as s, ValidateDocumentInternalOptions as t, validateDocumentInternal as u, ValidationContext$1 as v, LocaleSource as y };
-//# sourceMappingURL=validateDocument-6pLTIHIn.d.ts.map
+export { LocaleSource as C, ValidationContext$1 as S, validateItem as _, ValidateDocumentWorkspaceOptions as a, ValidationMarkerCode as b, ValidationSchema as c, evaluateDocumentObservable as d, resolveTypeForArrayItem as f, validateDocumentWithWorkspace as g, validateDocumentObservable as h, ValidateDocumentOptions as i, ValidationSource as l, validateDocumentInternal as m, ValidateDocumentInternalOptions as n, ValidateItemOptions as o, validateDocument as p, ValidateDocumentObservableOptions as r, ValidationClient as s, DocumentValidationResult as t, evaluateDocumentInternal as u, BuiltInValidationMarkerCode as v, validationMarkerCodes as x, DocumentValidationMarker as y };
+//# sourceMappingURL=validateDocument-CdvFjlAk.d.ts.map