Getting Started

Relevant source files

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

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

nth-check is a specialized library designed to parse and compile CSS nth-child formulas into highly optimized JavaScript functions. It follows the CSS 3 Selectors specification to determine if a given index matches a rule (e.g., 2n+3) or to generate a sequence of indices that satisfy the rule. Sources: README.md:1-12, src/parse.ts:1

The library is built with TypeScript and targets modern Node.js environments (>= 20.19.0). It focuses on execution speed by providing specialized logic paths for different types of nth-rules, such as constant offsets, linear increments, or negative steps. Sources: package.json:60-62, src/compile.ts:40-63

Core Workflow

The system operates by taking a string formula, parsing it into a numeric representation, and then compiling that representation into an executable function or generator.

This diagram illustrates the transformation from a raw CSS string into optimized runtime functions. Sources: src/index.ts:25-72, src/parse.ts:16-55

Installation and Environment

The project is distributed as an ES module. It relies on boolbase for standard boolean functions. Sources: package.json:2-15, package.json:65-67

Project Scripts

Key development scripts available in the repository:

Script	Description
npm run build	Compiles TypeScript source to dist/ using tsc.
npm run test	Executes the test suite using vitest and runs linting.
npm run lint	Performs linting using eslint and biome.
npm run format	Automatically formats code using biome and eslint.

Sources: package.json:23-35

Primary API Methods

Parsing Formulas

The parse function transforms a CSS formula string into a tuple [a, b], where a is the step size and b is the offset. It handles keyword aliases like even ([2, 0]) and odd ([2, 1]). Sources: src/parse.ts:16-32

import { parse } from "nth-check";

parse("2n+3"); // Returns [2, 3]
parse("even"); // Returns [2, 0]

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

Compiling Checkers

The compile function converts the [a, b] tuple into a function that takes a zero-based index and returns a boolean.

• Indexing Note: While CSS nth-rules start counting at 1, the compiled function uses 0-based indexing for compatibility with JavaScript arrays. Sources: README.md:27-29, src/compile.ts:32-35

The sequence demonstrates the lifecycle of a formula matching operation. Sources: README.md:32-42, src/index.ts:25-27

Generating Sequences

The generate function creates a generator that produces a monotonically increasing sequence of valid indices. If a formula has a finite number of matches (e.g., -2n+5), the generator returns null once the sequence is exhausted. Sources: README.md:73-88, src/compile.ts:79-114

Logic and Optimization

The compiler chooses the most efficient logic based on the a and b values:

1. Constant Functions: If the rule matches nothing, it returns boolbase.falseFunc. Sources: src/compile.ts:40-45
2. Simple Comparisons: If a is 0, 1, or -1, the check is a simple equality or inequality (e.g., index === b). Sources: src/compile.ts:47-51
3. Modulo Arithmetic: For rules where |a| > 1, the library uses modulo logic: (index % absA === bModulo). Sources: src/compile.ts:59-63

Valid Formula Examples

Formula	Parsed [a, b]	Matching Indices (1-based)
n	[1, 0]	1, 2, 3, 4, ...
2n+1	[2, 1]	1, 3, 5, 7, ...
-n+3	[-1, 3]	1, 2, 3
3n-1	[3, -1]	2, 5, 8, 11, ...

Sources: src/fixtures/rules.ts:7-35

Summary

nth-check provides a high-performance utility for handling CSS nth-selectors by separating parsing from execution. By compiling formulas into optimized JavaScript functions, it allows for rapid index matching and sequence generation in DOM libraries or CSS engines. Sources: README.md:1-10, package.json:5-8