From af544159593dfbc2b00ada9a12c4a67bb39fad6b Mon Sep 17 00:00:00 2001
From: Raymond Hill <rhill@raymondhill.net>
Date: Fri, 6 Aug 2021 08:29:13 -0400
Subject: [PATCH] README has unsaved pending edits...

---
 platform/nodejs/README.md    | 86 ++++++++++++++++++++----------------
 platform/nodejs/package.json |  2 +-
 2 files changed, 50 insertions(+), 38 deletions(-)

diff --git a/platform/nodejs/README.md b/platform/nodejs/README.md
index 94056a85f..30502c9a4 100644
--- a/platform/nodejs/README.md
+++ b/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() {
-    // 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();
+```js
+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 })),
-    ]);
+Now feed the SNFE with filter lists -- `useRawLists()` accepts an array of
+objects (or promises to object) which expose the raw text of a list
+through the `raw` property, and optionally the name of the list through the
+`name` property (how you fetch the lists is up to you):
 
-    // Reuse a single instance of filtering context used for matching
-    const fctxt = new FilteringContext();
+```js
+const snfe = await useRawLists([
+    fetch('easylist').then(raw => ({ name: 'easylist', raw })),
+    fetch('easyprivacy').then(raw => ({ name: 'easyprivacy', raw })),
+]);
+```
 
-    // 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());
-    }
+`useRawLists()` returns a reference to the SNFE, which you can use later to
+match network requests. First we need a filtering context instance, which is
+required as an argument to match networkrequests:
 
-    // 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());
-    }
+```js
+const fctxt = new FilteringContext();
+```
 
-    // 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());
-    }
+Now we are ready to match network requests:
+
+```js
+// 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());
 }
 ```
diff --git a/platform/nodejs/package.json b/platform/nodejs/package.json
index 50ba1d3f9..b40681075 100644
--- a/platform/nodejs/package.json
+++ b/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",