From 4495c37ca31db4e00a46509acdd8d0d9b710ccbe Mon Sep 17 00:00:00 2001
From: Raymond Hill <rhill@raymondhill.net>
Date: Fri, 6 Aug 2021 08:25:36 -0400
Subject: [PATCH] Provide basic documentation for the NPM package

---
 platform/nodejs/README.md    | 83 +++++++++++++++++++++++++++++++++++-
 platform/nodejs/package.json |  2 +-
 platform/nodejs/test.js      | 19 ++++-----
 3 files changed, 90 insertions(+), 14 deletions(-)

diff --git a/platform/nodejs/README.md b/platform/nodejs/README.md
index c45aec028..94056a85f 100644
--- a/platform/nodejs/README.md
+++ b/platform/nodejs/README.md
@@ -1,6 +1,85 @@
 # uBlock Origin Core
 
-The core filtering engines used in the uBlock Origin extension.
+The core filtering engines used in the uBlock Origin ("uBO") extension, and has
+no external dependencies.
 
-## Getting started
+## 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());
+    }
+}
+```
diff --git a/platform/nodejs/package.json b/platform/nodejs/package.json
index 74513395f..50ba1d3f9 100644
--- a/platform/nodejs/package.json
+++ b/platform/nodejs/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@gorhill/ubo-core",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "To create a working instance of uBlock Origin's static network filtering engine",
   "type": "module",
   "main": "index.js",
diff --git a/platform/nodejs/test.js b/platform/nodejs/test.js
index 838d2148b..0c8466102 100644
--- a/platform/nodejs/test.js
+++ b/platform/nodejs/test.js
@@ -44,7 +44,7 @@ function fetch(listName) {
     });
 }
 
-(async ( ) => {
+async function main() {
     try {
         const result = await enableWASM();
         if ( result !== true ) {
@@ -56,15 +56,10 @@ function fetch(listName) {
 
     await pslInit();
 
-    const snfe = await Promise.all([
-        fetch('easylist'),
-        fetch('easyprivacy'),
-    ]).then(rawLists => {
-        return useRawLists([
-            { name: 'easylist', raw: rawLists[0] },
-            { name: 'easyprivacy', raw: rawLists[1] },
-        ]);
-    });
+    const snfe = await useRawLists([
+        fetch('easylist').then(raw => ({ name: 'easylist', raw })),
+        fetch('easyprivacy').then(raw => ({ name: 'easyprivacy', raw })),
+    ]);
 
     // Reuse filtering context: it's what uBO does
     const fctxt = new FilteringContext();
@@ -95,6 +90,8 @@ function fetch(listName) {
     }
 
     process.exit();
-})();
+}
+
+main();
 
 /******************************************************************************/