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

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import Color, { type ColorSetting } from './color.js';
+export type Severity = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
 export interface LogOptions {
     logToFileByDefault: boolean;
     logTimestamp: boolean;
@@ -28,8 +29,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;
+    noticeWriteResult(path: string, targetLog: string, payload: Record<string, unknown> | null): void;
+    emitNotice(severity: Severity, 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

@@ -25,7 +25,7 @@ export default class Log {
     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
+    // resolved directory -> consecutive write failures, used to dedupe the operator notice
     writeFailures = new Map();
     constructor(options = {}) {
         const merged = {
@@ -93,7 +93,7 @@ export default class Log {
     chalk() {
         return this.color.getChalkInstance();
     }
-    // logs to console, and conditionally to file
+    // logs to console, and conditionally to file; propagates any writeToFile rejection to the caller
     async log(content, type, logToFile, overwrite) {
         const logTimestamp = this.getOptionForType(type, 'logTimestamp');
         const timestamp = `[${new Date().toLocaleString('en-US')}]`;
@@ -112,13 +112,24 @@ export default class Log {
             return;
         await this.writeToFile(type, `${timestamp} ${content}\n`, overwrite);
     }
-    // direct hardcoded debug method (log to file functionality is limited)
+    // direct hardcoded debug method (limited file logging); propagates any writeToFile rejection
     async debug(content, logToFile = false, overwrite = true) {
         console.dir(content, { depth: 6 }); // eslint-disable-line no-console
         if (!logToFile)
             return;
         await this.writeToFile('debug', JSON.stringify(content, null, 2), overwrite);
     }
+    /*
+     * Writes `content` to the resolved target for `type`, creating the target's directory on first
+     * use for that directory.
+     *
+     * The returned promise rejecting with the underlying `NodeJS.ErrnoException` (with `err.code`
+     * preserved) is the sole failure signal - callers that care must handle it. The structured
+     * stderr notice emitted alongside a failure is informational only and is deduped per episode.
+     *
+     * On `ENOENT`, `EACCES`, `EPERM` or `EROFS` the cached directory entry is dropped and the write
+     * is retried exactly once; every other code rejects on the first attempt without a retry.
+     */
     async writeToFile(type, content, overwrite) {
         const path = this.getOptionForType(type, 'path');
         const filenameTemplate = this.getOptionForType(type, 'filename');
@@ -139,29 +150,63 @@ export default class Log {
         }
         catch (error) {
             const { code, syscall } = error;
-            this.noticeWriteResult(targetLog, { targetLog, path, syscall, code, cached });
+            this.noticeWriteResult(path, targetLog, {
+                targetLog,
+                path,
+                syscall,
+                code,
+                cached,
+            });
             throw error;
         }
-        this.noticeWriteResult(targetLog, null);
+        this.noticeWriteResult(path, 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;
+    /*
+     * 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.
+     *
+     * Keyed on the directory rather than the resolved target, matching `directoryCache`: every code
+     * in the retry allowlist is a directory-level condition, so keying on the target would strand an
+     * un-reaped entry - and silently drop its suppressed count - whenever a `{date}` template rotates
+     * away from a still-failing filename.
+     */
+    noticeWriteResult(path, targetLog, payload) {
+        const failures = this.writeFailures.get(path) ?? 0;
         if (payload) {
-            this.writeFailures.set(targetLog, failures + 1);
-            if (!failures)
-                this.emitNotice('error', 'log-write-failed', { ...payload, suppressedCount: 0 });
+            this.writeFailures.set(path, 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 });
+            this.writeFailures.delete(path);
+            this.emitNotice('warn', 'log-write-recovered', {
+                targetLog,
+                path,
+                suppressedCount: failures - 1,
+            });
         }
     }
-    // the write-failure path must never re-enter this logger, so notices go straight to stderr
+    /*
+     * The write-failure path must never re-enter this logger, so notices go straight to stderr as a
+     * single JSONL record. Field order is the canonical one mandated by the framework logging
+     * schema, with the optional `schemaVersion` last.
+     */
     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 }));
+        console.error(JSON.stringify({
+            ts,
+            surface: 'stonyx-logs',
+            sessionKey: null,
+            project: null,
+            severity,
+            event,
+            payload,
+            schemaVersion: 1,
+        }));
     }
     // resolves template variables in a filename string
     resolveFilename(template, type) {
@@ -184,9 +229,11 @@ export default class Log {
         // sanitize: prevent path traversal and disallow directory separators
         return resolved.replace(/\.\./g, '').replace(/[/\\]/g, '');
     }
-    // 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.
+    /*
+     * 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) {
         let pending = this.directoryCache.get(path);
         if (!pending) {

package/package.json

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