# nwsapi

**Repository Path**: mirrors_addons/nwsapi

## Basic Information

- **Project Name**: nwsapi
- **Description**: Fast CSS Selectors API Engine
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-05-03
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# [NWSAPI](http://dperini.github.io/nwsapi/)

Fast CSS Selectors API Engine

![](https://img.shields.io/npm/v/nwsapi.svg?colorB=orange&style=flat) ![](https://img.shields.io/github/tag/dperini/nwsapi.svg?style=flat) ![](https://img.shields.io/npm/dw/nwshttps://ko-fi.com/dperiniapi.svg?style=flat) ![](https://img.shields.io/github/issues/dperini/nwsapi.svg?style=flat)

NWSAPI is the development progress of [NWMATCHER](https://github.com/dperini/nwmatcher) aiming at [Selectors Level 4](https://www.w3.org/TR/selectors-4/) conformance. It has been completely reworked to be easily extended and maintained. It is a right-to-left selector parser and compiler written in pure Javascript with no external dependencies. It was initially thought as a cross browser library to improve event delegation and web page scraping in various frameworks but it has become a popular replacement of the native CSS selection and matching functionality in newer browsers and headless environments.

It uses [regular expressions](https://en.wikipedia.org/wiki/Regular_expression) to parse CSS selector strings and [metaprogramming](https://en.wikipedia.org/wiki/Metaprogramming) to transforms these selector strings into Javascript function resolvers. This process is executed only once for each selector string allowing memoization of the function resolvers and achieving unmatched performances.

<!-- <onboarding> -->

## Start contributing

From the checkout root, install and prepare the checkout:

<!-- onboarding:install:start -->
```sh
npm i
```
<!-- onboarding:install:end -->

This installs the pinned tools and dependencies, then prepares the package.
[Make your first change](docs/repo/development/first-change.md) · [V2 toolchain notes](docs/repo/development/toolchain.md)

<details>
<summary>If npm is unavailable or too old</summary>

Use Node.js 22.18 or newer from the checkout root:

<!-- onboarding:bootstrap:start -->
```sh
node scripts/setup.mjs
```
<!-- onboarding:bootstrap:end -->

This installs pinned npm and prepares the checkout without changing global tools or PATH. If npm still cannot run, open the menu with `node scripts/develop/run.mts`.

</details>

<details>
<summary>For agents</summary>

Discover tasks:

<!-- onboarding:discovery:start -->
```sh
node scripts/develop/run.mts --list --json
```
<!-- onboarding:discovery:end -->

<!-- onboarding:readiness:start -->
```sh
node scripts/develop/run.mts --task setup:check --json
```
<!-- onboarding:readiness:end -->

</details>

<!-- </onboarding> -->

## Installation

To include NWSAPI in a standard web page:

```html
<script type="text/javascript" src="nwsapi.js"></script>
```

To include NWSAPI in a standard web page and automatically replace the native QSA:

```html
<script type="text/javascript" src="nwsapi.js" onload="NW.Dom.install()"></script>
```

To use NWSAPI with Node.js:

```
$ npm install nwsapi
```

NWSAPI currently supports browsers (as a global, `NW.Dom`) and headless environments (as a CommonJS module).

For contributor setup and staged v2 publishing, see [Releasing v2](https://github.com/dperini/nwsapi/blob/master/docs/releases.md).


## Supported Selectors

Here is a list of all the CSS2/CSS3/CSS4 [Supported selectors](https://github.com/dperini/nwsapi/wiki/CSS-supported-selectors).


## Features and Compliance

You can read more about NWSAPI [features and compliance](https://github.com/dperini/nwsapi/wiki/Features-and-compliance) on the wiki.


## API

### DOM Selection

#### `ancestor( selector, context, callback )`

Returns a reference to the nearest ancestor element matching `selector`, starting at `context`. Returns `null` if no element is found. If `callback` is provided, it is invoked for the matched element.

#### `first( selector, context, callback )`

Returns a reference to the first element matching `selector`, starting at `context`. Returns `null` if no element matches. If `callback` is provided, it is invoked for the matched element.

#### `match( selector, element, callback )`

Returns `true` if `element` matches `selector`, starting at `context`; returns `false` otherwise. If `callback` is provided, it is invoked for the matched element.

#### `select( selector, context, callback )`

Returns an array of all the elements matching `selector`, starting at `context`; returns empty `Array` otherwise. If `callback` is provided, it is invoked for each matching element.


### DOM Helpers

#### `byId( id, from )`

Returns a reference to the first element with ID `id`, optionally filtered to descendants of the element `from`.

#### `byTag( tag, from )`

Returns an array of elements having the specified tag name `tag`, optionally filtered to descendants of the element `from`.

#### `byClass( class, from )`

Returns an array of elements having the specified class name `class`, optionally filtered to descendants of the element `from`.


### Engine Configuration

#### `configure( options )`

The following is the list of currently available configuration options, their default values and descriptions, the existing flags can be set to `true` or `false`:

* `IDS_DUPES`: true  - true to allow using multiple elements having the same id, false to disallow
* `LIVECACHE`: true  - true for caching both results and resolvers, false for caching only resolvers
* `MIXEDCASE`: true  - true to match tag names case insensitive, false to match using case sensitive
* `LOGERRORS`: true  - true to print errors and warnings to the console, false to mute both of them


Two numeric settings control each compiled-plan cache:

* `CACHE_LIMIT`: `1000` entries by default.
* `CACHE_BYTES`: `2 * 1024 * 1024` estimated bytes by default.

Both accept nonnegative safe integers. Zero disables retention. Changing either setting clears existing query caches and applies the new bounds immediately. Invalid values throw a `TypeError` before any options change. Read a numeric setting with `configure("CACHE_LIMIT")` or `configure("CACHE_BYTES")`.

```js
engine.configure({ CACHE_LIMIT: 8192, CACHE_BYTES: 8 * 1024 * 1024 });
```

This example opts into larger bounds for a large stylesheet. Measure runtime and memory for your workload. The byte budget is per cache and estimates keys and compiled plans, not total JavaScript heap usage. Configure the `nwsapi` instance used by your host. Creating a separate instance does not change `jsdom`'s engine.

The eviction policy remains LRU. These settings can mitigate [issue #242](https://github.com/dperini/nwsapi/issues/242) when the stylesheet fits the configured bounds. Scans larger than those bounds can still miss on every query.

### Examples on extending the basic functionalities

#### `configure( { <configuration-flag>: [ true | false ] } )`

Disable logging errors/warnings to console, disallow duplicate ids. Example:

```js
NW.Dom.configure( { LOGERRORS: false, IDS_DUPES: false } );
```
NOTE: NW.Dom.configure() without parameters return the current configuration.

#### `registerCombinator( symbol, resolver )`

Registers a new symbol and its matching resolver in the combinators table. Example:

```js
NW.Dom.registerCombinator( '^', 'e.parentElement' );
```

#### `registerOperator( symbol, resolver )`

Registers a new symbol and its matching resolver in the attribute operators table. Example:

```js
NW.Dom.registerOperator( '!=', { p1: '^', p2: '$', p3: 'false' } );
```

#### `registerSelector( name, rexp, func )`

Registers a new selector, the matching RE and the resolver function, in the selectors table. Example:

```js
NW.Dom.registerSelector('Controls', /^\:(control)(.*)/i,
  (function(global) {
    return function(match, source, mode, callback) {
      var status = true;
      source = 'if(/^(button|input|select|textarea)/i.test(e.nodeName)){' + source + '}';
      return { 'source': source, 'status': status };
    };
  })(this));
```

## Development setup

For optional PHP, Web Platform Tests, and Chromium fixtures, run
`node scripts/setup.mjs --full`. Add `--tools-only` to provision checkout
tools without installing dependencies. V2 uses npm and `package-lock.json`.
Keep v2 and v3 in separate worktrees. See [Make your first change](docs/repo/development/first-change.md)
and the [v2 toolchain notes](docs/repo/development/toolchain.md) for details.

## 💖 Support & Sponsoring

**NWSAPI** powers millions of builds, web scrapers, and testing suites every single day—including key infrastructure like [jsdom](https://github.com/jsdom/jsdom).

Maintaining a zero-dependency, ultra-fast CSS engine that strictly adheres to evolving W3C Selectors specifications takes significant time, research, and testing. If NWSAPI helps your company save time, build features, or run reliable tests, **please consider supporting its ongoing maintenance!**

### Why Sponsor?
* **For Developers:** Keep the project actively maintained, bug-free, and ahead of new browser standard updates.
* **For Businesses:** Ensure the stability and long-term security of a critical dependency in your toolchain.

### 💳 Ways to Contribute

Choose the platform that works best for you or your organization:

* **[GitHub Sponsors](https://github.com/sponsors/dperini):** Monthly tier-based sponsorship directly on GitHub.
* **[Open Collective](https://opencollective.com/nwsapi):** Transparent funding for open-source projects, ideal for corporate backing.
* **[Patreon](https://www.patreon.com/dperini):** Recurring monthly support with backer rewards.
* **[Ko-fi](https://ko-fi.com/dperini):** Fast one-time tips or recurring micro-donations.
* **[Buy Me a Coffee](https://www.buymeacoffee.com/dperini):** Quick, casual one-time donations.
* **[Liberapay](https://liberapay.com/dperini):** Recurrent, zero-fee open-source support.
* **[IssueHunt](https://issuehunt.io/r/dperini/nwsapi):** Fund specific features or bug bounties.

---
*Custom licensing, dedicated support, or priority bug fixes are also available for corporate sponsors. Feel free to reach out!*