@stonyx/logs 1.0.1-alpha.20 → 1.0.1-alpha.22

package/README.md

@@ -57,11 +57,7 @@ const log = new Log();
 
 log.info('Info: sample application has started');
 log.warn('Warning: this is just a sample');
-
-// 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' */ });
+log.error('Error: no application logic detected', true); // logs to logs/error.log file
 ```
 
 Easily define your own logging mechanism and color-coding preference:
@@ -95,15 +91,8 @@ const log = new Log({
   suffix: '\n=============================================================== \n',
 });
 
-log.info('Info: sample application has started')
-  .catch(err => { /* see "Handling write failures" */ });
+log.info('Info: sample application has started');
 ```
-
-> **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)
 
 
@@ -118,7 +107,6 @@ 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)
@@ -165,23 +153,37 @@ 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 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** --
-see [handling write failures](#handling-write-failures) for the full contract.
+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.
 
 ```js
 async method() {
-  try {
-    await log.error('error message', true);
+  await log.error('error message', true);
 
-    // do something after logs/error.log (default) is created
-  } catch (err) {
-    // err.code is the underlying fs error code, e.g. 'EACCES'
-  }
+  // do something after logs/error.log (default) is created
 }
 ```
 
+#### File Write Failures
+
+When `logToFile` is true, **the returned promise rejecting is the only failure signal.** Nothing is
+printed and no fallback log is written when the log directory or file cannot be written: the
+underlying `fs` error is propagated to the caller with its `code` intact (`EACCES`, `EPERM`,
+`EROFS`, ...).
+
+A fire-and-forget call therefore produces an **unhandled promise rejection** on a failed write.
+Always `await` the call (or attach a `.catch()`) anywhere file logging is enabled:
+
+```js
+// unhandled rejection if the log directory is not writable
+log.error('error message', true);
+
+// handled
+log.error('error message', true).catch(err => process.stderr.write(`log write failed: ${err.code}\n`));
+```
+
+A write that fails because the log directory was removed at runtime is retried once against a
+freshly created directory before the rejection surfaces.
+
 ### 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:
@@ -196,11 +198,6 @@ 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 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
 
 ```js
@@ -210,161 +207,10 @@ 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. When true, the call returns a promise that rejects if the write fails -- see [handling write failures](#handling-write-failures). |
+| `logToFile` | **Boolean** | *false* | Option to log content to file. |
 | `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 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. 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.**
->
-> 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 not itself 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, 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
-
-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;
-  }
-}
-```
-
-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 -- `EISDIR`, `ENOTDIR`, `ENOSPC`, `EMFILE` and the rest -- does not itself trigger
-a retry. The decision is keyed on the *first* attempt's code, so a rejection carrying one of these
-can still arrive after a retry if conditions changed mid-call.
-
-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
-
-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 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` |
-| `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 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:
-
-```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:
@@ -388,7 +234,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 except `debug()` 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. |
 | `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,5 +1,4 @@
 import Color, { type ColorSetting } from './color.js';
-export type Severity = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
 export interface LogOptions {
     logToFileByDefault: boolean;
     logTimestamp: boolean;
@@ -15,131 +14,20 @@ export default class Log {
     color: Color;
     typeOptions: Record<string, Partial<LogOptions>>;
     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. Other codes do not themselves trigger a retry; the decision is keyed
-     * on the first attempt's code.
-     *
-     * 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

@@ -19,14 +19,21 @@ const defaultOptions = {
 };
 // used to sanitize defineType() options input
 const optionKeys = Object.keys(defaultOptions);
+/*
+ * Write failures where the cached log directory may have been removed or made
+ * unavailable at runtime. These invalidate the directory cache and are retried once.
+ */
+const recoverableWriteCodes = new Set(['ENOENT', 'EACCES', 'EPERM', 'EROFS']);
 export default class Log {
     options;
     color;
     typeOptions = {};
-    // resolved directory -> in-flight or settled mkdir; instance-scoped so it cannot outlive its directory
+    /*
+     * Instance-level cache of directory creation, keyed on the resolved directory path.
+     * resolveFilename() strips directory separators, so a filename template can never
+     * introduce a new directory and date rollover cannot invalidate an entry.
+     */
     directoryCache = new Map();
-    // resolved directory -> consecutive write failures, used to dedupe the operator notice
-    writeFailures = new Map();
     constructor(options = {}) {
         const merged = {
             ...defaultOptions,
@@ -72,21 +79,7 @@ export default class Log {
     createConvenienceMethod(type) {
         this[type] = (content, logToFile, overwrite = false) => this.logAction(type, content, logToFile, overwrite);
     }
-    /**
-     * 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
-     */
+    // validates params and sets configuration-based defaults for logging
     logAction(type, content, logToFile, overwrite) {
         // set logToFile default based on class options when not set
         if (logToFile === undefined)
@@ -107,13 +100,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
-     * the caller receives the underlying `NodeJS.ErrnoException`. Callers must handle it: see the
-     * `writeToFile` contract below.
-     */
+    // logs to console, and conditionally to file
     async log(content, type, logToFile, overwrite) {
         const logTimestamp = this.getOptionForType(type, 'logTimestamp');
         const timestamp = `[${new Date().toLocaleString('en-US')}]`;
@@ -132,118 +119,37 @@ export default class Log {
             return;
         await this.writeToFile(type, `${timestamp} ${content}\n`, overwrite);
     }
-    /**
-     * 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.
-     */
+    // direct hardcoded debug method (log to file functionality is limited)
     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. Other codes do not themselves trigger a retry; the decision is keyed
-     * on the first attempt's code.
-     *
-     * 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');
         const filenameTemplate = this.getOptionForType(type, 'filename');
-        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);
-        };
+        const resolvedName = this.resolveFilename(filenameTemplate, type);
+        const targetLog = `${path}${resolvedName}`;
+        const fileAction = overwrite ? fsp.writeFile : fsp.appendFile;
+        await this.validateFileAndDirectory(path, targetLog);
         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();
-            });
+            await fileAction(targetLog, content);
         }
         catch (error) {
-            const { code, syscall } = error;
-            this.noticeWriteResult(path, targetLog, {
-                targetLog,
-                path,
-                syscall,
-                code,
-                cached,
-            });
-            throw error;
-        }
-        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.
-     *
-     * 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(path, failures + 1);
-            if (!failures) {
-                this.emitNotice('error', 'log-write-failed', {
-                    ...payload,
-                    suppressedCount: 0,
-                });
-            }
-        }
-        else if (failures) {
-            this.writeFailures.delete(path);
-            this.emitNotice('warn', 'log-write-recovered', {
-                targetLog,
-                path,
-                suppressedCount: failures - 1,
-            });
+            const { code } = error;
+            if (!code || !recoverableWriteCodes.has(code))
+                throw error;
+            /*
+             * The cached directory may have been removed underneath a warm cache. Invalidate
+             * the entry and retry exactly once so a cache hit can never become a permanent
+             * silent write failure. The rejection is the caller's only failure signal.
+             */
+            this.directoryCache.delete(path);
+            await this.validateFileAndDirectory(path, targetLog);
+            await fileAction(targetLog, content);
         }
     }
-    /**
-     * 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();
-        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) {
         // default to '{type}.log' when no template is configured
@@ -265,20 +171,26 @@ 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 log directory exists, deduping concurrent and repeat calls onto a single
+     * mkdir per directory. No file bootstrap happens here: both write paths already create
+     * the file (appendFile opens 'a', writeFile opens 'w'), so a bootstrap write's only
+     * reachable effect was truncating a concurrent caller's content.
+     *
+     * targetLog is unused but retained for signature compatibility.
      */
     async validateFileAndDirectory(path, targetLog) {
-        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));
-        }
+        const cached = this.directoryCache.get(path);
+        if (cached)
+            return cached;
+        // cache the promise before awaiting so concurrent writers dedupe and none run early
+        const pending = fsp.mkdir(path, { recursive: true }).then(() => undefined);
+        this.directoryCache.set(path, pending);
+        // never cache a poisoned promise: drop the entry so the next write retries
+        pending.catch(() => {
+            if (this.directoryCache.get(path) === pending)
+                this.directoryCache.delete(path);
+        });
         return pending;
     }
     // method to conditionally sanitize user configuration input

package/package.json

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