@stonyx/logs 1.0.1-alpha.14 → 1.0.1-alpha.16

package/dist/index.d.ts

@@ -13,7 +13,12 @@ export default class Log {
     options: LogOptions;
     color: Color;
     typeOptions: Record<string, Partial<LogOptions>>;
+    directoryCache: Map<string, Promise<void>>;
+    writeFailures: Map<string, number>;
     [key: string]: unknown;
+    info: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;
+    warn: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;
+    error: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;
     constructor(options?: Partial<LogOptions>);
     defineType(type: string, setting: ColorSetting, options?: Partial<LogOptions> | null): void;
     createConvenienceMethod(type: string): void;
@@ -23,6 +28,8 @@ export default class Log {
     log(content: string, type: string, logToFile: boolean, overwrite: boolean): Promise<void>;
     debug(content: unknown, logToFile?: boolean, overwrite?: boolean): Promise<void>;
     writeToFile(type: string, content: string, overwrite: boolean): Promise<void>;
+    noticeWriteResult(targetLog: string, payload: Record<string, unknown> | null): void;
+    emitNotice(severity: string, event: string, payload: Record<string, unknown>): void;
     resolveFilename(template: string, type: string): string;
     validateFileAndDirectory(path: string, targetLog: string): Promise<void>;
     sanitizePath(path: string): string;

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';
@@ -23,6 +23,10 @@ export default class Log {
     options;
     color;
     typeOptions = {};
+    // resolved directory -> in-flight or settled mkdir; instance-scoped so it cannot outlive its directory
+    directoryCache = new Map();
+    // resolved target -> consecutive write failures, used to dedupe the operator notice
+    writeFailures = new Map();
     constructor(options = {}) {
         const merged = {
             ...defaultOptions,
@@ -118,11 +122,46 @@ export default class Log {
     async writeToFile(type, content, overwrite) {
         const path = this.getOptionForType(type, 'path');
         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);
+        const targetLog = `${path}${this.resolveFilename(filenameTemplate, type)}`;
+        const cached = this.directoryCache.has(path);
+        const attempt = async () => {
+            await this.validateFileAndDirectory(path, targetLog);
+            await (overwrite ? fsp.writeFile : fsp.appendFile)(targetLog, content);
+        };
+        try {
+            await attempt().catch(async (error) => {
+                // a warm cache can outlive its directory, so drop the entry and retry exactly once
+                if (!['ENOENT', 'EACCES', 'EPERM', 'EROFS'].includes(error?.code))
+                    throw error;
+                this.directoryCache.delete(path);
+                return attempt();
+            });
+        }
+        catch (error) {
+            const { code, syscall } = error;
+            this.noticeWriteResult(targetLog, { targetLog, path, syscall, code, cached });
+            throw error;
+        }
+        this.noticeWriteResult(targetLog, null);
+    }
+    // One structured stderr notice per failure episode: an emit on the first failure, silence while
+    // it keeps failing, one recovery emit on the next success. A null payload records a success.
+    noticeWriteResult(targetLog, payload) {
+        const failures = this.writeFailures.get(targetLog) ?? 0;
+        if (payload) {
+            this.writeFailures.set(targetLog, failures + 1);
+            if (!failures)
+                this.emitNotice('error', 'log-write-failed', { ...payload, suppressedCount: 0 });
+        }
+        else if (failures) {
+            this.writeFailures.delete(targetLog);
+            this.emitNotice('warn', 'log-write-recovered', { targetLog, suppressedCount: failures - 1 });
+        }
+    }
+    // the write-failure path must never re-enter this logger, so notices go straight to stderr
+    emitNotice(severity, event, payload) {
+        const ts = new Date().toISOString();
+        console.error(JSON.stringify({ ts, schemaVersion: 1, surface: 'stonyx-logs', sessionKey: null, project: null, severity, event, payload }));
     }
     // resolves template variables in a filename string
     resolveFilename(template, type) {
@@ -145,16 +184,19 @@ 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 target's directory exists. Both write paths auto-create the file itself, so no
+    // bootstrap write is needed. `targetLog` is unused but retained for signature compatibility:
+    // resolveFilename strips separators, so the only cached invariant is the directory.
     async validateFileAndDirectory(path, targetLog) {
-        const errorMethod = this.error || console.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');
-            });
-        });
+        let pending = this.directoryCache.get(path);
+        if (!pending) {
+            // cache the promise before awaiting: a flag here would let a concurrent write append first
+            pending = fsp.mkdir(path, { recursive: true }).then(() => undefined);
+            this.directoryCache.set(path, pending);
+            // never keep a poisoned entry - the next write retries from scratch
+            pending.catch(() => 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-alpha.14",
+  "version": "1.0.1-alpha.16",
   "description": "Simplified logging for node applications",
   "type": "module",
   "main": "dist/index.js",