@thi.ng/file-io - npm Package Compare versions

Comparing version 1.3.12 to 2.0.0

CHANGELOG.md

 # Change Log
 
-- **Last updated**: 2024-03-27T09:53:45Z
+- **Last updated**: 2024-03-29T12:16:20Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
@@ -12,2 +12,14 @@
 
+# [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)
@@ -14,0 +26,0 @@

hash.d.ts

@@ -0,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

hash.js

 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.json

 {
   "name": "@thi.ng/file-io",
-  "version": "1.3.12",
-  "description": "Assorted file I/O utils (with logging support) for NodeJS",
+  "version": "2.0.0",
+  "description": "Assorted file I/O utils (with logging support) for NodeJS/Bun",
   "type": "module",
@@ -53,2 +53,3 @@ "module": "./index.js",
   "keywords": [
+    "async",
     "file",
@@ -59,2 +60,3 @@ "hash",
     "nodejs",
+    "stream",
     "no-browser",
@@ -126,3 +128,3 @@ "typescript"
   },
-  "gitHead": "feb3b24654f2c931cd3c3308c1c0c807ee14d0e4\n"
+  "gitHead": "ce5ae2a322d50a7ce8ecccbd94fa55c496ba04fd\n"
 }

README.md

@@ -27,3 +27,3 @@ <!-- This file is generated - DO NOT EDIT! -->
 
-Assorted file I/O utils (with logging support) for NodeJS.
+Assorted file I/O utils (with logging support) for NodeJS/Bun.
 
@@ -52,3 +52,3 @@ Most functions in this package have optional support for the
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.99 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.04 KB
 
@@ -55,0 +55,0 @@ ## Dependencies

temp.d.ts

 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

temp.js

@@ -7,4 +7,4 @@ import { isString } from "@thi.ng/checks/is-string";
 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);
@@ -15,3 +15,3 @@ ensureDirForFile(path);
 };
-const tempFilePath = (name) => realpathSync(tmpdir()) + sep + (name || randomID(16, "tmp-"));
+const tempFilePath = (name, ext = "") => realpathSync(tmpdir()) + sep + (name || randomID(16, "tmp-")) + ext;
 export {
@@ -18,0 +18,0 @@ createTempFile,

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

42046

increased by5.55%

Lines of code

654

increased by9.55%

No dependency changes