Execution Flow

Relevant source files

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

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

The nth-check library provides a high-performance execution flow for parsing and compiling CSS nth-child formulas into optimized JavaScript functions. The system transforms a string representation of a rule (e.g., "2n+3") into a tuple of integers representing the step and offset, which are then used to generate either a boolean check function or a sequence generator.

The primary entry points are the nthCheck function, which returns a validator, and the sequence function, which returns an index generator. Both follow a two-stage pipeline: parsing the input formula and then compiling the resulting parameters into an optimized execution strategy.

Sources: src/index.ts:25-54, README.md:12-25

Entry Point Resolution

The execution flow begins when a user invokes the library through its high-level API. The library exposes two main paths: checking an index against a formula and generating a sequence of indices based on a formula.

The high-level functions orchestrate the transition from raw strings to executable logic.
Sources: src/index.ts:25-54, README.md:12-25

Phase 1: Parsing Logic

The parse function converts a CSS nth-formula into a tuple [a, b], where a is the step size and b is the offset. It handles standard keywords like even and odd, as well as the standard an+b notation.

Parsing Steps

1. Normalization: The input string is trimmed and converted to lowercase.
2. Keyword Check: Strings matching "even" return [2, 0], and "odd" return [2, 1].
3. Coefficient (a) Extraction: The parser looks for an optional sign (+ or -) and an integer before the n character.
4. Offset (b) Extraction: After the n, the parser skips whitespace and looks for a second sign and integer.

Sources: src/parse.ts:16-55

Formula Part	Logic	Default if missing
Sign of a	Reads + or -	1 (Positive)
Coefficient a	Reads digits before n	1 if n exists, else 0
Sign of b	Reads + or - after n	0
Offset b	Reads digits after sign	0

Sources: src/parse.ts:40-108

Phase 2: Compilation and Optimization

Once parsed into [a, b], the values are passed to compile(parsed). The library optimizes the returned function based on the specific values of a and b to avoid unnecessary math during runtime.

Optimization Matrix

The compiler selects a strategy based on the values provided:

• Static Matches: If the rule never matches any elements (e.g., negative offset with negative step), it returns boolbase.falseFunc.
• Linear Matches: If a is 0, it checks for exact equality with b-1.
• Infinite Matches: If a is 1 and b is minimal, it may return boolbase.trueFunc.
• Modulo Matches: For steps greater than 1, it uses the modulo operator (%) and a pre-calculated bModulo to verify the index.

Sources: src/compile.ts:22-55

Phase 3: Sequence Generation

Alternatively, the generate function provides a flow for producing an increasing sequence of indices.

1. Initialization: It sets an internal counter n = 0.
2. Directionality: If a < 0, it calculates the sequence's end-point and returns null once exceeded.
3. Monotonicity: The generator ensures that values are returned in an increasing order, even if the formula uses negative coefficients (by iterating from the lowest valid index up to the offset).

Sources: src/compile.ts:80-120

Sequence Flow Comparison

Feature	compile (Boolean Check)	generate (Sequence)
Input	A specific index	No input (invoked repeatedly)
Return	true or false	number or null
Internal State	Stateless	Stateful (increments n)
Starting Index	User-defined	Calculated from b

Sources: src/compile.ts:22-120, src/compile.spec.ts:70-112

Summary of Execution Flow

The library's execution flow is characterized by a "Parse Once, Run Often" architecture. By transforming complex CSS selector strings into simple mathematical operations (like index % a === b) or pre-calculated sequence generators, the project minimizes the overhead of CSS pseudo-class evaluation in selector engines.

Sources: README.md:5-10, src/compile.ts:5-10