Revamp (#83)

* See CHANGELOG for v3.0.0

* removed get-stream

* enabled linter just for test.js & from.js

* Any blob part is acceptable (jsdoc)
since the default fallback is to cast unknown items into strings

* async stat version

* import from fs/promise instead

* Updated the Readme and code examples

* known differences, buffer.Blob support, private stream, more test

* require node 14

* use fetch v3

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

CHANGELOG.md

@@ -1,8 +1,18 @@
 Changelog
 =========
 
-## next
-- Fixed a bug where in BlobDataItem when the file was empty (#86)
+## v3.0.0
+- Changed WeakMap for private field (require node 12)
+- Switch to ESM
+- blob.stream() return a subset of whatwg stream which is the async iterable
+  (it no longer return a node stream)
+- Reduced the dependency of Buffer by changing to global TextEncoder/Decoder (require node 11)
+- Disabled xo since it could understand private fields (#)
+- No longer transform the type to lowercase (https://github.com/w3c/FileAPI/issues/43)
+  This is more loose than strict, keys should be lowercased, but values should not.
+  It would require a more proper mime type parser - so we just made it loose.
+- index.js can now be imported by browser & deno since it no longer depends on any
+  core node features (but why would you? other environment can benefit from it)
 
 ## v2.1.2
 - Fixed a bug where `start` in BlobDataItem was undefined (#85)

README.md

@@ -13,18 +13,95 @@ 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)
+      (Read "Differences from other blobs" for more info.)
+
+    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>
+
+<details>
+  <summary>Differences from other Blobs</summary>
+
+  - Unlike NodeJS `buffer.Blob` (Added in: v15.7.0) and browser native Blob this polyfilled version can't be sent via PostMessage
+  - This blob version is more arbitrary, it can be constructed with blob parts that isn't a instance of itself
+  it has to look and behave as a blob to be accepted as a blob part.
+    - The benefit of this is that you can create other types of blobs that don't contain any internal data that has to be read in other ways, such as the `BlobDataItem` created in `from.js` that wraps a file path into a blob-like item and read lazily (nodejs plans to [implement this][fs-blobs] as well)
+  - The `blob.stream()` is the most noticeable differences. It returns a AsyncGeneratorFunction that yields Uint8Arrays
+
+  The reasoning behind `Blob.prototype.stream()` is that NodeJS readable stream
+  isn't spec compatible with whatwg streams and we didn't want to import the hole whatwg stream polyfill for node
+  or browserify NodeJS streams for the 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. this is the most isomorphic way with the use of `for-await-of` loops.
+  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 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 is isomorphic.
+  ```js
+    for await (const chunk of blob.stream()) {
+      console.log(chunk) // uInt8Array
+    }
+  ```
+  If you need to make some feature detection to fix this different behavior
+  ```js
+  if (Blob.prototype.stream?.constructor?.name === 'AsyncGeneratorFunction') {
+    // not spec compatible, monkey patch it...
+    // (Alternative you could extend the Blob and use super.stream())
+    let orig = Blob.prototype.stream
+    Blob.prototype.stream = function () {
+      const iterator = orig.call(this)
+      return new ReadableStream({
+        async pull (ctrl) {
+          const next = await iterator.next()
+          return next.done ? ctrl.close() : ctrl.enqueue(next.value)
+        }
+      })
+    }
+  }
+  ```
+  Possible feature whatwg version: `ReadableStream.from(iterator)`
+  It's also possible to delete this method and instead use `.slice()` and `.arrayBuffer()` since it has both a public and private stream method
+</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
+// (PS 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')
+
+
+// Ways to read the blob:
+const blob = new Blob(['hello, world'])
+
+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 +112,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} from '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
 ```
 
@@ -55,3 +135,4 @@ See the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Blo
 [codecov-url]: https://codecov.io/gh/node-fetch/fetch-blob
 [install-size-image]: https://flat.badgen.net/packagephobia/install/fetch-blob
 [install-size-url]: https://packagephobia.now.sh/result?p=fetch-blob
+[fs-blobs]: https://github.com/nodejs/node/issues/37340

from.js

@@ -1,61 +1,75 @@
-const {statSync, createReadStream} = require('fs');
-const Blob = require('./index.js');
-const DOMException = require('domexception');
+import {statSync, createReadStream} from 'fs';
+import {stat} from 'fs/promises';
+import DOMException from 'domexception';
+import Blob from './index.js';
 
 /**
  * @param {string} path filepath on the disk
  * @returns {Blob}
  */
-function blobFrom(path) {
-	const {size, mtime} = statSync(path);
-	const blob = new BlobDataItem({path, size, mtime});
+ const blobFromSync = path => from(statSync(path), path);
 
-	return new Blob([blob]);
-}
+/**
+ * @param {string} path filepath on the disk
+ * @returns {Promise<Blob>}
+ */
+ const blobFrom = path => stat(path).then(stat => from(stat, path));
+
+const from = (stat, path) => new Blob([new BlobDataItem({
+	path,
+	size: stat.size,
+	lastModified: stat.mtimeMs,
+	start: 0
+})]);
 
 /**
  * This is a blob backed up by a file on the disk
- * with minium requirement
+ * with minium requirement. Its wrapped around a Blob as a blobPart
+ * so you have no direct access to this.
  *
  * @private
  */
 class BlobDataItem {
+	#path;
+	#start;
+
 	constructor(options) {
+		this.#path = options.path;
+		this.#start = options.start;
 		this.size = options.size;
-		this.path = options.path;
-		this.start = options.start || 0;
-		this.mtime = options.mtime;
+		this.lastModified = options.lastModified
 	}
 
-	// Slicing arguments is first validated and formated
-	// to not be out of range by Blob.prototype.slice
+	/**
+	 * Slicing arguments is first validated and formatted
+	 * to not be out of range by Blob.prototype.slice
+	 */
 	slice(start, end) {
 		return new BlobDataItem({
-			path: this.path,
-			start,
-			mtime: this.mtime,
-			size: end - start
+			path: this.#path,
+			lastModified: this.lastModified,
+			size: end - start,
+			start
 		});
 	}
 
-	stream() {
-		if (statSync(this.path).mtime > this.mtime) {
+	async * stream() {
+		const {mtimeMs} = await stat(this.#path)
+		if (mtimeMs > this.lastModified) {
 			throw new DOMException('The requested file could not be read, typically due to permission problems that have occurred after a reference to a file was acquired.', 'NotReadableError');
 		}
-
-		if (!this.size) {
-			return new Blob().stream();
+		if (this.size) {
+			yield * createReadStream(this.#path, {
+				start: this.#start,
+				end: this.#start + this.size - 1
+			});
 		}
-
-		return createReadStream(this.path, {
-			start: this.start,
-			end: this.start + this.size - 1
-		});
 	}
 
 	get [Symbol.toStringTag]() {
 		return 'Blob';
 	}
 }
 
-module.exports = blobFrom;
+export default blobFromSync;
+export {Blob, blobFrom, blobFromSync};