@bablr/fs 1.0.0 → 2.0.1

package/README.md

@@ -5,16 +5,22 @@ This package offers fast, responsive, efficient access to the filesystem. Node's
 ## Usage
 
 ```js
-import { readFile, readDir } from '@bablr/fs';
+import { readFile, readDir, decodeUTF8 } from '@bablr/fs';
 
-let fileIterable = readFile(import.meta.url, 'utf8');
+let fileIterable = decodeUTF8(readFile(import.meta.url));
 let directoryIterable = readDir('./');
 ```
 
 ## Why stream iterables?
 
-Stream iterables offer a trifecta of desirable features:
+[Stream iterables](https://github.com/bablr-lang/stream-iterator) are a way of using iterators as an abstraction over asynchronous data access in Javascript. They propagate both sync-ness and async-ness, moving data in an efficient way comparable to how a bucket brigade moves buckets of water. Stream iterables offer a trifecta of desirable features:
 
 - Abstraction: they doesn’t require the provider to copy the data or expose its internal structure (benefit over web streams)
 - Throughput: stream iterators have high throughput and efficiency when used on streams of many small items because only some steps must wait (benefit over flat async iterators)
-- Responsiveness: returning the first data from a 20GB file doesn’t cause a huge delay, it takes just the same amount of time as opening a one-chunk file (benefit over fs.openFileSync style)
+- Responsiveness: returning the first data from a 20GB file doesn’t cause a huge delay, it takes just the same amount of time as opening a one-chunk file (benefit over fs.openFileSync)
+
+## Language support
+
+Stream iterables are not yet supported natively by JS, yet they are still possible to construct and consume using libraries. They are a primitive data type in JS: nothing about them can be made any simpler. Compare this to the officially supported "[web streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API)", nothing about which could be made more complex.
+
+We are thus looking for a champion for a `Symbol.streamIterator` proposal to TC39.

package/lib/index.js

@@ -121,14 +121,8 @@ function* __readFile(path) {
   } while (!result.done);
 }
 
-export const readFile = (path, options) => {
-  let encoding = typeof options === 'string' ? options : options.encoding;
-
-  if (encoding && !/utf-?8/i.test(encoding)) throw new Error('unsupported encoding');
-
-  let bytes = new StreamIterable(__readFile(path, options));
-
-  return encoding ? decodeUTF8(bytes) : bytes;
+export const readFile = (path) => {
+  return new StreamIterable(__readFile(path));
 };
 
 function* __readDir(path) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bablr/fs",
   "description": "A Node.js filesystem access library using stream iterators",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "author": "Conrad Buck<conartist6@gmail.com>",
   "type": "module",
   "files": [