@thi.ng/file-io 0.3.25 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-29T20:56:59Z
+- **Last updated**: 2023-02-05T14:42:21Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,19 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/file-io@0.5.0) (2023-02-05)
+
+#### 🚀 Features
+
+- add fileChunks() ([bcff691](https://github.com/thi-ng/umbrella/commit/bcff691))
+
+## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/file-io@0.4.0) (2023-01-10)
+
+#### 🚀 Features
+
+- add readText() encoding opts ([22366c0](https://github.com/thi-ng/umbrella/commit/22366c0))
+- add readBinary(), update pkg exports ([2c647ed](https://github.com/thi-ng/umbrella/commit/2c647ed))
+
 ### [0.3.25](https://github.com/thi-ng/umbrella/tree/@thi.ng/file-io@0.3.25) (2022-12-29)
 
 #### ♻️ Refactoring

package/README.md

@@ -43,7 +43,7 @@ For Node.js REPL:
 const fileIo = await import("@thi.ng/file-io");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 997 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 1.03 KB
 
 ## Dependencies
 
@@ -75,4 +75,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2022 Karsten Schmidt // Apache License 2.0
+© 2022 - 2023 Karsten Schmidt // Apache License 2.0

package/file-chunks.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="node" />
+import type { ILogger } from "@thi.ng/logger";
+export interface FileChunkOpts {
+    /**
+     * Optional logger instance
+     */
+    logger: ILogger;
+    /**
+     * Chunk size (in bytes).
+     *
+     * @defaultValue 1024
+     */
+    size: number;
+    /**
+     * Read start position (in bytes)
+     *
+     * @defaultValue 0
+     */
+    start: number;
+    /**
+     * Read end position (in bytes)
+     *
+     * @defaultValue Infinity
+     */
+    end: number;
+}
+/**
+ * Async iterator. Yields chunks of byte buffers from given file. User
+ * configurable size and byte ranges.
+ *
+ * @example
+ * ```ts
+ * for await(let buf of fileChunks("file.bin", { start: 16*1024*1024 })) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @param path
+ * @param opts
+ */
+export declare function fileChunks(path: string, opts?: Partial<FileChunkOpts>): AsyncGenerator<Buffer, void, unknown>;
+//# sourceMappingURL=file-chunks.d.ts.map

package/file-chunks.js

@@ -0,0 +1,48 @@
+import { U32 } from "@thi.ng/hex";
+import { open } from "fs/promises";
+/**
+ * Async iterator. Yields chunks of byte buffers from given file. User
+ * configurable size and byte ranges.
+ *
+ * @example
+ * ```ts
+ * for await(let buf of fileChunks("file.bin", { start: 16*1024*1024 })) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @param path
+ * @param opts
+ */
+export async function* fileChunks(path, opts) {
+    let { logger, size, start, end } = {
+        size: 1024,
+        start: 0,
+        end: Infinity,
+        ...opts,
+    };
+    logger &&
+        logger.debug(`start reading file chunks (size: 0x${size}): ${path}`);
+    let fd = undefined;
+    try {
+        fd = await open(path, "r");
+        while (start < end) {
+            logger &&
+                logger.debug(`reading chunk: 0x${U32(start)} - 0x${U32(start + size - 1)} (${path})`);
+            const { buffer, bytesRead } = await fd.read({
+                buffer: Buffer.alloc(size),
+                length: size,
+                position: start,
+            });
+            if (bytesRead === 0)
+                break;
+            yield buffer;
+            if (bytesRead < size)
+                break;
+            start += bytesRead;
+        }
+    }
+    finally {
+        await fd?.close();
+    }
+}

package/index.d.ts

@@ -1,10 +1,12 @@
 export * from "./delete.js";
 export * from "./dir.js";
 export * from "./ext.js";
+export * from "./file-chunks.js";
 export * from "./files.js";
 export * from "./hash.js";
 export * from "./json.js";
 export * from "./mask.js";
+export * from "./read.js";
 export * from "./temp.js";
 export * from "./text.js";
 export * from "./write.js";

package/index.js

@@ -1,10 +1,12 @@
 export * from "./delete.js";
 export * from "./dir.js";
 export * from "./ext.js";
+export * from "./file-chunks.js";
 export * from "./files.js";
 export * from "./hash.js";
 export * from "./json.js";
 export * from "./mask.js";
+export * from "./read.js";
 export * from "./temp.js";
 export * from "./text.js";
 export * from "./write.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/file-io",
-  "version": "0.3.25",
+  "version": "0.5.0",
   "description": "Assorted file I/O utils (with logging support) for NodeJS",
   "type": "module",
   "module": "./index.js",
@@ -34,18 +34,19 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.6.2",
-    "@thi.ng/checks": "^3.3.6",
-    "@thi.ng/logger": "^1.4.6",
-    "@thi.ng/random": "^3.3.20"
+    "@thi.ng/api": "^8.7.0",
+    "@thi.ng/checks": "^3.3.8",
+    "@thi.ng/hex": "^2.3.5",
+    "@thi.ng/logger": "^1.4.8",
+    "@thi.ng/random": "^3.3.22"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.33.7",
-    "@thi.ng/testament": "^0.3.8",
-    "rimraf": "^3.0.2",
+    "@microsoft/api-extractor": "^7.34.2",
+    "@thi.ng/testament": "^0.3.10",
+    "rimraf": "^4.1.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.23.22",
-    "typescript": "^4.9.4"
+    "typedoc": "^0.23.24",
+    "typescript": "^4.9.5"
   },
   "keywords": [
     "file",
@@ -83,6 +84,9 @@
     "./ext": {
       "default": "./ext.js"
     },
+    "./file-chunks": {
+      "default": "./file-chunks.js"
+    },
     "./files": {
       "default": "./files.js"
     },
@@ -95,6 +99,9 @@
     "./mask": {
       "default": "./mask.js"
     },
+    "./read": {
+      "default": "./read.js"
+    },
     "./temp": {
       "default": "./temp.js"
     },
@@ -109,5 +116,5 @@
     "status": "stable",
     "year": 2022
   },
-  "gitHead": "28bb74c67217a352d673b6efdab234921d4a370e\n"
+  "gitHead": "50ba9c87676fac60c46d2bc0e4d2c7711a374a68\n"
 }

package/read.d.ts

@@ -0,0 +1,9 @@
+import type { ILogger } from "@thi.ng/logger";
+/**
+ * Reads given file `path` into a byte array.
+ *
+ * @param path
+ * @param logger
+ */
+export declare const readBinary: (path: string, logger?: ILogger) => Uint8Array;
+//# sourceMappingURL=read.d.ts.map

package/read.js

@@ -0,0 +1,12 @@
+import { readFileSync } from "fs";
+/**
+ * Reads given file `path` into a byte array.
+ *
+ * @param path
+ * @param logger
+ */
+export const readBinary = (path, logger) => {
+    logger && logger.debug("reading file:", path);
+    const buf = readFileSync(path);
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+};

package/text.d.ts

@@ -1,5 +1,14 @@
+/// <reference types="node" />
 import type { ILogger } from "@thi.ng/logger";
-export declare const readText: (path: string, logger?: ILogger) => string;
+/**
+ * Reads text from given file `path`, optionally with custom encoding (default:
+ * UTF-8).
+ *
+ * @param path
+ * @param logger
+ * @param encoding
+ */
+export declare const readText: (path: string, logger?: ILogger, encoding?: Extract<BufferEncoding, "ascii" | "latin1" | "utf-8" | "utf-16le" | "ucs-2">) => string;
 /**
  * Writes `body` as UTF-8 file to given `path`. If `dryRun` is true (default:
  * false), the file WON'T be written, however if a `logger` is provided then at

package/text.js

@@ -1,9 +1,17 @@
 import { isArray } from "@thi.ng/checks/is-array";
 import { readFileSync } from "fs";
 import { writeFile } from "./write.js";
-export const readText = (path, logger) => {
+/**
+ * Reads text from given file `path`, optionally with custom encoding (default:
+ * UTF-8).
+ *
+ * @param path
+ * @param logger
+ * @param encoding
+ */
+export const readText = (path, logger, encoding = "utf-8") => {
     logger && logger.debug("reading file:", path);
-    return readFileSync(path, "utf-8");
+    return readFileSync(path, encoding);
 };
 /**
  * Writes `body` as UTF-8 file to given `path`. If `dryRun` is true (default: