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

DOM Helpers

Name: tessl/npm-nwsapi
Author: tessl

Fast helper methods for common element lookup operations by ID, tag name, and class name, with optional context filtering for improved performance over generic selector queries.

Capabilities

ById Function

Returns the first element with the specified ID, optionally filtered to descendants of a given element.

/**
 * Returns element by ID
 * @param id - Element ID to find
 * @param from - Optional root element to search within
 * @returns Element with matching ID or null
 */
function byId(id, from);

Usage Examples:

const nwsapi = require("nwsapi");

// Find element by ID in entire document
const header = nwsapi.byId('main-header');

// Find element by ID within specific context
const button = nwsapi.byId('submit-btn', formElement);

// Handle case where element doesn't exist
const element = nwsapi.byId('nonexistent');
if (element) {
  console.log('Found element:', element);
} else {
  console.log('Element not found');
}

ByTag Function

Returns an array of elements with the specified tag name, optionally filtered to descendants of a given element.

/**
 * Returns elements by tag name
 * @param tag - Tag name to search for
 * @param from - Optional root element to search within
 * @returns Array of elements with matching tag name
 */
function byTag(tag, from);

Usage Examples:

const nwsapi = require("nwsapi");

// Find all paragraphs in document
const paragraphs = nwsapi.byTag('p');

// Find all links within navigation
const navLinks = nwsapi.byTag('a', navigationElement);

// Find all form inputs
const inputs = nwsapi.byTag('input', formElement);

// Case insensitive by default
const divs = nwsapi.byTag('DIV'); // Same as byTag('div')

// Iterate through results
nwsapi.byTag('img').forEach(function(img) {
  console.log('Image source:', img.src);
});

ByClass Function

Returns an array of elements with the specified class name, optionally filtered to descendants of a given element.

/**
 * Returns elements by class name
 * @param class - Class name to search for (without dot prefix)
 * @param from - Optional root element to search within
 * @returns Array of elements with matching class name
 */
function byClass(class, from);

Usage Examples:

const nwsapi = require("nwsapi");

// Find all elements with 'highlight' class
const highlighted = nwsapi.byClass('highlight');

// Find elements with class within specific container
const cards = nwsapi.byClass('card', containerElement);

// Multiple class matching (finds elements with any of the classes)
const buttons = nwsapi.byClass('btn');
const primaryButtons = nwsapi.byClass('btn-primary');

// Iterate and modify
nwsapi.byClass('hidden').forEach(function(element) {
  element.style.display = 'block';
});

// Check if results exist
const warnings = nwsapi.byClass('warning');
if (warnings.length > 0) {
  console.log('Found', warnings.length, 'warning elements');
}

Performance Characteristics

Optimization Benefits

Direct DOM API usage: Helper methods use optimized native DOM methods when available
Reduced parsing overhead: No CSS selector parsing required
Context filtering: Optional from parameter allows efficient scoped searches
Browser optimization: Leverages browser's native getElementById, getElementsByTagName, and getElementsByClassName

Performance Comparison

// Faster - uses native DOM methods
const fast = nwsapi.byClass('button');

// Slower - requires CSS selector parsing and compilation
const slow = nwsapi.select('.button');

// Much faster for repeated operations due to direct API access
for (let i = 0; i < 1000; i++) {
  nwsapi.byId('element-' + i); // Optimized
}

Best Practices

Use helper methods when you need simple ID, tag, or class lookups
Use select() for complex selectors requiring CSS parsing
Provide from context when searching within specific containers
Helper methods are ideal for performance-critical code paths

Context Filtering

All helper methods support optional context filtering through the from parameter:

const nwsapi = require("nwsapi");

// Search entire document
const allButtons = nwsapi.byTag('button');

// Search only within form
const formButtons = nwsapi.byTag('button', formElement);

// Search within multiple contexts
const contexts = [nav, main, footer];
const allLinks = contexts.reduce((links, context) => {
  return links.concat(nwsapi.byTag('a', context));
}, []);

Error Handling

Helper methods are designed to be robust and handle edge cases gracefully:

const nwsapi = require("nwsapi");

// Returns null if ID not found
const missing = nwsapi.byId('nonexistent'); // null

// Returns empty array if no matches
const noMatches = nwsapi.byTag('nonexistent'); // []
const noClasses = nwsapi.byClass('nonexistent'); // []

// Handles invalid contexts gracefully
const invalid = nwsapi.byTag('div', null); // Searches document
const invalid2 = nwsapi.byClass('test', undefined); // Searches document

Install with Tessl CLI