@arcjet/analyze-wasm 1.0.0-beta.1 → 1.0.0-beta.10

package/README.md

@@ -22,41 +22,64 @@ against common attacks.
 
 This package provides WebAssembly bindings to [Arcjet's][arcjet] local analysis engine.
 
-## Installation
+- [npm package (`@arcjet/analyze-wasm`)](https://www.npmjs.com/package/@arcjet/analyze-wasm)
+- [GitHub source code (`analyze-wasm/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/analyze-wasm)
 
-```shell
-npm install -S @arcjet/analyze-wasm
-```
+## What is this?
+
+This package provides logic in WebAssembly to locally analyze requests.
+
+To load these binary files everywhere until something like
+[_Import Bytes_][tc39-proposal-import-bytes] is available,
+we settled on a technique that seems to work well everywhere.
+This technique gives us compatibility with for example Next.js which right now
+requires a special experimental `asyncWebAssembly` webpack configuration,
+
+The file `_virtual/arcjet_analyze_js_req.component.core.js` contains the
+WebAssembly inlined as a [`data:` URL][mdn-data-url].
+This is about 3 times smaller than using a `Uint8Array` (see
+[_Better Binary Batter: Mixing Base64 and Uint8Array_][wasm-base64-blog] for more
+info).
+That URL is then turned into an `ArrayBuffer` and passed to
+`WebAssembly.compile`.
 
-## Implementation
+The files here are generated.
+They are wrapped up into [`@arcjet/analyze`][github-arcjet-analyze] for use in
+JavaScript,
+in turn exposed in our core package
+([`arcjet`][github-arcjet-arcjet])
+and our adapters (such as `@arcjet/next`).
 
-This package provides analyze logic implemented as a WebAssembly module which
-will run local analysis on request details.
+<!-- TODO(@wooorm-arcjet): link `adapters` above when the main repo is up to date. -->
 
-The `_virtual/arcjet_analyze_js_req.component.core.js` file contains the binary inlined as
-a base64 [Data URL][mdn-data-url] with the `application/wasm` MIME type.
+## When should I use this?
 
-This was chosen to save on storage space over inlining the file directly as a
-Uint8Array, which would take up ~3x the space of the Wasm file. See
-[Better Binary Batter: Mixing Base64 and Uint8Array][wasm-base64-blog] for more
-details.
+This is an internal Arcjet package not designed for public use.
+See our [_Get started_ guide][arcjet-get-started] for how to use Arcjet in your
+application.
 
-It is then decoded into an ArrayBuffer to be used directly via WebAssembly's
-`compile()` function in our entry point file.
+## Install
+
+This package is ESM only.
+Install with npm in Node.js:
+
+```sh
+npm install @arcjet/analyze-wasm
+```
 
-This is all done to avoid trying to read or bundle the Wasm asset in various
-ways based on the platform or bundler a user is targeting. One example being
-that Next.js requires special `asyncWebAssembly` webpack config to load our
-Wasm file if we don't do this.
+## Use
 
-In the future, we hope to do away with this workaround when all bundlers
-properly support consistent asset bundling techniques.
+Use [`@arcjet/analyze`][file-analyze] instead.
 
 ## License
 
-Licensed under the [Apache License, Version 2.0][apache-license].
+[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
 
 [arcjet]: https://arcjet.com
+[arcjet-get-started]: https://docs.arcjet.com/get-started
+[file-analyze]: ../analyze/
 [mdn-data-url]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs
 [wasm-base64-blog]: https://blobfolio.com/2019/better-binary-batter-mixing-base64-and-uint8array/
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0
+[github-arcjet-analyze]: https://github.com/arcjet/arcjet-js/tree/main/analyze
+[tc39-proposal-import-bytes]: https://github.com/tc39/proposal-import-bytes