Add more detail to README.md

Author: mrbbot

.github/workflows/test.yml

@@ -18,6 +18,8 @@ jobs:
           profile: minimal
           toolchain: stable
       - uses: Swatinem/rust-cache@v1
+        with:
+          cache-on-failure: true
       - name: Use Node.js LTS
         uses: actions/setup-node@v2
         with:

README.md

@@ -10,6 +10,12 @@ their work on
 [lol-html's JavaScript API](https://github.com/cloudflare/lol-html/tree/master/js-api)
 which this package's Rust code is based on.
 
+## Features
+
+- 🔋 Supports all handler types, properties and methods
+- ⏰ Supports synchronous and asynchronous handlers
+- 📌 Supports class handlers with correctly bound methods
+
 ## Usage
 
 ```js
@@ -44,6 +50,25 @@ and output to strings.
 
 ## Caveats
 
+- Once `write` or `end` has been called, you cannot add any more handlers. You
+  must register all handlers before you start transforming:
+
+  ```js
+  const rewriter = new HTMLRewriter(...);
+
+  // ❌
+  rewriter.on("h1", { ... });
+  await rewriter.write(encoder.encode("<h1>1</h1"));
+  rewriter.on("p", { ... }); // not allowed
+  await rewriter.write(encoder.encode("<p>2</p>"));
+
+  // ✅
+  rewriter.on("h1", { ... });
+  rewriter.on("p", { ... });
+  await rewriter.write(encoder.encode("<h1>1</h1"));
+  await rewriter.write(encoder.encode("<p>2</p>"));
+  ```
+
 - `end` may only be called once per `HTMLRewriter` instance. This means you must
   create a new `HTMLRewriter` instance for each transformation:
 
@@ -86,6 +111,19 @@ and output to strings.
   await rewriter.write(encoder.encode("<p>2</p>"));
   ```
 
+## Internals
+
+`lol-html` doesn't natively support asynchronous handlers. Instead, whenever a
+handler returns a `Promise`, we have to unwind the WebAssembly stack into
+temporary storage, wait for the promise to resolve, then rewind the stack and
+continue parsing. This temporary storage is per `HTMLRewriter` instance, hence
+we cannot have concurrent `write` and `end` calls. We use the
+[Asyncify](https://github.com/WebAssembly/binaryen/blob/main/src/passes/Asyncify.cpp)
+feature of [Binaryen](https://github.com/WebAssembly/binaryen) to implement
+this. See
+[this article](https://kripken.github.io/blog/wasm/2019/07/16/asyncify.html) for
+more details.
+
 ## Building
 
 You can build the package by running `npm run build`. You must do this prior to

package-lock.json

@@ -16,14 +16,22 @@
     "type": "git",
     "url": "git+https://github.com/mrbbot/html-rewriter-wasm.git"
   },
-  "keywords": ["cloudflare", "workers", "worker", "html", "rewriter", "lol"],
+  "keywords": [
+    "cloudflare",
+    "workers",
+    "worker",
+    "html",
+    "rewriter",
+    "lol"
+  ],
   "author": "MrBBot",
   "license": "BSD-3-Clause",
   "bugs": {
     "url": "https://github.com/mrbbot/html-rewriter-wasm/issues"
   },
   "homepage": "https://github.com/mrbbot/html-rewriter-wasm#readme",
   "devDependencies": {
+    "@types/node": "^14.17.5",
     "ava": "^3.15.0",
     "prettier": "^2.3.2",
     "ts-node": "^10.1.0",