@bablr/fs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Conrad Buck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @bablr/fs
+
+This package offers fast, responsive, efficient access to the filesystem. Node's APIs are used under the hood, the created data streams are exposed as stream iterators.
+
+## Usage
+
+```js
+import { readFile, readDir } from '@bablr/fs';
+
+let fileIterable = readFile(import.meta.url, 'utf8');
+let directoryIterable = readDir('./');
+```
+
+## Why stream iterables?
+
+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)

package/lib/index.js

@@ -0,0 +1,161 @@
+import { open, opendir } from 'node:fs/promises';
+import { ReadableStream } from 'node:stream/web';
+import { Buffer } from 'node:buffer';
+import { getStreamIterator, StreamIterable } from '@bablr/stream-iterator';
+import { getDefaultHighWaterMark } from 'node:stream';
+
+let autoAllocateChunkSize = getDefaultHighWaterMark();
+
+let inRange = (v, min, max) => v > min && v < max;
+
+class StreamSource {
+  constructor(path) {
+    this.path = path;
+    this.type = 'bytes';
+    this.autoAllocateChunkSize = autoAllocateChunkSize;
+    this.controller = null;
+  }
+
+  async start(controller) {
+    this.file = await open(this.path);
+    this.controller = controller;
+  }
+
+  async pull(controller) {
+    const view = controller.byobRequest?.view;
+    const { bytesRead } = await this.file.read({
+      buffer: view,
+      offset: view.byteOffset,
+      length: view.byteLength,
+    });
+
+    if (bytesRead === 0) {
+      await this.file.close();
+      this.controller.close();
+    }
+    controller.byobRequest.respond(bytesRead);
+  }
+}
+
+function* __decodeUTF8(bytes) {
+  let codePoints = codePointsFor(bytes);
+  let iter = getStreamIterator(codePoints);
+  let step = iter.next();
+
+  for (;;) {
+    if (step instanceof Promise) {
+      step = yield step;
+    }
+
+    if (step.done) break;
+
+    let cp = step.value;
+
+    if (cp <= 0xffff) {
+      yield String.fromCharCode(cp);
+    } else {
+      cp -= 0x10000;
+      yield String.fromCharCode((cp >> 10) + 0xd800, (cp & 0x3ff) + 0xdc00);
+    }
+
+    step = iter.next();
+  }
+}
+
+export const decodeUTF8 = (bytes) => {
+  return new StreamIterable(__decodeUTF8(bytes));
+};
+
+// adapted from https://github.com/inexorabletash/text-encoding/blob/master/lib/encoding.js
+function* __codePointsFor(bytes) {
+  let iter = getStreamIterator(bytes);
+  let step = iter.next();
+  let partialValue = null;
+
+  for (;;) {
+    if (step instanceof Promise) {
+      step = yield step;
+    }
+
+    if (step.done) break;
+
+    let { value } = step;
+
+    if (partialValue) {
+      if (inRange(value, 0xdc00, 0xdfff)) {
+        yield (0x10000 + (partialValue & (0x3ff << 10)) + value) & 0x3ff;
+      } else {
+        yield 0xfffd;
+      }
+
+      partialValue = null;
+    } else if (!inRange(value, 0xd800, 0xdfff)) {
+      yield value;
+    } else if (inRange(value, 0xdc00, 0xdfff)) {
+      yield 0xfffd;
+    } else if (inRange(value, 0xd800, 0xdbff)) {
+      partialValue = value;
+    }
+
+    step = iter.next();
+  }
+
+  if (partialValue) {
+    yield 0xfffd;
+  }
+}
+
+export const codePointsFor = (bytes) => {
+  return new StreamIterable(__codePointsFor(bytes));
+};
+
+function* __readFile(path) {
+  let stream = new ReadableStream(new StreamSource(path));
+
+  const reader = stream.getReader({ mode: 'byob' });
+
+  let result;
+  do {
+    result = yield reader.read(Buffer.alloc(autoAllocateChunkSize));
+    if (result.value !== undefined) yield* result.value;
+  } 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;
+};
+
+function* __readDir(path) {
+  let dir = yield opendir(path);
+
+  let break_ = false;
+  let chunk = [];
+
+  while (!break_) {
+    for (let i = 0; i < 64; i++) {
+      chunk.push(dir.read());
+    }
+
+    let values = yield Promise.all(chunk);
+
+    for (let value of values) {
+      if (value === null) {
+        break_ = true;
+      } else {
+        yield value;
+      }
+    }
+
+    chunk.length = 0;
+  }
+}
+
+export const readDir = (path) => {
+  return new StreamIterable(__readDir(path));
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@bablr/fs",
+  "description": "A Node.js filesystem access library using stream iterators",
+  "version": "1.0.0",
+  "author": "Conrad Buck<conartist6@gmail.com>",
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@bablr/stream-iterator": "1.0.0"
+  },
+  "devDependencies": {
+    "@bablr/eslint-config-base": "github:bablr-lang/eslint-config-base#d834ccc52795d6c3b96ecc6c419960fceed221a6",
+    "enhanced-resolve": "^5.12.0",
+    "eslint": "^8.32.0",
+    "eslint-import-resolver-enhanced-resolve": "^1.0.5",
+    "eslint-plugin-import": "^2.27.5",
+    "iter-tools-es": "^7.3.1",
+    "prettier": "^2.6.2"
+  },
+  "repository": "github:bablr-lang/bablr-fs-node",
+  "homepage": "https://github.com/bablr-lang/bablr-fs-node",
+  "license": "MIT"
+}