@babel/helper-validator-option

import { OptionValidator, findSuggestion } from "@babel/helper-validator-option";

const { OptionValidator, findSuggestion } = require("@babel/helper-validator-option");

import { OptionValidator, findSuggestion } from "@babel/helper-validator-option";

// Create validator with descriptive name
const validator = new OptionValidator("my-babel-plugin");

// Validate top-level options
const options = { mode: "development", verbose: true };
const allowedOptions = { mode: "string", verbose: "boolean", debug: "boolean" };
validator.validateTopLevelOptions(options, allowedOptions);

// Validate specific option types
const mode = validator.validateStringOption("mode", options.mode, "production");
const verbose = validator.validateBooleanOption("verbose", options.verbose, false);

// Find suggestions for typos
const suggestion = findSuggestion("verbos", ["verbose", "debug", "mode"]);
// Returns: "verbose"

/**
 * Main validation class for plugin/preset options
 */
class OptionValidator {
  descriptor: string;
  
  /**
   * Creates a new OptionValidator instance
   * @param descriptor - Identifier used in error messages
   */
  constructor(descriptor: string);

  /**
   * Validate if the given options follow the name of keys defined in the TopLevelOptionShape
   * @param options - The options object to validate
   * @param TopLevelOptionShape - Object with all valid key names that options should be allowed to have
   * @throws Error with suggestion if invalid option found
   */
  validateTopLevelOptions(options: object, TopLevelOptionShape: object): void;

  /**
   * Validates boolean options with default value support
   * @param name - Option name for error messages
   * @param value - Optional boolean value to validate
   * @param defaultValue - Optional default value if value is undefined
   * @returns The validated value or default
   * @throws Error if value is not boolean when defined
   */
  validateBooleanOption<T extends boolean>(
    name: string,
    value?: boolean,
    defaultValue?: T
  ): boolean | T;

  /**
   * Validates string options with default value support
   * @param name - Option name for error messages
   * @param value - Optional string value to validate
   * @param defaultValue - Optional default value if value is undefined
   * @returns The validated value or default
   * @throws Error if value is not string when defined
   */
  validateStringOption<T extends string>(
    name: string,
    value?: string,
    defaultValue?: T
  ): string | T;

  /**
   * Throws formatted error message when condition is false
   * @param condition - Condition to check
   * @param message - Error message to format and throw
   * @throws Formatted error if condition is false
   */
  invariant(condition: boolean, message: string): void;

  /**
   * Formats error message with descriptor prefix
   * @param message - Raw error message
   * @returns Formatted message with descriptor prefix
   */
  formatMessage(message: string): string;
}

import { OptionValidator } from "@babel/helper-validator-option";

const validator = new OptionValidator("babel-plugin-example");

// Validate that all provided options are allowed
try {
  validator.validateTopLevelOptions(
    { mode: "production", verbos: true }, // typo in "verbos"
    { mode: "string", verbose: "boolean" }
  );
} catch (error) {
  // Error: babel-plugin-example: 'verbos' is not a valid top-level option.
  // - Did you mean 'verbose'?
}

// Validate and get boolean option with default
const debug = validator.validateBooleanOption("debug", options.debug, false);

// Validate and get string option with default
const mode = validator.validateStringOption("mode", options.mode, "development");

// Use invariant for custom validation
validator.invariant(
  mode === "development" || mode === "production",
  "mode must be either 'development' or 'production'"
);

/**
 * Finds the closest string match using Levenshtein distance algorithm
 * @param str - Input string to find suggestions for
 * @param arr - Array of candidate strings
 * @returns The candidate string with minimal Levenshtein distance, or undefined if array is empty
 */
function findSuggestion(str: string, arr: readonly string[]): string | undefined;

import { findSuggestion } from "@babel/helper-validator-option";

// Find closest match for a typo
const suggestion = findSuggestion("verbos", ["verbose", "debug", "mode"]);
console.log(suggestion); // "verbose"

// Find closest match among configuration options
const validOptions = ["presets", "plugins", "sourceMap", "minified"];
const userTypo = "sorceMap";
const corrected = findSuggestion(userTypo, validOptions);
console.log(corrected); // "sourceMap"

// Handle empty candidate array
const noMatch = findSuggestion("anything", []);
console.log(noMatch); // undefined

babel-plugin-example: 'verbos' is not a valid top-level option.
- Did you mean 'verbose'?

babel-plugin-example: 'mode' option must be a string.

babel-plugin-example: Custom validation message here.