@stonyx/logs 1.0.1-alpha.17 → 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.js

@@ -93,7 +93,13 @@ export default class Log {
     chalk() {
         return this.color.getChalkInstance();
     }
-    // logs to console, and conditionally to file; propagates any writeToFile rejection to the caller
+    /*
+     * 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,7 +118,12 @@ export default class Log {
             return;
         await this.writeToFile(type, `${timestamp} ${content}\n`, overwrite);
     }
-    // direct hardcoded debug method (limited file logging); propagates any writeToFile rejection
+    /*
+     * 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)
@@ -129,6 +140,12 @@ export default class Log {
      *
      * 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');

package/package.json

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