@markuplint/types 4.8.1 → 4.18.0

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,5 +1,7 @@
 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 = () => {

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;

package/lib/token/token-collection.js

@@ -1,6 +1,21 @@
 import { matched, unmatched } from '../match-result.js';
 import { Token } from './token.js';
+/**
+ * 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 class TokenCollection extends Array {
+    /**
+     * 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, patterns, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     typeOptions) {
@@ -15,7 +30,7 @@ export class TokenCollection extends Array {
             cumulativeOffset += tokenValue.length;
             return token;
         }
-        let isBroken = false;
+        let isBroken;
         do {
             isBroken = false;
             for (const pattern of patterns) {
@@ -107,10 +122,23 @@ export class TokenCollection extends Array {
             offset += v.length;
         }
     }
+    /**
+     * The concatenated string value of all tokens in this collection.
+     */
     get value() {
         const value = this.map(t => t.value).join('');
         return value;
     }
+    /**
+     * 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 = {}) {
         const { expects, ref } = options;
         if (this.separator !== 'space' && this.disallowToSurroundBySpaces) {
@@ -187,6 +215,12 @@ export class TokenCollection extends Array {
         }
         return matched();
     }
+    /**
+     * 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) {
         const chunks = [];
         const tokens = this.slice();
@@ -197,6 +231,12 @@ export class TokenCollection extends Array {
         }
         return chunks;
     }
+    /**
+     * 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) {
         const _tokens = this.slice();
         let prev = _tokens.shift();
@@ -213,6 +253,12 @@ export class TokenCollection extends Array {
         }
         return null;
     }
+    /**
+     * 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) {
         const _a = this.slice(0, position);
         const _b = this.slice(position);
@@ -220,6 +266,15 @@ export class TokenCollection extends Array {
         const b = TokenCollection._new(_b, this);
         return [a, b];
     }
+    /**
+     * 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) {
         let headAndTail = this.headAndTail();
         let head = headAndTail.head;
@@ -286,9 +341,21 @@ export class TokenCollection extends Array {
         }
         return matched();
     }
+    /**
+     * 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) {
         return TokenCollection._new(super.filter(callback), this);
     }
+    /**
+     * 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) {
         const resultToken = this.compareTokens((prev, current) => {
             if (prev.type === tokenType && current.type === tokenType) {
@@ -297,6 +364,13 @@ export class TokenCollection extends Array {
         });
         return resultToken ?? 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() {
         const aList = this.slice();
         const bList = this.slice();
@@ -318,16 +392,28 @@ export class TokenCollection extends Array {
         }
         return null;
     }
+    /**
+     * Returns only the identifier tokens, excluding whitespace and separators.
+     *
+     * @returns A new TokenCollection containing only Ident-type tokens
+     */
     getIdentTokens() {
         return this.filter(token => token.type === Token.Ident);
     }
     /**
+     * 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) {
         return this.some(t => t.matches(value));
     }
+    /**
+     * 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() {
         const copy = this.slice();
         const head = copy.shift();
@@ -338,8 +424,10 @@ export class TokenCollection extends Array {
         return { head, tail };
     }
     /**
+     * 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) {
         for (const token of this) {
@@ -349,6 +437,13 @@ export class TokenCollection extends Array {
         }
         return 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, lastTokenNumber) {
         const tokens = this.slice();
         for (let i = 0; i < tokens.length; i++) {
@@ -374,6 +469,11 @@ export class TokenCollection extends Array {
         }
         return null;
     }
+    /**
+     * Converts all tokens in this collection to plain JSON-serializable objects.
+     *
+     * @returns An array of plain token objects
+     */
     toJSON() {
         return this.map(t => t.toJSON());
     }

package/lib/token/token.d.ts

@@ -1,5 +1,12 @@
 import type { TokenValue } from './types.js';
 import type { UnmatchedResult, UnmatchedResultOptions, UnmatchedResultReason } from '../types.js';
+/**
+ * Represents a single token within a parsed string value.
+ *
+ * Tracks the token's value, type (whitespace, comma, or identifier),
+ * offset position within the original string, and provides methods
+ * for matching and comparison operations.
+ */
 export declare class Token {
     /**
      * @see https://github.com/csstree/csstree/blob/master/lib/tokenizer/types.js
@@ -26,11 +33,32 @@ export declare class Token {
      * @deprecated Use {@link getPosition} instead. Will be removed in v5.0.0.
      */
     static getLine(value: string, offset: number): number;
+    /**
+     * Calculates the line and column position at the given offset within a string.
+     *
+     * @param value - The source string
+     * @param offset - The character offset to calculate the position for
+     * @returns The line number (1-based) and column number (1-based)
+     */
     static getPosition(value: string, offset: number): {
         line: number;
         column: number;
     };
+    /**
+     * Determines the token type based on the first character.
+     *
+     * @param value - The token string value
+     * @param separators - Optional separator characters to detect
+     * @returns The token type number (WhiteSpace, Comma, or Ident)
+     */
     static getType(value: string, separators?: readonly string[]): 1 | 18 | 13;
+    /**
+     * Calculates a new position by shifting from a token's offset.
+     *
+     * @param token - The base token to shift from
+     * @param offset - The additional offset to apply
+     * @returns The shifted offset, line, and column
+     */
     static shiftLocation(token: Readonly<Token>, offset: number): {
         offset: number;
         line: number;
@@ -40,25 +68,61 @@ export declare class Token {
     readonly originalValue: string;
     readonly type: number;
     readonly value: string;
+    /**
+     * @param value - The token string value
+     * @param offset - The offset position within the original string
+     * @param originalValue - The complete original string this token was parsed from
+     * @param separators - Optional separator characters used for type detection
+     */
     constructor(value: string, offset: number, originalValue: string, separators?: readonly string[]);
+    /**
+     * The character length of the token value.
+     */
     get length(): number;
+    /**
+     * Creates a copy of this token.
+     *
+     * @returns A new Token instance with the same value, offset, and original value
+     */
     clone(): Token;
     /**
+     * Checks whether this token's value contains 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
+     * @param caseInsensitive - Whether to perform case-insensitive comparison
+     * @returns Whether this token includes the given value
      */
     includes(value: TokenValue, caseInsensitive?: boolean): boolean;
     /**
+     * Checks whether this token exactly 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 match against
+     * @param caseInsensitive - Whether to perform case-insensitive comparison
+     * @returns Whether this token matches the given value
      */
     matches(value: TokenValue, caseInsensitive?: boolean): boolean;
+    /**
+     * Converts this token to a plain JSON-serializable object.
+     *
+     * @returns An object with type, value, and offset properties
+     */
     toJSON(): {
         type: number;
         value: string;
         offset: number;
     };
+    /**
+     * Parses the token value as a floating-point number.
+     *
+     * @returns The parsed number, or 0 if parsing fails
+     */
     toNumber(): number;
+    /**
+     * Creates an unmatched result positioned at this token's location.
+     *
+     * @param options - Optional settings including ref, reason, and expected values
+     * @returns An unmatched result with this token's position information
+     */
     unmatched(options?: UnmatchedResultOptions & {
         readonly ref?: string;
         readonly reason?: UnmatchedResultReason;