Index Validation

Relevant source files

The following files were used as context for generating this wiki page:

• src/compile.ts
• src/parse.ts
• src/index.ts
• src/compile.spec.ts
• README.md
• src/fixtures/rules.ts

Index Validation in the nth-check module refers to the process of parsing CSS nth-child formulas and transforming them into optimized functions that verify if a specific zero-based index matches the criteria defined by the formula. The system follows the W3C CSS3 Selectors specification to ensure compliance while focusing on execution speed.

The validation pipeline consists of two primary stages: parsing a string formula into a tuple representing the arithmetic progression an + b, and compiling that tuple into a highly optimized predicate function. This allows developers to check indices (starting at 0) against rules that naturally start counting at 1.

Sources: README.md:5-13, src/index.ts:25-27, src/parse.ts:1-2

Architecture and Data Flow

The Index Validation process flows from a raw string input to a boolean output for a given index. The nthCheck default export acts as the primary entry point, orchestrating the parse and compile phases.

The Parsing Phase

The parse function handles string normalization, keyword mapping (like even and odd), and arithmetic extraction. It identifies the step size (a) and the offset (b).

Formula Segment	Description	Mapping
even	Matches every second element starting from index 0	[2, 0]
odd	Matches every second element starting from index 1	[2, 1]
an + b	Standard arithmetic progression	[a, b]

Sources: src/parse.ts:16-25, src/fixtures/rules.ts:1-32

Optimized Compilation Logic

The compile function generates a predicate function tailored to the specific a and b values provided. To account for the difference between CSS counting (1-based) and programming indices (0-based), the system subtracts 1 from the offset b during compilation.

export function compile(
    parsed: [a: number, b: number],
): (index: number) => boolean {
    const a = parsed[0];
    const b = parsed[1] - 1; // Convert to zero-indexed
    
    // ... logic selection based on a and b
}

Sources: src/compile.ts:27-33

Validation Scenarios

The compiler selects different strategies based on the values of a and b:

1. Constant Matches: When a === 0, the function only checks if the index is exactly b - 1.
2. Range Matches: When a === 1 or a === -1, the function performs a simple inequality check (>= or <=).
3. Cyclic Matches: When abs(a) > 1, the system uses the modulo operator to verify if the index falls into the sequence.

Validation Rule Samples

The system handles a variety of valid and invalid formats as defined in the test fixtures.

Valid Rule Examples

Formula	a (Step)	b (Offset)	Logic
2n+1	2	1	Matches indices 0, 2, 4...
-n+3	-1	3	Matches indices 0, 1, 2
even	2	0	Matches indices 1, 3, 5...
5	0	5	Matches only index 4

Sources: src/fixtures/rules.ts:2-36

Invalid Formats

The parser throws an error for strings that do not follow the CSS specification, such as:

• Non-numeric expressions (e.g., an+b, asdf)
• Incorrectly spaced signs (e.g., - 1n)
• Empty or incomplete symbols (e.g., -)

Sources: src/fixtures/rules.ts:39-50, src/parse.ts:54-56

Conclusion

Index Validation within this module provides a robust bridge between CSS selector syntax and programmatic array indexing. By pre-compiling formulas into specific logic branches (modulo, inequality, or equality), it ensures that high-frequency checks in large document trees remain performant while adhering strictly to the W3C nth-child specification.

Sources: README.md:12-13, src/compile.ts:38-60