README has unsaved pending edits...

platform/nodejs/README.md

@@ -16,7 +16,8 @@ This package uses [native JavaScript modules](https://developer.mozilla.org/en-U
 
 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.
+efficient, and _especially_ optimized to match against large sets of pure
+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), 
@@ -39,47 +40,58 @@ If you must import as a NodeJS module:
 const { FilteringContext, pslInit, useRawLists } await import from '@gorhill/ubo-core';
 ```
 
+uBO's SNFE works best with a properly initialized Public Suffix List database,
+since it needs to evaluate whether a network request to match is either 1st-
+or 3rd-party to the context in which it is fired:
 
-async function main() {
+```js
-    // Initialize the internal Public Suffix List database, which is necessary
+await pslInit();
-    // 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
+Now feed the SNFE with filter lists -- `useRawLists()` accepts an array of
-    // an object exposing the property `raw`, which contains the raw text of
+objects (or promises to object) which expose the raw text of a list
-    // the filter lists.
+through the `raw` property, and optionally the name of the list through the
-    const snfe = await useRawLists([
+`name` property (how you fetch the lists is up to you):
-        fetch('easylist').then(raw => ({ name: 'easylist', raw })),
-        fetch('easyprivacy').then(raw => ({ name: 'easyprivacy', raw })),
-    ]);
 
-    // Reuse a single instance of filtering context used for matching
+```js
-    const fctxt = new FilteringContext();
+const snfe = await useRawLists([
+    fetch('easylist').then(raw => ({ name: 'easylist', raw })),
+    fetch('easyprivacy').then(raw => ({ name: 'easyprivacy', raw })),
+]);
+```
 
-    // Tests
+`useRawLists()` returns a reference to the SNFE, which you can use later to
-    // Not blocked
+match network requests. First we need a filtering context instance, which is
-    fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
+required as an argument to match networkrequests:
-    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
+```js
-    fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
+const fctxt = new FilteringContext();
-    fctxt.setURL('https://securepubads.g.doubleclick.net/tag/js/gpt.js');
+```
-    fctxt.setType('script');
-    if ( snfe.matchRequest(fctxt) !== 0 ) {
-        console.log(snfe.toLogData());
-    }
 
-    // Unblocked
+Now we are ready to match network requests:
-    fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
+
-    fctxt.setURL('https://sourcepointcmp.bloomberg.com/ccpa.js');
+```js
-    fctxt.setType('script');
+// Not blocked
-    if ( snfe.matchRequest(fctxt) !== 0 ) {
+fctxt.setDocOriginFromURL('https://www.bloomberg.com/');
-        console.log(snfe.toLogData());
+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());
 }
 ```

platform/nodejs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gorhill/ubo-core",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "To create a working instance of uBlock Origin's static network filtering engine",
   "type": "module",
   "main": "index.js",