@thi.ng/file-io 2.1.37 → 2.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-05-28T12:02:39Z
+- **Last updated**: 2025-07-03T15:03:31Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,16 @@ 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.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/file-io@2.2.0) (2025-07-03)
+
+#### 🚀 Features
+
+- add makedPath() and mask registry fns ([74796f8](https://github.com/thi-ng/umbrella/commit/74796f8))
+- add copyFile() fns (incl. async version) ([19ad5f3](https://github.com/thi-ng/umbrella/commit/19ad5f3))
+- update logging calls to use masked paths only ([c25a2cb](https://github.com/thi-ng/umbrella/commit/c25a2cb))
+- add async versions of various file fns ([eff47b7](https://github.com/thi-ng/umbrella/commit/eff47b7))
+- add deleteFiles() and async versions ([1185911](https://github.com/thi-ng/umbrella/commit/1185911))
+
 ### [2.1.21](https://github.com/thi-ng/umbrella/tree/@thi.ng/file-io@2.1.21) (2025-01-14)
 
 #### ♻️ 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 208 standalone projects, maintained as part
+> This is one of 209 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -15,6 +15,10 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
+- [Available functions](#available-functions)
+  - [Files](#files)
+  - [Directories](#directories)
+  - [Logging](#logging)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -25,12 +29,58 @@
 
 ## About
 
-Assorted file I/O utils (with logging support) for NodeJS/Bun.
+Assorted file I/O utils (w/ 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)
 logging interface.
 
+## Available functions
+
+### Files
+
+- [bufferHash](https://docs.thi.ng/umbrella/file-io/functions/bufferHash.html)
+- [copyFile](https://docs.thi.ng/umbrella/file-io/functions/copyFile.html)
+- [copyFileAsync](https://docs.thi.ng/umbrella/file-io/functions/copyFileAsync.html)
+- [createTempFile](https://docs.thi.ng/umbrella/file-io/functions/createTempFile.html)
+- [deleteFile](https://docs.thi.ng/umbrella/file-io/functions/deleteFile.html)
+- [deleteFileAsync](https://docs.thi.ng/umbrella/file-io/functions/deleteFileAsync.html)
+- [deleteFiles](https://docs.thi.ng/umbrella/file-io/functions/deleteFiles.html)
+- [deleteFilesAsync](https://docs.thi.ng/umbrella/file-io/functions/deleteFilesAsync.html)
+- [files](https://docs.thi.ng/umbrella/file-io/functions/files.html)
+- [fileChunks](https://docs.thi.ng/umbrella/file-io/functions/fileChunks.html)
+- [fileExt](https://docs.thi.ng/umbrella/file-io/functions/fileExt.html)
+- [fileHash](https://docs.thi.ng/umbrella/file-io/functions/fileHash.html)
+- [fileWatcher](https://docs.thi.ng/umbrella/file-io/functions/fileWatcher.html)
+- [readBinary](https://docs.thi.ng/umbrella/file-io/functions/readBinary.html)
+- [readBinaryAsync](https://docs.thi.ng/umbrella/file-io/functions/readBinaryAsync.html)
+- [readJSON](https://docs.thi.ng/umbrella/file-io/functions/readJSON.html)
+- [readJSONAsync](https://docs.thi.ng/umbrella/file-io/functions/readJSONAsync.html)
+- [readText](https://docs.thi.ng/umbrella/file-io/functions/readText.html)
+- [readTextAsync](https://docs.thi.ng/umbrella/file-io/functions/readTextAsync.html)
+- [streamHash](https://docs.thi.ng/umbrella/file-io/functions/streamHash.html)
+- [tempFilePath](https://docs.thi.ng/umbrella/file-io/functions/tempFilePath.html)
+- [writeFile](https://docs.thi.ng/umbrella/file-io/functions/writeFile.html)
+- [writeFileAsync](https://docs.thi.ng/umbrella/file-io/functions/writeFileAsync.html)
+- [writeJSON](https://docs.thi.ng/umbrella/file-io/functions/writeJSON.html)
+- [writeJSONAsync](https://docs.thi.ng/umbrella/file-io/functions/writeJSONAsync.html)
+- [writeText](https://docs.thi.ng/umbrella/file-io/functions/writeText.html)
+- [writeTextAsync](https://docs.thi.ng/umbrella/file-io/functions/writeTextAsync.html)
+
+### Directories
+
+- [deleteDir](https://docs.thi.ng/umbrella/file-io/functions/deleteDir.html)
+- [dirs](https://docs.thi.ng/umbrella/file-io/functions/dirs.html)
+- [ensureDir](https://docs.thi.ng/umbrella/file-io/functions/ensureDir.html)
+- [ensureDirForFile](https://docs.thi.ng/umbrella/file-io/functions/ensureDirForFile.html)
+- [isDirectory](https://docs.thi.ng/umbrella/file-io/functions/isDirectory.html)
+
+### Logging
+
+- [maskedPath](https://docs.thi.ng/umbrella/file-io/functions/maskedPath.html)
+- [addPathMask](https://docs.thi.ng/umbrella/file-io/functions/addPathMask.html)
+- [setPathMasks](https://docs.thi.ng/umbrella/file-io/functions/setPathMasks.html)
+
 ## Status
 
 **STABLE** - used in production
@@ -55,7 +105,7 @@ For Node.js REPL:
 const fio = await import("@thi.ng/file-io");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.05 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.44 KB
 
 ## Dependencies
 

package/copy.d.ts

@@ -0,0 +1,4 @@
+import type { ILogger } from "@thi.ng/logger";
+export declare const copyFile: (src: string, dest: string, logger?: ILogger) => void;
+export declare const copyFileAsync: (src: string, dest: string, logger?: ILogger) => Promise<void>;
+//# sourceMappingURL=copy.d.ts.map

package/copy.js

@@ -0,0 +1,15 @@
+import { copyFileSync } from "node:fs";
+import { copyFile as $copy } from "node:fs/promises";
+import { maskedPath } from "./mask.js";
+const copyFile = (src, dest, logger) => {
+  logger?.debug(maskedPath(`copying file: ${src} \u2192 ${dest}`));
+  copyFileSync(src, dest);
+};
+const copyFileAsync = (src, dest, logger) => {
+  logger?.debug(maskedPath(`copying file: ${src} \u2192 ${dest}`));
+  return $copy(src, dest);
+};
+export {
+  copyFile,
+  copyFileAsync
+};

package/delete.d.ts

@@ -9,6 +9,17 @@ import type { ILogger } from "@thi.ng/logger";
  * @param dryRun
  */
 export declare const deleteFile: (path: string, logger?: ILogger, dryRun?: boolean) => void;
+export declare const deleteFileAsync: (path: string, logger?: ILogger, dryRun?: boolean) => Promise<void>;
+/**
+ * Deletes multiple files via {@link deleteFile}. Any errors are caught and
+ * logged, but ignored otherwise. If `dryRun` is true, files WON'T be deleted.
+ *
+ * @param paths
+ * @param logger
+ * @param dryRun
+ */
+export declare const deleteFiles: (paths: Iterable<string>, logger?: ILogger, dryRun?: boolean) => void;
+export declare const deleteFilesAsync: (paths: Iterable<string>, logger?: ILogger, dryRun?: boolean) => Promise<void>;
 /**
  * Like {@link deleteFile}, but attempts to recursively remove an entire
  * directory at given path.

package/delete.js

@@ -1,15 +1,53 @@
 import { rmSync, unlinkSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { maskedPath } from "./mask.js";
 const deleteFile = (path, logger, dryRun = false) => {
-  logger?.info(`${dryRun ? "[dryrun] " : ""}deleting file: ${path}`);
+  logger?.info(
+    `${dryRun ? "[dryrun] " : ""}deleting file:`,
+    maskedPath(path)
+  );
   if (dryRun) return;
   unlinkSync(path);
 };
+const deleteFileAsync = async (path, logger, dryRun = false) => {
+  logger?.info(
+    `${dryRun ? "[dryrun] " : ""}deleting file:`,
+    maskedPath(path)
+  );
+  if (dryRun) return;
+  return unlink(path);
+};
+const deleteFiles = (paths, logger, dryRun = false) => {
+  for (let path of paths) {
+    try {
+      deleteFile(path, logger, dryRun);
+    } catch (e) {
+      logger?.warn(
+        "error deleting file:",
+        maskedPath(e.message)
+      );
+    }
+  }
+};
+const deleteFilesAsync = async (paths, logger, dryRun = false) => {
+  const promises = [];
+  for (let path of paths) {
+    promises.push(deleteFileAsync(path, logger, dryRun));
+  }
+  await Promise.allSettled(promises);
+};
 const deleteDir = (path, logger, dryRun = false) => {
-  logger?.info(`${dryRun ? "[dryrun] " : ""}deleting file: ${path}`);
+  logger?.info(
+    `${dryRun ? "[dryrun] " : ""}deleting directory:`,
+    maskedPath(path)
+  );
   if (dryRun) return;
   rmSync(path, { recursive: true, force: true });
 };
 export {
   deleteDir,
-  deleteFile
+  deleteFile,
+  deleteFileAsync,
+  deleteFiles,
+  deleteFilesAsync
 };

package/ext.d.ts

@@ -1,5 +1,5 @@
 /**
- * Returns file extension of given file `path`.
+ * Returns file extension (always lowercase) of given file `path`.
  *
  * @param path
  */

package/file-chunks.js

@@ -1,16 +1,18 @@
 import { U32 } from "@thi.ng/hex";
 import { open } from "node:fs/promises";
+import { maskedPath } from "./mask.js";
 async function* fileChunks(path, opts = {}) {
   let { size = 1024, start = 0, end = Infinity, logger } = opts;
-  logger && logger.debug(`start reading file chunks (size: 0x${size}): ${path}`);
+  const mpath = maskedPath(path);
+  logger?.debug(`start reading file chunks (size: 0x${size}):`, mpath);
   let fd = void 0;
   try {
     fd = await open(path, "r");
     while (start < end) {
-      logger && logger.debug(
+      logger?.debug(
         `reading chunk: 0x${U32(start)} - 0x${U32(
           start + size - 1
-        )} (${path})`
+        )} (${mpath})`
       );
       const { buffer, bytesRead } = await fd.read({
         buffer: Buffer.alloc(size),

package/files.js

@@ -2,6 +2,7 @@ import { readdirSync } from "node:fs";
 import { sep } from "node:path";
 import { isDirectory } from "./dir.js";
 import { __ensurePred } from "./internal/ensure.js";
+import { maskedPath } from "./mask.js";
 const files = (dir, match = "", maxDepth = Infinity, logger) => __files(dir, match, logger, maxDepth, 0);
 function* __files(dir, match = "", logger, maxDepth = Infinity, depth = 0) {
   if (depth >= maxDepth) return;
@@ -15,7 +16,7 @@ function* __files(dir, match = "", logger, maxDepth = Infinity, depth = 0) {
         yield curr;
       }
     } catch (e) {
-      logger && logger.warn(`ignoring file: ${f} (${e.message})`);
+      __error(logger, f, e);
     }
   }
 }
@@ -31,10 +32,13 @@ function* __dirs(dir, match = "", logger, maxDepth = Infinity, depth = 0) {
         yield* __dirs(curr, match, logger, maxDepth, depth + 1);
       }
     } catch (e) {
-      logger && logger.warn(`ignoring file/dir: ${f} (${e.message})`);
+      __error(logger, f, e);
     }
   }
 }
+const __error = (logger, path, e) => logger?.warn(
+  `ignoring: ${maskedPath(path)} (${maskedPath(e.message)})`
+);
 export {
   dirs,
   files

package/hash.js

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
+import { maskedPath } from "./mask.js";
 const fileHash = async (path, logger, algo = "sha256") => {
-  logger?.info("reading file:", path);
+  logger?.info("reading file:", maskedPath(path));
   return await streamHash(createReadStream(path), logger, algo);
 };
 const streamHash = async (src, logger, algo = "sha256") => {

package/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./copy.js";
 export * from "./delete.js";
 export * from "./dir.js";
 export * from "./ext.js";

package/index.js

@@ -1,3 +1,4 @@
+export * from "./copy.js";
 export * from "./delete.js";
 export * from "./dir.js";
 export * from "./ext.js";

package/json.d.ts

@@ -1,6 +1,19 @@
 import type { Fn3, Maybe, Nullable, NumOrString } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
+/**
+ * Reads given file as UTF-8 and parses result as JSON of type `T`.
+ *
+ * @param path
+ * @param logger
+ */
 export declare const readJSON: <T = any>(path: string, logger?: ILogger) => T;
+/**
+ * Async version of {@link readJSON}.
+ *
+ * @param path
+ * @param logger
+ */
+export declare const readJSONAsync: <T = any>(path: string, logger?: ILogger) => Promise<T>;
 /**
  * Serializes `obj` to JSON and writes result to UTF-8 file `path`. See
  * {@link writeText} for more details.
@@ -17,4 +30,15 @@ export declare const readJSON: <T = any>(path: string, logger?: ILogger) => T;
  * @param dryRun
  */
 export declare const writeJSON: (path: string, obj: any, replacer?: Fn3<any, string, any, any> | Nullable<NumOrString[]>, space?: Maybe<NumOrString>, logger?: ILogger, dryRun?: boolean) => void;
+/**
+ * Async version of {@link writeJSON}.
+ *
+ * @param path
+ * @param obj
+ * @param replacer
+ * @param space
+ * @param logger
+ * @param dryRun
+ */
+export declare const writeJSONAsync: (path: string, obj: any, replacer?: Fn3<any, string, any, any> | Nullable<NumOrString[]>, space?: Maybe<NumOrString>, logger?: ILogger, dryRun?: boolean) => Promise<void>;
 //# sourceMappingURL=json.d.ts.map

package/json.js

@@ -1,12 +1,21 @@
-import { readText, writeText } from "./text.js";
+import { readText, readTextAsync, writeText, writeTextAsync } from "./text.js";
 const readJSON = (path, logger) => JSON.parse(readText(path, logger));
+const readJSONAsync = async (path, logger) => JSON.parse(await readTextAsync(path, logger));
 const writeJSON = (path, obj, replacer, space, logger, dryRun = false) => writeText(
   path,
   JSON.stringify(obj, replacer, space) + "\n",
   logger,
   dryRun
 );
+const writeJSONAsync = (path, obj, replacer, space, logger, dryRun = false) => writeTextAsync(
+  path,
+  JSON.stringify(obj, replacer, space) + "\n",
+  logger,
+  dryRun
+);
 export {
   readJSON,
-  writeJSON
+  readJSONAsync,
+  writeJSON,
+  writeJSONAsync
 };

package/mask.d.ts

@@ -1,9 +1,51 @@
+/**
+ * Adds given path pattern and its replacement string to registered path masks.
+ *
+ * @remarks
+ * By default only the `$HOME` dir will be masked (if that env var is defined).
+ *
+ * Also see {@link maskedPath} and {@link setPathMasks}.
+ *
+ * @param pattern
+ * @param mask
+ */
+export declare const addPathMask: (pattern: string | RegExp, mask?: string) => void;
+/**
+ * Overrides ALL registered path masks with those given.
+ *
+ * @remarks
+ * Also see {@link maskedPath} and {@link addPathMasks}.
+ *
+ * @param masks
+ */
+export declare const setPathMasks: (masks: [RegExp, string][]) => [RegExp, string][];
+/**
+ * Iteratively applies all registered path masks to given `path` and returns
+ * result.
+ *
+ * @remarks
+ * This function is used by all logging functions in this package. By default
+ * only the `$HOME` dir will be masked (if that env var is defined).
+ *
+ * See {@link addPathMask}, {@link setPathMasks}.
+ *
+ * @example
+ * ```ts
+ * maskedPath("/Users/asterix/foo/bar.txt");
+ * // "~/foo/bar.txt"
+ * ```
+ *
+ * @param path
+ */
+export declare const maskedPath: (path: string) => string;
 /**
  * Replaces `home` (default: `process.env.HOME`) sub-path with given `mask`
- * (default: `~`).
+ * (default: `~`). Used by all path logging calls in this package.
  *
  * @param path
  * @param home
+ *
+ * @deprecated use {@link maskedPath} instead
  */
 export declare const maskHomeDir: (path: string, home?: string | undefined, mask?: string) => string;
 //# sourceMappingURL=mask.d.ts.map

package/mask.js

@@ -1,4 +1,21 @@
+import { isString } from "@thi.ng/checks/is-string";
+let MASKS = [
+  [process.env.HOME ? new RegExp(process.env.HOME, "g") : /~/, "~"]
+];
+const addPathMask = (pattern, mask = "****") => {
+  MASKS.push([isString(pattern) ? new RegExp(pattern, "g") : pattern, mask]);
+};
+const setPathMasks = (masks) => MASKS = masks;
+const maskedPath = (path) => {
+  for (let [re, mask] of MASKS) {
+    path = path.replace(re, mask);
+  }
+  return path;
+};
 const maskHomeDir = (path, home = process.env.HOME, mask = "~") => home ? path.replace(home, mask) : path;
 export {
-  maskHomeDir
+  addPathMask,
+  maskHomeDir,
+  maskedPath,
+  setPathMasks
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/file-io",
-  "version": "2.1.37",
-  "description": "Assorted file I/O utils (with logging support) for NodeJS/Bun",
+  "version": "2.2.0",
+  "description": "Assorted file I/O utils (w/ logging support) for NodeJS/Bun",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -39,11 +39,11 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.28",
-    "@thi.ng/checks": "^3.7.8",
-    "@thi.ng/hex": "^2.3.72",
-    "@thi.ng/logger": "^3.1.9",
-    "@thi.ng/random": "^4.1.19"
+    "@thi.ng/api": "^8.11.29",
+    "@thi.ng/checks": "^3.7.9",
+    "@thi.ng/hex": "^2.3.73",
+    "@thi.ng/logger": "^3.1.10",
+    "@thi.ng/random": "^4.1.20"
   },
   "devDependencies": {
     "@types/node": "^22.15.21",
@@ -53,14 +53,19 @@
   },
   "keywords": [
     "async",
+    "delete",
+    "directory",
     "file",
     "hash",
+    "iterator",
     "json",
     "logger",
     "no-browser",
     "nodejs",
     "stream",
-    "typescript"
+    "text",
+    "typescript",
+    "watch"
   ],
   "publishConfig": {
     "access": "public"
@@ -81,6 +86,9 @@
     ".": {
       "default": "./index.js"
     },
+    "./copy": {
+      "default": "./copy.js"
+    },
     "./delete": {
       "default": "./delete.js"
     },
@@ -126,5 +134,5 @@
     "status": "stable",
     "year": 2022
   },
-  "gitHead": "61c3833b7ef7d044621454b5ea4af885d39f065e\n"
+  "gitHead": "06e582f962a9cd3abb905e91d97d652e1d3bb971\n"
 }

package/read.d.ts

@@ -6,4 +6,11 @@ import type { ILogger } from "@thi.ng/logger";
  * @param logger
  */
 export declare const readBinary: (path: string, logger?: ILogger) => Uint8Array<ArrayBuffer>;
+/**
+ * Async version of {@link readBinary}.
+ *
+ * @param path
+ * @param logger
+ */
+export declare const readBinaryAsync: (path: string, logger?: ILogger) => Promise<Uint8Array<ArrayBufferLike>>;
 //# sourceMappingURL=read.d.ts.map

package/read.js

@@ -1,9 +1,17 @@
 import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { maskedPath } from "./mask.js";
 const readBinary = (path, logger) => {
-  logger?.debug("reading file:", path);
+  logger?.debug("reading file:", maskedPath(path));
   const buf = readFileSync(path);
   return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
 };
+const readBinaryAsync = async (path, logger) => {
+  logger?.debug("reading file:", maskedPath(path));
+  const buf = await readFile(path);
+  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+};
 export {
-  readBinary
+  readBinary,
+  readBinaryAsync
 };

package/temp.d.ts

@@ -17,7 +17,7 @@ export declare const createTempFile: (body: string | TypedArray, logger?: ILogge
  *
  * @remarks
  * If no `name` is given, constructs a random filename of `tmp-XXX` (16 random
- * chars).
+ * chars). Default extension is an empty string.
  *
  * @param name
  * @param ext

package/temp.js

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

package/text.d.ts

@@ -8,6 +8,14 @@ import type { ILogger } from "@thi.ng/logger";
  * @param encoding
  */
 export declare const readText: (path: string, logger?: ILogger, encoding?: Extract<BufferEncoding, "ascii" | "latin1" | "utf-8" | "utf-16le" | "ucs-2">) => string;
+/**
+ * Async version of {@link readText}.
+ *
+ * @param path
+ * @param logger
+ * @param encoding
+ */
+export declare const readTextAsync: (path: string, logger?: ILogger, encoding?: Extract<BufferEncoding, "ascii" | "latin1" | "utf-8" | "utf-16le" | "ucs-2">) => Promise<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
@@ -19,4 +27,13 @@ export declare const readText: (path: string, logger?: ILogger, encoding?: Extra
  * @param dryRun
  */
 export declare const writeText: (path: string, body: string | string[], logger?: ILogger, dryRun?: boolean) => void;
+/**
+ * Async version of {@link writeText}.
+ *
+ * @param path
+ * @param body
+ * @param logger
+ * @param dryRun
+ */
+export declare const writeTextAsync: (path: string, body: string | string[], logger?: ILogger, dryRun?: boolean) => Promise<void>;
 //# sourceMappingURL=text.d.ts.map

package/text.js

@@ -1,10 +1,16 @@
 import { isArray } from "@thi.ng/checks/is-array";
 import { readFileSync } from "node:fs";
-import { writeFile } from "./write.js";
+import { readFile } from "node:fs/promises";
+import { maskedPath } from "./mask.js";
+import { writeFile, writeFileAsync } from "./write.js";
 const readText = (path, logger, encoding = "utf-8") => {
-  logger?.debug("reading file:", path);
+  logger?.debug("reading file:", maskedPath(path));
   return readFileSync(path, encoding);
 };
+const readTextAsync = (path, logger, encoding = "utf-8") => {
+  logger?.debug("reading file:", maskedPath(path));
+  return readFile(path, encoding);
+};
 const writeText = (path, body, logger, dryRun = false) => writeFile(
   path,
   isArray(body) ? body.join("\n") : body,
@@ -12,7 +18,16 @@ const writeText = (path, body, logger, dryRun = false) => writeFile(
   logger,
   dryRun
 );
+const writeTextAsync = (path, body, logger, dryRun = false) => writeFileAsync(
+  path,
+  isArray(body) ? body.join("\n") : body,
+  "utf-8",
+  logger,
+  dryRun
+);
 export {
   readText,
-  writeText
+  readTextAsync,
+  writeText,
+  writeTextAsync
 };

package/watch.d.ts

@@ -44,5 +44,10 @@ export declare class Watcher implements IClear, INotify {
     removeListener(id: string, fn: Listener<string>, scope?: any): boolean;
     notify(event: Event<string>): boolean;
 }
+/**
+ * Creates a new {@link Watcher} instance with given options.
+ *
+ * @param opts
+ */
 export declare const fileWatcher: (opts?: Partial<WatcherOpts>) => Watcher;
 //# sourceMappingURL=watch.d.ts.map

package/watch.js

@@ -13,10 +13,11 @@ import {
 } from "@thi.ng/api";
 import { isString } from "@thi.ng/checks/is-string";
 import { NULL_LOGGER } from "@thi.ng/logger/null";
-import { watch as $watch, existsSync } from "node:fs";
+import { existsSync, watch } from "node:fs";
 import { join } from "node:path";
 import { isDirectory } from "./dir.js";
 import { __ensurePred } from "./internal/ensure.js";
+import { maskedPath } from "./mask.js";
 const EVENT_ADDED = "added";
 const EVENT_CHANGED = "changed";
 const EVENT_REMOVED = "removed";
@@ -40,8 +41,8 @@ let Watcher = class {
     if (this.watchers[path]) return false;
     const isDir = isDirectory(path);
     const pred = __ensurePred(opts?.ext || "");
-    this.opts.logger.debug(`adding watcher for: ${path}`);
-    this.watchers[path] = $watch(
+    this.opts.logger.debug(`adding watcher for:`, maskedPath(path));
+    this.watchers[path] = watch(
       path,
       { recursive: opts?.recursive !== false },
       (event, currPath) => {
@@ -49,19 +50,20 @@ let Watcher = class {
         currPath = isDir ? join(path, currPath) : path;
         if (!pred(currPath)) return;
         setTimeout(() => {
+          const mpath = maskedPath(currPath);
           if (event === "change") {
-            this.opts.logger.info(`file changed: ${currPath}`);
+            this.opts.logger.info(`file changed: ${mpath}`);
             this.notify({
               id: EVENT_CHANGED,
               value: currPath
             });
           } else if (!isDir || path === currPath) {
-            this.opts.logger.info(`file removed: ${path}`);
+            this.opts.logger.info(`file removed: ${mpath}`);
             this.notify({ id: EVENT_REMOVED, value: path });
             this.remove(path);
           } else {
             const id = existsSync(currPath) ? EVENT_ADDED : EVENT_REMOVED;
-            this.opts.logger.info(`file ${id}: ${path}`);
+            this.opts.logger.info(`file ${id}: ${mpath}`);
             this.notify({ id, value: currPath });
           }
         }, this.opts.delay);
@@ -72,7 +74,7 @@ let Watcher = class {
   remove(path) {
     const watcher = this.watchers[path];
     if (!watcher) return false;
-    this.opts.logger.debug(`removing watcher for: ${path}`);
+    this.opts.logger.debug(`removing watcher for:`, maskedPath(path));
     watcher.close();
     delete this.watchers[path];
     return true;

package/write.d.ts

@@ -13,4 +13,14 @@ import { type WriteFileOptions } from "node:fs";
  * @param dryRun
  */
 export declare const writeFile: (path: string, body: string | TypedArray, opts?: WriteFileOptions, logger?: ILogger, dryRun?: boolean) => void;
+/**
+ * Async version of {@link writeFile}.
+ *
+ * @param path
+ * @param body
+ * @param opts
+ * @param logger
+ * @param dryRun
+ */
+export declare const writeFileAsync: (path: string, body: string | TypedArray, opts?: WriteFileOptions, logger?: ILogger, dryRun?: boolean) => Promise<void>;
 //# sourceMappingURL=write.d.ts.map

package/write.js

@@ -1,12 +1,19 @@
 import { isString } from "@thi.ng/checks/is-string";
 import { writeFileSync } from "node:fs";
+import { writeFile as writeAsync } from "node:fs/promises";
 import { ensureDirForFile } from "./dir.js";
-const writeFile = (path, body, opts, logger, dryRun = false) => {
-  logger?.info(`${dryRun ? "[dryrun] " : ""}writing file: ${path}`);
+import { maskedPath } from "./mask.js";
+const writeFile = (path, body, opts, logger, dryRun = false) => __write(writeFileSync, path, body, opts, logger, dryRun);
+const writeFileAsync = (path, body, opts, logger, dryRun = false) => __write(writeAsync, path, body, opts, logger, dryRun);
+const __write = (writeFn, path, body, opts, logger, dryRun = false) => {
+  logger?.info(
+    `${dryRun ? "[dryrun] " : ""}writing file: ${maskedPath(path)}`
+  );
   if (dryRun) return;
   ensureDirForFile(path);
-  writeFileSync(path, body, !opts && isString(body) ? "utf-8" : opts);
+  return writeFn(path, body, !opts && isString(body) ? "utf-8" : opts);
 };
 export {
-  writeFile
+  writeFile,
+  writeFileAsync
 };