@tldraw/validate 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.b73a0d46b63f

package/dist-esm/index.mjs

@@ -9,7 +9,7 @@ import {
 } from "./lib/validation.mjs";
 registerTldrawLibraryVersion(
   "@tldraw/validate",
-  "4.1.0-next.b6dfe9bccde9",
+  "4.1.0-next.b73a0d46b63f",
   "esm"
 );
 export {

package/dist-esm/lib/validation.mjs

@@ -30,6 +30,12 @@ function formatPath(path) {
   return formattedPath;
 }
 class ValidationError extends Error {
+  /**
+   * Creates a new ValidationError with contextual information about where the error occurred.
+   *
+   * rawMessage - The raw error message without path information
+   * path - Array indicating the location in the data structure where validation failed
+   */
   constructor(rawMessage, path = []) {
     const formattedPath = formatPath(path);
     const indentedMessage = rawMessage.split("\n").map((line, i) => i === 0 ? line : `  ${line}`).join("\n");
@@ -70,13 +76,35 @@ function typeToString(value) {
   }
 }
 class Validator {
+  /**
+   * Creates a new Validator instance.
+   *
+   * validationFn - Function that validates and returns a value of type T
+   * validateUsingKnownGoodVersionFn - Optional performance-optimized validation function
+   */
   constructor(validationFn, validateUsingKnownGoodVersionFn) {
     this.validationFn = validationFn;
     this.validateUsingKnownGoodVersionFn = validateUsingKnownGoodVersionFn;
   }
   /**
-   * Asserts that the passed value is of the correct type and returns it. The returned value is
+   * Validates an unknown value and returns it with the correct type. The returned value is
    * guaranteed to be referentially equal to the passed value.
+   *
+   * @param value - The unknown value to validate
+   * @returns The validated value with type T
+   * @throws ValidationError When validation fails
+   * @example
+   * ```ts
+   * import { T } from '@tldraw/validate'
+   *
+   * const name = T.string.validate("Alice") // Returns "Alice" as string
+   * const title = T.string.validate("") // Returns "" (empty strings are valid)
+   *
+   * // These will throw ValidationError:
+   * T.string.validate(123) // Expected string, got a number
+   * T.string.validate(null) // Expected string, got null
+   * T.string.validate(undefined) // Expected string, got undefined
+   * ```
    */
   validate(value) {
     const validated = this.validationFn(value);
@@ -85,6 +113,31 @@ class Validator {
     }
     return validated;
   }
+  /**
+   * Performance-optimized validation using a previously validated value. If the new value
+   * is referentially equal to the known good value, returns the known good value immediately.
+   *
+   * @param knownGoodValue - A previously validated value
+   * @param newValue - The new value to validate
+   * @returns The validated value, potentially reusing the known good value
+   * @throws ValidationError When validation fails
+   * @example
+   * ```ts
+   * import { T } from '@tldraw/validate'
+   *
+   * const userValidator = T.object({
+   *   name: T.string,
+   *   settings: T.object({ theme: T.literalEnum('light', 'dark') })
+   * })
+   *
+   * const user = userValidator.validate({ name: "Alice", settings: { theme: "light" } })
+   *
+   * // Later, with partially changed data:
+   * const newData = { name: "Alice", settings: { theme: "dark" } }
+   * const updated = userValidator.validateUsingKnownGoodVersion(user, newData)
+   * // Only validates the changed 'theme' field for better performance
+   * ```
+   */
   validateUsingKnownGoodVersion(knownGoodValue, newValue) {
     if (Object.is(knownGoodValue, newValue)) {
       return knownGoodValue;
@@ -94,7 +147,28 @@ class Validator {
     }
     return this.validate(newValue);
   }
-  /** Checks that the passed value is of the correct type. */
+  /**
+   * Type guard that checks if a value is valid without throwing an error.
+   *
+   * @param value - The value to check
+   * @returns True if the value is valid, false otherwise
+   * @example
+   * ```ts
+   * import { T } from '@tldraw/validate'
+   *
+   * function processUserInput(input: unknown) {
+   *   if (T.string.isValid(input)) {
+   *     // input is now typed as string within this block
+   *     return input.toUpperCase()
+   *   }
+   *   if (T.number.isValid(input)) {
+   *     // input is now typed as number within this block
+   *     return input.toFixed(2)
+   *   }
+   *   throw new Error('Expected string or number')
+   * }
+   * ```
+   */
   isValid(value) {
     try {
       this.validate(value);
@@ -104,22 +178,85 @@ class Validator {
     }
   }
   /**
-   * Returns a new validator that also accepts null or undefined. The resulting value will always be
-   * null.
+   * Returns a new validator that also accepts null values.
+   *
+   * @returns A new validator that accepts T or null
+   * @example
+   * ```ts
+   * import { T } from '@tldraw/validate'
+   *
+   * const assetValidator = T.object({
+   *   id: T.string,
+   *   name: T.string,
+   *   src: T.srcUrl.nullable(), // Can be null if not loaded yet
+   *   mimeType: T.string.nullable()
+   * })
+   *
+   * const asset = assetValidator.validate({
+   *   id: "image-123",
+   *   name: "photo.jpg",
+   *   src: null, // Valid - asset not loaded yet
+   *   mimeType: "image/jpeg"
+   * })
+   * ```
    */
   nullable() {
     return nullable(this);
   }
   /**
-   * Returns a new validator that also accepts null or undefined. The resulting value will always be
-   * null.
+   * Returns a new validator that also accepts undefined values.
+   *
+   * @returns A new validator that accepts T or undefined
+   * @example
+   * ```ts
+   * import { T } from '@tldraw/validate'
+   *
+   * const shapeConfigValidator = T.object({
+   *   type: T.literal('rectangle'),
+   *   x: T.number,
+   *   y: T.number,
+   *   label: T.string.optional(), // Optional property
+   *   metadata: T.object({ created: T.string }).optional()
+   * })
+   *
+   * // Both of these are valid:
+   * const shape1 = shapeConfigValidator.validate({ type: 'rectangle', x: 0, y: 0 })
+   * const shape2 = shapeConfigValidator.validate({
+   *   type: 'rectangle', x: 0, y: 0, label: "My Shape"
+   * })
+   * ```
    */
   optional() {
     return optional(this);
   }
   /**
-   * Refine this validation to a new type. The passed-in validation function should throw an error
-   * if the value can't be converted to the new type, or return the new type otherwise.
+   * Creates a new validator by refining this validator with additional logic that can transform
+   * the validated value to a new type.
+   *
+   * @param otherValidationFn - Function that transforms/validates the value to type U
+   * @returns A new validator that validates to type U
+   * @throws ValidationError When validation or refinement fails
+   * @example
+   * ```ts
+   * import { T, ValidationError } from '@tldraw/validate'
+   *
+   * // Transform string to ensure it starts with a prefix
+   * const prefixedIdValidator = T.string.refine((id) => {
+   *   return id.startsWith('shape:') ? id : `shape:${id}`
+   * })
+   *
+   * const id1 = prefixedIdValidator.validate("rectangle-123") // Returns "shape:rectangle-123"
+   * const id2 = prefixedIdValidator.validate("shape:circle-456") // Returns "shape:circle-456"
+   *
+   * // Parse and validate JSON strings
+   * const jsonValidator = T.string.refine((str) => {
+   *   try {
+   *     return JSON.parse(str)
+   *   } catch {
+   *     throw new ValidationError('Invalid JSON string')
+   *   }
+   * })
+   * ```
    */
   refine(otherValidationFn) {
     return new Validator(
@@ -150,6 +287,11 @@ class Validator {
   }
 }
 class ArrayOfValidator extends Validator {
+  /**
+   * Creates a new ArrayOfValidator.
+   *
+   * itemValidator - Validator used to validate each array element
+   */
   constructor(itemValidator) {
     super(
       (value) => {
@@ -186,6 +328,18 @@ class ArrayOfValidator extends Validator {
     );
     this.itemValidator = itemValidator;
   }
+  /**
+   * Returns a new validator that ensures the array is not empty.
+   *
+   * @returns A new validator that rejects empty arrays
+   * @throws ValidationError When the array is empty
+   * @example
+   * ```ts
+   * const nonEmptyStrings = T.arrayOf(T.string).nonEmpty()
+   * nonEmptyStrings.validate(["hello"]) // Valid
+   * nonEmptyStrings.validate([]) // Throws ValidationError
+   * ```
+   */
   nonEmpty() {
     return this.check((value) => {
       if (value.length === 0) {
@@ -193,6 +347,18 @@ class ArrayOfValidator extends Validator {
       }
     });
   }
+  /**
+   * Returns a new validator that ensures the array has more than one element.
+   *
+   * @returns A new validator that requires at least 2 elements
+   * @throws ValidationError When the array has 1 or fewer elements
+   * @example
+   * ```ts
+   * const multipleItems = T.arrayOf(T.string).lengthGreaterThan1()
+   * multipleItems.validate(["a", "b"]) // Valid
+   * multipleItems.validate(["a"]) // Throws ValidationError
+   * ```
+   */
   lengthGreaterThan1() {
     return this.check((value) => {
       if (value.length <= 1) {
@@ -202,6 +368,12 @@ class ArrayOfValidator extends Validator {
   }
 }
 class ObjectValidator extends Validator {
+  /**
+   * Creates a new ObjectValidator.
+   *
+   * config - Object mapping property names to their validators
+   * shouldAllowUnknownProperties - Whether to allow properties not defined in config
+   */
   constructor(config, shouldAllowUnknownProperties = false) {
     super(
       (object2) => {
@@ -265,21 +437,32 @@ class ObjectValidator extends Validator {
     this.config = config;
     this.shouldAllowUnknownProperties = shouldAllowUnknownProperties;
   }
+  /**
+   * Returns a new validator that allows unknown properties in the validated object.
+   *
+   * @returns A new ObjectValidator that accepts extra properties
+   * @example
+   * ```ts
+   * const flexibleUser = T.object({ name: T.string }).allowUnknownProperties()
+   * flexibleUser.validate({ name: "Alice", extra: "allowed" }) // Valid
+   * ```
+   */
   allowUnknownProperties() {
     return new ObjectValidator(this.config, true);
   }
   /**
-   * Extend an object validator by adding additional properties.
+   * Creates a new ObjectValidator by extending this validator with additional properties.
    *
+   * @param extension - Object mapping new property names to their validators
+   * @returns A new ObjectValidator that validates both original and extended properties
    * @example
-   *
    * ```ts
-   * const animalValidator = T.object({
-   * 	name: T.string,
-   * })
-   * const catValidator = animalValidator.extend({
-   * 	meowVolume: T.number,
+   * const baseUser = T.object({ name: T.string, age: T.number })
+   * const adminUser = baseUser.extend({
+   *   permissions: T.arrayOf(T.string),
+   *   isAdmin: T.boolean
    * })
+   * // adminUser validates: { name: string; age: number; permissions: string[]; isAdmin: boolean }
    * ```
    */
   extend(extension) {
@@ -287,6 +470,14 @@ class ObjectValidator extends Validator {
   }
 }
 class UnionValidator extends Validator {
+  /**
+   * Creates a new UnionValidator.
+   *
+   * key - The discriminator property name used to determine the variant
+   * config - Object mapping variant names to their validators
+   * unknownValueValidation - Function to handle unknown variants
+   * useNumberKeys - Whether the discriminator uses number keys instead of strings
+   */
   constructor(key, config, unknownValueValidation, useNumberKeys) {
     super(
       (input) => {
@@ -338,11 +529,31 @@ class UnionValidator extends Validator {
     const matchingSchema = hasOwnProperty(this.config, variant) ? this.config[variant] : void 0;
     return { matchingSchema, variant };
   }
+  /**
+   * Returns a new UnionValidator that can handle unknown variants using the provided function.
+   *
+   * @param unknownValueValidation - Function to validate/transform unknown variants
+   * @returns A new UnionValidator that accepts unknown variants
+   * @example
+   * ```ts
+   * const shapeValidator = T.union('type', { circle: circleValidator })
+   *   .validateUnknownVariants((obj, variant) => {
+   *     console.warn(`Unknown shape type: ${variant}`)
+   *     return obj as UnknownShape
+   *   })
+   * ```
+   */
   validateUnknownVariants(unknownValueValidation) {
     return new UnionValidator(this.key, this.config, unknownValueValidation, this.useNumberKeys);
   }
 }
 class DictValidator extends Validator {
+  /**
+   * Creates a new DictValidator.
+   *
+   * keyValidator - Validator for object keys
+   * valueValidator - Validator for object values
+   */
   constructor(keyValidator, valueValidator) {
     super(
       (object2) => {