@stonyx/logs 1.0.1-beta.20 → 1.0.1-beta.21

package/README.md

@@ -153,16 +153,65 @@ These methods can then be called in your application with [logging parameters](#
 
 Color settings are handled by determining whether your input is a color name or a hex value (prefixed with **#**). For example, passing `red` as a color setting will utilize `chalk.red`, while passing `#ff0000` would use `chalk.hex('#ff0000')` instead. A [list of available colors](https://github.com/chalk/chalk#colors) can be found in chalks' documentation.
 
-Additionally, these methods return a promise when `logToFile` is true, allowing you use them with `await` in an async method, or append `then(), catch(), or finally()` for more advanced callback usage.
+Additionally, these methods return a promise when `logToFile` is true. That promise rejecting is the only signal that a write failed, so you must either `await` the call or attach a `.catch()` — see [File Write Failures](#file-write-failures). `then()` and `finally()` are also available.
 
 ```js
 async method() {
-  await log.error('error message', true);
+  try {
+    await log.error('error message', true);
 
-  // do something after logs/error.log (default) is created
+    // do something after logs/error.log (default) is created
+  } catch (err) {
+    // the write failed; the rejection is the only notice you get
+    process.stderr.write(`log write failed: ${err.code}\n`);
+  }
 }
 ```
 
+#### File Write Failures
+
+When `logToFile` is true, **the returned promise rejecting is the only failure signal.** The log
+line itself is still written to the console as usual, but **no error notice is printed** and no
+fallback log is written when the log directory or file cannot be written: the underlying `fs` error
+is propagated to the caller with its `code` intact (`ENOENT`, `ENOTDIR`, `EACCES`, `EPERM`,
+`EROFS`, ...).
+
+A fire-and-forget call therefore produces an **unhandled promise rejection** on a failed write.
+Always `await` the call (or attach a `.catch()`) anywhere file logging is enabled:
+
+```js
+// unhandled rejection if the log directory is not writable
+log.error('error message', true);
+
+// handled
+log.error('error message', true).catch(err => process.stderr.write(`log write failed: ${err.code}\n`));
+```
+
+A failed write is retried exactly once, and only for the two codes that recreating the log directory
+can repair: `ENOENT` (the directory was removed at runtime) and `ENOTDIR` (a path component was
+replaced by a non-directory). The directory cache entry is dropped, the directory is recreated, and
+the write is reattempted once before the rejection surfaces. If the recreate itself fails, that
+error is what surfaces.
+
+Every other code — including `EACCES`, `EPERM` and `EROFS` — rejects immediately with no retry,
+because `mkdir` on an existing directory is a successful no-op: it cannot change a permission bit or
+a read-only mount, so a retry could only ever repeat the same failure at twice the syscall cost.
+
+##### The directory cache
+
+To keep the write path free of repeated `mkdir` calls, each `Log` instance exposes a
+`directoryCache` field: a `Map` keyed on the resolved directory (not on the target filename), whose
+values are the in-flight or settled `mkdir` promises. It is **instance-scoped, not module-scoped** —
+two `Log` instances pointing at the same directory each call `mkdir` once. Entries are **never
+evicted on success**, so a directory is created at most once per instance for the process lifetime;
+entries are dropped only when the `mkdir` rejects, or when a write fails with a retryable code and
+the directory is recreated.
+
+It is public only because the class carries an index signature, and it is not part of the supported
+API: treat it as read-only, since mutating it corrupts the write path. Note also that the name is
+reserved — a log type called `directoryCache` is silently skipped rather than overwriting the cache,
+so no convenience method is generated for it.
+
 ### The Debug Method
 
 **Log** allows for the `log.debug()` method to be overridden by a color setting. However, by default we do not define a color for debug and debug is handled differently. For console logging, all **debug** does is output the following:

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export default class Log {
     options: LogOptions;
     color: Color;
     typeOptions: Record<string, Partial<LogOptions>>;
+    directoryCache: Map<string, Promise<void>>;
     [key: string]: unknown;
     info: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;
     warn: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { mkdirSync, promises as fsp } from 'fs';
+import { promises as fsp } from 'fs';
 import { fileURLToPath } from 'url';
 import { hostname } from 'os';
 import projectPath from 'path';
@@ -19,10 +19,29 @@ const defaultOptions = {
 };
 // used to sanitize defineType() options input
 const optionKeys = Object.keys(defaultOptions);
+/*
+ * Write failures that a recursive mkdir of the log directory can actually repair:
+ * ENOENT (the cached directory was removed at runtime) and ENOTDIR (a path component
+ * was replaced by a non-directory). These invalidate the directory cache and are
+ * retried once.
+ *
+ * Permission and mount faults (EACCES, EPERM, EROFS) are deliberately excluded: the
+ * retry's only remediation is mkdir(recursive), which is a successful no-op on an
+ * existing directory and can change neither a mode nor a mount flag. Retrying them
+ * doubled the syscalls on a permanently failing write and defeated the
+ * one-mkdir-per-directory invariant this cache exists to establish.
+ */
+const recoverableWriteCodes = new Set(['ENOENT', 'ENOTDIR']);
 export default class Log {
     options;
     color;
     typeOptions = {};
+    /*
+     * Instance-level cache of directory creation, keyed on the resolved directory path.
+     * resolveFilename() strips directory separators, so a filename template can never
+     * introduce a new directory and date rollover cannot invalidate an entry.
+     */
+    directoryCache = new Map();
     constructor(options = {}) {
         const merged = {
             ...defaultOptions,
@@ -120,9 +139,24 @@ export default class Log {
         const filenameTemplate = this.getOptionForType(type, 'filename');
         const resolvedName = this.resolveFilename(filenameTemplate, type);
         const targetLog = `${path}${resolvedName}`;
-        await this.validateFileAndDirectory(path, targetLog);
         const fileAction = overwrite ? fsp.writeFile : fsp.appendFile;
-        await fileAction(targetLog, content);
+        await this.validateFileAndDirectory(path, targetLog);
+        try {
+            await fileAction(targetLog, content);
+        }
+        catch (error) {
+            const { code } = error;
+            if (!recoverableWriteCodes.has(code))
+                throw error;
+            /*
+             * The cached directory may have been removed underneath a warm cache. Invalidate
+             * the entry and retry exactly once so a cache hit can never become a permanent
+             * silent write failure. The rejection is the caller's only failure signal.
+             */
+            this.directoryCache.delete(path);
+            await this.validateFileAndDirectory(path, targetLog);
+            await fileAction(targetLog, content);
+        }
     }
     // resolves template variables in a filename string
     resolveFilename(template, type) {
@@ -145,16 +179,27 @@ export default class Log {
         // sanitize: prevent path traversal and disallow directory separators
         return resolved.replace(/\.\./g, '').replace(/[/\\]/g, '');
     }
-    // attempts to create file and/or directory if they don't already exist
+    /*
+     * Ensures the log directory exists, deduping concurrent and repeat calls onto a single
+     * mkdir per directory. No file bootstrap happens here: both write paths already create
+     * the file (appendFile opens 'a', writeFile opens 'w'), so a bootstrap write's only
+     * reachable effect was truncating a concurrent caller's content.
+     *
+     * targetLog is unused but retained for signature compatibility.
+     */
     async validateFileAndDirectory(path, targetLog) {
-        const errorMethod = this.error;
-        mkdirSync(path, { recursive: true });
-        await fsp.access(targetLog).catch(() => {
-            fsp.writeFile(targetLog, '').catch(() => {
-                errorMethod(`Failed to create log file: ${targetLog}.`
-                    + '\n Verify that the application runner has write permissions');
-            });
+        const cached = this.directoryCache.get(path);
+        if (cached)
+            return cached;
+        // cache the promise before awaiting so concurrent writers dedupe and none run early
+        const pending = fsp.mkdir(path, { recursive: true }).then(() => undefined);
+        this.directoryCache.set(path, pending);
+        // never cache a poisoned promise: drop the entry so the next write retries
+        pending.catch(() => {
+            if (this.directoryCache.get(path) === pending)
+                this.directoryCache.delete(path);
         });
+        return pending;
     }
     // method to conditionally sanitize user configuration input
     sanitizePath(path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonyx/logs",
-  "version": "1.0.1-beta.20",
+  "version": "1.0.1-beta.21",
   "description": "Simplified logging for node applications",
   "type": "module",
   "main": "dist/index.js",