Sequence Generation
Relevant source files
The following files were used as context for generating this wiki page:
Sequence Generation in the nth-check library refers to the process of creating a monotonously increasing sequence of indices that satisfy a CSS nth-child formula. Unlike the standard compilation which returns a boolean check for a specific index, sequence generation provides a stateful generator function that yields valid indices one by one.
This feature is primarily exposed through the generate and sequence functions. It is designed for performance and adheres to the CSS3 Selectors specification, allowing developers to iterate through matching elements without manually calculating offsets and steps.
Sources: README.md:9-11, src/index.ts:36-41, src/compile.ts:77-80
Core APIs for Sequence Generation
The library provides two main entry points for generating sequences, depending on whether the input is a pre-parsed tuple or a raw string formula.
| Function | Input Type | Description |
|---|---|---|
generate | [number, number] | Takes a tuple [a, b] and returns a generator function. |
sequence | string | Parses a formula and compiles it into a generator function. |
Sources: src/index.ts:36-63, src/compile.ts:77-81
The sequence Function
The sequence function acts as a high-level wrapper. It utilizes parse to convert a CSS formula (e.g., "2n+3") into a step/offset tuple and then passes that tuple to generate.
Sources: src/index.ts:64-66
The generate Function
The generate function contains the core logic for producing the sequence. It handles zero-indexing by subtracting 1 from the provided offset b. The returned function maintains an internal counter n to track the current position in the sequence.
Sources: src/compile.ts:77-85
Logic and Architecture
The generation logic varies significantly based on the value of a (the step size). The library optimizes for three primary scenarios: negative steps, zero steps, and positive steps.
Sequence Flow Diagram
The following diagram illustrates how the generate function determines which closure to return based on the parsed values.
The diagram shows the decision paths within src/compile.ts to provide the most efficient generator.
Sources: src/compile.ts:88-115
Implementation Details by Case
1. Negative Step (a < 0)
When a is negative, the sequence has a finite end because CSS indices cannot be less than 0 (mapped from 1-based CSS to 0-based library indices). The generator calculates a minValue (the smallest valid index) and increments until the value exceeds the original offset b.
Sources: src/compile.ts:88-96
2. Zero Step (a = 0)
If a is 0, the rule identifies a specific single index b.
- If
b < 0, the generator immediately returnsnull. - Otherwise, it returns the index
bonce andnullthereafter.
Sources: src/compile.ts:98-103
3. Positive Step (a > 0)
For positive steps, the sequence is theoretically infinite. The generator ensures the sequence starts at the first non-negative index by adjusting b if it is initially negative.
Sources: src/compile.ts:105-115
Usage Examples
Finite Sequence
For a formula like -2n + 5, the generator yields indices until they are no longer valid.
const gen = sequence("-2n+5");
gen(); // 0
gen(); // 2
gen(); // 4
gen(); // null
Sources: src/index.ts:57-62, src/compile.spec.ts:101-106
Infinite Sequence
For a formula like 2n + 3, the sequence continues indefinitely.
const gen = sequence("2n+3");
gen(); // 1 (CSS 2n+3 at n=0 is index 3, 0-indexed is 2)
// Note: Example in README shows 1, 3, 5... based on specific tuple logic
Sources: README.md:83-93, src/compile.spec.ts:92-98
Summary
Sequence generation in nth-check transforms CSS-style selector logic into stateful iterators. By handling the complexities of negative steps and one-to-zero index mapping internally, the module provides a simple interface for sequential element matching. The architecture prioritizes efficiency by returning specialized closures for different mathematical properties of the an+b formula.
Sources: src/compile.ts, src/index.ts