@thi.ng/file-io 1.3.12 → 2.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-27T09:53:45Z
+- **Last updated**: 2024-04-08T14:59:29Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,18 @@ 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.
 
+# [2.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/file-io@2.0.0) (2024-03-29)
+
+#### 🛑 Breaking changes
+
+- add `streamHash()`, update other hashing fns ([64a8cad](https://github.com/thi-ng/umbrella/commit/64a8cad))
+- BREAKING CHANGE: `fileHash()` now async, rename `stringHash()` => `bufferHash()`
+
+#### 🚀 Features
+
+- update args for `createTempFile()` & `tempFilePath()` ([d944789](https://github.com/thi-ng/umbrella/commit/d944789))
+  - add docstrings
+
 ### [1.3.3](https://github.com/thi-ng/umbrella/tree/@thi.ng/file-io@1.3.3) (2024-02-22)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 190 standalone projects, maintained as part
+> This is one of 191 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -24,7 +24,7 @@
 
 ## About
 
-Assorted file I/O utils (with logging support) for NodeJS.
+Assorted file I/O utils (with logging support) for NodeJS/Bun.
 
 Most functions in this package have optional support for the
 [`ILogger`](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
@@ -42,13 +42,19 @@ logging interface.
 yarn add @thi.ng/file-io
 ```
 
+ESM import:
+
+```ts
+import * as fio from "@thi.ng/file-io";
+```
+
 For Node.js REPL:
 
 ```js
-const fileIo = await import("@thi.ng/file-io");
+const fio = await import("@thi.ng/file-io");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.99 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.04 KB
 
 ## Dependencies
 

package/hash.d.ts

@@ -1,5 +1,37 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import type { TypedArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
+import type { Readable } from "node:stream";
 export type HashAlgo = "gost-mac" | "md4" | "md5" | "md_gost94" | "ripemd160" | "sha1" | "sha224" | "sha256" | "sha384" | "sha512" | "streebog256" | "streebog512" | "whirlpool";
-export declare const fileHash: (path: string, logger?: ILogger, algo?: HashAlgo) => string;
-export declare const stringHash: (src: string, logger?: ILogger, algo?: HashAlgo) => string;
+/**
+ * Creates a readable stream for given file and computes its hash digest using
+ * {@link streamHash}.
+ *
+ * @param path
+ * @param logger
+ * @param algo
+ */
+export declare const fileHash: (path: string, logger?: ILogger, algo?: HashAlgo) => Promise<string>;
+/**
+ * Computes hash digest from given stream using chosen hash algorithm (default:
+ * "sha256"). If `logger` is given, the hash will be logged too.
+ *
+ * @remarks
+ * Also see {@link fileHash} and {@link stringHash}.
+ *
+ * @param src
+ * @param logger
+ * @param algo
+ */
+export declare const streamHash: (src: Readable, logger?: ILogger, algo?: HashAlgo) => Promise<string>;
+/**
+ * Computes hash digest from given string or buffer using chosen hash algorithm
+ * (default: "sha256"). If `logger` is given, the hash will be logged too.
+ *
+ * @param src
+ * @param logger
+ * @param algo
+ */
+export declare const bufferHash: (src: TypedArray | Buffer | DataView | string, logger?: ILogger, algo?: HashAlgo) => string;
 //# sourceMappingURL=hash.d.ts.map

package/hash.js

@@ -1,20 +1,24 @@
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-const fileHash = (path, logger, algo = "sha256") => {
+import { createReadStream } from "node:fs";
+const fileHash = async (path, logger, algo = "sha256") => {
+  logger && logger.info("reading file:", path);
+  return await streamHash(createReadStream(path), logger, algo);
+};
+const streamHash = async (src, logger, algo = "sha256") => {
   const sum = createHash(algo);
-  sum.update(readFileSync(path));
+  for await (let chunk of src)
+    sum.update(chunk);
   const hash = sum.digest("hex");
-  logger && logger.info(`${algo} hash for ${path}: ${hash}`);
+  logger && logger.info(`${algo} hash: ${hash}`);
   return hash;
 };
-const stringHash = (src, logger, algo = "sha256") => {
-  const sum = createHash(algo);
-  sum.update(src);
-  const hash = sum.digest("hex");
-  logger && logger.info(`${algo} hash for string: ${hash}`);
+const bufferHash = (src, logger, algo = "sha256") => {
+  const hash = createHash(algo).update(src).digest("hex");
+  logger && logger.info(`${algo} hash: ${hash}`);
   return hash;
 };
 export {
+  bufferHash,
   fileHash,
-  stringHash
+  streamHash
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/file-io",
-  "version": "1.3.12",
-  "description": "Assorted file I/O utils (with logging support) for NodeJS",
+  "version": "2.0.1",
+  "description": "Assorted file I/O utils (with logging support) for NodeJS/Bun",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -36,11 +36,11 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.31",
-    "@thi.ng/checks": "^3.5.5",
-    "@thi.ng/hex": "^2.3.41",
-    "@thi.ng/logger": "^3.0.7",
-    "@thi.ng/random": "^3.7.1"
+    "@thi.ng/api": "^8.10.0",
+    "@thi.ng/checks": "^3.6.0",
+    "@thi.ng/hex": "^2.3.42",
+    "@thi.ng/logger": "^3.0.8",
+    "@thi.ng/random": "^3.7.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.43.0",
@@ -50,11 +50,13 @@
     "typescript": "^5.4.3"
   },
   "keywords": [
+    "async",
     "file",
     "hash",
     "json",
     "logger",
     "nodejs",
+    "stream",
     "no-browser",
     "typescript"
   ],
@@ -118,8 +120,9 @@
     }
   },
   "thi.ng": {
+    "alias": "fio",
     "status": "stable",
     "year": 2022
   },
-  "gitHead": "feb3b24654f2c931cd3c3308c1c0c807ee14d0e4\n"
+  "gitHead": "85ac4bd4d6d89f8e3689e2863d5bea0cecdb371c\n"
 }

package/temp.d.ts

@@ -1,5 +1,26 @@
 import type { TypedArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-export declare const createTempFile: (body: string | TypedArray, logger?: ILogger, name?: string) => string;
-export declare const tempFilePath: (name?: string) => string;
+/**
+ * Constructs a temp file path using {@link tempFilePath} and writes `body` to
+ * this path, then returns path. If `name` is given and contains
+ * sub-directories, they will be created automatically.
+ *
+ * @param body
+ * @param logger
+ * @param name
+ * @param ext
+ */
+export declare const createTempFile: (body: string | TypedArray, logger?: ILogger, name?: string, ext?: string) => string;
+/**
+ * Constructs a file path in the system-defined temp directory, optionally using
+ * provided basename and/or file extension.
+ *
+ * @remarks
+ * If no `name` is given, constructs a random filename of `tmp-XXX` (16 random
+ * chars).
+ *
+ * @param name
+ * @param ext
+ */
+export declare const tempFilePath: (name?: string, ext?: string) => string;
 //# sourceMappingURL=temp.d.ts.map

package/temp.js

@@ -4,14 +4,14 @@ import { realpathSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { sep } from "node:path";
 import { ensureDirForFile } from "./dir.js";
-const createTempFile = (body, logger, name) => {
-  const path = tempFilePath(name);
+const createTempFile = (body, logger, name, ext) => {
+  const path = tempFilePath(name, ext);
   logger && logger.debug("creating temp file:", path);
   ensureDirForFile(path);
   writeFileSync(path, body, isString(body) ? "utf-8" : void 0);
   return path;
 };
-const tempFilePath = (name) => realpathSync(tmpdir()) + sep + (name || randomID(16, "tmp-"));
+const tempFilePath = (name, ext = "") => realpathSync(tmpdir()) + sep + (name || randomID(16, "tmp-")) + ext;
 export {
   createTempFile,
   tempFilePath