@markuplint/types 5.0.0-rc.2 → 5.0.0-rc.5

package/lib/match-result.js

@@ -1,11 +1,3 @@
-/**
- * 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);
@@ -15,24 +7,11 @@ 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,15 +1,3 @@
 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,17 +1,5 @@
 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/primitive/is-float.d.ts

@@ -1,9 +1,8 @@
 /**
- * Checks whether a string is a valid floating-point number.
+ * Intentionally looser than the strict WHATWG grammar: `Number.parseFloat()`
+ * accepts leading-dot values (`.5`) and ignores trailing non-numeric
+ * characters (`1.5abc`), both of which the spec production rejects.
  *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#floating-point-numbers
- *
- * @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,10 +1,9 @@
 /**
- * Checks whether a string is a valid floating-point number.
+ * Intentionally looser than the strict WHATWG grammar: `Number.parseFloat()`
+ * accepts leading-dot values (`.5`) and ignores trailing non-numeric
+ * characters (`1.5abc`), both of which the spec production rejects.
  *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#floating-point-numbers
- *
- * @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,9 +1,4 @@
 /**
- * Checks whether a string is a valid signed integer.
- *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#signed-integers
- *
- * @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,10 +1,5 @@
 /**
- * Checks whether a string is a valid signed integer.
- *
  * @see https://html.spec.whatwg.org/dev/common-microsyntaxes.html#signed-integers
- *
- * @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,7 +1 @@
-/**
- * Checks whether a string is a valid non-negative integer greater than zero.
- *
- * @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,9 +1,3 @@
-/**
- * Checks whether a string is a valid non-negative integer greater than zero.
- *
- * @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,9 +1 @@
-/**
- * Checks whether a string is a valid number with one of the allowed unit suffixes.
- *
- * @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

@@ -2,14 +2,6 @@ import { isFloat } from './is-float.js';
 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 - 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);
     if (!units.includes(unit.toLowerCase())) {

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

@@ -1,11 +1,5 @@
 /**
- * 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 - 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,11 +1,5 @@
 /**
- * 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 - 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,9 +1 @@
-/**
- * Checks whether a numeric string value falls within an inclusive range.
- *
- * @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,11 +1,3 @@
-/**
- * Checks whether a numeric string value falls within an inclusive range.
- *
- * @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);
     if (Number.isNaN(num)) {

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

@@ -1,9 +1,3 @@
-/**
- * Splits a value string into its numeric and unit parts.
- *
- * @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;
     unit: string;

package/lib/primitive/split-unit.js

@@ -1,9 +1,3 @@
-/**
- * Splits a value string into its numeric and unit parts.
- *
- * @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();
     const matched = value.match(/(^-?\.\d+|^-?\d+(?:\.\d+(?:e[+-]\d+)?)?)([a-z]+$)/i);

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

@@ -1,7 +1,30 @@
 import type { FormattedPrimitiveTypeCreator } from '../types.js';
 /**
- * Checks whether a string is a valid BCP 47 language tag.
+ * Checks **validity**, not just well-formedness, per RFC 5646 §2.2.9:
+ * "Either the tag is in the list of grandfathered tags or all of its
+ * primary language, extended language, script, region, and variant subtags
+ * appear in the IANA Language Subtag Registry as of the particular registry
+ * date", "There are no duplicate variant subtags", and "There are no
+ * duplicate singleton (extension) subtags". Extension subtags themselves
+ * are not registry-checked — §2.2.9 defines that as validity *for a given
+ * extension* (governed by the extension's own RFC), a stricter class than
+ * plain validity.
+ *
+ * Deprecated subtags (e.g. `mo`) remain registered, so they stay valid —
+ * §2.2.9 draws no distinction; deprecation is advisory only.
+ *
+ * The `bcp-47` parser (with its default normalization) resolves the 26
+ * grandfathered tags: those with a modern replacement (e.g. `i-klingon` →
+ * `tlh`) come back as ordinary subtags that pass the registry test, and
+ * those without one (e.g. `i-default`) come back flagged `irregular` /
+ * `regular` and are accepted via the grandfathered branch of §2.2.9.
+ *
+ * Accepts privateuse-only tags (e.g. `x-default`, common in `hreflang`)
+ * in addition to ordinary language tags, because BCP 47's `Language-Tag`
+ * production is `langtag / privateuse / grandfathered` — a tag with no
+ * `language` subtag is still valid when it is entirely private use.
  *
  * @see https://tools.ietf.org/rfc/bcp/bcp47.html
+ * @see https://www.rfc-editor.org/rfc/rfc5646.html#section-2.2.9
  */
 export declare const isBCP47: FormattedPrimitiveTypeCreator;

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

@@ -1,12 +1,97 @@
 import { parse } from 'bcp-47';
+import extlangIndex from 'language-subtag-registry/data/json/extlang.json' with { type: 'json' };
+import languageIndex from 'language-subtag-registry/data/json/language.json' with { type: 'json' };
+import regionIndex from 'language-subtag-registry/data/json/region.json' with { type: 'json' };
+import scriptIndex from 'language-subtag-registry/data/json/script.json' with { type: 'json' };
+import variantIndex from 'language-subtag-registry/data/json/variant.json' with { type: 'json' };
 /**
- * Checks whether a string is a valid BCP 47 language tag.
+ * Membership test against one subtag type of the IANA Language Subtag
+ * Registry (vendored as the `language-subtag-registry` npm package, which
+ * tracks the official registry; updating the dependency refreshes the data).
+ *
+ * The index files key every registered subtag in lowercase. Private-use
+ * allocations are recorded as ranged keys (`qaa..qtz` for languages,
+ * `qaaa..qabx` for scripts, `qm..qz` / `xa..xz` for regions) and are
+ * expanded here by lexicographic comparison — a subtag inside a range is
+ * registered per RFC 5646 §3.1.2 ("Private use subtags ... 'qaa..qtz'"
+ * range notation).
+ *
+ * @see https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
+ */
+function createSubtagLookup(index) {
+    const ranges = Object.keys(index)
+        .filter(key => key.includes('..'))
+        .map(key => key.split('..'));
+    return subtag => {
+        const lowered = subtag.toLowerCase();
+        if (Object.hasOwn(index, lowered)) {
+            return true;
+        }
+        return ranges.some(([start, end]) => lowered.length === start.length && start <= lowered && lowered <= end);
+    };
+}
+const isRegisteredLanguage = createSubtagLookup(languageIndex);
+const isRegisteredExtlang = createSubtagLookup(extlangIndex);
+const isRegisteredScript = createSubtagLookup(scriptIndex);
+const isRegisteredRegion = createSubtagLookup(regionIndex);
+const isRegisteredVariant = createSubtagLookup(variantIndex);
+/**
+ * Checks **validity**, not just well-formedness, per RFC 5646 §2.2.9:
+ * "Either the tag is in the list of grandfathered tags or all of its
+ * primary language, extended language, script, region, and variant subtags
+ * appear in the IANA Language Subtag Registry as of the particular registry
+ * date", "There are no duplicate variant subtags", and "There are no
+ * duplicate singleton (extension) subtags". Extension subtags themselves
+ * are not registry-checked — §2.2.9 defines that as validity *for a given
+ * extension* (governed by the extension's own RFC), a stricter class than
+ * plain validity.
+ *
+ * Deprecated subtags (e.g. `mo`) remain registered, so they stay valid —
+ * §2.2.9 draws no distinction; deprecation is advisory only.
+ *
+ * The `bcp-47` parser (with its default normalization) resolves the 26
+ * grandfathered tags: those with a modern replacement (e.g. `i-klingon` →
+ * `tlh`) come back as ordinary subtags that pass the registry test, and
+ * those without one (e.g. `i-default`) come back flagged `irregular` /
+ * `regular` and are accepted via the grandfathered branch of §2.2.9.
+ *
+ * Accepts privateuse-only tags (e.g. `x-default`, common in `hreflang`)
+ * in addition to ordinary language tags, because BCP 47's `Language-Tag`
+ * production is `langtag / privateuse / grandfathered` — a tag with no
+ * `language` subtag is still valid when it is entirely private use.
  *
  * @see https://tools.ietf.org/rfc/bcp/bcp47.html
+ * @see https://www.rfc-editor.org/rfc/rfc5646.html#section-2.2.9
  */
 export const isBCP47 = () => {
     return value => {
-        const { language, privateuse } = parse(value);
-        return !!language || (privateuse != null && privateuse.length > 0);
+        const { language, extendedLanguageSubtags, script, region, variants, extensions, privateuse, irregular, regular, } = parse(value);
+        if (irregular != null || regular != null) {
+            return true;
+        }
+        if (!language) {
+            return privateuse.length > 0;
+        }
+        if (!isRegisteredLanguage(language)) {
+            return false;
+        }
+        if (!extendedLanguageSubtags.every(subtag => isRegisteredExtlang(subtag))) {
+            return false;
+        }
+        if (script != null && !isRegisteredScript(script)) {
+            return false;
+        }
+        if (region != null && !isRegisteredRegion(region)) {
+            return false;
+        }
+        if (!variants.every(subtag => isRegisteredVariant(subtag))) {
+            return false;
+        }
+        const loweredVariants = variants.map(subtag => subtag.toLowerCase());
+        if (new Set(loweredVariants).size !== loweredVariants.length) {
+            return false;
+        }
+        const singletons = extensions.map(extension => extension.singleton.toLowerCase());
+        return new Set(singletons).size === singletons.length;
     };
 };

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

@@ -5,28 +5,11 @@ 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.
+ * Returning a result stops iteration; returning `void` continues to the next token.
  */
 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> {
     #private;
-    /**
-     * 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;
@@ -40,124 +23,31 @@ 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;
     }): 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, 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, 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;