parse() API

Relevant source files

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

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

The parse() API is a core component of the nth-check library, responsible for converting CSS nth-rule expressions (e.g., 2n+3, even, odd) into a structured numerical format. It specifically targets formulas used in CSS3 pseudo-classes like :nth-child() and :nth-last-of-type(). The output of this API serves as the primary input for the compile() and generate() functions.

Sources: src/parse.ts:1-12, README.md:1-12

Function Definition

The parse function takes a string formula and returns a tuple representing the step size (a) and the offset (b).

Signature

export function parse(formula: string): [a: number, b: number]

Sources: src/parse.ts:13-13, src/index.ts:74-74

Parameters and Return Value

Element	Type	Description
formula	string	The CSS nth-formula to be parsed (e.g., "even", "2n+1").
Returns	[number, number]	An array containing the integer step size a and the integer offset b.

Sources: src/parse.ts:14-19, README.md:37-43

Logic and Architecture

The parser follows the W3C Selectors Level 3 specification. It employs a sequential scanning approach to handle signs, numbers, and the 'n' identifier.

Parsing Flow

1. Normalization: The input string is trimmed and converted to lowercase.
2. Special Case Handling: Direct matching for the keywords even (returns [2, 0]) and odd (returns [2, 1]).
3. Component Extraction:
   • Read Sign: Detects leading + or -.
   • Read Number: Parses digits into an integer.
   • N-Identifier: Checks for the presence of the character n to distinguish between a constant and a linear rule.
   • Offset Parsing: If n is found, the parser skips whitespace and attempts to read a second sign and number (the b component).

The following diagram illustrates the internal decision logic within the parse function:

Internal Utilities

The parse function utilizes several localized helper functions to process the string pointer (index):

• readSign(): Returns -1 for -, and 1 for + or when no sign is present.
• readNumber(): Iterates through character codes between 0 (48) and 9 (57) to build an integer. Returns null if no digits are found.
• skipWhitespace(): Advances the pointer past characters defined in the CSS spec as whitespace (space, tab, carriage return, line feed, form feed).

Sources: src/parse.ts:4-6, src/parse.ts:57-93

Error Handling

The parser throws an Error if the formula cannot be fully consumed or if a required numerical component is missing after a sign.

if (number === null || index < formula.length) {
    throw new Error(`n-th rule couldn't be parsed ('${formula}')`);
}

Sources: src/parse.ts:51-53, src/parse.spec.ts:6-10

Integration with Library API

The parse function serves as the foundation for higher-level functions in the index.ts entry point:

• nthCheck(formula): Returns compile(parse(formula)).
• sequence(formula): Returns generate(parse(formula)).

Usage Examples

Input Formula	Resulting Tuple [a, b]	Interpretation
"even"	[2, 0]	Every 2nd element.
"2n+3"	[2, 3]	Starting at 3, every 2nd element.
"5"	[0, 5]	Only the 5th element.
"-n+2"	[-1, 2]	Elements at index <= 2 (1 and 2).
"3n-1"	[3, -1]	Every 3rd element with a -1 offset.

Sources: src/fixtures/rules.ts:1-33, README.md:41-43

Summary

The parse() API provides robust, specification-compliant parsing of CSS nth-expressions. By converting string-based formulas into a simple [a, b] numeric pair, it enables the library to perform high-performance index checks and sequence generation without repeated string processing.

Sources: src/parse.ts:1-55, package.json:3-3