tessl/npm-nwsapi

Fast CSS Selectors API Engine that serves as a cross-browser replacement for native CSS selection and matching functionality

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Compilation

Name: tessl/npm-nwsapi
Author: tessl

Advanced selector compilation functionality for creating optimized resolver functions and managing the compilation pipeline. NWSAPI uses metaprogramming to transform CSS selectors into high-performance JavaScript functions.

Capabilities

Compile Function

Compiles a CSS selector into an optimized JavaScript resolver function using the specified source template and compilation mode.

/**
 * Compiles CSS selector into JavaScript resolver function
 * @param selector - CSS selector string to compile
 * @param mode - Compilation mode (true=select, false=match, null=collect)
 * @param callback - Optional callback function for result processing
 * @returns Compiled resolver function
 */
function compile(selector, mode, callback);

Usage Examples:

const nwsapi = require("nwsapi");

// Basic compilation for selection
const selectResolver = nwsapi.compile(
  'div.container > p',
  true  // select mode
);

// Basic compilation for matching
const matchResolver = nwsapi.compile(
  '.active',
  false  // match mode
);

// Compilation with callback
const callbackResolver = nwsapi.compile(
  'button',
  true,  // select mode
  function(element) { console.log('Found button:', element); }
);

// Use compiled resolver
const elements = selectResolver(document, null, [], []);
const matches = matchResolver(element);

Compilation Modes

Match Mode (false)

Compiles selectors for element matching operations (used by match() function).

/**
 * Match compilation mode
 * @value false
 */
const MATCH_MODE = false;

Characteristics:

Returns boolean result
Optimized for single element testing
Uses minimal memory allocation
Fast execution for repeated matching operations

Select Mode (true)

Compiles selectors for element selection operations (used by select() and first() functions).

/**
 * Select compilation mode  
 * @value true
 */
const SELECT_MODE = true;

Characteristics:

Returns array of matching elements
Optimized for traversing DOM trees
Includes result collection logic
Supports early termination for first() queries

Collect Mode (null)

Compiles selectors for element collection operations with advanced filtering.

/**
 * Collect compilation mode
 * @value null
 */
const COLLECT_MODE = null;

Characteristics:

Advanced collection with deduplication
Supports complex DOM traversal patterns
Includes document order sorting
Used for complex selector combinations

Compilation Templates

Source Templates

The compilation system uses configurable templates for different operational modes:

/**
 * Compilation body templates
 */
const S_BODY = 'r[++j]=c[k];';        // Select body template
const M_BODY = '';                     // Match body template  
const N_BODY = 'r[++j]=c.item(k);';   // NodeList body template

/**
 * Compilation test templates
 */
const S_TEST = 'if(f(c[k])){break main;}';     // Select test template
const M_TEST = 'f(c);';                        // Match test template
const N_TEST = 'if(f(c.item(k))){break main;}'; // NodeList test template

Usage in Custom Compilation:

const nwsapi = require("nwsapi");

// Access compilation templates
const templates = {
  selectBody: nwsapi.S_BODY,
  matchBody: nwsapi.M_BODY,
  selectTest: nwsapi.S_TEST,
  matchTest: nwsapi.M_TEST
};

// Custom source template
const customSource = `
  var elements = [];
  var index = 0;
  // Custom logic here
  ${nwsapi.S_BODY}
`;

const customResolver = nwsapi.compile('.my-selector', customSource, 1);

Advanced Compilation Features

Resolver Caching

Compilation results are automatically cached for performance:

const nwsapi = require("nwsapi");

// First compilation - creates and caches resolver
console.time('first-compile');
const resolver1 = nwsapi.compile('.test', source, 1);
console.timeEnd('first-compile');

// Second compilation - returns cached resolver
console.time('second-compile');
const resolver2 = nwsapi.compile('.test', source, 1);
console.timeEnd('second-compile');

// resolver1 === resolver2 (same cached function)

Custom Resolver Integration

const nwsapi = require("nwsapi");

// Create specialized resolver
function createCustomResolver(selector) {
  const source = `
    var results = [];
    var walker = document.createTreeWalker(
      context,
      NodeFilter.SHOW_ELEMENT,
      null,
      false
    );
    
    var node;
    while (node = walker.nextNode()) {
      if (/* custom matching logic */) {
        ${nwsapi.S_BODY.replace('c[k]', 'node')}
      }
    }
  `;
  
  return nwsapi.compile(selector, source, 1);
}

const customResolver = createCustomResolver('.special');

Performance Optimization

const nwsapi = require("nwsapi");

// Pre-compile frequently used selectors
const commonSelectors = ['.button', '.nav-item', '.content'];
const precompiledResolvers = commonSelectors.map(selector => ({
  selector,
  resolver: nwsapi.compile(selector, nwsapi.S_BODY, 1)
}));

// Use pre-compiled resolvers
function fastSelect(selector, context) {
  const cached = precompiledResolvers.find(r => r.selector === selector);
  if (cached) {
    return cached.resolver(context, null, [], []);
  }
  return nwsapi.select(selector, context);
}

Compilation Diagnostics

Error Handling

const nwsapi = require("nwsapi");

try {
  const resolver = nwsapi.compile('invalid::selector', source, 1);
} catch (error) {
  console.error('Compilation failed:', error.message);
}

// Validate selector before compilation
function safeCompile(selector, source, mode) {
  try {
    return nwsapi.compile(selector, source, mode);
  } catch (error) {
    console.warn(`Failed to compile selector "${selector}":`, error.message);
    return null;
  }
}

Compilation Analysis

const nwsapi = require("nwsapi");

// Analyze compilation performance
function analyzeCompilation(selector) {
  const startTime = performance.now();
  const resolver = nwsapi.compile(selector, nwsapi.S_BODY, 1);
  const compileTime = performance.now() - startTime;
  
  // Test resolver performance
  const testStart = performance.now();
  resolver(document, null, [], []);
  const executeTime = performance.now() - testStart;
  
  return {
    selector,
    compileTime,
    executeTime,
    resolver
  };
}

const analysis = analyzeCompilation('div.container > p.highlight');
console.log('Compilation analysis:', analysis);

Compilation Context

Snapshot Object

Internal state object containing document context and method references passed to resolver functions during compilation.

/**
 * Compilation context and state information
 * @type object
 */
const Snapshot: {
  doc: Document;              // Current document context
  from: Element | Document;   // Starting context element
  root: Element;              // Document root element
  
  // Method references available to resolvers
  byTag: Function;            // Tag lookup method
  first: Function;            // First match method  
  match: Function;            // Element matching method
  ancestor: Function;         // Ancestor traversal method
  nthOfType: Function;        // nth-of-type calculation
  nthElement: Function;       // nth-child calculation
  
  // State utilities
  isFocusable: Function;      // Focus state checker
  isContentEditable: Function; // Content editable checker
  hasAttributeNS: Function;   // Namespaced attribute checker
  
  // Dynamic properties (set during compilation)
  HOVER?: Element;            // Currently hovered element
};

Usage Examples:

const nwsapi = require("nwsapi");

// Access current compilation context
console.log('Current document:', nwsapi.Snapshot.doc);
console.log('Root element:', nwsapi.Snapshot.root);

// Check document context during compilation
function checkContext() {
  if (nwsapi.Snapshot.doc !== document) {
    console.log('Working with different document context');
  }
  
  console.log('Compilation from element:', nwsapi.Snapshot.from);
}

// The Snapshot object is primarily used internally by compiled resolvers
// but can be accessed for debugging compilation behavior
function debugResolver(element) {
  console.log('Snapshot during resolution:', {
    doc: nwsapi.Snapshot.doc === element.ownerDocument,
    root: nwsapi.Snapshot.root === element.ownerDocument.documentElement,
    context: nwsapi.Snapshot.from
  });
}