@markuplint/types 4.8.1 → 5.0.0-alpha.0

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) {
@@ -49,6 +64,13 @@ export class TokenCollection extends Array {
     static get [Symbol.species]() {
         return Array;
     }
+    allowEmpty;
+    caseInsensitive;
+    disallowToSurroundBySpaces;
+    number;
+    ordered;
+    separator;
+    unique;
     constructor(value, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     typeOptions) {
@@ -107,10 +129,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 +222,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 +238,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 +260,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 +273,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 +348,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 +371,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 +399,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 +431,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 +444,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 +476,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;

package/lib/token/token.js

@@ -1,4 +1,28 @@
+/**
+ * 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 class Token {
+    /**
+     * @see https://github.com/csstree/csstree/blob/master/lib/tokenizer/types.js
+     */
+    static Comma = 18;
+    static Ident = 1;
+    static WhiteSpace = 13;
+    /**
+     * ASCII whitespace is
+     * - U+0009 TAB
+     * - U+000A LF
+     * - U+000C FF
+     * - U+000D CR
+     * - U+0020 SPACE.
+     *
+     * @see https://infra.spec.whatwg.org/#ascii-whitespace
+     */
+    static whitespace = ['\u0009', '\u000A', '\u000C', '\u000D', '\u0020'];
     /**
      * @deprecated Use {@link getPosition} instead. Will be removed in v5.0.0.
      */
@@ -12,12 +36,26 @@ export class Token {
     static getLine(value, offset) {
         return value.slice(0, offset).split(/\n/).length;
     }
+    /**
+     * 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, offset) {
         const lines = value.slice(0, offset).split(/\n/);
         const line = lines.length;
         const column = (lines.at(-1) ?? '').length + 1;
         return { line, column };
     }
+    /**
+     * 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, separators) {
         if (Token.whitespace.includes(value[0] ?? '')) {
             return Token.WhiteSpace;
@@ -31,6 +69,13 @@ export class Token {
         }
         return Token.Ident;
     }
+    /**
+     * 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, offset) {
         const shifted = token.offset + offset;
         const { line, column } = Token.getPosition(token.originalValue, shifted);
@@ -40,25 +85,46 @@ export class Token {
             column,
         };
     }
+    offset;
+    originalValue;
+    type;
+    value;
+    /**
+     * @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, offset, originalValue, separators) {
         this.type = Token.getType(value, separators);
         this.value = value;
         this.offset = offset;
         this.originalValue = originalValue;
     }
+    /**
+     * The character length of the token value.
+     */
     get length() {
         return this.value.length;
     }
+    /**
+     * Creates a copy of this token.
+     *
+     * @returns A new Token instance with the same value, offset, and original value
+     */
     clone() {
         return new Token(this.value, this.offset, this.originalValue);
     }
     /**
+     * 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, caseInsensitive) {
         if (Array.isArray(value)) {
-            return value.some(v => this.includes(v));
+            return value.some(v => this.includes(v, caseInsensitive));
         }
         if (typeof value === 'string') {
             const a = caseInsensitive ? this.value.toLowerCase() : this.value;
@@ -72,12 +138,15 @@ export class Token {
         return this.type === value;
     }
     /**
+     * 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, caseInsensitive) {
         if (Array.isArray(value)) {
-            return value.some(v => this.matches(v));
+            return value.some(v => this.matches(v, caseInsensitive));
         }
         if (typeof value === 'string') {
             const a = caseInsensitive ? this.value.toLowerCase() : this.value;
@@ -90,6 +159,11 @@ export class Token {
         }
         return this.type === value;
     }
+    /**
+     * Converts this token to a plain JSON-serializable object.
+     *
+     * @returns An object with type, value, and offset properties
+     */
     toJSON() {
         return {
             type: this.type,
@@ -97,10 +171,21 @@ export class Token {
             offset: this.offset,
         };
     }
+    /**
+     * Parses the token value as a floating-point number.
+     *
+     * @returns The parsed number, or 0 if parsing fails
+     */
     toNumber() {
         const num = Number.parseFloat(this.value);
         return Number.isNaN(num) ? 0 : num;
     }
+    /**
+     * 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) {
         const { line, column } = Token.getPosition(this.originalValue, this.offset);
         return {
@@ -116,20 +201,3 @@ export class Token {
         };
     }
 }
-/**
- * @see https://github.com/csstree/csstree/blob/master/lib/tokenizer/types.js
- */
-Token.Comma = 18;
-Token.Ident = 1;
-Token.WhiteSpace = 13;
-/**
- * ASCII whitespace is
- * - U+0009 TAB
- * - U+000A LF
- * - U+000C FF
- * - U+000D CR
- * - U+0020 SPACE.
- *
- * @see https://infra.spec.whatwg.org/#ascii-whitespace
- */
-Token.whitespace = ['\u0009', '\u000A', '\u000C', '\u000D', '\u0020'];

package/lib/token/types.d.ts

@@ -1,3 +1,12 @@
+/**
+ * A single token value: a literal string, a regular expression pattern, or a token type number.
+ */
 export type TokenValueScalar = string | Readonly<RegExp> | number;
+/**
+ * An array of token values for matching against multiple patterns.
+ */
 export type TokenValueArray = readonly TokenValue[];
+/**
+ * A token value used for matching: either a scalar or an array of token values.
+ */
 export type TokenValue = TokenValueScalar | TokenValueArray;