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

package/README.md

@@ -58,10 +58,9 @@ const log = new Log();
 log.info('Info: sample application has started');
 log.warn('Warning: this is just a sample');
 
-// 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
+// logs to logs/error.log; a failed write rejects, and handling that rejection is required
+// see "Handling write failures" below
+log.error('Error: no application logic detected', true)
   .catch(err => { /* err.code is the underlying fs error code, e.g. 'EACCES' */ });
 ```
 
@@ -100,9 +99,10 @@ 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).
+> **Caveat:** with `logToFileByDefault: true`, every log call *except* [`debug()`](#the-debug-method)
+> becomes a file write, and therefore 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)
 
@@ -167,10 +167,8 @@ Color settings are handled by determining whether your input is a color name or
 
 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.
+When `logToFile` is true that promise **can reject**, and handling the rejection is **required** --
+see [handling write failures](#handling-write-failures) for the full contract.
 
 ```js
 async method() {
@@ -184,8 +182,6 @@ async method() {
 }
 ```
 
-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:
@@ -200,9 +196,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).
+`debug(content, logToFile)` writes to file on the same contract as every other log type -- a failed
+write rejects with the underlying `fs` error and must be handled -- with one difference: `debug()`
+ignores [`logToFileByDefault`](#configuration), so it writes to file only when you pass `true`.
+See [handling write failures](#handling-write-failures).
 
 ### Logging Parameters
 
@@ -218,26 +215,33 @@ log.error('error message', true, false); // content, logToFile, overwrite
 
 **logToFile** will log to *<project-root>/logs* unless [configured](#configuration) differently during instantiation. <br>
 
-### Handling write failures
+### 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`.
+`log.error(content, true)`, `log.debug(content, true)`, and every log call except `debug()` when
+[`logToFileByDefault`](#configuration) is `true` -- `debug()` is a direct method that never consults
+`logToFileByDefault`, so it only writes to file when you pass `true` explicitly.
 
 That rejection is the only actionable failure signal, so every file-writing call must be awaited
-inside `try`/`catch`, or have `.catch()` attached.
+inside `try`/`catch`, or have `.catch()` attached. The console line is written *before* the file
+write is attempted, so a rejection means only the file copy was lost -- do not re-log the message in
+your handler, or it prints twice.
 
 > **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.
+> For the recoverable directory-level codes -- `ENOENT`, `EACCES`, `EPERM`, `EROFS` -- **Log** has
+> already retried internally by the time the rejection reaches you (see
+> [self-healing retry](#self-healing-retry) below), so that retry ran and failed too. Every other
+> code -- `EISDIR`, `ENOTDIR` and `ENOSPC` among them -- is never retried, because a retry cannot
+> help it. Either way a consumer-side retry layer races the internal self-heal or repeats a call that
+> already cannot succeed, 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.
+> Treat the **first** rejection as the signal to disable file logging or back off, and do not attempt
+> the write again straight away. If you do want file logging to come back without a restart, re-arm
+> on a timer -- see [recovering after a latch](#recovering-after-a-latch).
 
-#### What the promise rejects with
+#### 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.
@@ -277,29 +281,52 @@ async function logError(message) {
 }
 ```
 
-#### Self-healing retry
+That latch is deliberately terminal for the lifetime of the process: nothing in it ever re-enables
+file logging. Records are degraded rather than lost, because the console line is still written on
+every call -- but a consumer using the file sink for audit or compliance should treat the first
+rejection as an **alertable** event, or fail closed, rather than degrade silently.
+
+#### Recovering After a Latch
+
+If file logging must come back without a restart, re-arm the latch on a **timer**, never on the next
+log call. Hold it closed for a fixed back-off window -- a minute or more, long enough that a
+permissions fix or a freed disk has a chance to land -- then let exactly one write through. If that
+write rejects, latch again and lengthen the window; if it succeeds, clear the latch. Anything faster
+is a consumer-side retry under another name.
+
+This also decides what your operators can see. `log-write-recovered` (see
+[structured stderr notices](#structured-stderr-notices)) is emitted **only** on a subsequent
+successful write, and a consumer that latches off permanently never issues one. Its entire stderr
+output for the episode is a single `log-write-failed` followed by silence, which is indistinguishable
+from a failure that self-healed -- so an alert-clear rule keyed on `log-write-recovered` will never
+fire for it. Either treat `log-write-failed` as latching on the operator side too, or use the timed
+re-arm above, which is what makes a recovery notice reachable at all.
+
+#### 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.
+Any other code -- `EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE` and the rest -- 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.
+A retry that succeeds emits no *failure* notice: the promise resolves normally and the write counts
+as a success, closing any failure episode already open for that directory with the usual
+`log-write-recovered`. A rejection carrying one of those four codes has therefore already spent its
+single retry; every other code was never retryable in the first place. The retry is per call and per
+`Log` instance -- independent instances retry independently.
 
-#### Structured stderr notices
+#### 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.
+bypass all formatting and configuration: they are emitted via `console.error` as one JSON object per
+line (JSONL), regardless of your color, prefix, suffix or path settings. Anything that wraps or
+patches `console.error` sees them too. Notices are informational; the promise rejection is the
+failure signal.
 
 | Field | Value |
-| :--- | :--- |
+| :---: | :--- |
 | `ts` | ISO-8601 timestamp of the notice |
 | `surface` | Always `"stonyx-logs"` |
 | `sessionKey` | Always `null` |
@@ -312,7 +339,7 @@ Never leave a write unhandled on the assumption that stderr covers it.
 `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"` |
@@ -322,10 +349,12 @@ Never leave a write unhandled on the assumption that stderr covers it.
 
 `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.
+**Dedupe:** notices are one per failure episode, keyed on the resolved directory and scoped to the
+`Log` instance -- the failure counters are instance state, so two instances writing to the same
+directory emit one notice each. 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:
@@ -358,7 +387,7 @@ const log = new Log({
 
 | Option | Type | Default | Description |
 | :---: | :---: | :---: | :--- |
-| `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). |
+| `logToFileByDefault` | **Boolean** | *false* | Option to change default setting for `logToFile` parameter of logging functions. When true, every log call except `debug()` 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

@@ -17,21 +17,128 @@ export default class Log {
     directoryCache: Map<string, Promise<void>>;
     writeFailures: Map<string, number>;
     [key: string]: unknown;
+    /**
+     * Logs `content` to the console in the `info` color, and to file when `logToFile` is true.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     info: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;
+    /**
+     * Logs `content` to the console in the `warn` color, and to file when `logToFile` is true.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     warn: (content: string, logToFile?: boolean, overwrite?: boolean) => Promise<void>;
+    /**
+     * Logs `content` to the console in the `error` color, and to file when `logToFile` is true.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     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;
+    /**
+     * Validates params and applies configuration-based defaults for logging. Every convenience method
+     * created by `defineType` - including `info`, `warn` and `error` - routes through here. Note that
+     * `debug` does not: it is a direct method that never consults `logToFileByDefault`.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     logAction(type: string, content: string, logToFile?: boolean, overwrite?: boolean): Promise<void>;
     getOptionForType(type: string, option: keyof LogOptions): LogOptions[keyof LogOptions];
     chalk(): ReturnType<Color['getChalkInstance']>;
+    /**
+     * 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.
+     */
     log(content: string, type: string, logToFile: boolean, overwrite: boolean): Promise<void>;
+    /**
+     * Direct hardcoded debug method (limited file logging). Unlike the `defineType` convenience
+     * methods this does not route through `logAction`, so it never consults `logToFileByDefault` and
+     * only writes to file when `logToFile` is passed explicitly.
+     *
+     * When `logToFile` is true this awaits `writeToFile` and propagates its rejection unchanged, on
+     * exactly the same contract as `log` - see `writeToFile` below.
+     */
     debug(content: unknown, logToFile?: boolean, overwrite?: boolean): Promise<void>;
+    /**
+     * 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.
+     *
+     * A rejection is terminal either way. For those four codes the self-heal has already run and
+     * failed by the time one escapes; the rest were never retryable, so repeating the call cannot
+     * change the outcome. Consumers must not layer their own retry on top - doing so either races the
+     * internal one or repeats a call that already cannot succeed, 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".
+     */
     writeToFile(type: string, content: string, overwrite: boolean): Promise<void>;
+    /**
+     * 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: string, targetLog: string, payload: Record<string, unknown> | null): void;
+    /**
+     * The write-failure path must never re-enter this logger, so notices go straight out through
+     * `console.error` as a single JSONL record, bypassing all of this package's formatting. Field
+     * order is the canonical one mandated by the framework logging schema, with the optional
+     * `schemaVersion` last.
+     */
     emitNotice(severity: Severity, event: string, payload: Record<string, unknown>): void;
     resolveFilename(template: string, type: string): string;
+    /**
+     * 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.
+     */
     validateFileAndDirectory(path: string, targetLog: string): Promise<void>;
     sanitizePath(path: string): string;
 }

package/dist/index.js

@@ -72,7 +72,21 @@ export default class Log {
     createConvenienceMethod(type) {
         this[type] = (content, logToFile, overwrite = false) => this.logAction(type, content, logToFile, overwrite);
     }
-    // validates params and sets configuration-based defaults for logging
+    /**
+     * Validates params and applies configuration-based defaults for logging. Every convenience method
+     * created by `defineType` - including `info`, `warn` and `error` - routes through here. Note that
+     * `debug` does not: it is a direct method that never consults `logToFileByDefault`.
+     *
+     * **A failed file write rejects the returned promise, and that rejection is terminal - do not retry
+     * it.** `ENOENT`, `EACCES`, `EPERM` and `EROFS` have already been retried once internally by the
+     * time one reaches you; every other code (`EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE`, ...) is never
+     * retried, because a retry cannot help it. Handle the first rejection by disabling file logging or
+     * backing off - never by writing again. The rejection value is the underlying
+     * `NodeJS.ErrnoException` with `err.code` preserved, and leaving it unhandled terminates the
+     * process.
+     *
+     * @see https://github.com/abofs/stonyx-logs#handling-write-failures
+     */
     logAction(type, content, logToFile, overwrite) {
         // set logToFile default based on class options when not set
         if (logToFile === undefined)
@@ -93,7 +107,7 @@ export default class Log {
     chalk() {
         return this.color.getChalkInstance();
     }
-    /*
+    /**
      * Logs to console, and conditionally to file.
      *
      * When `logToFile` is true this awaits `writeToFile` and propagates its rejection unchanged, so
@@ -118,8 +132,10 @@ export default class Log {
             return;
         await this.writeToFile(type, `${timestamp} ${content}\n`, overwrite);
     }
-    /*
-     * Direct hardcoded debug method (limited file logging).
+    /**
+     * Direct hardcoded debug method (limited file logging). Unlike the `defineType` convenience
+     * methods this does not route through `logAction`, so it never consults `logToFileByDefault` and
+     * only writes to file when `logToFile` is passed explicitly.
      *
      * When `logToFile` is true this awaits `writeToFile` and propagates its rejection unchanged, on
      * exactly the same contract as `log` - see `writeToFile` below.
@@ -130,7 +146,7 @@ export default class Log {
             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.
      *
@@ -141,11 +157,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".
+     * A rejection is terminal either way. For those four codes the self-heal has already run and
+     * failed by the time one escapes; the rest were never retryable, so repeating the call cannot
+     * change the outcome. Consumers must not layer their own retry on top - doing so either races the
+     * internal one or repeats a call that already cannot succeed, 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');
@@ -178,7 +195,7 @@ export default class Log {
         }
         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.
      *
@@ -207,10 +224,11 @@ export default class Log {
             });
         }
     }
-    /*
-     * 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.
+    /**
+     * The write-failure path must never re-enter this logger, so notices go straight out through
+     * `console.error` as a single JSONL record, bypassing all of this package's formatting. 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();
@@ -246,7 +264,7 @@ 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.

package/package.json

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