Formula String Formats

Relevant source files

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

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

Formula string formats in nth-check define the syntax used to represent CSS nth-child and nth-last-of-type selectors. These strings are parsed into a tuple representing a mathematical sequence an + b, where a is the step size and b is the offset. The library supports standard CSS3 selector specifications, including keywords and functional notations.

Sources: README.md:5-10, src/parse.ts:1-2

Supported Syntax Formats

The parser recognizes several distinct string formats, ranging from simple keywords to complex mathematical expressions.

Keyword Formats

The library supports two specific keyword constants that map directly to predefined step and offset values:

• even: Equivalent to 2n or [2, 0].
• odd: Equivalent to 2n+1 or [2, 1].

Sources: src/parse.ts:21-27, src/fixtures/rules.ts:28-31

Functional Notations

The primary format follows the pattern [+-]? [INTEGER]? {n} [ S* [+-] S* INTEGER ]?. This allows for various representations of the an + b formula:

Format Type	Example String	Parsed Tuple [a, b]	Description
Integers Only	"5"	[0, 5]	Matches only the element at the specified index.
Step Only	"2n"	[2, 0]	Matches elements at multiples of the step.
Full Formula	"2n+3"	[2, 3]	Matches elements starting at index 3, every 2 elements.
Negative Step	"-n+2"	[-1, 2]	Matches elements in reverse up to a certain point.
Negative Offset	"3n-1"	[3, -1]	Matches with a negative starting offset.

Sources: src/parse.ts:31-64, src/fixtures/rules.ts:2-35

Parsing Logic

The parsing process involves cleaning the input string, identifying keywords, and then using a state-based approach to extract the a and b components.

The diagram shows the logical flow within src/parse.ts to convert a string into a numerical tuple.
Sources: src/parse.ts:17-66

Whitespace and Normalization

The parser is resilient to whitespace variations. It ignores standard whitespace characters including space (32), tab (9), carriage return (13), line feed (10), and form feed (12). Formulas are also normalized to lowercase before processing.
Sources: src/parse.ts:4-6, src/parse.ts:18, src/parse.ts:98-105

Sequence Generation and Validation

Once a formula string is parsed into [a, b], it is used to either validate indices or generate sequences.

Index Validation (compile)

The compile function transforms the parsed tuple into an optimized boolean check.

• a = 0: Checks if index === b - 1.
• a > 0: Checks if index >= b - 1 and (index - (b - 1)) % a === 0.
• a < 0: Checks if index <= b - 1 and (index - (b - 1)) % abs(a) === 0.

Sources: src/compile.ts:25-58

Sequence Generation (generate)

The generate function creates a stateful function that returns the next index in the sequence on each call.

The sequence diagram illustrates how nthCheck.sequence (or generate) produces a monotonously increasing sequence of indices based on the parsed formula.
Sources: src/compile.ts:98-129, src/index.ts:43-65

Technical Constraints

• One-based vs Zero-based: CSS nth-child formulas start counting at 1. The internal logic and returned functions from nth-check operate on 0 based indices.
• Parsing Errors: Any formula that does not conform to the an + b structure or the supported keywords will throw an Error with the message n-th rule couldn't be parsed.

Sources: README.md:32, src/parse.ts:70-72, src/compile.ts:27

Formula string formats provide a flexible way to define element selection patterns, ranging from simple every-other-element checks to complex, bounded reverse sequences, all strictly adhering to CSS specifications while optimizing for runtime performance.