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

package/README.md

@@ -57,7 +57,12 @@ const log = new Log();
 
 log.info('Info: sample application has started');
 log.warn('Warning: this is just a sample');
-log.error('Error: no application logic detected', true); // logs to logs/error.log file
+
+// Writing to a file can fail, and the returned promise is the only signal that it did.
+// Always handle it -- an unhandled rejection terminates the process.
+// See "Handling write failures" below.
+log.error('Error: no application logic detected', true) // logs to logs/error.log file
+  .catch(err => { /* err.code is the underlying fs error code, e.g. 'EACCES' */ });
 ```
 
 Easily define your own logging mechanism and color-coding preference:
@@ -91,8 +96,14 @@ const log = new Log({
   suffix: '\n=============================================================== \n',
 });
 
-log.info('Info: sample application has started');
+log.info('Info: sample application has started')
+  .catch(err => { /* see "Handling write failures" */ });
 ```
+
+> **Caveat:** with `logToFileByDefault: true`, *every* log call becomes a file write, and therefore
+> every log call returns a promise that can reject. A failing log directory turns an unhandled
+> `log.info()` into a process-terminating rejection. See [handling write failures](#handling-write-failures).
+
 ![](https://github.com/abofs/stonyx-logs/raw/main/media/examples/custom-options.jpg)
 
 
@@ -107,6 +118,7 @@ const log = new Log({ additionalLogs: { question: 'green' } });
 log.defineType('query', log.chalk().black.bgGreen);
 
 log.question('What will a fully custom chalk color function look like?');
+// second argument writes to file, so this can reject -- see "Handling write failures"
 await log.query('This is what a custom chalk color setting looks like', true);
 ```
 ![](https://github.com/abofs/stonyx-logs/raw/main/media/examples/additional-logs.jpg)
@@ -153,16 +165,27 @@ 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, allowing you to use them with `await` in an async method, or to append `then()`, `catch()` or `finally()`.
+
+When `logToFile` is true that promise **can reject**, and handling the rejection is **required**, not
+optional: the rejection is the only signal that the write failed, and an unhandled rejection
+terminates your process under Node's default settings. Wrap the call in `try`/`catch` (or attach
+`.catch()`) for every call that writes to a file.
 
 ```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) {
+    // err.code is the underlying fs error code, e.g. 'EACCES'
+  }
 }
 ```
 
+See [handling write failures](#handling-write-failures) for the full contract.
+
 ### 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:
@@ -177,6 +200,10 @@ JSON.stringify(content, null, 2);
 
 We believe that when wanting to output complicated objects or debug **typescript** applications, there are better methods than utilizing this **Log** package. But for anyone who's fully incorporated **Log** into their project, this function offers some convenience.
 
+`debug(content, logToFile)` writes to file on exactly the same contract as every other log type:
+`log.debug(content, true)` returns a promise that rejects with the underlying `fs` error when the
+write fails, and that rejection must be handled. See [handling write failures](#handling-write-failures).
+
 ### Logging Parameters
 
 ```js
@@ -186,10 +213,128 @@ log.error('error message', true, false); // content, logToFile, overwrite
 | Parameter | Type | Default | Description |
 | :---: | :---: | :---: | :--- |
 | `content` | **String** | | Content of log that will output on your console. |
-| `logToFile` | **Boolean** | *false* | Option to log content to file. |
+| `logToFile` | **Boolean** | *false* | Option to log content to file. When true, the call returns a promise that rejects if the write fails -- see [handling write failures](#handling-write-failures). |
 | `overwrite` | **Boolean** | *false <br> (true on debug())* | Option to overwrite log file, rather than append to it. This option is redundant if logToFile is false.  |
 
 **logToFile** will log to *<project-root>/logs* unless [configured](#configuration) differently during instantiation. <br>
+
+### Handling write failures
+
+Any call that writes to a file returns a promise that **rejects when the write fails**. That covers
+`log.error(content, true)`, `log.debug(content, true)`, and *every* log call when
+[`logToFileByDefault`](#configuration) is `true`.
+
+That rejection is the only actionable failure signal, so every file-writing call must be awaited
+inside `try`/`catch`, or have `.catch()` attached.
+
+> **A rejection is terminal. Do not retry it.**
+>
+> **Log** has already retried internally by the time a rejection reaches you (see
+> [self-healing retry](#self-healing-retry) below). A rejection means that retry ran and failed too,
+> so a consumer-side retry layer races the internal self-heal and only delays the disable or back-off
+> that your error path exists to trigger.
+>
+> Treat the **first** rejection as the signal to disable file logging or back off. Do not attempt the
+> write again.
+
+#### What the promise rejects with
+
+The rejection value is the underlying Node `fs` error - a `NodeJS.ErrnoException` passed through
+unmodified, with `err.code`, `err.syscall`, `err.errno` and `err.path` all preserved.
+
+```js
+try {
+  await log.error('error message', true);
+} catch (err) {
+  // err.code is the underlying fs error code, e.g. 'EACCES'
+  // err.syscall is the failing call, e.g. 'mkdir' or 'open'
+}
+```
+
+Codes you are most likely to see are `EACCES` and `EPERM` (no permission to create the log directory
+or write the log file), `ENOENT` (the directory disappeared and could not be recreated) and `EROFS`
+(read-only filesystem) - but any error the filesystem raises reaches the caller as-is.
+
+**An unhandled rejection terminates your process** under Node's default `--unhandled-rejections=throw`.
+A fire-and-forget `log.error('...', true)` pointed at an unwritable log directory exits the process
+with `Error: EACCES: permission denied, mkdir '...'`.
+
+The recommended consumer shape is a latch that trips on the first rejection:
+
+```js
+let fileLoggingDisabled = false;
+
+async function logError(message) {
+  // once file logging has failed, stay on the console
+  if (fileLoggingDisabled) return log.error(message);
+
+  try {
+    await log.error(message, true);
+  } catch (err) {
+    // the first rejection is terminal - disable, do not retry
+    fileLoggingDisabled = true;
+  }
+}
+```
+
+#### Self-healing retry
+
+A cached log directory can outlive the directory it describes - for example, something deletes
+`logs/` while your process is running. To cover that, a failure whose `err.code` is `ENOENT`,
+`EACCES`, `EPERM` or `EROFS` drops the cached directory entry and retries the write **exactly once**.
+Any other code rejects on the first attempt, with no retry.
+
+A successful retry is silent: the promise resolves normally and no notice is emitted. A rejection
+therefore always means the single retry has already been spent, which is why consumers must not add
+one of their own.
+
+#### Structured stderr notices
+
+Alongside the rejection, **Log** emits a machine-parseable notice to `stderr` so that operators have
+something to key on. The write-failure path must never re-enter the logger itself, so these notices
+bypass all formatting and configuration: they are written directly to `stderr` as one JSON object per
+line (JSONL), regardless of your color, prefix, suffix or path settings.
+
+These notices are **informational only**. They are not the failure signal - the promise rejection is.
+Never leave a write unhandled on the assumption that stderr covers it.
+
+| Field | Value |
+| :--- | :--- |
+| `ts` | ISO-8601 timestamp of the notice |
+| `surface` | Always `"stonyx-logs"` |
+| `sessionKey` | Always `null` |
+| `project` | Always `null` |
+| `severity` | `"error"` for a failure, `"warn"` for a recovery |
+| `event` | `"log-write-failed"` or `"log-write-recovered"` |
+| `payload` | Event-specific, see below |
+| `schemaVersion` | Always `1` |
+
+`log-write-failed` payload:
+
+| Field | Description |
+| :--- | :--- |
+| `targetLog` | Resolved path of the log file that could not be written |
+| `path` | Resolved log *directory*, with trailing separator - this is the dedupe key |
+| `syscall` | The failing syscall, e.g. `"mkdir"` or `"open"` |
+| `code` | The same `err.code` carried by the rejection |
+| `cached` | Whether the directory was already cached when the write started |
+| `suppressedCount` | Always `0` on a failure notice |
+
+`log-write-recovered` carries `targetLog`, `path` and `suppressedCount` only.
+
+**Dedupe:** notices are one per failure episode, keyed on the resolved directory. The first failure
+for a directory emits `log-write-failed`; every subsequent failure for that same directory is silent.
+The next successful write to it emits a single `log-write-recovered` carrying `suppressedCount` - the
+number of notices that were suppressed, i.e. `N - 1` for an episode of `N` consecutive failures.
+Every failure still rejects its own promise; only the notices are deduped.
+
+Five consecutive failures followed by one success emit exactly these two records:
+
+```jsonl
+{"ts":"2026-08-29T23:08:50.343Z","surface":"stonyx-logs","sessionKey":null,"project":null,"severity":"error","event":"log-write-failed","payload":{"targetLog":"/private/tmp/my-app/logs/error.log","path":"/private/tmp/my-app/logs/","syscall":"mkdir","code":"EACCES","cached":false,"suppressedCount":0},"schemaVersion":1}
+{"ts":"2026-08-29T23:08:50.344Z","surface":"stonyx-logs","sessionKey":null,"project":null,"severity":"warn","event":"log-write-recovered","payload":{"targetLog":"/private/tmp/my-app/logs/error.log","path":"/private/tmp/my-app/logs/","suppressedCount":4},"schemaVersion":1}
+```
+
 ### Configuration
 
 When instantiating **Log**, you can pass an object to customize your settings. Below is the default configuration:
@@ -213,7 +358,7 @@ const log = new Log({
 
 | Option | Type | Default | Description |
 | :---: | :---: | :---: | :--- |
-| `logToFileByDefault` | **Boolean** | *false* | Option to change default setting for `logToFile` parameter of logging functions. |
+| `logToFileByDefault` | **Boolean** | *false* | Option to change default setting for `logToFile` parameter of logging functions. When true, every log call becomes a rejectable file write -- see [handling write failures](#handling-write-failures). |
 | `logTimestamp` | **Boolean** | *false* | Option to include timestamp in console logging. Timestamps are automatically included in file logs. |
 | `path` | **String** | *'logs/'* | Path in which to store log files. This setting is relative to your project's root directory. |
 | `prefix` | **String** | *''* | Prefix string to prepend all log messages for all log types with the exception of *debug*. |

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,13 @@ export default class Log {
     chalk() {
         return this.color.getChalkInstance();
     }
-    // logs to console, and conditionally to file
+    /*
+     * Logs to console, and conditionally to file.
+     *
+     * When `logToFile` is true this awaits `writeToFile` and propagates its rejection unchanged, so
+     * the caller receives the underlying `NodeJS.ErrnoException`. Callers must handle it: see the
+     * `writeToFile` contract below.
+     */
     async log(content, type, logToFile, overwrite) {
         const logTimestamp = this.getOptionForType(type, 'logTimestamp');
         const timestamp = `[${new Date().toLocaleString('en-US')}]`;
@@ -112,13 +118,35 @@ 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).
+     *
+     * When `logToFile` is true this awaits `writeToFile` and propagates its rejection unchanged, on
+     * exactly the same contract as `log` - see `writeToFile` below.
+     */
     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.
+     *
+     * That retry is why a rejection is terminal rather than transient: by the time one escapes, the
+     * self-heal has already run and failed. Consumers must not layer their own retry on top - doing
+     * so races the internal one and delays the disable/back-off the rejection exists to trigger. The
+     * correct response to the first rejection is to stop writing. See README "Handling write
+     * failures".
+     */
     async writeToFile(type, content, overwrite) {
         const path = this.getOptionForType(type, 'path');
         const filenameTemplate = this.getOptionForType(type, 'filename');
@@ -139,29 +167,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 +246,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.18",
   "description": "Simplified logging for node applications",
   "type": "module",
   "main": "dist/index.js",