Home

Relevant source files

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

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

nth-check is a high-performance utility designed to parse and compile CSS nth-child formulas into optimized JavaScript functions. It follows the CSS3 Selectors specification to determine if a specific element index matches a given rule or to generate a sequence of valid indices.

Sources: README.md:3-8, package.json:5

System Architecture

The project is structured into three primary phases: parsing, compilation, and execution. The library exports high-level functions that combine these steps for ease of use, while also exposing the underlying modular components.

Component Overview

Component	Responsibility	Key Files
Parser	Converts a string formula (e.g., "2n+3") into a tuple [a, b].	src/parse.ts
Compiler	Transforms the [a, b] tuple into a boolean check function or a generator.	src/compile.ts
API Entry	Provides the public interface for checking indices and generating sequences.	src/index.ts

Sources: src/index.ts:1-73, README.md:12-88

Core Data Flow

The following diagram illustrates the transformation from a CSS string formula to an executable function.

The flow shows how a formula string is decomposed into numerical components before being transformed into specific functional logic.
Sources: src/index.ts:28-73, src/compile.ts:25-117

Parsing Logic

The parse(formula) function processes CSS-style nth-expressions. It handles keywords like even and odd, as well as standard functional notation an+b.

Parsing Characteristics

• Standard Keywords: even maps to [2, 0], and odd maps to [2, 1].
• Complex Patterns: Handles signs (+, -), optional step sizes (defaulting to 1 if n is present), and offsets.
• Strictness: Throws an Error if the formula cannot be fully parsed or contains invalid characters.

Sources: src/parse.ts:15-60, src/fixtures/rules.ts:36-47

The parser uses a state-based approach to consume the string, identifying the coefficient a and the offset b.
Sources: src/parse.ts:15-60

Compilation and Optimization

The compile and generate functions transform the parsed tuple into optimized logic. The library uses boolbase for cases where a rule will never match (e.g., falseFunc).

The compile Function

The compiler produces a function (index: number) => boolean. It optimizes based on the values of a and b:

• If a is 0, it checks for strict equality with the offset.
• If a is 1, it checks if the index is greater than or equal to the offset.
• If a is -1, it checks if the index is less than or equal to the offset.
• For other values, it uses modulo arithmetic for efficient periodic matching.

Note: CSS nth-rules are 1-indexed, while the returned JavaScript functions expect 0-indexed values. The compiler automatically subtracts 1 from b to handle this conversion.

Sources: src/compile.ts:25-56, README.md:31-33

The generate Function

The generate function produces a function that, when called repeatedly, returns a monotonously increasing sequence of matching indices.

Sequence generation ensures that even with negative steps in the formula (e.g., -2n+5), the resulting indices are returned in increasing order.
Sources: src/compile.ts:81-117, README.md:61-88

Main API Methods

The library provides several entry points for different use cases.

Method	Description
nthCheck(formula)	Default export. Combines parse and compile to return a matcher function.
parse(formula)	Returns the raw [a, b] tuple.
compile([a, b])	Compiles a tuple into a matcher function.
generate([a, b])	Compiles a tuple into a sequence generator.
sequence(formula)	Combines parse and generate to return a sequence generator.

Sources: src/index.ts:28-73, README.md:12-88

Summary

nth-check provides a robust implementation for CSS nth-child logic, focusing on performance and specification compliance. By decoupling parsing from execution, it allows for pre-compilation of rules, which is highly efficient for frequent index checking in large DOM trees or virtualized lists.

Sources: README.md:3-10, package.json:5