generate() API

The generate() API is a core utility within the nth-check module designed to produce a monotonously increasing sequence of indices based on a CSS nth-child formula. Unlike the compile() function, which validates if a specific index matches a rule, generate() provides a stateful iterator-like function that returns the next valid index in the sequence upon each invocation.

This API is primarily used to programmatically determine which elements in a set match a specific nth-rule, such as 2n+3 or -n+5. It handles various mathematical scenarios including positive steps, negative steps with finite ends, and zero-step offsets to ensure compliance with the W3C Selector Specification.
Sources: README.md:9-13, src/compile.ts:74-77

Core Functionality and Logic

The generate() function accepts a tuple [a, b] representing the step size and offset, respectively. The function normalizes the input by converting the 1-based CSS index to a 0-based index used in JavaScript environments.

Implementation Branches

The internal logic branches based on the value of the step size a:

• Negative Step (a < 0): Produces a finite sequence. It calculates a minValue (the start of the sequence) and increments until the value exceeds the offset b.
• Zero Step (a === 0): If the offset b is valid, it returns the 0-indexed offset exactly once. If b is negative, it returns no values.
• Positive Step (a > 0): Produces an infinite sequence starting from the first non-negative matching index.

The following flowchart illustrates the decision logic within generate():

API Reference

Function Signature

Sources: src/index.ts:47-51, src/compile.ts:77-79

Handling of n and b

The module maps CSS nth-expressions to internal a and b values.

• Step Size (a): The coefficient of n.
• Offset (b): The constant value.
• Conversion: Internally, b is transformed via b = parsed[1] - 1 to align with 0-based indexing.

Sources: src/compile.ts:79-81, src/parse.ts:22-26

Integration with Sequence API

The sequence() function serves as a wrapper that combines parse() and generate(). It is the recommended entry point for developers working with raw CSS selector strings.

Implementation Details

Infinite vs. Finite Sequences

The generator's behavior is strictly determined by the sign of a:

1. Finite Sequences: Occur when a is negative (e.g., -2n+5). The function identifies the maximum possible value and counts up until it hits the limit defined by the original offset.
   • Example: [-2, 5] results in sequence 0, 2, 4, null.
2. Infinite Sequences: Occur when a is positive. The function continues to return values indefinitely.
   • Example: [2, 3] results in sequence 2, 4, 6, 8....

Code Logic Snippet

The following logic ensures that even if the calculated 0-indexed offset b is negative, a positive step a will eventually bring the sequence into a valid non-negative range:

// src/compile.ts:119-121
if (b < 0) {
    b += a * Math.ceil(-b / a);
}

Sources: src/compile.ts:107-124, src/compile.spec.ts:88-106

Summary

The generate() API provides a memory-efficient way to iterate through matching indices of an nth-child formula. By abstracting the complex sign-based logic and 0-indexing adjustments, it allows developers to easily retrieve a sequence of indices that comply with CSS standards. It is closely integrated with the parse module to support standard CSS syntax like even, odd, and complex an+b formulas.
Sources: README.md:68-108, src/index.ts:47-74