tessl/npm-postcss-selector-parser

Selector parser with built in methods for working with selector strings.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Parser & Processor

Name: tessl/npm-postcss-selector-parser
Author: tessl

Core parser function and processor class for parsing and transforming CSS selectors with both synchronous and asynchronous processing capabilities.

Capabilities

Parser Function

Main entry point that creates processor instances with optional transform functions and default options.

/**
 * Creates a new processor instance
 * @param transform - Optional transform function to process the AST
 * @param options - Default options for all processor calls
 * @returns Processor instance
 */
function parser(transform?: ProcessorFn, options?: Options): Processor;

type ProcessorFn = (root: Root) => any;
type AsyncProcessor = (root: Root) => Promise<any>;
type SyncProcessor = (root: Root) => any;

Usage Examples:

const parser = require('postcss-selector-parser');

// Basic processor
const processor = parser();

// With transform function
const transform = selectors => {
    selectors.walkUniversals(selector => {
        selector.remove();
    });
};
const processor = parser(transform);

// With options
const processor = parser(null, { lossless: false });

Processor Class

Handles parsing, transformation, and output generation for CSS selectors.

/**
 * Processor for parsing and transforming CSS selectors
 */
interface Processor<TransformType = never, SyncSelectorsType extends Selectors | never = Selectors> {
  /** The parsed AST root node */
  res: Root;
  /** String representation of the result */
  result: string;
  
  /**
   * Parse selectors to AST asynchronously
   * @param selectors - CSS selector string or PostCSS rule
   * @param options - Parsing options
   * @returns Promise resolving to Root AST node
   */
  ast(selectors: Selectors, options?: Options): Promise<Root>;
  
  /**
   * Parse selectors to AST synchronously
   * @param selectors - CSS selector string or PostCSS rule
   * @param options - Parsing options
   * @returns Root AST node
   */
  astSync(selectors: Selectors, options?: Options): Root;
  
  /**
   * Transform selectors asynchronously
   * @param selectors - CSS selector string or PostCSS rule
   * @param options - Processing options
   * @returns Promise resolving to transform result
   */
  transform(selectors: Selectors, options?: Options): Promise<any>;
  
  /**
   * Transform selectors synchronously
   * @param selectors - CSS selector string or PostCSS rule
   * @param options - Processing options
   * @returns Transform result
   */
  transformSync(selectors: Selectors, options?: Options): any;
  
  /**
   * Process selectors to string asynchronously
   * @param selectors - CSS selector string or PostCSS rule
   * @param options - Processing options
   * @returns Promise resolving to processed selector string
   */
  process(selectors: Selectors, options?: Options): Promise<string>;
  
  /**
   * Process selectors to string synchronously
   * @param selectors - CSS selector string or PostCSS rule
   * @param options - Processing options
   * @returns Processed selector string
   */
  processSync(selectors: Selectors, options?: Options): string;
}

Usage Examples:

const parser = require('postcss-selector-parser');
const processor = parser();

// Async processing
const ast = await processor.ast('.class1, .class2');
const result = await processor.process('.class1, .class2');

// Sync processing
const ast = processor.astSync('.class1, .class2');
const result = processor.processSync('.class1, .class2');

// With options
const normalized = processor.processSync('h1 , h2 , h3', { lossless: false });
// Result: "h1,h2,h3"

Processing Options

Configuration options for parsing and processing selectors.

interface Options {
  /**
   * Preserve whitespace when true (default: true)
   */
  lossless?: boolean;
  
  /**
   * When true and a PostCSS Rule is passed, set the result back onto the rule (default: true)
   */
  updateSelector?: boolean;
}

type Selectors = string | PostCSSRuleNode;

interface PostCSSRuleNode {
  selector: string;
  error(message: string, options?: ErrorOptions): Error;
}

interface ErrorOptions {
  plugin?: string;
  word?: string;
  index?: number;
}

Usage Examples:

// Lossless parsing (preserves formatting)
const result1 = processor.processSync('h1 , h2 , h3', { lossless: true });
// Result: "h1 , h2 , h3"

// Non-lossless parsing (normalizes whitespace)
const result2 = processor.processSync('h1 , h2 , h3', { lossless: false });
// Result: "h1,h2,h3"

// Working with PostCSS rule
const rule = { selector: '.class1, .class2' };
processor.processSync(rule, { updateSelector: true });
// rule.selector is updated with the processed result

Parser Class

Internal parser class used for low-level parsing operations.

/**
 * Internal parser class for CSS selector parsing
 */
interface Parser {
  input: ParserOptions;
  lossy: boolean;
  position: number;
  root: Root;
  selectors: string;
  current: Selector;
  
  /**
   * Creates new parser instance
   * @param input - Parser configuration
   */
  constructor(input: ParserOptions): Parser;
  
  /**
   * Raises a parsing error with context
   * @param message - Error message
   * @param options - Error options
   */
  error(message: string, options?: ErrorOptions): void;
}

interface ParserOptions {
  css: string;
  error: (message: string, options: ErrorOptions) => Error;
  options: Options;
}

Install with Tessl CLI

npx tessl i tessl/npm-postcss-selector-parser

docs

tessl/npm-postcss-selector-parser