@thi.ng/file-io 0.2.0 → 0.3.2

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-05-19T13:17:54Z
+- **Last updated**: 2022-06-09T16:14:01Z
 - **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.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/file-io@0.3.0) (2022-05-20)
+
+#### 🚀 Features
+
+- add more fns (hashing, masking etc.) ([95b9e2b](https://github.com/thi-ng/umbrella/commit/95b9e2b))
+  - add fileHash(), stringHash()
+  - add maskHomeDir()
+  - add fileExt(), isDirectory()
+
+#### 🩹 Bug fixes
+
+- fix ensureDir() for local file paths ([4ae95c2](https://github.com/thi-ng/umbrella/commit/4ae95c2))
+
 ## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/file-io@0.2.0) (2022-05-19)
 
 #### 🚀 Features

package/delete.d.ts

@@ -8,5 +8,5 @@ import type { ILogger } from "@thi.ng/logger";
  * @param logger
  * @param dryRun
  */
-export declare const deleteFile: (path: string, logger?: ILogger | undefined, dryRun?: boolean) => void;
+export declare const deleteFile: (path: string, logger?: ILogger, dryRun?: boolean) => void;
 //# sourceMappingURL=delete.d.ts.map

package/dir.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Checks if the directory for given file `path` already exists, and if not the
+ * case, creates it. Returns true if the latter case.
+ *
+ * @remarks
+ * If `path` only contains a filename (without any directory structure), the
+ * function does nothing.
+ *
+ * @param path
+ */
+export declare const ensureDirForFile: (path: string) => boolean;
+/**
+ * Returns true if `path` is a directory (assumes path exists).
+ *
+ * @param path
+ */
+export declare const isDirectory: (path: string) => boolean;
+//# sourceMappingURL=dir.d.ts.map

package/dir.js

@@ -0,0 +1,24 @@
+import { existsSync, mkdirSync, statSync } from "fs";
+import { sep } from "path";
+/**
+ * Checks if the directory for given file `path` already exists, and if not the
+ * case, creates it. Returns true if the latter case.
+ *
+ * @remarks
+ * If `path` only contains a filename (without any directory structure), the
+ * function does nothing.
+ *
+ * @param path
+ */
+export const ensureDirForFile = (path) => {
+    const dir = path.substring(0, path.lastIndexOf(sep));
+    return dir.length > 0 && !existsSync(dir)
+        ? (mkdirSync(dir, { recursive: true }), true)
+        : false;
+};
+/**
+ * Returns true if `path` is a directory (assumes path exists).
+ *
+ * @param path
+ */
+export const isDirectory = (path) => statSync(path).isDirectory();

package/ext.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns file extension of given file `path`.
+ *
+ * @param path
+ */
+export declare const fileExt: (path: string) => string;
+//# sourceMappingURL=ext.d.ts.map

package/ext.js

@@ -0,0 +1,9 @@
+/**
+ * Returns file extension of given file `path`.
+ *
+ * @param path
+ */
+export const fileExt = (path) => {
+    const match = /\.(\w+)$/.exec(path);
+    return match ? match[1].toLowerCase() : "";
+};

package/files.d.ts

@@ -15,7 +15,7 @@ import type { ILogger } from "@thi.ng/logger";
  * @param maxDepth
  * @param logger
  */
-export declare const files: (dir: string, match?: string | RegExp, maxDepth?: number, logger?: ILogger | undefined) => IterableIterator<string>;
+export declare const files: (dir: string, match?: string | RegExp, maxDepth?: number, logger?: ILogger) => IterableIterator<string>;
 /**
  * Similar to {@link files}, however yields iterator of only matching
  * sub-directories in given `dir`. Normal files are being ignored.
@@ -29,5 +29,5 @@ export declare const files: (dir: string, match?: string | RegExp, maxDepth?: nu
  * @param maxDepth
  * @param logger
  */
-export declare const dirs: (dir: string, match?: string | RegExp, maxDepth?: number, logger?: ILogger | undefined) => IterableIterator<string>;
+export declare const dirs: (dir: string, match?: string | RegExp, maxDepth?: number, logger?: ILogger) => IterableIterator<string>;
 //# sourceMappingURL=files.d.ts.map

package/files.js

@@ -1,6 +1,7 @@
 import { isString } from "@thi.ng/checks/is-string";
 import { readdirSync, statSync } from "fs";
 import { sep } from "path";
+import { isDirectory } from "./dir.js";
 /**
  * Recursively reads given directory (up to given max. depth, default: infinite)
  * and yields sequence of file names matching given extension (or regexp).
@@ -25,7 +26,7 @@ function* __files(dir, match = "", logger, maxDepth = Infinity, depth = 0) {
     for (let f of readdirSync(dir)) {
         const curr = dir + sep + f;
         try {
-            if (statSync(curr).isDirectory()) {
+            if (isDirectory(curr)) {
                 yield* __files(curr, match, logger, maxDepth, depth + 1);
             }
             else if (re.test(f)) {

package/hash.d.ts

@@ -0,0 +1,5 @@
+import type { ILogger } from "@thi.ng/logger";
+export declare 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;
+//# sourceMappingURL=hash.d.ts.map

package/hash.js

@@ -0,0 +1,16 @@
+import { createHash } from "crypto";
+import { readFileSync } from "fs";
+export const fileHash = (path, logger, algo = "sha256") => {
+    const sum = createHash(algo);
+    sum.update(readFileSync(path));
+    const hash = sum.digest("hex");
+    logger && logger.info(`${algo} hash for ${path}: ${hash}`);
+    return hash;
+};
+export 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}`);
+    return hash;
+};

package/index.d.ts

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

package/index.js

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

package/json.d.ts

@@ -1,6 +1,6 @@
 import type { Fn3, NumOrString } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-export declare const readJSON: (path: string, logger?: ILogger | undefined) => any;
+export declare const readJSON: (path: string, logger?: ILogger) => any;
 /**
  * Serializes `obj` to JSON and writes result to UTF-8 file `path`. See
  * {@link writeText} for more details.
@@ -16,5 +16,5 @@ export declare const readJSON: (path: string, logger?: ILogger | undefined) => a
  * @param logger
  * @param dryRun
  */
-export declare const writeJSON: (path: string, obj: any, replacer?: Fn3<any, string, any, any> | NumOrString[] | null | undefined, space?: NumOrString | undefined, logger?: ILogger | undefined, dryRun?: boolean) => void;
+export declare const writeJSON: (path: string, obj: any, replacer?: Fn3<any, string, any, any> | NumOrString[] | null | undefined, space?: NumOrString | undefined, logger?: ILogger, dryRun?: boolean) => void;
 //# sourceMappingURL=json.d.ts.map

package/mask.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Replaces `home` (default: `process.env.HOME`) sub-path with given `mask`
+ * (default: `~`).
+ *
+ * @param path
+ * @param home
+ */
+export declare const maskHomeDir: (path: string, home?: string | undefined, mask?: string) => string;
+//# sourceMappingURL=mask.d.ts.map

package/mask.js

@@ -0,0 +1,8 @@
+/**
+ * Replaces `home` (default: `process.env.HOME`) sub-path with given `mask`
+ * (default: `~`).
+ *
+ * @param path
+ * @param home
+ */
+export const maskHomeDir = (path, home = process.env.HOME, mask = "~") => (home ? path.replace(home, mask) : path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/file-io",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "Assorted file I/O utils (with logging support) for NodeJS",
   "type": "module",
   "module": "./index.js",
@@ -34,21 +34,24 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.3.6",
-    "@thi.ng/checks": "^3.1.6",
-    "@thi.ng/logger": "^1.1.6",
-    "@thi.ng/random": "^3.2.6"
+    "@thi.ng/api": "^8.3.7",
+    "@thi.ng/checks": "^3.2.0",
+    "@thi.ng/logger": "^1.1.7",
+    "@thi.ng/random": "^3.3.1"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.23.1",
-    "@thi.ng/testament": "^0.2.6",
+    "@microsoft/api-extractor": "^7.25.0",
+    "@thi.ng/testament": "^0.2.8",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.22.15",
-    "typescript": "^4.6.4"
+    "typedoc": "^0.22.17",
+    "typescript": "^4.7.3"
   },
   "keywords": [
     "file",
+    "hash",
+    "json",
+    "logger",
     "node-only",
     "typescript"
   ],
@@ -73,15 +76,24 @@
     "./delete": {
       "default": "./delete.js"
     },
-    "./ensure-dir": {
-      "default": "./ensure-dir.js"
+    "./dir": {
+      "default": "./dir.js"
+    },
+    "./ext": {
+      "default": "./ext.js"
     },
     "./files": {
       "default": "./files.js"
     },
+    "./hash": {
+      "default": "./hash.js"
+    },
     "./json": {
       "default": "./json.js"
     },
+    "./mask": {
+      "default": "./mask.js"
+    },
     "./temp": {
       "default": "./temp.js"
     },
@@ -96,5 +108,5 @@
     "status": "stable",
     "year": 2022
   },
-  "gitHead": "ec1685021284dc0e98bbfe67abefc3d1f6c0f7dd\n"
+  "gitHead": "9e516d30a1a537e027a6b3d78bf9121bc5831d31\n"
 }

package/temp.d.ts

@@ -1,5 +1,5 @@
 import type { TypedArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-export declare const createTempFile: (body: string | TypedArray, logger?: ILogger | undefined, name?: string | undefined) => string;
-export declare const tempFilePath: (name?: string | undefined) => string;
+export declare const createTempFile: (body: string | TypedArray, logger?: ILogger, name?: string) => string;
+export declare const tempFilePath: (name?: string) => string;
 //# sourceMappingURL=temp.d.ts.map

package/temp.js

@@ -3,7 +3,7 @@ import { randomID } from "@thi.ng/random/random-id";
 import { realpathSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { sep } from "path";
-import { ensureDirForFile } from "./ensure-dir.js";
+import { ensureDirForFile } from "./dir.js";
 export const createTempFile = (body, logger, name) => {
     const path = tempFilePath(name);
     logger && logger.debug("creating temp file:", path);

package/text.d.ts

@@ -1,5 +1,5 @@
 import type { ILogger } from "@thi.ng/logger";
-export declare const readText: (path: string, logger?: ILogger | undefined) => string;
+export declare const readText: (path: string, logger?: ILogger) => 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
@@ -10,5 +10,5 @@ export declare const readText: (path: string, logger?: ILogger | undefined) => s
  * @param logger
  * @param dryRun
  */
-export declare const writeText: (path: string, body: string | string[], logger?: ILogger | undefined, dryRun?: boolean) => void;
+export declare const writeText: (path: string, body: string | string[], logger?: ILogger, dryRun?: boolean) => void;
 //# sourceMappingURL=text.d.ts.map

package/write.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import type { TypedArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import { WriteFileOptions } from "fs";
@@ -13,5 +12,5 @@ import { WriteFileOptions } from "fs";
  * @param logger
  * @param dryRun
  */
-export declare const writeFile: (path: string, body: string | TypedArray, opts?: WriteFileOptions | undefined, logger?: ILogger | undefined, dryRun?: boolean) => void;
+export declare const writeFile: (path: string, body: string | TypedArray, opts?: WriteFileOptions, logger?: ILogger, dryRun?: boolean) => void;
 //# sourceMappingURL=write.d.ts.map

package/write.js

@@ -1,6 +1,6 @@
 import { isString } from "@thi.ng/checks/is-string";
 import { writeFileSync } from "fs";
-import { ensureDirForFile } from "./ensure-dir.js";
+import { ensureDirForFile } from "./dir.js";
 /**
  * Writes `body` as to given `path` (using optional `opts` to define encoding).
  * If `dryRun` is true (default: false), the file WON'T be written, however if a

package/ensure-dir.d.ts

@@ -1,8 +0,0 @@
-/**
- * Checks if the directory for given file path already exists, and if not the
- * case, creates it. Returns true if the latter case.
- *
- * @param path
- */
-export declare const ensureDirForFile: (path: string) => boolean;
-//# sourceMappingURL=ensure-dir.d.ts.map

package/ensure-dir.js

@@ -1,14 +0,0 @@
-import { existsSync, mkdirSync } from "fs";
-import { sep } from "path";
-/**
- * Checks if the directory for given file path already exists, and if not the
- * case, creates it. Returns true if the latter case.
- *
- * @param path
- */
-export const ensureDirForFile = (path) => {
-    const dir = path.substring(0, path.lastIndexOf(sep));
-    return !existsSync(dir)
-        ? (mkdirSync(dir, { recursive: true }), true)
-        : false;
-};