Basic Index Checking Examples

Relevant source files

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

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

The nth-check module provides high-performance utilities for parsing and compiling CSS nth-child formulas into optimized JavaScript functions. Its primary purpose is to determine if a specific element index matches a CSS selector rule or to generate a sequence of indices that satisfy such a rule. These capabilities are critical for CSS engine implementations and DOM manipulation libraries that need to support pseudo-classes like :nth-child() and :nth-last-of-type().

Sources: README.md:1-10, src/index.ts:5-15

Core Logic and API Flow

The system operates by first transforming a string formula into a numeric tuple representation [a, b], where a is the step size and b is the offset. This tuple is then used to generate either a validation function or a sequence generator.

The following diagram illustrates the standard data flow from a string formula to a functional index checker:

The flow starts with a user-provided string which is parsed into internal integer components before being compiled into optimized logic.
Sources: src/index.ts:25-58, src/compile.ts:23-30

Functional Components

Function	Input	Output	Description
parse	string	[number, number]	Converts CSS formulas (e.g., "even", "2n+1") into step and offset integers.
compile	[number, number]	(index: number) => boolean	Returns a function that checks if a 0-based index matches the 1-based CSS rule.
nthCheck	string	(index: number) => boolean	A convenience wrapper combining parse and compile.
generate	[number, number]	() => number | null	Returns a generator for a monotonously increasing sequence of matching indices.
sequence	string	() => number | null	A convenience wrapper combining parse and generate.

Sources: src/index.ts:5-66, src/compile.ts:23-26, src/parse.ts:13-16

Parsing Formulas

The parse function handles standard CSS syntax, keywords, and edge cases. It normalizes inputs by trimming whitespace and converting to lowercase.

Supported Rule Variations

• Keywords: even is parsed as [2, 0], and odd is parsed as [2, 1].
• Standard Forms: Rules like 2n+3, n+2, and -n+5.
• Constant Offsets: Simple integers like 5 (parsed as [0, 5]).

Sources: src/parse.ts:17-48, src/fixtures/rules.ts:1-33

The parsing logic includes specific branches for keywords and manual integer extraction for complex formulas.
Sources: src/parse.ts:17-68

Index Validation Logic

The compile function performs index normalization because CSS rules are 1-indexed while JavaScript arrays and the resulting functions are 0-indexed. The function internally subtracts 1 from the offset b.

Optimization Strategies

The compiler selects different logic based on the value of a:

• a = 0: Checks for exact match with b.
• a = 1: Checks if index is greater than or equal to b.
• a = -1: Checks if index is less than or equal to b.
• a > 1 or a < -1: Uses modulo arithmetic (index % absA === bModulo) to determine matches efficiently.

Sources: src/compile.ts:27-59

Logic Selection for compile(parsed)

The compiler chooses the most efficient comparison operator based on the step size a.
Sources: src/compile.ts:38-59

Sequence Generation

The generate function provides an iterator-like interface to retrieve matching indices in increasing order.

• Positive Step (a > 0): Produces an infinite sequence starting from the first valid index.
• Negative Step (a < 0): Produces a finite sequence until the index exceeds the boundary defined by the formula.
• Zero Step (a = 0): Produces a single value (the offset) and then returns null.

Sources: src/compile.ts:98-128

Examples from Fixtures

Formula	Parsed Tuple	First 3 Generated Indices
2n+3	[2, 3]	2, 4, 6 (0-indexed results: check(2)=true)
even	[2, 0]	1, 3, 5
-2n+5	[-2, 5]	0, 2, 4
3n-1	[3, -1]	1, 4, 7

Sources: src/fixtures/rules.ts:1-33, src/compile.spec.ts:74-106, README.md:27-40

Conclusion

nth-check serves as a robust utility for handling CSS-style index logic by decoupling formula parsing from execution logic. By transforming string expressions into optimized functions and generators, it enables efficient element filtering and sequence calculation in compliance with the CSS3 Selectors specification.

Sources: README.md:7-10, src/compile.ts:27-30