@markuplint/types 4.8.1 → 5.0.0-alpha.0

package/lib/check-base.js

@@ -4,6 +4,21 @@ import { checkEnum } from './enum.js';
 import { checkKeywordType } from './keyword-type.js';
 import { checkList } from './list.js';
 import { checkNumber } from './number.js';
+import { checkPattern } from './pattern.js';
+/**
+ * Validates a string value against a specified type definition using the provided
+ * set of custom type definitions. This is the core type-checking dispatcher that
+ * routes validation to the appropriate checker based on the type's structure
+ * (keyword, list, enum, number, or directive).
+ *
+ * @param value - The string value to validate
+ * @param type - The type definition to validate against
+ * @param defs - A map of custom type definitions (both CSS syntax and custom syntax) used for resolving keyword types
+ * @param ref - An optional reference identifier used for error reporting context
+ * @param cache - Whether to use cached results for repeated checks with the same inputs
+ * @returns A result indicating whether the value matches the type, or details about the mismatch
+ * @throws Error if the type does not match any known type structure
+ */
 export function checkBase(value, type, defs, ref, cache = true) {
     if (isKeyword(type)) {
         log('Check keyword: %s', type);
@@ -25,26 +40,98 @@ export function checkBase(value, type, defs, ref, cache = true) {
         log('Check directive: %O', type);
         return checkDirective(value, type, defs, ref, cache);
     }
+    if (isPattern(type)) {
+        log('Check pattern: %O', type);
+        return checkPattern(value, type);
+    }
     throw new Error('Unknown type');
 }
+/**
+ * Determines whether a type definition is a keyword-based type.
+ * Keyword types are represented as plain strings (e.g., CSS syntax names
+ * like `"<color>"` or extended types like `"URL"`).
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a keyword-defined type string
+ */
 export function isKeyword(type) {
     return typeof type === 'string';
 }
+/**
+ * Determines whether a type definition represents a list type.
+ * List types define space-separated or comma-separated token sequences
+ * and are identified by having a `separator` property.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a list definition
+ */
 export function isList(type) {
     return typeof type !== 'string' && 'separator' in type;
 }
+/**
+ * Determines whether a type definition represents an enumerated type.
+ * Enum types define a fixed set of allowed string values and are
+ * identified by having an `enum` property.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is an enum definition
+ */
 export function isEnum(type) {
     return typeof type !== 'string' && 'enum' in type;
 }
+/**
+ * Determines whether a type definition represents a numeric type.
+ * Number types specify either `float` or `integer` validation with
+ * optional range constraints, and are identified by having a `type`
+ * property set to one of those values.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a number definition
+ */
 export function isNumber(type) {
     return typeof type !== 'string' && 'type' in type && (type.type === 'float' || type.type === 'integer');
 }
+/**
+ * Determines whether a type definition represents a directive type.
+ * Directive types allow separating and individually validating parts of
+ * an attribute value, and are identified by having a `directive` property.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a directive definition
+ */
 export function isDirective(type) {
     return typeof type !== 'string' && 'directive' in type;
 }
+/**
+ * Determines whether a type definition represents a pattern type.
+ * Pattern types validate attribute values against a regular expression
+ * or plain string, and are identified by having a `pattern` property.
+ *
+ * @param type - The type definition to test
+ * @returns True if the type is a pattern definition
+ */
+export function isPattern(type) {
+    return typeof type !== 'string' && 'pattern' in type;
+}
+/**
+ * Determines whether a custom type definition uses CSS syntax matching.
+ * CSS syntax definitions are either plain strings or objects with a `syntax`
+ * property that specifies CSS value definition syntax for matching.
+ *
+ * @param type - The custom type definition to test
+ * @returns True if the definition uses CSS syntax matching
+ */
 export function isCSSSyntax(type) {
     return typeof type === 'string' || 'syntax' in type;
 }
+/**
+ * Determines whether a custom type definition uses a programmatic custom
+ * syntax checker rather than CSS syntax matching. This is the inverse
+ * of {@link isCSSSyntax}.
+ *
+ * @param type - The custom type definition to test
+ * @returns True if the definition uses a custom programmatic checker function
+ */
 export function isCustomSyntax(type) {
     return !isCSSSyntax(type);
 }

package/lib/check-multi-types.d.ts

@@ -1,2 +1,13 @@
 import type { CustomSyntaxCheck, UnmatchedResult } from './types.js';
-export declare function checkMultiTypes(value: string, checks: readonly CustomSyntaxCheck[]): UnmatchedResult | import("./types.js").MatchedResult;
+/**
+ * Checks a value against multiple type checkers and returns the best result.
+ *
+ * Iterates through the provided checks and returns the first matched result.
+ * If none match, returns the unmatched result with the highest pass count
+ * or furthest offset, providing the most informative error.
+ *
+ * @param value - The string value to check
+ * @param checks - The array of type check functions to try
+ * @returns The matched result or the best unmatched result
+ */
+export declare function checkMultiTypes(value: string, checks: readonly CustomSyntaxCheck[]): import("./types.js").MatchedResult | UnmatchedResult;

package/lib/check-multi-types.js

@@ -1,5 +1,16 @@
 import { log } from './debug.js';
 import { matched } from './match-result.js';
+/**
+ * Checks a value against multiple type checkers and returns the best result.
+ *
+ * Iterates through the provided checks and returns the first matched result.
+ * If none match, returns the unmatched result with the highest pass count
+ * or furthest offset, providing the most informative error.
+ *
+ * @param value - The string value to check
+ * @param checks - The array of type check functions to try
+ * @returns The matched result or the best unmatched result
+ */
 export function checkMultiTypes(value, checks) {
     let unmatched;
     for (const check of checks) {

package/lib/check.d.ts

@@ -1,3 +1,16 @@
 import type { Type, Result } from './types.js';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Validates a string value against a specified type definition using
+ * the built-in HTML and CSS type definitions.
+ *
+ * This is the primary entry point for type checking in the @markuplint/types package.
+ * It delegates to {@link checkBase} with the combined set of HTML and CSS definitions.
+ *
+ * @param value - The string value to validate
+ * @param type - The type definition to validate against
+ * @param ref - An optional reference identifier used for error reporting context
+ * @param cache - Whether to use cached results for repeated checks with the same inputs
+ * @returns A result indicating whether the value matches the type, or details about the mismatch
+ */
 export declare function check(value: string, type: ReadonlyDeep<Type>, ref?: string, cache?: boolean): Result;

package/lib/check.js

@@ -1,6 +1,19 @@
 import { checkBase } from './check-base.js';
 import { defs } from './defs.js';
 import { cssDefs } from './css-defs.js';
+/**
+ * Validates a string value against a specified type definition using
+ * the built-in HTML and CSS type definitions.
+ *
+ * This is the primary entry point for type checking in the @markuplint/types package.
+ * It delegates to {@link checkBase} with the combined set of HTML and CSS definitions.
+ *
+ * @param value - The string value to validate
+ * @param type - The type definition to validate against
+ * @param ref - An optional reference identifier used for error reporting context
+ * @param cache - Whether to use cached results for repeated checks with the same inputs
+ * @returns A result indicating whether the value matches the type, or details about the mismatch
+ */
 export function check(value, type, ref, cache = true) {
     return checkBase(value, type, { ...defs, ...cssDefs }, ref, cache);
 }

package/lib/css-defs.d.ts

@@ -1,2 +1,10 @@
 import type { Defs } from './types.js';
+/**
+ * CSS and SVG type definitions for attribute value validation.
+ *
+ * Contains definitions for CSS declaration lists, SVG-specific types
+ * (paths, viewBox, preserveAspectRatio, etc.), and animation-related types.
+ * Each definition includes a reference URL and either a CSS syntax or
+ * a custom validation function.
+ */
 export declare const cssDefs: Defs;

package/lib/css-defs.js

@@ -1,4 +1,12 @@
 import { matched } from './match-result.js';
+/**
+ * CSS and SVG type definitions for attribute value validation.
+ *
+ * Contains definitions for CSS declaration lists, SVG-specific types
+ * (paths, viewBox, preserveAspectRatio, etc.), and animation-related types.
+ * Each definition includes a reference URL and either a CSS syntax or
+ * a custom validation function.
+ */
 export const cssDefs = {
     '<css-declaration-list>': {
         ref: 'https://drafts.csswg.org/css-style-attr/#syntax',

package/lib/css-overrides.d.ts

@@ -1 +1,8 @@
+/**
+ * CSS syntax overrides for css-tree's built-in definitions.
+ *
+ * Provides alternative syntax definitions for CSS transform functions
+ * and legacy value types to support SVG attribute validation where
+ * the standard CSS syntax is too strict.
+ */
 export declare const cssOverrides: Record<string, string>;

package/lib/css-overrides.js

@@ -1,3 +1,10 @@
+/**
+ * CSS syntax overrides for css-tree's built-in definitions.
+ *
+ * Provides alternative syntax definitions for CSS transform functions
+ * and legacy value types to support SVG attribute validation where
+ * the standard CSS syntax is too strict.
+ */
 export const cssOverrides = {
     // Alias
     'legacy-length-percentage': '<length> | <percentage> | <svg-length>',

package/lib/css-syntax.d.ts

@@ -1,2 +1,13 @@
 import type { CustomCssSyntax, Result, CssSyntax } from './types.js';
+/**
+ * Matches a value against a CSS syntax definition using css-tree.
+ *
+ * Supports both standard CSS syntax types (e.g., `<color>`) and custom syntax
+ * definitions with extended types, properties, and case-sensitive matching.
+ * Uses css-tree's lexer for syntax validation.
+ *
+ * @param value - The string value to match
+ * @param type - The CSS syntax identifier or custom syntax definition
+ * @returns The validation result
+ */
 export declare function cssSyntaxMatch(value: string, type: CssSyntax | CustomCssSyntax): Result;

package/lib/css-syntax.js

@@ -6,6 +6,17 @@ import { cssOverrides } from './css-overrides.js';
 const MIMIC_TAG_L = 'mimiccases---';
 const MIMIC_TAG_R = '---mimiccases';
 const MIMIC_LENGTH = (MIMIC_TAG_L + MIMIC_TAG_R).length;
+/**
+ * Matches a value against a CSS syntax definition using css-tree.
+ *
+ * Supports both standard CSS syntax types (e.g., `<color>`) and custom syntax
+ * definitions with extended types, properties, and case-sensitive matching.
+ * Uses css-tree's lexer for syntax validation.
+ *
+ * @param value - The string value to match
+ * @param type - The CSS syntax identifier or custom syntax definition
+ * @returns The validation result
+ */
 export function cssSyntaxMatch(value, type) {
     log('Search CSS Syntax: "%s"', type);
     const origin = value;
@@ -15,7 +26,7 @@ export function cssSyntaxMatch(value, type) {
     let propsExtended;
     let ref = undefined;
     let caseSensitive = false;
-    let ebnf = null;
+    let ebnf;
     if (typeof type === 'string') {
         defName = type;
         propsExtended = {};

package/lib/css-tokenizers.d.ts

@@ -1,2 +1,8 @@
 import type { CssSyntaxTokenizer } from './types.js';
+/**
+ * Custom CSS syntax tokenizers for css-tree integration.
+ *
+ * Provides tokenizer functions for CSS value types that require
+ * custom parsing logic beyond what css-tree supports natively.
+ */
 export declare const cssTokenizers: Record<string, CssSyntaxTokenizer>;

package/lib/css-tokenizers.js

@@ -1,4 +1,10 @@
 import { isBCP47 } from './rfc/is-bcp-47.js';
+/**
+ * Custom CSS syntax tokenizers for css-tree integration.
+ *
+ * Provides tokenizer functions for CSS value types that require
+ * custom parsing logic beyond what css-tree supports natively.
+ */
 export const cssTokenizers = {
     // RFC
     // https://tools.ietf.org/rfc/bcp/bcp47.html

package/lib/debug.d.ts

@@ -1,2 +1,5 @@
 import debug from 'debug';
+/**
+ * Debug logger for the `@markuplint/types` package.
+ */
 export declare const log: debug.Debugger;

package/lib/debug.js

@@ -1,2 +1,5 @@
 import debug from 'debug';
+/**
+ * Debug logger for the `@markuplint/types` package.
+ */
 export const log = debug('@markuplint/types');

package/lib/defs.d.ts

@@ -1,2 +1,10 @@
 import type { Defs } from './types.js';
+/**
+ * Built-in type definitions registry for HTML attribute value validation.
+ *
+ * Maps type identifiers to their validation logic, reference URLs,
+ * and expected value descriptions. Includes definitions for common types
+ * (Any, Number, URL, etc.), WHATWG-specified types (DateTime, MIMEType,
+ * CustomElementName, etc.), and format-specific validators (BCP47, Pattern, etc.).
+ */
 export declare const defs: Defs;

package/lib/defs.js

@@ -14,6 +14,14 @@ import { isCustomElementName } from './whatwg/is-custom-element-name.js';
 import { isItempropName } from './whatwg/is-itemprop-name.js';
 import { isNavigableTargetName } from './whatwg/is-navigable-target-name.js';
 import { checkLinkType } from './whatwg/check-link-type.js';
+/**
+ * Built-in type definitions registry for HTML attribute value validation.
+ *
+ * Maps type identifiers to their validation logic, reference URLs,
+ * and expected value descriptions. Includes definitions for common types
+ * (Any, Number, URL, etc.), WHATWG-specified types (DateTime, MIMEType,
+ * CustomElementName, etc.), and format-specific validators (BCP47, Pattern, etc.).
+ */
 export const defs = {
     Any: {
         ref: '',
@@ -426,6 +434,8 @@ export const defs = {
         ref: 'https://html.spec.whatwg.org/multipage/images.html#srcset-attributes',
         is(value) {
             const images = value.split(',');
+            let hasWidth = false;
+            let hasDensity = false;
             for (const image of images) {
                 // image candidate string
                 const [url, , descriptor, ...tail] = new TokenCollection(image.trim(), {
@@ -456,6 +466,7 @@ export const defs = {
                                     ],
                                 });
                             }
+                            hasWidth = true;
                             break;
                         }
                         case 'x': {
@@ -469,6 +480,7 @@ export const defs = {
                                     ],
                                 });
                             }
+                            hasDensity = true;
                             break;
                         }
                         default: {
@@ -487,6 +499,10 @@ export const defs = {
                         }
                     }
                 }
+                else {
+                    // No descriptor implies 1x (density descriptor)
+                    hasDensity = true;
+                }
                 if (tail[0]) {
                     return unmatched(value, 'unexpected-token', {
                         expects: [
@@ -498,6 +514,16 @@ export const defs = {
                     });
                 }
             }
+            if (hasWidth && hasDensity) {
+                return unmatched(value, 'unexpected-token', {
+                    expects: [
+                        {
+                            type: 'format',
+                            value: 'consistent descriptors (all width or all density, not mixed)',
+                        },
+                    ],
+                });
+            }
             return matched();
         },
     },

package/lib/directive.d.ts

@@ -1,3 +1,17 @@
 import type { Result, Directive, Defs } from './types.js';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Checks a value against a directive type definition.
+ *
+ * A directive type consists of a prefix pattern (string or regex) followed by
+ * a token value. This function extracts the token portion after the directive
+ * prefix and validates it against the token type.
+ *
+ * @param value - The string value to check
+ * @param type - The directive type definition containing directive patterns and token type
+ * @param defs - The type definitions registry for resolving nested types
+ * @param ref - Optional reference URL for the unmatched result
+ * @param cache - Whether to use cached results (defaults to `true`)
+ * @returns The validation result
+ */
 export declare function checkDirective(value: string, type: ReadonlyDeep<Directive>, defs: Defs, ref?: string, cache?: boolean): Result;

package/lib/directive.js

@@ -1,6 +1,20 @@
 import { regexParser } from '@markuplint/shared';
 import { checkBase } from './check-base.js';
 import { matched, unmatched } from './match-result.js';
+/**
+ * Checks a value against a directive type definition.
+ *
+ * A directive type consists of a prefix pattern (string or regex) followed by
+ * a token value. This function extracts the token portion after the directive
+ * prefix and validates it against the token type.
+ *
+ * @param value - The string value to check
+ * @param type - The directive type definition containing directive patterns and token type
+ * @param defs - The type definitions registry for resolving nested types
+ * @param ref - Optional reference URL for the unmatched result
+ * @param cache - Whether to use cached results (defaults to `true`)
+ * @returns The validation result
+ */
 export function checkDirective(value, type, defs, ref, cache = true) {
     const unmatches = [];
     for (const directive of type.directive) {

package/lib/enum.d.ts

@@ -1,4 +1,15 @@
 import type { Result } from './types.js';
 import type { Enum } from './types.schema.js';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Checks whether a value matches one of the allowed enumeration values.
+ *
+ * By default, comparison is case-insensitive and surrounding spaces are not allowed.
+ * These behaviors can be configured through the type definition.
+ *
+ * @param value - The string value to check
+ * @param type - The enum type definition containing the allowed values and options
+ * @param ref - Optional reference URL for the unmatched result
+ * @returns The validation result
+ */
 export declare function checkEnum(value: string, type: ReadonlyDeep<Enum>, ref?: string): Result;

package/lib/enum.js

@@ -1,4 +1,15 @@
 import { matched, unmatched } from './match-result.js';
+/**
+ * Checks whether a value matches one of the allowed enumeration values.
+ *
+ * By default, comparison is case-insensitive and surrounding spaces are not allowed.
+ * These behaviors can be configured through the type definition.
+ *
+ * @param value - The string value to check
+ * @param type - The enum type definition containing the allowed values and options
+ * @param ref - Optional reference URL for the unmatched result
+ * @returns The validation result
+ */
 export function checkEnum(value, type, ref) {
     const disallowToSurroundBySpaces = type.disallowToSurroundBySpaces ?? true;
     const caseInsensitive = type.caseInsensitive ?? true;

package/lib/get-candidate.d.ts

@@ -1,3 +1,14 @@
 type NullableString = string | null | undefined;
+/**
+ * Finds the closest matching candidate string using Levenshtein distance.
+ *
+ * Compares the input value against a list of candidate strings and returns
+ * the one with the highest similarity ratio (at least 50% similar).
+ * Returns `undefined` if no close match is found or the value exactly matches a candidate.
+ *
+ * @param value - The input string to find a candidate for
+ * @param candidates - The candidate strings or arrays of strings to compare against
+ * @returns The closest matching candidate, or `undefined` if none is close enough
+ */
 export declare function getCandidate(value: NullableString, ...candidates: readonly (NullableString | readonly NullableString[])[]): string | undefined;
 export {};

package/lib/get-candidate.js

@@ -1,5 +1,16 @@
 import leven from 'leven';
 const FLAT_DEPTH = 2;
+/**
+ * Finds the closest matching candidate string using Levenshtein distance.
+ *
+ * Compares the input value against a list of candidate strings and returns
+ * the one with the highest similarity ratio (at least 50% similar).
+ * Returns `undefined` if no close match is found or the value exactly matches a candidate.
+ *
+ * @param value - The input string to find a candidate for
+ * @param candidates - The candidate strings or arrays of strings to compare against
+ * @returns The closest matching candidate, or `undefined` if none is close enough
+ */
 export function getCandidate(value, ...candidates) {
     if (!value) {
         return;

package/lib/index.d.ts

@@ -1,4 +1,13 @@
+/**
+ * @module @markuplint/types
+ *
+ * Provides type checking utilities for HTML attribute values,
+ * CSS syntax validation, and custom type definitions used by markuplint rules.
+ */
 export * from './whatwg/is-custom-element-name.js';
+export * from './whatwg/check-link-type.js';
 export * from './check.js';
 export * from './check-base.js';
-export * from './types.js';
+export { getCandidate } from './get-candidate.js';
+export { checkPattern } from './pattern.js';
+export type * from './types.js';

package/lib/index.js

@@ -1,4 +1,12 @@
+/**
+ * @module @markuplint/types
+ *
+ * Provides type checking utilities for HTML attribute values,
+ * CSS syntax validation, and custom type definitions used by markuplint rules.
+ */
 export * from './whatwg/is-custom-element-name.js';
+export * from './whatwg/check-link-type.js';
 export * from './check.js';
 export * from './check-base.js';
-export * from './types.js';
+export { getCandidate } from './get-candidate.js';
+export { checkPattern } from './pattern.js';

package/lib/keyword-type.d.ts

@@ -1,3 +1,16 @@
 import type { Defs, Result } from './types.js';
 import type { KeywordDefinedType } from './types.schema.js';
+/**
+ * Checks a value against a keyword-defined type or CSS syntax type.
+ *
+ * Looks up the type in the definitions registry and validates the value.
+ * If the type is not found in custom definitions, falls back to CSS syntax matching.
+ * Results are cached by default for performance.
+ *
+ * @param value - The string value to check
+ * @param type - The keyword type identifier to look up
+ * @param defs - The type definitions registry
+ * @param cache - Whether to use cached results (defaults to `true`)
+ * @returns The validation result
+ */
 export declare function checkKeywordType(value: string, type: KeywordDefinedType, defs: Defs, cache?: boolean): Result;

package/lib/keyword-type.js

@@ -4,6 +4,19 @@ import { log } from './debug.js';
 import { matched } from './match-result.js';
 const resultCache = new Map();
 const CACHE_KEY_PREFIX = '@markuplint/types/checkKeywordType/cache:::';
+/**
+ * Checks a value against a keyword-defined type or CSS syntax type.
+ *
+ * Looks up the type in the definitions registry and validates the value.
+ * If the type is not found in custom definitions, falls back to CSS syntax matching.
+ * Results are cached by default for performance.
+ *
+ * @param value - The string value to check
+ * @param type - The keyword type identifier to look up
+ * @param defs - The type definitions registry
+ * @param cache - Whether to use cached results (defaults to `true`)
+ * @returns The validation result
+ */
 export function checkKeywordType(value, type, defs, cache = true) {
     const key = `${CACHE_KEY_PREFIX}${value}${type}`;
     if (cache) {

package/lib/list.d.ts

@@ -1,4 +1,17 @@
 import type { Defs, Result } from './types.js';
 import type { List } from './types.schema.js';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Checks a value as a separated list of tokens against a type definition.
+ *
+ * Parses the value into tokens based on the list separator configuration,
+ * then validates each individual token against the list's token type.
+ *
+ * @param value - The string value to check as a list
+ * @param type - The list type definition containing separator and token type
+ * @param defs - The type definitions registry for resolving nested types
+ * @param ref - Optional reference URL for the unmatched result
+ * @param cache - Whether to use cached results (defaults to `true`)
+ * @returns The validation result
+ */
 export declare function checkList(value: string, type: ReadonlyDeep<List>, defs: Defs, ref?: string, cache?: boolean): Result;

package/lib/list.js

@@ -1,6 +1,19 @@
 import { checkBase } from './check-base.js';
 import { matched } from './match-result.js';
 import { Token, TokenCollection } from './token/index.js';
+/**
+ * Checks a value as a separated list of tokens against a type definition.
+ *
+ * Parses the value into tokens based on the list separator configuration,
+ * then validates each individual token against the list's token type.
+ *
+ * @param value - The string value to check as a list
+ * @param type - The list type definition containing separator and token type
+ * @param defs - The type definitions registry for resolving nested types
+ * @param ref - Optional reference URL for the unmatched result
+ * @param cache - Whether to use cached results (defaults to `true`)
+ * @returns The validation result
+ */
 export function checkList(value, type, defs, ref, cache = true) {
     const tokens = new TokenCollection(value, type);
     const matches = tokens.check({ ref });

package/lib/match-result.d.ts

@@ -1,9 +1,30 @@
 import type { FormattedPrimitiveTypeCheck, MatchedResult, UnmatchedResult, UnmatchedResultOptions, UnmatchedResultReason } from './types.js';
+/**
+ * Creates a value checker function that wraps a primitive type check
+ * and returns a matched or unmatched result.
+ *
+ * @param checker - The primitive type check function to wrap
+ * @param options - Optional settings for the unmatched result including ref and reason
+ * @returns A function that takes a string value and returns a match result
+ */
 export declare function matches(checker: FormattedPrimitiveTypeCheck, options?: UnmatchedResultOptions & {
     readonly ref?: string;
     readonly reason?: UnmatchedResultReason;
-}): (value: string) => UnmatchedResult | MatchedResult;
+}): (value: string) => MatchedResult | UnmatchedResult;
+/**
+ * Creates a successful match result.
+ *
+ * @returns A matched result object
+ */
 export declare function matched(): MatchedResult;
+/**
+ * Creates a failed match result with location and reason information.
+ *
+ * @param value - The raw string value that failed to match
+ * @param reason - The reason for the mismatch
+ * @param options - Optional settings including ref URL and expected values
+ * @returns An unmatched result object with position details
+ */
 export declare function unmatched(value: string, reason?: UnmatchedResultReason, options?: UnmatchedResultOptions & {
     readonly ref?: string;
 }): UnmatchedResult;