@markuplint/types 4.8.1 → 5.0.0-alpha.0

package/lib/match-result.js

@@ -1,3 +1,11 @@
+/**
+ * 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 function matches(checker, options) {
     return (value) => {
         const valid = checker(value);
@@ -7,11 +15,24 @@ export function matches(checker, options) {
         return valid ? matched() : unmatched(value, options?.reason, options);
     };
 }
+/**
+ * Creates a successful match result.
+ *
+ * @returns A matched result object
+ */
 export function matched() {
     return {
         matched: true,
     };
 }
+/**
+ * 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 function unmatched(value, reason, options) {
     return {
         ...options,

package/lib/number.d.ts

@@ -1,3 +1,15 @@
 import type { Result } from './types.js';
 import type { Number as TypeNumber } from './types.schema.js';
+/**
+ * Checks whether a value matches a number type definition.
+ *
+ * Validates the value as either an integer or float, then checks range
+ * constraints (gt, gte, lt, lte) if defined. Supports clampable values
+ * that suggest the nearest valid boundary value as a candidate.
+ *
+ * @param value - The string value to check
+ * @param type - The number type definition with format and range constraints
+ * @param ref - Optional reference URL for the unmatched result
+ * @returns The validation result
+ */
 export declare function checkNumber(value: string, type: Readonly<TypeNumber>, ref?: string): Result;

package/lib/number.js

@@ -1,5 +1,17 @@
 import { matched, unmatched } from './match-result.js';
 import { isFloat, isInt } from './primitive/index.js';
+/**
+ * Checks whether a value matches a number type definition.
+ *
+ * Validates the value as either an integer or float, then checks range
+ * constraints (gt, gte, lt, lte) if defined. Supports clampable values
+ * that suggest the nearest valid boundary value as a candidate.
+ *
+ * @param value - The string value to check
+ * @param type - The number type definition with format and range constraints
+ * @param ref - Optional reference URL for the unmatched result
+ * @returns The validation result
+ */
 export function checkNumber(value, type, ref) {
     if (!value) {
         return unmatched(value, 'empty-token');

package/lib/pattern.d.ts

@@ -0,0 +1,12 @@
+import type { Pattern, Result } from './types.js';
+import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Validates a string value against a pattern type definition.
+ * The pattern can be either a regular expression literal in the form
+ * `/pattern/flags` or a plain string for exact equality matching.
+ *
+ * @param value - The string value to validate
+ * @param type - The pattern type definition containing the pattern string
+ * @returns A result indicating whether the value matches the pattern
+ */
+export declare function checkPattern(value: string, type: ReadonlyDeep<Pattern>): Result;

package/lib/pattern.js

@@ -0,0 +1,33 @@
+/**
+ * Validates a string value against a pattern type definition.
+ * The pattern can be either a regular expression literal in the form
+ * `/pattern/flags` or a plain string for exact equality matching.
+ *
+ * @param value - The string value to validate
+ * @param type - The pattern type definition containing the pattern string
+ * @returns A result indicating whether the value matches the pattern
+ */
+export function checkPattern(value, type) {
+    const regexMatch = type.pattern.match(/^\/(.*)\/([gim])*$/);
+    if (regexMatch && regexMatch[1]) {
+        const re = regexMatch[1];
+        const flag = regexMatch[2];
+        if (new RegExp(re, flag).test(value)) {
+            return { matched: true };
+        }
+    }
+    else if (value === type.pattern) {
+        return { matched: true };
+    }
+    return {
+        matched: false,
+        ref: null,
+        raw: value,
+        length: value.length,
+        offset: 0,
+        line: 1,
+        column: 1,
+        reason: 'syntax-error',
+        expects: [{ type: 'regexp', value: type.pattern }],
+    };
+}

package/lib/primitive/is-float.d.ts

@@ -1,6 +1,9 @@
 /**
+ * Checks whether a string is a valid floating-point number.
+ *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#floating-point-numbers
  *
- * @param value
+ * @param value - The string to validate
+ * @returns Whether the value is a valid floating-point number
  */
 export declare function isFloat(value: string): boolean;

package/lib/primitive/is-float.js

@@ -1,7 +1,10 @@
 /**
+ * Checks whether a string is a valid floating-point number.
+ *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#floating-point-numbers
  *
- * @param value
+ * @param value - The string to validate
+ * @returns Whether the value is a valid floating-point number
  */
 export function isFloat(value) {
     return value === value.trim() && Number.isFinite(Number.parseFloat(value));

package/lib/primitive/is-int.d.ts

@@ -1,6 +1,9 @@
 /**
+ * Checks whether a string is a valid signed integer.
+ *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#signed-integers
  *
- * @param value
+ * @param value - The string to validate
+ * @returns Whether the value is a valid signed integer
  */
 export declare function isInt(value: string): boolean;

package/lib/primitive/is-int.js

@@ -1,7 +1,10 @@
 /**
+ * Checks whether a string is a valid signed integer.
+ *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#signed-integers
  *
- * @param value
+ * @param value - The string to validate
+ * @returns Whether the value is a valid signed integer
  */
 export function isInt(value) {
     return /^-?\d+$/.test(value);

package/lib/primitive/is-non-zero-uint.d.ts

@@ -1,6 +1,7 @@
 /**
- * Non-negative integer greater than zero
+ * Checks whether a string is a valid non-negative integer greater than zero.
  *
- * @param value
+ * @param value - The string to validate
+ * @returns Whether the value is a valid non-zero unsigned integer
  */
 export declare function isNonZeroUint(value: string): boolean;

package/lib/primitive/is-non-zero-uint.js

@@ -1,7 +1,8 @@
 /**
- * Non-negative integer greater than zero
+ * Checks whether a string is a valid non-negative integer greater than zero.
  *
- * @param value
+ * @param value - The string to validate
+ * @returns Whether the value is a valid non-zero unsigned integer
  */
 export function isNonZeroUint(value) {
     return /^\d+$/.test(value) && !/^0+$/.test(value);

package/lib/primitive/is-quantity.d.ts

@@ -1,7 +1,9 @@
 /**
+ * Checks whether a string is a valid number with one of the allowed unit suffixes.
  *
- * @param value
- * @param units
- * @param numberType
+ * @param value - The string to validate (e.g., "10px", "1.5em")
+ * @param units - The allowed unit suffixes (e.g., `["px", "em", "rem"]`)
+ * @param numberType - The number format constraint: `"int"`, `"uint"`, or `"float"` (defaults to `"float"`)
+ * @returns Whether the value is a valid quantity with an allowed unit
  */
 export declare function isQuantity(value: string, units: readonly string[], numberType?: 'int' | 'uint' | 'float'): boolean;

package/lib/primitive/is-quantity.js

@@ -3,10 +3,12 @@ import { isInt } from './is-int.js';
 import { isUint } from './is-uint.js';
 import { splitUnit } from './split-unit.js';
 /**
+ * Checks whether a string is a valid number with one of the allowed unit suffixes.
  *
- * @param value
- * @param units
- * @param numberType
+ * @param value - The string to validate (e.g., "10px", "1.5em")
+ * @param units - The allowed unit suffixes (e.g., `["px", "em", "rem"]`)
+ * @param numberType - The number format constraint: `"int"`, `"uint"`, or `"float"` (defaults to `"float"`)
+ * @returns Whether the value is a valid quantity with an allowed unit
  */
 export function isQuantity(value, units, numberType = 'float') {
     const { num, unit } = splitUnit(value);

package/lib/primitive/is-uint.d.ts

@@ -1,7 +1,11 @@
 /**
+ * Checks whether a string is a valid non-negative integer.
+ *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#non-negative-integers
  *
- * @param value
+ * @param value - The string to validate
+ * @param options - Optional constraints; use `gt` to require a value greater than the specified number
+ * @returns Whether the value is a valid non-negative integer within the constraints
  */
 export declare function isUint(value: string, options?: {
     readonly gt?: number;

package/lib/primitive/is-uint.js

@@ -1,7 +1,11 @@
 /**
+ * Checks whether a string is a valid non-negative integer.
+ *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#non-negative-integers
  *
- * @param value
+ * @param value - The string to validate
+ * @param options - Optional constraints; use `gt` to require a value greater than the specified number
+ * @returns Whether the value is a valid non-negative integer within the constraints
  */
 export function isUint(value, options) {
     const matched = /^\d+$/.test(value);

package/lib/primitive/range.d.ts

@@ -1,8 +1,9 @@
 /**
- * It is in the range between `from` and `to`.
+ * Checks whether a numeric string value falls within an inclusive range.
  *
- * @param value
- * @param from
- * @param to
+ * @param value - The string to parse as a number and validate
+ * @param from - The minimum allowed value (inclusive)
+ * @param to - The maximum allowed value (inclusive)
+ * @returns Whether the parsed number is within the range `[from, to]`
  */
 export declare function range(value: string, from: number, to: number): boolean;

package/lib/primitive/range.js

@@ -1,9 +1,10 @@
 /**
- * It is in the range between `from` and `to`.
+ * Checks whether a numeric string value falls within an inclusive range.
  *
- * @param value
- * @param from
- * @param to
+ * @param value - The string to parse as a number and validate
+ * @param from - The minimum allowed value (inclusive)
+ * @param to - The maximum allowed value (inclusive)
+ * @returns Whether the parsed number is within the range `[from, to]`
  */
 export function range(value, from, to) {
     const num = Number.parseFloat(value);

package/lib/primitive/split-unit.d.ts

@@ -1,7 +1,8 @@
 /**
+ * Splits a value string into its numeric and unit parts.
  *
- * @param value
- * @returns
+ * @param value - The string to split (e.g., "10px", "1.5em")
+ * @returns An object with `num` (the numeric part) and `unit` (the unit suffix, or empty string)
  */
 export declare function splitUnit(value: string): {
     num: string;

package/lib/primitive/split-unit.js

@@ -1,7 +1,8 @@
 /**
+ * Splits a value string into its numeric and unit parts.
  *
- * @param value
- * @returns
+ * @param value - The string to split (e.g., "10px", "1.5em")
+ * @returns An object with `num` (the numeric part) and `unit` (the unit suffix, or empty string)
  */
 export function splitUnit(value) {
     value = value.trim().toLowerCase();

package/lib/rfc/is-bcp-47.d.ts

@@ -1,5 +1,7 @@
 import type { FormattedPrimitiveTypeCreator } from '../types.js';
 /**
+ * Checks whether a string is a valid BCP 47 language tag.
+ *
  * @see https://tools.ietf.org/rfc/bcp/bcp47.html
  */
 export declare const isBCP47: FormattedPrimitiveTypeCreator;

package/lib/rfc/is-bcp-47.js

@@ -1,10 +1,12 @@
 import { parse } from 'bcp-47';
 /**
+ * Checks whether a string is a valid BCP 47 language tag.
+ *
  * @see https://tools.ietf.org/rfc/bcp/bcp47.html
  */
 export const isBCP47 = () => {
     return value => {
-        const { language } = parse(value);
-        return !!language;
+        const { language, privateuse } = parse(value);
+        return !!language || (privateuse != null && privateuse.length > 0);
     };
 };

package/lib/token/token-collection.d.ts

@@ -4,8 +4,28 @@ import { Token } from './token.js';
 type TokenCollectionOptions = Partial<Omit<List, 'token'> & {
     specificSeparator: string | string[];
 }>;
+/**
+ * Callback function for sequential token checking in {@link TokenCollection.eachCheck}.
+ * Receives the current head token and remaining tail tokens.
+ * Returns a result to stop iteration, or `void` to continue.
+ */
 export type TokenEachCheck = (head: Readonly<Token> | null, tail: TokenCollection) => Result | void;
+/**
+ * An ordered collection of tokens parsed from a string value.
+ *
+ * Extends `Array<Token>` with parsing, validation, and query capabilities.
+ * Supports configurable separators (space, comma, or custom), uniqueness
+ * constraints, ordering checks, and case sensitivity options.
+ */
 export declare class TokenCollection extends Array<Token> {
+    /**
+     * Creates a TokenCollection by matching a value against a sequence of regex patterns.
+     *
+     * @param value - The source token or string to parse
+     * @param patterns - The regex patterns to match sequentially
+     * @param typeOptions - Optional collection configuration
+     * @returns A new TokenCollection containing the matched tokens
+     */
     static fromPatterns(value: Readonly<Token> | string, patterns: readonly Readonly<RegExp>[], typeOptions?: Omit<TokenCollectionOptions, 'specificSeparator'> & {
         repeat?: boolean;
     }): TokenCollection;
@@ -19,39 +39,124 @@ export declare class TokenCollection extends Array<Token> {
     readonly unique: NonNullable<List['unique']>;
     constructor(value?: string, typeOptions?: TokenCollectionOptions);
     constructor(value?: number);
+    /**
+     * The concatenated string value of all tokens in this collection.
+     */
     get value(): string;
+    /**
+     * Validates the token collection structure against its configuration.
+     *
+     * Checks for unexpected spaces, consecutive commas, empty tokens,
+     * and duplicate values based on the collection's separator, allowEmpty,
+     * and unique settings.
+     *
+     * @param options - Optional validation settings including expected values and reference URL
+     * @returns The validation result
+     */
     check(options?: {
         expects?: Expect[];
         ref?: string;
         cache?: boolean;
-    }): UnmatchedResult | import("../types.js").MatchedResult;
+    }): import("../types.js").MatchedResult | UnmatchedResult;
+    /**
+     * Splits this collection into chunks of the specified size.
+     *
+     * @param split - The number of tokens per chunk
+     * @returns An array of TokenCollection chunks
+     */
     chunk(split: number): TokenCollection[];
+    /**
+     * Iterates over consecutive token pairs, calling the callback for each pair.
+     *
+     * @param callback - A function receiving the previous and current token; return a token to stop iteration
+     * @returns The token returned by the callback, or `null` if iteration completes
+     */
     compareTokens(callback: (prev: Readonly<Token>, current: Readonly<Token>) => Readonly<Token> | null | void): Readonly<Token> | null | undefined;
+    /**
+     * Splits this collection into two at the given position.
+     *
+     * @param position - The index at which to split
+     * @returns A tuple of two TokenCollections: before and after the position
+     */
     divide(position: number): readonly [TokenCollection, TokenCollection];
+    /**
+     * Applies a sequence of check callbacks to consecutive tokens.
+     *
+     * Each callback receives the current head token and remaining tail.
+     * Tracks pass count and cumulative offset for error reporting.
+     *
+     * @param callbacks - The check functions to apply sequentially
+     * @returns The validation result
+     */
     eachCheck(...callbacks: readonly TokenEachCheck[]): Result;
+    /**
+     * Creates a new TokenCollection containing only tokens that pass the test.
+     *
+     * @param callback - The filter predicate function
+     * @returns A new TokenCollection with the filtered tokens
+     */
     filter(callback: Parameters<Array<Token>['filter']>[0]): TokenCollection;
+    /**
+     * Finds the first occurrence of two consecutive tokens of the same type.
+     *
+     * @param tokenType - The token type number to check for consecutive occurrences
+     * @returns The second consecutive token, or `null` if none found
+     */
     getConsecutiveToken(tokenType: number): Readonly<Token> | null;
+    /**
+     * Finds the first duplicated token in this collection.
+     *
+     * Comparison respects the `caseInsensitive` setting of this collection.
+     *
+     * @returns The duplicated token, or `null` if all tokens are unique
+     */
     getDuplicated(): Token | null;
+    /**
+     * Returns only the identifier tokens, excluding whitespace and separators.
+     *
+     * @returns A new TokenCollection containing only Ident-type tokens
+     */
     getIdentTokens(): TokenCollection;
     /**
+     * Checks whether any token in this collection matches the given value.
      *
-     * @param value The token value or the token type or its list
+     * @param value - The token value, type number, regex, or array to check against
+     * @returns Whether any token matches
      */
     has(value: TokenValue): boolean;
+    /**
+     * Splits this collection into a head token and a tail collection.
+     *
+     * @returns An object with `head` (first token or null) and `tail` (remaining tokens)
+     */
     headAndTail(): {
         head: Token | null;
         tail: TokenCollection;
     };
     /**
+     * Searches for the first token that includes the given value.
      *
-     * @param value The token value or the token type or its list
+     * @param value - The token value, type number, regex, or array to search for
+     * @returns The first matching token, or `null` if not found
      */
     search(value: TokenValue): Token | null;
+    /**
+     * Verifies that tokens alternate between the specified types in order.
+     *
+     * @param tokenNumbers - The expected repeating pattern of token types
+     * @param lastTokenNumber - Optional expected type for the last token
+     * @returns An error object if the pattern is violated, or `null` if valid
+     */
     takeTurns(tokenNumbers: ReadonlyArray<number>, lastTokenNumber?: number): {
         unexpectedLastToken: boolean;
         expectedTokenNumber: number | undefined;
         token: Token;
     } | null;
+    /**
+     * Converts all tokens in this collection to plain JSON-serializable objects.
+     *
+     * @returns An array of plain token objects
+     */
     toJSON(): {
         type: number;
         value: string;