uBlock/platform/nodejs/README.md

# uBlock Origin Core

The core filtering engines used in the uBlock Origin ("uBO") extension, and has
no external dependencies.

## Installation

Install: `npm install --save @gorhill/ubo-core`

This is a very early version and the API is subject to change at any time.

This package uses [native JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).


## Description

The package contains uBO's static network filtering engine ("SNFE"), which
purpose is to parse and enforce filter lists. The matching algorithm is highly
efficient, and especially optimized to for large lists of hostnames.

The SNFE can be fed filter lists from a variety of sources, such as [EasyList/EasyPrivacy](https://easylist.to/), 
[uBlock filters](https://github.com/uBlockOrigin/uAssets/tree/master/filters), 
and also lists of domain names or hosts file format (i.e. block lists from [The Block List Project](https://github.com/blocklistproject/Lists#the-block-list-project), 
[Steven Black's HOSTS](https://github.com/StevenBlack/hosts#readme), etc).


## Usage

At the moment, there can be only one instance of the static network filtering
engine, which API must be imported as follow:

```js
import { FilteringContext, pslInit, useRawLists } from '@gorhill/ubo-core';
```

If you must import as a NodeJS module:

```js
const { FilteringContext, pslInit, useRawLists } await import from '@gorhill/ubo-core';
```


async function main() {
    // Initialize the internal Public Suffix List database, which is necessary
    // for the filtering engine to assess whether a network request is
    // 3rd-party to the context from which it is fired.
    await pslInit();

    // Feed EasyList and EasyPrivacy to the filtering engine. A list is
    // an object exposing the property `raw`, which contains the raw text of
    // the filter lists.
    const snfe = await useRawLists([
        fetch('easylist').then(raw => ({ name: 'easylist', raw })),
        fetch('easyprivacy').then(raw => ({ name: 'easyprivacy', raw })),
    ]);

    // Reuse a single instance of filtering context used for matching
    const fctxt = new FilteringContext();

    // Tests
    // Not blocked
    fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
    fctxt.setURL('https://www.bloomberg.com/tophat/assets/v2.6.1/that.css');
    fctxt.setType('stylesheet');
    if ( snfe.matchRequest(fctxt) !== 0 ) {
        console.log(snfe.toLogData());
    }

    // Blocked
    fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
    fctxt.setURL('https://securepubads.g.doubleclick.net/tag/js/gpt.js');
    fctxt.setType('script');
    if ( snfe.matchRequest(fctxt) !== 0 ) {
        console.log(snfe.toLogData());
    }

    // Unblocked
    fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
    fctxt.setURL('https://sourcepointcmp.bloomberg.com/ccpa.js');
    fctxt.setType('script');
    if ( snfe.matchRequest(fctxt) !== 0 ) {
        console.log(snfe.toLogData());
    }
}
```