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

Installation

Name: tessl/npm-nwsapi
Author: tessl

System for installing NWSAPI as a replacement for native browser querySelector methods and restoring original functionality. The installation system allows NWSAPI to override native DOM methods transparently.

Capabilities

Install Function

Installs NWSAPI as the default CSS selector engine by replacing native querySelector/querySelectorAll methods.

/**
 * Installs NWSAPI as native QSA replacement
 * @param all - Optional boolean to enable automatic iframe installation
 * @returns NWSAPI Dom object
 */
function install(all);

Usage Examples:

const nwsapi = require("nwsapi");

// Basic installation
nwsapi.install();

// Now native methods use NWSAPI
const elements = document.querySelectorAll('.test'); // Uses NWSAPI
const element = document.querySelector('#header');   // Uses NWSAPI

// Installation with iframe support
nwsapi.install(true); // Automatically installs in iframes as well

// Verify installation
console.log('Original querySelector available:', !!document._querySelector);

Uninstall Function

Restores native querySelector/querySelectorAll methods and removes NWSAPI overrides.

/**
 * Restores native QSA methods
 * @returns NWSAPI Dom object
 */
function uninstall();

Usage Examples:

const nwsapi = require("nwsapi");

// Install NWSAPI first
nwsapi.install();

// Later, restore native methods
nwsapi.uninstall();

// Native methods restored
const elements = document.querySelectorAll('.test'); // Uses native browser engine

// Verify uninstall
console.log('NWSAPI uninstalled, native methods restored');

Installation Modes

Automatic Installation

NWSAPI can be automatically installed when the script loads:

<!-- Automatic installation on load -->
<script type="text/javascript" src="nwsapi.js" onload="NW.Dom.install()"></script>

Conditional Installation

const nwsapi = require("nwsapi");

// Install only in specific environments
if (typeof window !== 'undefined' && window.document) {
  // Browser environment
  nwsapi.install();
} else {
  // Node.js or headless environment - no installation needed
  console.log('Running in headless mode');
}

// Install based on browser capabilities
if (!document.querySelector || !document.querySelectorAll) {
  // Older browser without native QSA
  nwsapi.install();
} else {
  // Modern browser - compare performance first
  benchmarkAndInstall();
}

Selective Installation

const nwsapi = require("nwsapi");

// Custom installation that preserves some native methods
function selectiveInstall() {
  // Store native methods
  const nativeQS = document.querySelector;
  const nativeQSA = document.querySelectorAll;
  
  // Install NWSAPI
  nwsapi.install();
  
  // Restore native for simple selectors (performance optimization)
  const originalQSA = document.querySelectorAll;
  document.querySelectorAll = function(selector) {
    if (/^[#.]?[\w-]+$/.test(selector)) {
      // Simple selector - use native for best performance
      return nativeQSA.call(this, selector);
    } else {
      // Complex selector - use NWSAPI for compatibility
      return originalQSA.call(this, selector);
    }
  };
}

Installation Effects

Method Overrides

When installed, NWSAPI overrides the following native methods:

// Before installation
document.querySelector           // Native browser implementation
document.querySelectorAll        // Native browser implementation
Element.prototype.querySelector  // Native browser implementation
Element.prototype.querySelectorAll // Native browser implementation

// After installation
document.querySelector           // NWSAPI implementation
document.querySelectorAll        // NWSAPI implementation  
Element.prototype.querySelector  // NWSAPI implementation
Element.prototype.querySelectorAll // NWSAPI implementation

// Original methods preserved as
document._querySelector          // Original native method
document._querySelectorAll       // Original native method
Element.prototype._querySelector // Original native method
Element.prototype._querySelectorAll // Original native method

Performance Impact

const nwsapi = require("nwsapi");

// Benchmark before installation
console.time('native-query');
document.querySelectorAll('.test');
console.timeEnd('native-query');

// Install NWSAPI
nwsapi.install();

// Benchmark after installation
console.time('nwsapi-query');
document.querySelectorAll('.test');
console.timeEnd('nwsapi-query');

// NWSAPI often faster for complex selectors
console.time('complex-native');
document._querySelectorAll('div:has(> p:nth-child(2n+1))');
console.timeEnd('complex-native');

console.time('complex-nwsapi');
document.querySelectorAll('div:has(> p:nth-child(2n+1))');
console.timeEnd('complex-nwsapi');

Installation Patterns

Framework Integration

const nwsapi = require("nwsapi");

// Vue.js integration
const VueNWSAPI = {
  install(Vue) {
    nwsapi.install();
    Vue.prototype.$nwsapi = nwsapi;
  }
};

// React integration
function withNWSAPI(Component) {
  // Install on first render
  nwsapi.install();
  return Component;
}

// jQuery integration
if (typeof jQuery !== 'undefined') {
  nwsapi.install();
  jQuery.fn.nwsapi = function(selector) {
    return nwsapi.select(selector, this[0]);
  };
}

Testing Environment Setup

const nwsapi = require("nwsapi");

// Jest setup
beforeAll(() => {
  nwsapi.install();
});

afterAll(() => {
  nwsapi.uninstall();
});

// Mocha setup
before(function() {
  nwsapi.install();
});

after(function() {
  nwsapi.uninstall();
});

// Custom test helper
function withNWSAPI(testFn) {
  return function() {
    nwsapi.install();
    try {
      return testFn.apply(this, arguments);
    } finally {
      nwsapi.uninstall();
    }
  };
}

// Usage
it('should work with NWSAPI', withNWSAPI(function() {
  const elements = document.querySelectorAll(':has(> img)');
  expect(elements.length).toBe(3);
}));

Production Deployment

const nwsapi = require("nwsapi");

// Production installation with error handling
function safeInstall() {
  try {
    nwsapi.configure({
      LOGERRORS: false  // Disable logging in production
    });
    
    nwsapi.install();
    
    // Track installation success
    if (window.gtag) {
      gtag('event', 'nwsapi_installed', {
        'custom_parameters': {
          'version': nwsapi.Version
        }
      });
    }
    
    return true;
  } catch (error) {
    console.error('NWSAPI installation failed:', error);
    return false;
  }
}

// Conditional production installation
if (window.location.hostname !== 'localhost') {
  safeInstall();
}

Installation Verification

Testing Installation Status

const nwsapi = require("nwsapi");

// Check if installed
function isNWSAPIInstalled() {
  return document.querySelector === nwsapi.select ||
         typeof document._querySelector !== 'undefined';
}

// Verify installation works
function verifyInstallation() {
  nwsapi.install();
  
  try {
    // Test with NWSAPI-specific selector
    const elements = document.querySelectorAll(':has(> *)');
    console.log('Installation verified - advanced selectors work');
    return true;
  } catch (error) {
    console.error('Installation verification failed:', error);
    return false;
  }
}

// Health check
function healthCheck() {
  const tests = [
    () => document.querySelectorAll('div').length >= 0,
    () => document.querySelector('body') !== null,
    () => typeof document._querySelector === 'function'
  ];
  
  return tests.every(test => {
    try {
      return test();
    } catch (error) {
      return false;
    }
  });
}

Compatibility Checks

const nwsapi = require("nwsapi");

// Browser compatibility check
function checkCompatibility() {
  const features = {
    querySelector: !!document.querySelector,
    querySelectorAll: !!document.querySelectorAll,
    getElementsByClassName: !!document.getElementsByClassName,
    documentElement: !!document.documentElement
  };
  
  const compatible = Object.values(features).every(Boolean);
  
  if (compatible) {
    nwsapi.install();
    return true;
  } else {
    console.warn('Browser not compatible with NWSAPI installation');
    return false;
  }
}

// Feature detection for advanced selectors
function supportsAdvancedSelectors() {
  try {
    document.querySelectorAll(':has(*)');
    return false; // Native support found
  } catch (error) {
    return true;  // Native support missing - NWSAPI beneficial
  }
}

if (supportsAdvancedSelectors()) {
  nwsapi.install();
}

Install with Tessl CLI