Compilation Engine

Relevant source files

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

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

The Compilation Engine is the core component of the nth-check library, responsible for transforming CSS nth-child formulas into highly optimized JavaScript functions. Its primary purpose is to provide a performant way to determine if a specific element index matches a CSS selector rule or to generate a sequence of indices that satisfy such a rule. It strictly follows the CSS 3 Selectors specification while prioritizing execution speed.

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

Data Flow Architecture

The engine operates in two distinct phases: parsing and compilation. The parse function converts a string formula into a numeric tuple [a, b], representing the step size and offset respectively. The compile or generate functions then ingest this tuple to produce the final executable logic.

This diagram illustrates the transformation of a raw string input into optimized functional outputs.
Sources: src/index.ts:25-50, src/compile.ts:1-5

Core Components

The compile Function

The compile function generates a matcher function. It handles various edge cases for the a (step) and b (offset) values to ensure the fastest possible execution path. It converts the 1-based indexing of CSS selectors to the 0-based indexing used in JavaScript by subtracting 1 from the offset b.

Sources: src/compile.ts:21-25

Optimization Case	Condition	Logic Result
Empty Match	b < 0 && a <= 0	returns falseFunc
Single Limit	a === -1	index <= b
Exact Match	a === 0	index === b
All Elements	a === 1 && b < 0	returns trueFunc
Greater/Equal	a === 1 && b >= 0	index >= b
Step Match (Pos)	a > 1	index >= b && index % absA === bModulo
Step Match (Neg)	a < -1	index <= b && index % absA === bModulo

Sources: src/compile.ts:33-54

The generate Function

The generate function returns a stateful function that, when called, produces the next index in a monotonously increasing sequence. It handles both infinite sequences (e.g., 2n+3) and finite sequences (e.g., -2n+10).

This flow represents the logic used to ensure generated sequences are always increasing, even for negative step values.
Sources: src/compile.ts:88-115

Optimization Logic

The engine uses modulo arithmetic to avoid iterative loops when checking indices. By calculating bModulo = ((b % absA) + absA) % absA, the matcher can instantly validate an index using a single remainder check.

const absA = Math.abs(a);
const bModulo = ((b % absA) + absA) % absA;

return a > 1
    ? (index) => index >= b && index % absA === bModulo
    : (index) => index <= b && index % absA === bModulo;

Sources: src/compile.ts:50-54

Functional Interfaces

The engine exposes several high-level APIs through src/index.ts that combine the parsing and compilation steps for convenience.

• nthCheck(formula): Returns a function that checks if an index matches the formula. Sources: src/index.ts:25-27
• sequence(formula): Returns a generator function that produces matching indices. Sources: src/index.ts:50-52
• parse(formula): Direct access to the parser that returns the [a, b] tuple. Sources: src/parse.ts:14-16

Summary

The Compilation Engine transforms CSS nth-rule syntax into optimized functional primitives. By leveraging pre-calculated modulo values and specialized paths for constant or linear rules, it provides a high-performance solution for DOM filtering and sequence generation. Its architecture separates the concerns of string parsing from execution logic, allowing for reusable parsed tuples.

Sources: README.md:12-18, src/compile.ts:1-5