docs: update docs

docs/README.md

@@ -4,7 +4,7 @@ torrefy / [Exports](modules.md)
 <img width="200" src="https://user-images.githubusercontent.com/10386119/202842623-06e8ca3f-5761-41ed-9a8a-3a617b4e33a5.svg">
   <h1>torrefy</h1>
   <p>
-    <img src="https://img.shields.io/github/languages/top/Sec-ant/torrefy" alt="GitHub top language"> <a href="https://www.npmjs.com/package/torrefy"><img src="https://img.shields.io/npm/v/torrefy" alt="npm version"></a> <a href="https://www.npmjs.com/package/torrefy"><img src="https://img.shields.io/npm/dm/torrefy" alt="npm downloads"></a> <a href="https://www.jsdelivr.com/package/npm/torrefy"><img src="https://data.jsdelivr.com/v1/package/npm/torrefy/badge?style=rounded" alt=""></a> <img src="https://img.shields.io/github/search/Sec-ant/torrefy/goto" alt="GitHub search hit counter"> <a href="https://openbase.com/js/torrefy?utm_source=embedded&amp;utm_medium=badge&amp;utm_campaign=rate-badge"><img src="https://badges.openbase.com/js/rating/torrefy.svg?token=SBYugeYmOxDXIoCFLx5bHr1urYSXTjmWD51wO5PzyH0=" alt="Rate this package"></a>
+    <img src="https://img.shields.io/github/languages/top/Sec-ant/torrefy" alt="GitHub top language"> <a href="https://www.npmjs.com/package/torrefy"><img src="https://img.shields.io/npm/v/torrefy" alt="npm version"></a> <a href="https://www.npmjs.com/package/torrefy"><img src="https://img.shields.io/npm/dm/torrefy" alt="npm downloads"></a> <a href="https://www.jsdelivr.com/package/npm/torrefy"><img src="https://data.jsdelivr.com/v1/package/npm/torrefy/badge?style=rounded" alt=""></a> <img src="https://img.shields.io/github/search/Sec-ant/torrefy/goto" alt="GitHub search hit counter"> <a href="https://openbase.com/js/torrefy?utm_source=embedded&amp;utm_medium=badge&amp;utm_campaign=rate-badge"><img src="https://badges.openbase.com/js/rating/torrefy.svg?token=UY9uJPeXa2wpaK3OZLFien356kfd00deRlZejfs6B6g=" alt="Rate this package"></a>
   </p>
   <p>
     An <a href="https://developer.mozilla.org/docs/Web/JavaScript/Guide/Modules">ESM</a> package that uses <a href="https://developer.mozilla.org/docs/Web/API/Streams_API">Web Streams API</a> to create v1, v2 or hybrid torrents in your web browser.
@@ -49,8 +49,81 @@ const decodedMetaInfo = await decode(torrentStream2);
 
 ## Features
 
-### Supports Different Web File APIs
+### Supports Creating V1, V2 or Hybrid Torrents
+
+This package supports creating [V1](http://bittorrent.org/beps/bep_0003.html), [V2](https://www.bittorrent.org/beps/bep_0052.html) ([introduction blog](https://blog.libtorrent.org/2020/09/bittorrent-v2/)) or [Hybrid](https://www.bittorrent.org/beps/bep_0052.html#upgrade-path) ([introduction blog](https://blog.libtorrent.org/2020/09/bittorrent-v2/#:~:text=for%20backwards%20compatibility.-,backwards%20compatibility,-All%20new%20features)) torrents.
+
+### Covers Various Web File APIs
 
 This package can handle input files or directories acquired from [File API](https://developer.mozilla.org/docs/Web/API/File), [File and Directory Entries API](https://developer.mozilla.org/docs/Web/API/File_and_Directory_Entries_API) or [File System Access API](https://developer.mozilla.org/docs/Web/API/File_System_Access_API).
 
-### TBD
+### Supports Comprehensive Options
+
+TBD
+
+### Supports Handling Progress
+
+TBD
+
+### Exposes Stream-Based APIs
+
+The `create` function consumes an [iterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) of input files as [`ReadableStream`](https://developer.mozilla.org/docs/Web/API/ReadableStream)s with options and populates a `MetaInfo` object. This function internally uses several [`TransformStream`](https://developer.mozilla.org/docs/Web/API/TransformStream)s to chop the files into pieces and hash them.
+
+The `encode` function consumes any bcodec friendly entity (e.g. `MetaInfo` object) and [bencode](http://bittorrent.org/beps/bep_0003.html#bencoding)s it into a `ReadableStream`.
+
+The `decode` function consumes any bcodec friendly `ReadableStream` (e.g. torrent `ReadableStream`) and bdecodes it into the corresponding entity. This function internally uses a `TransformStream` called `Tokenizer` to tokenize the input `ReadableStream` and then calls `parse` function to parse the `Tokens`.
+
+All `TransformStream`s used in this package are also exported.
+
+### Supports a Comprehensive Set of Bcodec Friendly Javascript Types
+
+Bcodec friendly Javascript types includes (for the time being):
+
+| Bcodec Type \ Javascript Type |                                                           `Strict`                                                            |                                                                 `Loose` (`& Strict`)                                                                  |
+| :---------------------------: | :---------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------: |
+|         `ByteString`          |                                [`string`](https://developer.mozilla.org/docs/Glossary/String)                                 |                        [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)                        |
+|           `Integer`           | [`number`](https://developer.mozilla.org/docs/Glossary/Number) [`bigint`](https://developer.mozilla.org/docs/Glossary/BigInt) |                                           [`boolean`](https://developer.mozilla.org/docs/Glossary/Boolean)                                            |
+|            `List`             |                [`Strict[]`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)                 |                                                                       `Loose[]`                                                                       |
+|         `Dictionary`          |        [`{[key: string]: Strict}`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)         | ` {[key: string]: Loose}` <br/> [`Map<string \| ArrayBuffer, Loose>`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map) |
+|            ignored            |                                                               -                                                               |                                                                  `undefined` `null`                                                                   |
+
+`encode` function supports all `Loose` type inputs and `decode` function always returns `Strict` type results.
+
+### Supports Hooks in Bencoding
+
+> ⚠ The terminology may change in the future.
+
+You can register hooks when using the `encode` function. A common use case is extracting the bencoded `info` dictionary and calculating the [`infohash`](http://bittorrent.org/beps/bep_0052.html#infohash). (This package doesn't provide an out-of-box function to calculate `infohash` for now)
+
+To use hooks, you will have to install the peer dependency [`@sec-ant/trie-map`](https://www.npmjs.com/package/@sec-ant/trie-map), which allows you to register hook handlers with iterable paths as keys. You can learn more about this package in its [README](https://github.com/Sec-ant/trie-map).
+
+This package provides 3 helper functions to help you register hook handlers on hooks and consume their results as you please: `useUint8ArrayStreamHook`, `useArrayBufferPromiseHook`, `useTextPromiseHook`.
+
+Here is how you should use this feature:
+
+```ts
+import { encode, EncoderHooks, useArrayBufferPromiseHook } from "torrefy";
+import { TrieMap } from "@sec-ant/trie-map";
+
+// create a dummy object to encode
+const dummyObject = {
+  a: "b",
+  c: 1,
+  info: {
+    foo: "bar",
+  },
+  s: ["t"],
+};
+
+// initialize hooks for registration of hook handlers
+const hooks: EncoderHooks = new TrieMap();
+
+// register an array buffer promise hook under `dummyObject.info`
+const [infoArrayBufferPromise] = useArrayBufferPromiseHook(["info"], hooks);
+
+// provide the hooks as an input argument into the encode function
+const bencodedReadableStream = encode(dummyObject, hooks);
+
+// await the hook result
+const infoArrayBuffer = await infoArrayBufferPromise; // => ArrayBuffer(12)
+```

docs/classes/BlockHasher.md

@@ -37,7 +37,7 @@ TransformStream<Uint8Array, Uint8Array[]\>.constructor
 
 #### Defined in
 
-[src/transformers/blockHasher.ts:67](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/blockHasher.ts#L67)
+[src/transformers/blockHasher.ts:67](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/blockHasher.ts#L67)
 
 ## Properties
 

docs/classes/ChunkSplitter.md

@@ -39,7 +39,7 @@ TransformStream<Uint8Array, Uint8Array\>.constructor
 
 #### Defined in
 
-[src/transformers/chunkSplitter.ts:45](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/chunkSplitter.ts#L45)
+[src/transformers/chunkSplitter.ts:45](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/chunkSplitter.ts#L45)
 
 ## Properties
 

docs/classes/MerkleRootCalculator.md

@@ -40,7 +40,7 @@ TransformStream<
 
 #### Defined in
 
-[src/transformers/merkleRootCalculator.ts:28](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/merkleRootCalculator.ts#L28)
+[src/transformers/merkleRootCalculator.ts:28](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/merkleRootCalculator.ts#L28)
 
 ## Properties
 

docs/classes/MerkleTreeBalancer.md

@@ -40,7 +40,7 @@ TransformStream<
 
 #### Defined in
 
-[src/transformers/merkleTreeBalancer.ts:40](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/merkleTreeBalancer.ts#L40)
+[src/transformers/merkleTreeBalancer.ts:40](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/merkleTreeBalancer.ts#L40)
 
 ## Properties
 

docs/classes/PieceHasher.md

@@ -37,7 +37,7 @@ TransformStream<Uint8Array, Uint8Array\>.constructor
 
 #### Defined in
 
-[src/transformers/pieceHasher.ts:32](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/pieceHasher.ts#L32)
+[src/transformers/pieceHasher.ts:32](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/pieceHasher.ts#L32)
 
 ## Properties
 

docs/classes/Tokenizer.md

@@ -31,7 +31,7 @@ TransformStream<Uint8Array, Token\>.constructor
 
 #### Defined in
 
-[src/transformers/tokenizer.ts:249](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/tokenizer.ts#L249)
+[src/transformers/tokenizer.ts:248](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/tokenizer.ts#L248)
 
 ## Properties
 

docs/enums/CommonPieceLength.md

@@ -29,7 +29,7 @@ common piece lengths
 
 #### Defined in
 
-[src/create.ts:398](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L398)
+[src/create.ts:398](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L398)
 
 ___
 
@@ -39,7 +39,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:395](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L395)
+[src/create.ts:395](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L395)
 
 ___
 
@@ -49,7 +49,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:405](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L405)
+[src/create.ts:405](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L405)
 
 ___
 
@@ -59,7 +59,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:401](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L401)
+[src/create.ts:401](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L401)
 
 ___
 
@@ -69,7 +69,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:399](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L399)
+[src/create.ts:399](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L399)
 
 ___
 
@@ -79,7 +79,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:402](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L402)
+[src/create.ts:402](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L402)
 
 ___
 
@@ -89,7 +89,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:396](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L396)
+[src/create.ts:396](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L396)
 
 ___
 
@@ -99,7 +99,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:406](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L406)
+[src/create.ts:406](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L406)
 
 ___
 
@@ -109,7 +109,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:403](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L403)
+[src/create.ts:403](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L403)
 
 ___
 
@@ -119,7 +119,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:400](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L400)
+[src/create.ts:400](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L400)
 
 ___
 
@@ -129,7 +129,7 @@ ___
 
 #### Defined in
 
-[src/create.ts:397](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L397)
+[src/create.ts:397](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L397)
 
 ___
 
@@ -139,4 +139,4 @@ ___
 
 #### Defined in
 
-[src/create.ts:404](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L404)
+[src/create.ts:404](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L404)

docs/enums/TokenType.md

@@ -12,7 +12,6 @@
 - [Integer](TokenType.md#integer)
 - [ListEnd](TokenType.md#listend)
 - [ListStart](TokenType.md#liststart)
-- [NewTokenType](TokenType.md#newtokentype)
 
 ## Enumeration Members
 
@@ -22,7 +21,7 @@
 
 #### Defined in
 
-[src/transformers/tokenizer.ts:14](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/tokenizer.ts#L14)
+[src/transformers/tokenizer.ts:14](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/tokenizer.ts#L14)
 
 ___
 
@@ -32,7 +31,7 @@ ___
 
 #### Defined in
 
-[src/transformers/tokenizer.ts:18](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/tokenizer.ts#L18)
+[src/transformers/tokenizer.ts:18](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/tokenizer.ts#L18)
 
 ___
 
@@ -42,7 +41,7 @@ ___
 
 #### Defined in
 
-[src/transformers/tokenizer.ts:17](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/tokenizer.ts#L17)
+[src/transformers/tokenizer.ts:17](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/tokenizer.ts#L17)
 
 ___
 
@@ -52,7 +51,7 @@ ___
 
 #### Defined in
 
-[src/transformers/tokenizer.ts:13](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/tokenizer.ts#L13)
+[src/transformers/tokenizer.ts:13](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/tokenizer.ts#L13)
 
 ___
 
@@ -62,7 +61,7 @@ ___
 
 #### Defined in
 
-[src/transformers/tokenizer.ts:16](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/tokenizer.ts#L16)
+[src/transformers/tokenizer.ts:16](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/tokenizer.ts#L16)
 
 ___
 
@@ -72,14 +71,4 @@ ___
 
 #### Defined in
 
-[src/transformers/tokenizer.ts:15](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/tokenizer.ts#L15)
-
-___
-
-### NewTokenType
-
-• **NewTokenType** = ``"NewTokenType"``
-
-#### Defined in
-
-[src/transformers/tokenizer.ts:19](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/transformers/tokenizer.ts#L19)
+[src/transformers/tokenizer.ts:15](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/transformers/tokenizer.ts#L15)

docs/enums/TorrentType.md

@@ -24,7 +24,7 @@ v1 + v2 hybrid torrent
 
 #### Defined in
 
-[src/create.ts:61](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L61)
+[src/create.ts:61](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L61)
 
 ___
 
@@ -38,7 +38,7 @@ v1 torrent
 
 #### Defined in
 
-[src/create.ts:49](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L49)
+[src/create.ts:49](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L49)
 
 ___
 
@@ -52,4 +52,4 @@ v2 torrent
 
 #### Defined in
 
-[src/create.ts:55](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/create.ts#L55)
+[src/create.ts:55](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/create.ts#L55)

docs/interfaces/FilePropsV1.md

@@ -40,7 +40,7 @@ FilePropsBase.attr
 
 #### Defined in
 
-[src/utils/fileTree.ts:75](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/utils/fileTree.ts#L75)
+[src/utils/fileTree.ts:75](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/utils/fileTree.ts#L75)
 
 ___
 
@@ -60,7 +60,7 @@ FilePropsBase.length
 
 #### Defined in
 
-[src/utils/fileTree.ts:63](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/utils/fileTree.ts#L63)
+[src/utils/fileTree.ts:63](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/utils/fileTree.ts#L63)
 
 ___
 
@@ -75,4 +75,4 @@ corresponding to **subdirectory** names
 
 #### Defined in
 
-[src/utils/fileTree.ts:88](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/utils/fileTree.ts#L88)
+[src/utils/fileTree.ts:88](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/utils/fileTree.ts#L88)

docs/interfaces/FilePropsV2.md

@@ -40,7 +40,7 @@ FilePropsBase.attr
 
 #### Defined in
 
-[src/utils/fileTree.ts:75](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/utils/fileTree.ts#L75)
+[src/utils/fileTree.ts:75](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/utils/fileTree.ts#L75)
 
 ___
 
@@ -60,7 +60,7 @@ FilePropsBase.length
 
 #### Defined in
 
-[src/utils/fileTree.ts:63](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/utils/fileTree.ts#L63)
+[src/utils/fileTree.ts:63](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/utils/fileTree.ts#L63)
 
 ___
 
@@ -76,4 +76,4 @@ constructed from 16KiB blocks of the file
 
 #### Defined in
 
-[src/utils/fileTree.ts:102](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/utils/fileTree.ts#L102)
+[src/utils/fileTree.ts:102](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/utils/fileTree.ts#L102)

docs/interfaces/FileTreeFileNode.md

@@ -27,4 +27,4 @@ of the composed path at that point
 
 #### Defined in
 
-[src/utils/fileTree.ts:120](https://github.com/Sec-ant/bepjs/blob/5d0ef68/src/utils/fileTree.ts#L120)
+[src/utils/fileTree.ts:120](https://github.com/Sec-ant/bepjs/blob/9d6a68a/src/utils/fileTree.ts#L120)