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

Node Constructors

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

Factory functions for creating all types of CSS selector AST nodes. These constructors are essential for programmatically building selector structures.

Capabilities

Attribute Constructor

Creates attribute selector nodes for CSS attribute selectors like [href], [class="btn"], [data-*].

/**
 * Creates a new attribute selector node
 * @param props - Attribute node properties
 * @returns Attribute node
 */
function attribute(props?: AttributeOptions): Attribute;

interface AttributeOptions extends NamespaceOptions {
  /** The attribute name */
  attribute: string;
  /** Comparison operator (=, ~=, |=, ^=, $=, *=) */
  operator?: AttributeOperator;
  /** Case insensitive flag */
  insensitive?: boolean;
  /** Quote mark for the value */
  quoteMark?: QuoteMark;
  /** Whether the value is quoted (deprecated, use quoteMark) */
  quoted?: boolean;
  /** Spacing configuration */
  spaces?: AttributeSpaces;
  /** Raw values for precise output control */
  raws?: AttributeRaws;
}

type AttributeOperator = "=" | "~=" | "|=" | "^=" | "$=" | "*=";
type QuoteMark = '"' | "'" | null;

interface AttributeSpaces {
  before?: string;
  after?: string;
  attribute?: Partial<SpaceAround>;
  operator?: Partial<SpaceAround>;
  value?: Partial<SpaceAround>;
  insensitive?: Partial<SpaceAround>;
}

Usage Examples:

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

// Simple attribute selector
const attr1 = parser.attribute({ attribute: 'href' });
// Result: [href]

// Attribute with value
const attr2 = parser.attribute({
  attribute: 'class',
  operator: '=',
  value: 'button',
  quoteMark: '"'
});
// Result: [class="button"]

// Case insensitive attribute
const attr3 = parser.attribute({
  attribute: 'data-value',
  operator: '*=',
  value: 'test',
  insensitive: true
});
// Result: [data-value*="test" i]

Attribute Interface

The Attribute class provides additional methods for advanced attribute manipulation.

interface Attribute extends Base {
  attribute: string;
  operator?: AttributeOperator;
  value?: string;
  insensitive?: boolean;
  quoteMark?: QuoteMark;
  namespace?: string | true;
  
  /** Get the attribute value with proper quoting */
  getQuotedValue(options?: { quoteMark?: QuoteMark }): string;
  
  /** Set the attribute value with quote options */
  setValue(value: string, options?: { quoteMark?: QuoteMark; smart?: boolean }): this;
  
  /** Get intelligently selected quote mark */
  smartQuoteMark(options?: { preferredQuote?: QuoteMark }): QuoteMark;
  
  /** Get preferred quote mark based on content */
  preferredQuoteMark(options?: { preferredQuote?: QuoteMark }): QuoteMark;
  
  /** Read-only property returning 'i' or empty string */
  readonly insensitiveFlag: string;
  
  /** Read-only property for namespaced attribute name */
  readonly qualifiedAttribute: string;
}

// Static constants
Attribute.NO_QUOTE = null;
Attribute.SINGLE_QUOTE = "'";
Attribute.DOUBLE_QUOTE = '"';

Class Name Constructor

Creates class selector nodes for CSS class selectors like .button, .nav-item.

/**
 * Creates a new class selector node
 * @param props - Class node properties
 * @returns ClassName node
 */
function className(props?: NamespaceOptions): ClassName;

Usage Examples:

// Simple class selector
const cls1 = parser.className({ value: 'button' });
// Result: .button

// Namespaced class
const cls2 = parser.className({
  value: 'component',
  namespace: 'ui'
});
// Result: ui|.component

Combinator Constructor

Creates combinator nodes for CSS selector combinators like >, +, ~, (space).

/**
 * Creates a new combinator node
 * @param props - Combinator node properties
 * @returns Combinator node
 */
function combinator(props?: NodeOptions): Combinator;

interface CombinatorRaws {
  value?: string;
  spaces?: {
    before?: string;
    after?: string;
  };
}

Usage Examples:

// Child combinator
const comb1 = parser.combinator({ value: '>' });
// Result: >

// Adjacent sibling combinator
const comb2 = parser.combinator({ value: '+' });
// Result: +

// General sibling combinator
const comb3 = parser.combinator({ value: '~' });
// Result: ~

// Descendant combinator (space)
const comb4 = parser.combinator({ value: ' ' });
// Result: (space)

Comment Constructor

Creates comment nodes for CSS comments within selectors.

/**
 * Creates a new comment node
 * @param props - Comment node properties
 * @returns Comment node
 */
function comment(props?: NodeOptions): Comment;

Usage Examples:

// CSS comment
const comm = parser.comment({ value: '/* comment */' });
// Result: /* comment */

ID Constructor

Creates ID selector nodes for CSS ID selectors like #header, #nav-menu.

/**
 * Creates a new ID selector node
 * @param props - ID node properties
 * @returns Identifier node
 */
function id(props?: NamespaceOptions): Identifier;

Usage Examples:

// Simple ID selector
const id1 = parser.id({ value: 'header' });
// Result: #header

// Namespaced ID
const id2 = parser.id({
  value: 'nav',
  namespace: 'main'
});
// Result: main|#nav

Nesting Constructor

Creates nesting selector nodes for CSS nesting selectors like &.

/**
 * Creates a new nesting selector node
 * @param props - Nesting node properties
 * @returns Nesting node
 */
function nesting(props?: NodeOptions): Nesting;

Usage Examples:

// Nesting selector
const nest = parser.nesting({ value: '&' });
// Result: &

Pseudo Constructor

Creates pseudo-class and pseudo-element nodes like :hover, ::before, :nth-child().

/**
 * Creates a new pseudo selector node
 * @param props - Pseudo node properties
 * @returns Pseudo node
 */
function pseudo(props?: ContainerOptions): Pseudo;

Usage Examples:

// Simple pseudo-class
const pseudo1 = parser.pseudo({ value: ':hover' });
// Result: :hover

// Pseudo-element
const pseudo2 = parser.pseudo({ value: '::before' });
// Result: ::before

// Functional pseudo with content
const pseudo3 = parser.pseudo({ 
  value: ':nth-child',
  nodes: [parser.string({ value: '2n+1' })]
});
// Result: :nth-child(2n+1)

Root Constructor

Creates root container nodes that hold all selectors in a selector list.

/**
 * Creates a new root container node
 * @param props - Root node properties
 * @returns Root node
 */
function root(props?: ContainerOptions): Root;

Usage Examples:

// Empty root
const root1 = parser.root();

// Root with selectors
const root2 = parser.root({
  nodes: [
    parser.selector({ nodes: [parser.className({ value: 'btn' })] }),
    parser.selector({ nodes: [parser.id({ value: 'header' })] })
  ]
});
// Result: .btn, #header

Root Interface

The Root class provides additional methods and properties for root container nodes.

interface Root extends Container {
  /** Indicates if the input selector had a trailing comma */
  trailingComma: boolean;
  
  /** 
   * Create an error with better context information
   * @param message - Error message
   * @param options - Error options including word and index
   * @returns Error with source location context
   */
  error(message: string, options?: ErrorOptions): Error;
  
  /**
   * Find node at specific line and column
   * @param line - Line number (1-based)
   * @param column - Column number (1-based)
   * @returns Node at specified location
   */
  nodeAt(line: number, column: number): Node | undefined;
}

Selector Constructor

Creates selector nodes that contain the components of individual CSS selectors.

/**
 * Creates a new selector node
 * @param props - Selector node properties
 * @returns Selector node
 */
function selector(props?: ContainerOptions): Selector;

Usage Examples:

// Simple selector
const sel1 = parser.selector({
  nodes: [
    parser.tag({ value: 'div' }),
    parser.className({ value: 'container' })
  ]
});
// Result: div.container

// Complex selector
const sel2 = parser.selector({
  nodes: [
    parser.id({ value: 'main' }),
    parser.combinator({ value: '>' }),
    parser.className({ value: 'content' })
  ]
});
// Result: #main > .content

String Constructor

Creates string literal nodes for values within functional pseudo-selectors or other contexts.

/**
 * Creates a new string literal node
 * @param props - String node properties
 * @returns String node
 */
function string(props?: NodeOptions): String;

Usage Examples:

// String literal
const str = parser.string({ value: '2n+1' });
// Used in contexts like :nth-child(2n+1)

Tag Constructor

Creates tag/element selector nodes for HTML elements like div, span, h1.

/**
 * Creates a new tag selector node
 * @param props - Tag node properties
 * @returns Tag node
 */
function tag(props?: NamespaceOptions): Tag;

Usage Examples:

// Simple tag selector
const tag1 = parser.tag({ value: 'div' });
// Result: div

// Namespaced tag
const tag2 = parser.tag({
  value: 'svg',
  namespace: 'http://www.w3.org/2000/svg'
});
// Result: svg (with namespace context)

Namespace Interface

Node types that support namespaces (Tag and Attribute) provide additional namespace-related methods.

interface Namespace extends Base {
  namespace?: string | true;
  
  /**
   * Get qualified name with namespace prefix
   * @param value - Name to qualify
   * @returns Qualified name with namespace
   */
  qualifiedName(value?: string): string;
  
  /** Read-only namespace string property */
  readonly namespaceString: string | undefined;
  
  /** Alias for namespace property */
  ns: string | true | undefined;
}

Universal Constructor

Creates universal selector nodes for the CSS universal selector *.

/**
 * Creates a new universal selector node
 * @param props - Universal node properties
 * @returns Universal node
 */
function universal(props?: NamespaceOptions): Universal;

Usage Examples:

// Universal selector
const univ1 = parser.universal({ value: '*' });
// Result: *

// Namespaced universal
const univ2 = parser.universal({
  value: '*',
  namespace: 'ui'
});
// Result: ui|*

Common Types

interface NodeOptions {
  value?: string;
  spaces?: Spaces;
  source?: NodeSource;
  sourceIndex?: number;
}

interface ContainerOptions extends NodeOptions {
  nodes?: Node[];
}

interface NamespaceOptions extends NodeOptions {
  namespace?: string | true;
}

interface Spaces {
  before: string;
  after: string;
}

interface SpaceAround {
  before: string;
  after: string;
}

interface NodeSource {
  start?: { line: number; column: number };
  end?: { line: number; column: number };
}

Install with Tessl CLI

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

docs

tessl/npm-postcss-selector-parser