sequence() API

Relevant source files

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

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

The sequence() API is a high-level utility within the nth-check library that combines parsing and generation logic. It takes a CSS nth-child formula string and returns a generator function. This generator function produces a monotonously increasing sequence of indices (starting from 0) that match the provided formula.

Sources: src/index.ts:34-40, README.md:92-95

The API is primarily used when developers need to iterate through valid matching indices rather than checking if a specific index matches. It abstracts the underlying steps of converting a string formula into a numeric tuple and subsequently into a stateful generator.

Sources: src/index.ts:60-61, src/compile.ts:79-84

Architecture and Data Flow

The sequence() function acts as a wrapper that orchestrates two main internal processes: parsing the input string into an [a, b] tuple and passing that tuple to the generate function to create the iterator.

The diagram shows the transformation from a string input to a stateful generator function.
Sources: src/index.ts:60-61, src/parse.ts:16, src/compile.ts:114

Component Interaction Table

Component	Responsibility	Relevant File
parse(formula)	Converts CSS strings (e.g., "even", "2n+1") into a step/offset tuple.	src/parse.ts
generate([a, b])	Creates a stateful function that calculates the next index in a sequence.	src/compile.ts
sequence(formula)	Convenience entry point combining parse and generate.	src/index.ts

Sources: src/index.ts:60-61, src/compile.ts:114, src/parse.ts:16

Underlying Logic and Implementation

The behavior of the generator returned by sequence() depends on the a (step) and b (offset) values extracted during parsing.

1. Parsing Logic

The parse function handles standard CSS keywords and complex formulas. It normalizes inputs by trimming and converting to lowercase.

• Keywords: "even" becomes [2, 0], "odd" becomes [2, 1].
• Formulas: Supports signs, numbers, and the "n" variable (e.g., -2n+5).

Sources: src/parse.ts:17-48

2. Generation Strategies

The generate function (and by extension sequence) adjusts its logic based on the value of a:

• Positive Step (a > 0): Returns an infinite increasing sequence: a * n++ + b.
• Zero Step (a = 0): Returns the offset b exactly once (if b >= 0), then returns null.
• Negative Step (a < 0): Returns a finite sequence. It calculates the minValue using modulo and increments until the value exceeds the original offset b.

Sources: src/compile.ts:114-148

Sequence Calculation Flow

Logic flow within the generator function returned by sequence().
Sources: src/compile.ts:121-147

API Usage Examples

Increasing Sequence

When provided with a positive step, the sequence continues indefinitely.

const gen = sequence("2n+3");
gen(); // 2 (3-1 internally for 0-indexing)
gen(); // 4
gen(); // 6

Note: While the CSS spec counts from 1, the generator returns 0-based indices.
Sources: README.md:99-105, src/compile.ts:116-117

Finite Sequence

Negative steps result in a sequence that ends with null.

const gen = sequence("-2n+5");
gen(); // 0
gen(); // 2
gen(); // 4
gen(); // null

Sources: src/index.ts:51-58, src/compile.spec.ts:106-112

Technical Specifications

Input Parsing Constraints

Formula	Parsed [a, b]	Description
even	[2, 0]	Every second element starting from the second.
odd	[2, 1]	Every second element starting from the first.
n	[1, 0]	Every element.
-n+3	[-1, 3]	First three elements (indices 0, 1, 2).

Sources: src/fixtures/rules.ts:2-30, src/parse.ts:20-26

Internal Indexing

The library performs internal adjustment to convert CSS 1-based indexing to JavaScript 0-based indexing by subtracting 1 from the b value during compilation and generation.
Sources: src/compile.ts:117

Conclusion

The sequence() API provides a high-performance mechanism for iterating through element indices matching CSS selectors. By leveraging the optimized generate logic and robust parse implementation, it ensures spec-compliant behavior for both infinite and finite sets of indices while maintaining a simple, stateful function interface for the consumer.