compile() API
Relevant source files
The following files were used as context for generating this wiki page:
The compile() API is a core component of the nth-check module, designed to transform parsed CSS nth-child formulas into highly optimized JavaScript functions. These functions determine whether a given element index matches the criteria defined by the nth-rule formula, such as 2n+3, even, or odd.
The module prioritizes performance by returning specialized functions tailored to specific types of formulas, ensuring the fastest possible execution during DOM traversal or style application. While CSS nth-rules follow a 1-based indexing system, the functions produced by compile() operate on 0-based indices, which is the standard for JavaScript arrays and most DOM APIs.
Sources: README.md:5-13, src/index.ts:7-17, src/compile.ts:18-22
Core Functionality
The compile function accepts a tuple representing the step (a) and offset (b) of an nth-rule and returns a predicate function.
Input Transformation
Before logic is applied, the 1-based offset b is converted to a 0-based index by subtracting 1. This alignment ensures compatibility with standard JavaScript iteration.
Sources: src/compile.ts:23-25
Logical Flow and Optimization
The compile API evaluates the values of a and b to return the most efficient predicate.
This flowchart illustrates the decision tree used to select the optimal matching function based on the nth-rule parameters.
Sources: src/compile.ts:34-51
Optimization Strategies
The API implements several specialized cases to avoid unnecessary calculations:
| Case | Condition | Resulting Function |
|---|---|---|
| No Match | b < 0 and a <= 0 | boolbase.falseFunc (always returns false) |
| Linear Limit | a === -1 | (index) => index <= b |
| Exact Match | a === 0 | (index) => index === b |
| Always Match | a === 1 and b < 0 | boolbase.trueFunc (always returns true) |
| Greater/Equal | a === 1 and b >= 0 | (index) => index >= b |
Sources: src/compile.ts:34-42
Modulo-Based Matching
For cases where |a| > 1, the API uses a modulo operation to check for matches. To handle negative steps or offsets correctly, the API calculates a bModulo value: ((b % absA) + absA) % absA.
- Positive Step (
a > 1): Matches ifindex >= bandindex % |a| === bModulo. - Negative Step (
a < -1): Matches ifindex <= bandindex % |a| === bModulo.
Sources: src/compile.ts:48-57
Integration and Usage
The compile() function is typically used in conjunction with parse(), which converts raw CSS strings into the required [a, b] tuple format.
The sequence shows the standard data flow from a formula string to an optimized predicate.
Sources: src/index.ts:25-27, src/parse.ts:16-18
Example Implementation
import { compile } from "nth-check";
// Represents 2n+3
const check = compile([2, 3]);
check(0); // false
check(2); // true (Matches index 2, which is the 3rd element)
Sources: src/compile.ts:11-16, src/compile.spec.ts:37-40
Testing and Validation
The compile() API is validated against a slowNth implementation in the test suite to ensure parity with standard selection logic across all valid nth-rule variations defined in the CSS specification.
Sources: src/compile.spec.ts:14-29, src/compile.spec.ts:35-43
Conclusion
The compile() API provides a high-performance bridge between CSS selector syntax and JavaScript execution. By specializing the returned function based on the input parameters, it minimizes the computational overhead required to validate element indices during complex selector matching operations.