From b7df1cea1b746291b11b48ca704db9677b698dbb Mon Sep 17 00:00:00 2001 From: myl7 Date: Wed, 12 Jul 2023 20:20:32 +0800 Subject: [PATCH] Update readme for usage and links --- README.md | 76 +++++++++++++++++++++++++------------------------------ 1 file changed, 34 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 3223253..68cb138 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,30 @@ # brotli-dec-wasm -[Brotli](https://github.com/google/brotli) decompressor for browsers and web workers with WASM, which still has a small size (about 300KB) +[Brotli][google/brotli] decompressor for browsers and web workers with WASM, which still has a small size (about +300KB) + +[google/brotli]: https://github.com/google/brotli If you are looking for a compressor, see [Alternatives](#alternatives) ## Features -- [Streaming](https://brotli.org/decode.html#a234) support - -## Quick start - -**NOTICE: This needs update!** - -```ts -// One-shot decompressing -const brotli = await import('brotli-dec-wasm') -const output = brotli.brotliDec(input) - -// Streaming decompressing -const brotli = await import('brotli-dec-wasm') -const stream = new brotli.BrotliDecStream() -// Set max output buffer size as 1024 -const output1 = stream.dec(input1, 1024) -const result = stream.result() -// If result = NeedsMoreInput = 1, put more input into the stream to get next output -if (result == brotli.BrotliDecStreamResult.NeedsMoreInput) { - const output2 = stream.dec(input2, 1024) -} -// If result = NeedsMoreOutput = 2, slice the input and take another output buffer out -if (result == brotli.BrotliDecStreamResult.NeedsMoreOutput) { - const input1r = input1.slice(steam.lastInputOffset()) - const output2 = stream.dec(input1r, 1024) -} -// If result = ResultSuccess = 3, decompressing succeeded and finished. No more input is required. -if (result == brotli.BrotliDecStreamResult.ResultSuccess) { - console.log(output1) -} -// If result < 0, an error occurs. You may refer BrotliDecStreamErrCode to lookup the error code. -if (result < 0) { - console.error('Brotli decompressing failed') -} -``` +- [Stream][brotli_doc_stream] support + +[brotli_doc_stream]: https://brotli.org/decode.html#a234 + +## Usage + +Starting from v2.0.0, this package becomes an exact drop-in replacement of [brotli-wasm]. +You can simply replace `import brotli from 'brotli-wasm'` with `import brotli from 'brotli-dec-wasm'` to switch from or to this package. + +More detailed usage can be found in [brotli-wasm] _Usage_ section. + +Notice that brotli-wasm is going to release a new version for the new stream pattern, +which is also used by this package, and has not update the README yet. +If you are urgent, you can refer to the unit tests in [brotli-wasm:test/brotli.spec.ts] to see how to use by examples. + +[brotli-wasm:test/brotli.spec.ts]: https://github.com/httptoolkit/brotli-wasm/blob/main/test/brotli.spec.ts ## Problems @@ -53,25 +37,31 @@ Set `experiments.syncWebAssembly: true` for old code, `experiments.asyncWebAssem ## Implementation -The code is quite simple, which is just a wrapper of [`brotli-decompressor`](https://crates.io/crates/brotli-decompressor) crate (other than [`brotli`](https://crates.io/crates/brotli) crate, though `brotli` depends on `brotli-decompressor`) +The code is quite simple, which is just a wrapper of the crate [brotli-decompressor] (other than crate [brotli], though brotli depends on brotli-decompressor) + +[brotli-decompressor]: https://crates.io/crates/brotli-decompressor +[brotli]: https://crates.io/crates/brotli Build configuration such as `opt-level = "s"`, are fine-tuned with manual tests, to make the bundle as small as possible ## Maintenance -The package is at least used by myself in my blog [`mylmoe`](https://github.com/myl7/mylmoe), which provides [a page to (de)compress Brotli online](https://myl.moe/utils/brotli) +The package is at least used by myself in my blog [mylmoe], which provides [a page to (de)compress Brotli online] + +[mylmoe]: https://github.com/myl7/mylmoe +[a page to (de)compress Brotli online]: https://myl.moe/utils/brotli ## Alternatives -- [brotli-wasm](https://github.com/httptoolkit/brotli-wasm): A reliable compressor and decompressor for Brotli, supporting node & browsers via wasm. If you need a compressor, use it. Actively maintained by an organization. +- [brotli-wasm]: A reliable compressor and decompressor for Brotli, supporting node & browsers via wasm. If you need a compressor, use it. Actively maintained by an organization. -More alternatives are available in [brotli-wasm](https://github.com/httptoolkit/brotli-wasm) _Alternatives_ section +More alternatives are available in [brotli-wasm] _Alternatives_ section -One surprising thing is, in `js` folder of the offical [google/brotli](https://github.com/google/brotli) repository, there is a pure JavaScript decompressor implementation, which is even a little smaller than this package in size. However, it is not published on NPM. I can not imagine the reason and since that, I do not suggest you to use it. +One surprising thing is, in `js` folder of the offical [google/brotli] repository, there is a pure JavaScript decompressor implementation, which is even a little smaller than this package in size. However, it is not published on NPM. I can not imagine the reason and since that, I do not suggest you to use it. ## Security -At least **>= 1.3.3** +At least **>= v1.3.3** - < v1.3.3: Rust dependency wee_alloc is unmaintained and has open serious issues. Use version >= 1.3.3 to replace it with the default Rust allocator on wasm32 targets. @@ -82,3 +72,5 @@ Copyright (C) myl7 SPDX-License-Identifier: MIT OR Apache-2.0 At your option. Unless otherwise explicitly stated. + +[brotli-wasm]: https://github.com/httptoolkit/brotli-wasm