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

Configuration

Name: tessl/npm-nwsapi
Author: tessl

Configuration system for customizing NWSAPI engine behavior including duplicate ID handling, caching strategies, case sensitivity options, and error logging preferences.

Capabilities

Configure Function

Configures engine behavior with various options. When called without parameters, returns the current configuration.

/**
 * Configures engine behavior
 * @param option - Configuration object with boolean flags, or string to get single option value
 * @param clear - Optional boolean to clear resolver cache
 * @returns Current configuration object or boolean value for string queries
 */
function configure(option, clear);

Usage Examples:

const nwsapi = require("nwsapi");

// Get current configuration
const currentConfig = nwsapi.configure();
console.log('Current config:', currentConfig);

// Set specific options
nwsapi.configure({
  LOGERRORS: false,    // Disable error logging
  IDS_DUPES: false     // Disallow duplicate IDs
});

// Enable all caching
nwsapi.configure({
  LIVECACHE: true
});

// Case sensitive tag matching
nwsapi.configure({
  MIXEDCASE: false
});

// Reset to defaults
nwsapi.configure({
  IDS_DUPES: true,
  LIVECACHE: true,
  MIXEDCASE: true,
  LOGERRORS: true
});

// Query single configuration option
const logErrors = nwsapi.configure('LOGERRORS');
console.log('Error logging enabled:', logErrors);

// Configure with cache clearing
nwsapi.configure({
  LIVECACHE: false  // Disable caching
}, true);  // Clear existing resolver cache

Emit Function

Emits error or warning messages to the console or throws exceptions based on configuration.

/**
 * Emits error/warning messages
 * @param message - Message to emit
 * @param proto - Optional error constructor prototype
 * @returns void
 */
function emit(message, proto);

Usage Examples:

const nwsapi = require("nwsapi");

// Basic error emission (logs to console if LOGERRORS is true)
nwsapi.emit('Invalid selector syntax');

// Emit with custom error type
nwsapi.emit('Custom error message', TypeError);

// Behavior depends on configuration
nwsapi.configure({ LOGERRORS: true });
nwsapi.emit('This will be logged');

nwsapi.configure({ LOGERRORS: false });
nwsapi.emit('This will be silent');

Config Object

Direct access to the current configuration state object.

/**
 * Current configuration state object
 * @type ConfigOptions
 */
const Config: {
  IDS_DUPES: boolean;   // Allow duplicate IDs
  LIVECACHE: boolean;   // Cache results and resolvers  
  MIXEDCASE: boolean;   // Case insensitive tag matching
  LOGERRORS: boolean;   // Log errors to console
};

Usage Examples:

const nwsapi = require("nwsapi");

// Read current configuration directly
console.log('Duplicate IDs allowed:', nwsapi.Config.IDS_DUPES);
console.log('Caching enabled:', nwsapi.Config.LIVECACHE);

// Check all settings
Object.entries(nwsapi.Config).forEach(([key, value]) => {
  console.log(`${key}: ${value}`);
});

// Note: Direct modification not recommended - use configure() instead
// nwsapi.Config.LOGERRORS = false; // Don't do this
nwsapi.configure({ LOGERRORS: false }); // Do this instead

Configuration Options

IDS_DUPES

Controls whether multiple elements with the same ID are allowed.

/**
 * Allow duplicate IDs option
 * @default true
 * @type boolean
 */
IDS_DUPES: boolean;

Behavior:

true (default): Allows multiple elements with same ID, returns first match
false: Strict mode, warns about duplicate IDs

Examples:

const nwsapi = require("nwsapi");

// Allow duplicates (default)
nwsapi.configure({ IDS_DUPES: true });
const element = nwsapi.byId('duplicate-id'); // Returns first match

// Strict mode - no duplicates
nwsapi.configure({ IDS_DUPES: false });
const element2 = nwsapi.byId('duplicate-id'); // May warn about duplicates

LIVECACHE

Controls caching behavior for both query results and compiled resolvers.

/**
 * Enable live caching option
 * @default true
 * @type boolean
 */
LIVECACHE: boolean;

Behavior:

true (default): Caches both compiled resolvers and query results
false: Only caches compiled resolvers, not results

Examples:

const nwsapi = require("nwsapi");

// Full caching (default) - best performance
nwsapi.configure({ LIVECACHE: true });

// Resolver-only caching - saves memory but slower repeated queries
nwsapi.configure({ LIVECACHE: false });

// Performance comparison
console.time('first-query');
nwsapi.select('.test'); // Compiles selector
console.timeEnd('first-query');

console.time('second-query');
nwsapi.select('.test'); // Uses cached resolver (and result if LIVECACHE: true)
console.timeEnd('second-query');

MIXEDCASE

Controls case sensitivity for tag name matching.

/**
 * Case insensitive tag matching option
 * @default true
 * @type boolean
 */
MIXEDCASE: boolean;

Behavior:

true (default): Tag names are matched case-insensitively
false: Tag names are matched case-sensitively

Examples:

const nwsapi = require("nwsapi");

// Case insensitive (default)
nwsapi.configure({ MIXEDCASE: true });
const divs1 = nwsapi.byTag('div');  // Matches <div>
const divs2 = nwsapi.byTag('DIV');  // Also matches <div>

// Case sensitive
nwsapi.configure({ MIXEDCASE: false });
const divs3 = nwsapi.byTag('div');  // Matches <div>
const divs4 = nwsapi.byTag('DIV');  // Does NOT match <div>

LOGERRORS

Controls whether errors and warnings are logged to the console.

/**
 * Enable error logging option
 * @default true
 * @type boolean
 */
LOGERRORS: boolean;

Behavior:

true (default): Logs errors and warnings to console
false: Suppresses error and warning output

Examples:

const nwsapi = require("nwsapi");

// Enable logging (default)
nwsapi.configure({ LOGERRORS: true });
nwsapi.select('invalid::selector'); // Will log error to console

// Disable logging
nwsapi.configure({ LOGERRORS: false });
nwsapi.select('invalid::selector'); // Silent failure

// Selective logging for production
if (process.env.NODE_ENV !== 'production') {
  nwsapi.configure({ LOGERRORS: true });
} else {
  nwsapi.configure({ LOGERRORS: false });
}

Configuration Patterns

Development vs Production

const nwsapi = require("nwsapi");

// Development configuration
nwsapi.configure({
  LOGERRORS: true,     // Enable debugging
  IDS_DUPES: false,    // Strict validation
  LIVECACHE: true,     // Full performance
  MIXEDCASE: true      // Flexible matching
});

// Production configuration
nwsapi.configure({
  LOGERRORS: false,    // Silent operation
  IDS_DUPES: true,     // Tolerant of duplicates
  LIVECACHE: true,     // Maximum performance
  MIXEDCASE: true      // Cross-browser compatibility
});

Memory-Conscious Configuration

const nwsapi = require("nwsapi");

// Reduce memory usage
nwsapi.configure({
  LIVECACHE: false,    // Don't cache results
  LOGERRORS: false,    // Minimal overhead
  IDS_DUPES: true,     // Standard behavior
  MIXEDCASE: true      // Standard behavior
});

Strict Validation Configuration

const nwsapi = require("nwsapi");

// Maximum validation
nwsapi.configure({
  IDS_DUPES: false,    // No duplicate IDs
  LOGERRORS: true,     // Show all warnings
  MIXEDCASE: false,    // Exact case matching
  LIVECACHE: true      // Performance optimization
});

Configuration State Management

Saving and Restoring Configuration

const nwsapi = require("nwsapi");

// Save current configuration
const savedConfig = nwsapi.configure();

// Make temporary changes
nwsapi.configure({ LOGERRORS: false });

// Perform operations...
nwsapi.select('.test');

// Restore previous configuration
nwsapi.configure(savedConfig);

Configuration Validation

const nwsapi = require("nwsapi");

// Validate configuration before applying
function safeConfig(options) {
  const validKeys = ['IDS_DUPES', 'LIVECACHE', 'MIXEDCASE', 'LOGERRORS'];
  const filtered = {};
  
  for (const key in options) {
    if (validKeys.includes(key) && typeof options[key] === 'boolean') {
      filtered[key] = options[key];
    }
  }
  
  return nwsapi.configure(filtered);
}

// Use safe configuration
safeConfig({
  LOGERRORS: false,
  INVALID_OPTION: true  // Will be ignored
});

Install with Tessl CLI