Updated the Readme and code examples

Author: jimmywarting

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macOS-latest]
-        node: ["15", "14", "12", engines]
+        node: ["16", "15", "14", engines]
         exclude:
           # On Windows, run tests with only the LTS environments.
           - os: windows-latest

README.md

@@ -13,18 +13,66 @@ A Blob implementation in Node.js, originally from [node-fetch](https://github.co
 npm install fetch-blob
 ```
 
+<details>
+  <summary>Upgrading from 2x to 3x</summary>
+
+  Updating from 2 to 3 should be a breeze since there is not many changes to the blob specification.
+  The major cause of a major release is coding standards.
+    - internal WeakMaps was replaced with private fields
+    - internal Buffer.from was replaced with TextEncoder/Decoder
+    - internal buffers was replaced with Uint8Arrays
+    - CommonJS was replaced with ESM
+    - The node stream returned by calling `blob.stream()` was replaced with a simple generator function that yields Uint8Array (Breaking change)
+
+  The reasoning behind `Blob.prototype.stream()` is that node readable stream
+  isn't spec compatible with whatwg stream and we didn't want to import a hole whatwg stream polyfill for node
+  or browserify hole node-stream for browsers and picking any flavor over the other. So we decided to opted out
+  of any stream and just implement the bear minium of what both streams have in common which is the asyncIterator
+  that both yields Uint8Array. It would be redundant to convert anything to whatwg streams and than convert it back to
+  node streams since you work inside of Node.
+  It will probably stay like this until nodejs get native support for whatwg<sup>[1][https://github.com/nodejs/whatwg-stream]</sup> streams and whatwg stream add the node
+  equivalent for `Readable.from(iterable)`<sup>[2](https://github.com/whatwg/streams/issues/1018)</sup>
+
+  But for now if you really want/need a Node Stream then you can do so using this transformation
+  ```js
+    import {Readable} from 'stream'
+    const stream = Readable.from(blob.stream())
+  ```
+  But if you don't need it to be a stream then you can just use the asyncIterator part of it that both whatwg stream and node stream have in common
+  ```js
+    for await (const chunk of blob.stream()) {
+      console.log(chunk) // uInt8Array
+    }
+  ```
+
+  All of this changes have made it dependency free of any core node modules, so it would be possible to just import it using http-import from a CDN without any bundling
+
+</details>
+
 ## Usage
 
 ```js
-const Blob = require('fetch-blob');
-const fetch = require('node-fetch');
-
-fetch('https://httpbin.org/post', {
-    method: 'POST',
-    body: new Blob(['Hello World'], { type: 'text/plain' })
-})
-    .then(res => res.json());
-    .then(json => console.log(json));
+// Ways to import
+// (note that it's dependency free ESM package so regular http-import from CDN works too)
+import Blob from 'fetch-blob';
+import {Blob} from 'fetch-blob';
+const {Blob} = await import('fetch-blob');
+
+const blob = new Blob(['hello, world']);
+
+// Ways to read the blob:
+
+await blob.text()
+
+await blob.arrayBuffer()
+
+for await (let chunk of  blob.stream()) { ... }
+
+// turn the async iterator into a node stream
+stream.Readable.from(blob.stream())
+
+// turn the async iterator into a whatwg stream (feature)
+globalThis.ReadableStream.from(blob.stream())
 ```
 
 ### Blob part backed up by filesystem
@@ -35,13 +83,16 @@ npm install fetch-blob domexception
 ```
 
 ```js
-const blobFrom = require('fetch-blob/from.js');
-const blob1 = blobFrom('./2-GiB-file.bin');
-const blob2 = blobFrom('./2-GiB-file.bin');
+// The default export is sync and use fs.stat to retrieve size & last modified
+import blobFromSync from 'fetch-blob/from.js'
+import {Blob, blobFrom, blobFromSync} 'fetch-blob/from.js'
+
+const fsBlob1 = blobFromSync('./2-GiB-file.bin');
+const fsBlob2 = await blobFrom('./2-GiB-file.bin');
 
 // Not a 4 GiB memory snapshot, just holds 3 references
 // points to where data is located on the disk
-const blob = new Blob([blob1, blob2]);
+const blob = new Blob([fsBlob1, fsBlob2, 'memory']);
 console.log(blob.size) // 4 GiB
 ```
 

from.js

@@ -29,7 +29,7 @@ const from = (stat, path) => new Blob([new BlobDataItem({
  *
  * @private
  */
-class BlobDataItem {
+export default class BlobDataItem {
 	#path;
 	#start;
 
@@ -71,5 +71,4 @@ class BlobDataItem {
 	}
 }
 
-export default blobFromSync;
 export {Blob, blobFrom, blobFromSync};

package.json

@@ -1,6 +1,6 @@
 {
     "name": "fetch-blob",
-    "version": "3.0.0",
+    "version": "3.0.0-rc.0",
     "description": "A Blob implementation in Node.js, originally from node-fetch.",
     "main": "index.js",
     "type": "module",