Parsing Flow

Relevant source files

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

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

The Parsing Flow in nth-check is the initial stage of processing CSS nth-child formulas. Its primary purpose is to transform a string-based CSS selector expression (e.g., "2n+3") into a structured mathematical representation consisting of a step size (a) and an offset (b). This representation is then used by the compilation and generation modules to execute optimized index matching or sequence generation.

This flow adheres to the W3C CSS3 Selectors specification, supporting keyword aliases, signed integers, and the characteristic n notation. The parser is designed to be efficient, performing a single pass over the input string while handling whitespace and case-insensitivity.

Sources: src/parse.ts:1-12, README.md:1-15

Architectural Overview

The parsing logic is encapsulated within the parse function, which serves as the entry point for all formula interpretation. It is frequently invoked as a prerequisite for both compile (for matching) and generate (for sequences).

Sources: src/parse.ts:18-62

Component Breakdown

Core Parsing Logic

The parser operates by maintaining an internal index pointer as it traverses the formula. It utilizes helper functions to handle specific lexical patterns like signs, numbers, and whitespace.

Component	Description
readSign	Detects + or - characters and returns 1 or -1.
readNumber	Consumes digit characters (0-9) to form an integer. Returns null if no digits are found.
skipWhitespace	Skips characters defined by CSS spec as whitespace: , \t, \r, \n, \f.

Sources: src/parse.ts:5-7, src/parse.ts:66-107

Formula Structure Handling

The parser looks for the following patterns in order:

1. Keywords: Specifically even (mapped to [2, 0]) and odd (mapped to [2, 1]).
2. Step Size (a): Parsed before the n character. If n is present but no number precedes it, the value defaults to 1 (or -1 if a negative sign is present).
3. Offset (b): Parsed after the n character and an optional sign/whitespace.

Data Transformation

The parser converts various CSS syntax variations into a standardized [number, number] tuple.

Input Formula	a (Step)	b (Offset)	Explanation
"even"	2	0	Standard keyword
"odd"	2	1	Standard keyword
"5"	0	5	Offset only
"n+2"	1	2	a defaults to 1
"-n+3"	-1	3	a defaults to -1
"2n+1"	2	1	Fully specified

Sources: src/fixtures/rules.ts:1-35, src/parse.ts:21-26

Error Handling and Validation

The parser is strict regarding the formula structure. An Error is thrown if:

• The formula contains trailing characters after a valid expression (e.g., "2n+3 extra").
• The number component is missing where expected (e.g., a trailing sign without a following number in the offset position).
• The input does not match the expected an+b grammar.

Sources: src/parse.ts:60-63, src/parse.spec.ts:7-11

Integration in the Ecosystem

The parse function is the foundation for the library's high-level API.

// src/index.ts
export default function nthCheck(formula: string): (index: number) => boolean {
    return compile(parse(formula));
}

export function sequence(formula: string): () => number | null {
    return generate(parse(formula));
}

Sources: src/index.ts:27-29, src/index.ts:60-62

Summary

The Parsing Flow effectively normalizes complex CSS selector syntax into a simple mathematical pair. By handling edge cases like negative steps, omitted coefficients, and keyword aliases, it provides a robust starting point for the optimization and execution phases of the nth-check utility.

Sources: README.md:18-40