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

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/abofs/stonyx-logs/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-logs/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/logs.svg)](https://www.npmjs.com/package/@stonyx/logs)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 <h1 align="center">
 	<br>
 	<br>
@@ -27,10 +31,10 @@
 
 ---
 
-**Chronicle** is built on top of all the great work done by "Sindre Sorhus" and other collaborators of the [chalk](https://www.npmjs.com/package/chalk) project.
-This project is not directly associated with chalk other than chalk being a core dependency of **Chronicle**.
+**Log** is built on top of all the great work done by "Sindre Sorhus" and other collaborators of the [chalk](https://www.npmjs.com/package/chalk) project.
+This project is not directly associated with chalk other than chalk being a core dependency of **Log**.
 
-**IMPORTANT**: Please note that although **Chronicle** can be configured to any color through chalk, your output is subject to your terminal's color limitations.
+**IMPORTANT**: Please note that although **Log** can be configured to any color through chalk, your output is subject to your terminal's color limitations.
 
 ## Highlights
 
@@ -41,27 +45,31 @@ This project is not directly associated with chalk other than chalk being a core
 ## Install
 
 ```sh
-npm install node-chronicle
+npm install @stonyx/logs
 ```
 
 ## Usage
 
 ```js
-import Chronicle from 'node-chronicle';
+import Log from '@stonyx/logs';
+
+const log = new Log();
 
-const chronicle = new Chronicle();
+log.info('Info: sample application has started');
+log.warn('Warning: this is just a sample');
 
-chronicle.info('Info: sample application has started');
-chronicle.warn('Warning: this is just a sample');
-chronicle.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' */ });
 ```
 
 Easily define your own logging mechanism and color-coding preference:
 
 ```js
-import Chronicle from 'node-chronicle';
+import Log from '@stonyx/logs';
 
-const chronicle = new Chronicle({
+const log = new Log({
   systemLogs: {
     blue: '#007cae', // indigo blue
     yellow: '#ae8f00', // bright orange
@@ -69,17 +77,17 @@ const chronicle = new Chronicle({
   },
 });
 
-chronicle.blue('Info: using custom method blue, sample application has started');
-chronicle.yellow('Warning: using custom method yellow, this is just a sample');
-chronicle.red('Error: using custom method red, no application logic detected', false);
+log.blue('Info: using custom method blue, sample application has started');
+log.yellow('Warning: using custom method yellow, this is just a sample');
+log.red('Error: using custom method red, no application logic detected', false);
 ```
 
 Customize logging options to best suit your project
 
 ```js
-import Chronicle from 'node-chronicle';
+import Log from '@stonyx/logs';
 
-const chronicle = new Chronicle({
+const log = new Log({
   logToFileByDefault: true,
   logTimestamp: true,
   path: 'custom-logs', // <project root>/custom-logs/*.log
@@ -87,23 +95,31 @@ const chronicle = new Chronicle({
   suffix: '\n=============================================================== \n',
 });
 
-chronicle.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 *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)
 
 
 Add additional log types extending the default options of "info", "warn", "error" and "debug"
 
 ```js
-import Chronicle from '../source/index.js';
+import Log from '@stonyx/logs';
 
-const chronicle = new Chronicle({ additionalLogs: { question: 'green' } });
+const log = new Log({ additionalLogs: { question: 'green' } });
 
 // create additional log with direct chalk configuration
-chronicle.defineType('query', chronicle.chalk().black.bgGreen);
+log.defineType('query', log.chalk().black.bgGreen);
 
-chronicle.question('What will a fully custom chalk color function look like?');
-await chronicle.query('This is what a custom chalk color setting looks like', true);
+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)
 
@@ -111,7 +127,7 @@ await chronicle.query('This is what a custom chalk color setting looks like', tr
 
 ### Defining Logs & Colors
 
-By default, **Chronicle** is instantiated with the following options:
+By default, **Log** is instantiated with the following options:
 
 ```js
   additionalLogs: {},
@@ -122,10 +138,10 @@ By default, **Chronicle** is instantiated with the following options:
   },
 ```
 
-You can add to a new log/color setting by passing the `additionalLogs` option to the **Chronicle** constructor. Any setting that already exists in `systemLogs` will be replaced, otherwise they will be added.
+You can add to a new log/color setting by passing the `additionalLogs` option to the **Log** constructor. Any setting that already exists in `systemLogs` will be replaced, otherwise they will be added.
  
 ```js
-  const chronicle = new Chronicle({ additionalLogs: { info: 'green', custom: 'cyan' } });
+  const log = new Log({ additionalLogs: { info: 'green', custom: 'cyan' } });
 
   // output configuration:
   {
@@ -136,32 +152,39 @@ You can add to a new log/color setting by passing the `additionalLogs` option to
   }
 ```
 
-**Chronicle** will generate convenience methods for all keys provided, with the corresponding color settings. The example above would create the following convenience methods, for logging:
+**Log** will generate convenience methods for all keys provided, with the corresponding color settings. The example above would create the following convenience methods, for logging:
 
 ```js
-  chronicle.info() // green output
-  chronicle.warn() // yellow output
-  chronicle.error() // red output
-  chronicle.custom() // cyan output
+  log.info() // green output
+  log.warn() // yellow output
+  log.error() // red output
+  log.custom() // cyan output
 ```
 
 These methods can then be called in your application with [logging parameters](#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** --
+see [handling write failures](#handling-write-failures) for the full contract.
 
 ```js
 async method() {
-  await chronicle.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'
+  }
 }
 ```
 
 ### The Debug Method
 
-**Chronicle** allows for the `chronicle.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:
+**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:
 
 ```js
 // For logging to console:
@@ -171,32 +194,189 @@ console.dir(content);
 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 **Chronicle** package. But for anyone who's fully incorporated **Chronicle** into their project, this function offers some convenience.
+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
-chronicle.error('error message', true, false); // content, logToFile, overwrite
+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 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 **Chronicle**, you can pass an object to customize your settings. Below is the default configuration:
+When instantiating **Log**, you can pass an object to customize your settings. Below is the default configuration:
 
 ```js
-const chronicle = new Chronicle({
+const log = new Log({
   logToFileByDefault: false,
   logTimestamp: false,
   path: 'logs/',
   prefix: '',
   suffix: '',
+  filename: '',
   additionalLogs: {},
   systemLogs: {
     info: 'cyan',
@@ -208,32 +388,33 @@ const chronicle = new Chronicle({
 
 | 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 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*. |
 | `suffix` | **String** | *''* | Suffix string to tack on to all log messages for all log types with the exception of *debug*. |
+| `filename` | **String** | *''* | Template for log file names with variable support. Defaults to `{type}.log` when empty. See [dynamic file names](#dynamic-file-names). |
 | `additionalLogs` | **Object** | | Key value pair object containing log type to color setting for logs that will be merged with `systemLogs` |
-| `systemLogs` | **Object** | | Key value pair object containing log type to color setting for main **Chronicle** logs available in application |
+| `systemLogs` | **Object** | | Key value pair object containing log type to color setting for main **Log** logs available in application |
 
 `additionalLogs` and `systemLogs` are explained with more detail in the [defining logs and colors](#defining-logs) section.
 
 ### Advanced Configuration
 
-You may want to do more than just pick a basic color for your output. **chalk** offers a variety of different options, and can be configured via `defineType()`. **Chronicle** exposes the chalk instance via `chalk()` so that you don't have to import **chalk** directly into your project. Here is an example of how you can use this method to fully customize your log color setting:
+You may want to do more than just pick a basic color for your output. **chalk** offers a variety of different options, and can be configured via `defineType()`. **Log** exposes the chalk instance via `chalk()` so that you don't have to import **chalk** directly into your project. Here is an example of how you can use this method to fully customize your log color setting:
 
 ```js
-const chronicle = new Chronicle();
+const log = new Log();
 
-chronicle.defineType('critical', chronicle.chalk().bold.red);
-chronicle.critical('This is a critical error');
+log.defineType('critical', log.chalk().bold.red);
+log.critical('This is a critical error');
 ```
 
 Additionally, any [configuration](#configuration) that can be set during instantiation, can also be applied exclusively to any given type by passing in a third **options** parameter.
 
 ```js
 // params: type, setting, options
-chronicle.definetype('notice', '#c0c0c0', {
+log.definetype('notice', '#c0c0c0', {
   prefix: '--------------------------------------------------------------- \n',
   suffix: '\n=============================================================== \n'
 });
@@ -248,29 +429,62 @@ chronicle.definetype('notice', '#c0c0c0', {
 
 
 ```js
-const chronicle = new Chronicle();
+const log = new Log();
 
-chronicle.defineType('info', chronicle.chalk().black.bgCyan);
-chronicle.defineType('critical', chronicle.chalk().bold.red);
-chronicle.defineType('dialog', 'magentaBright');
-chronicle.definetype('notice', '#c0c0c0', {
+log.defineType('info', log.chalk().black.bgCyan);
+log.defineType('critical', log.chalk().bold.red);
+log.defineType('dialog', 'magentaBright');
+log.definetype('notice', '#c0c0c0', {
   prefix: '--------------------------------------------------------------- \n',
   suffix: '\n=============================================================== \n'
 });
 
-chronicle.info('This pre-existing log now has a cyan background and black foreground');
-chronicle.critical('This new log is bold and red');
-chronicle.dialog('This new dialog is bright magenta');
-chronicle.notice('This new log is the hex "#c0c0c0" share of gray');
+log.info('This pre-existing log now has a cyan background and black foreground');
+log.critical('This new log is bold and red');
+log.dialog('This new dialog is bright magenta');
+log.notice('This new log is the hex "#c0c0c0" share of gray');
 ```
 
 `defineType()` can also be used as an alternative to populating the `additionalLogs` setting in the constructor, as if the setting doesn't already exist, it will then be created.
 
+### Dynamic File Names
+
+The `filename` option supports template variables that are resolved at write-time, allowing each log type to produce uniquely named files.
+
+#### Supported Variables
+
+| Variable | Resolves To | Example Output |
+| :---: | :--- | :--- |
+| `{date}` | Current date in YYYY-MM-DD format | `2026-04-04` |
+| `{type}` | Log type name | `error` |
+| `{pid}` | Current process ID | `12345` |
+| `{hostname}` | Machine hostname | `my-server` |
+
+#### Examples
+
+```js
+// Per-type filename via defineType
+log.defineType('error', 'red', { filename: 'error-{date}.log' });
+// writes to: logs/error-2026-04-04.log
+
+// Per-type filename with multiple variables
+log.defineType('info', 'cyan', { filename: '{type}-{hostname}-{date}.log' });
+// writes to: logs/info-my-server-2026-04-04.log
+
+// Global filename template via constructor
+const log = new Log({ filename: '{type}-{date}.log' });
+// all types write to: logs/<type>-2026-04-04.log
+```
+
+When no `filename` is configured, the default behavior of `{type}.log` is preserved for full backward compatibility.
+
+Path traversal characters (`..`, `/`, `\`) are automatically stripped from resolved file names for security.
+
 ## Origin
 
-As a team of developers who are constantly working on side projects, we often litter our codebase with TODOs to refactor convenience utils such as **chronicle** into classes of their own, or projects of their own. This usually turns into internal tech debt that never gets addressed. Furthermore, we also often find ourselves going the *copy -> paste -> modify* route of previously written useful logic, which saves us time in new projects, but not as much as it would if all we had to do was run an `npm install` instead. 
+As a team of developers who are constantly working on side projects, we often litter our codebase with TODOs to refactor convenience utils such as **@stonyx/logs** into classes of their own, or projects of their own. This usually turns into internal tech debt that never gets addressed. Furthermore, we also often find ourselves going the *copy -> paste -> modify* route of previously written useful logic, which saves us time in new projects, but not as much as it would if all we had to do was run an `npm install` instead. 
 
-With that in mind, we are proud to release **chronicle** as an open source package, in hopes others will find this just as useful as we do in their own projects.  
+With that in mind, we are proud to release **@stonyx/logs** as an open source package, in hopes others will find this just as useful as we do in their own projects.  
 
 ## Maintainers
 

package/dist/color.d.ts

@@ -0,0 +1,10 @@
+import chalk from 'chalk';
+export type ChalkColorFn = (text: string) => string;
+export type ColorSetting = string | ChalkColorFn;
+export default class Color {
+    types: Record<string, ChalkColorFn>;
+    getLogColor(type: string): ChalkColorFn;
+    getChalkInstance(): typeof chalk;
+    setLogColor(type: string, setting: ColorSetting): void;
+    settingToChalkColorFunction(setting: ColorSetting): ChalkColorFn;
+}

package/dist/color.js

@@ -0,0 +1,39 @@
+import chalk from 'chalk';
+export default class Color {
+    types = {};
+    getLogColor(type) {
+        return this.types[type];
+    }
+    getChalkInstance() {
+        return chalk;
+    }
+    setLogColor(type, setting) {
+        const chalkColorFunction = this.settingToChalkColorFunction(setting);
+        this.types[type] = chalkColorFunction;
+    }
+    // retrieves chalk color function, and fully validates output
+    settingToChalkColorFunction(setting) {
+        const errorMessage = 'Invalid chalk color function. '
+            + 'For help with color settings, see https://github.com/abofs/stonyx-logs#defining-logs--colors';
+        switch (typeof setting) {
+            case 'string':
+                const chalkColorFunction = (setting[0] === '#')
+                    ? chalk.hex(setting)
+                    : chalk[setting];
+                if (!chalkColorFunction
+                    || typeof chalkColorFunction !== 'function'
+                    || typeof chalkColorFunction('') !== 'string') {
+                    throw new Error(errorMessage);
+                }
+                return chalkColorFunction;
+            case 'function':
+                // validate that given function returns a string
+                if (typeof setting('') !== 'string') {
+                    throw new Error(errorMessage);
+                }
+                return setting;
+            default:
+                throw new Error(errorMessage);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import Color, { type ColorSetting } from './color.js';
+export type Severity = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface LogOptions {
+    logToFileByDefault: boolean;
+    logTimestamp: boolean;
+    path: string;
+    prefix: string;
+    suffix: string;
+    filename: string;
+    additionalLogs: Record<string, ColorSetting>;
+    systemLogs: Record<string, ColorSetting>;
+}
+export default class Log {
+    options: LogOptions;
+    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

@@ -0,0 +1,299 @@
+import { promises as fsp } from 'fs';
+import { fileURLToPath } from 'url';
+import { hostname } from 'os';
+import projectPath from 'path';
+import Color from './color.js';
+const defaultOptions = {
+    logToFileByDefault: false,
+    logTimestamp: false,
+    path: 'logs/',
+    prefix: '',
+    suffix: '',
+    filename: '',
+    additionalLogs: {},
+    systemLogs: {
+        info: 'cyan',
+        warn: 'yellow',
+        error: 'red',
+    },
+};
+// used to sanitize defineType() options input
+const optionKeys = Object.keys(defaultOptions);
+export default class Log {
+    options;
+    color;
+    typeOptions = {};
+    // resolved directory -> in-flight or settled mkdir; instance-scoped so it cannot outlive its directory
+    directoryCache = new Map();
+    // resolved directory -> consecutive write failures, used to dedupe the operator notice
+    writeFailures = new Map();
+    constructor(options = {}) {
+        const merged = {
+            ...defaultOptions,
+            ...options,
+        };
+        this.options = merged;
+        this.options.path = this.sanitizePath(this.options.path);
+        const { additionalLogs, systemLogs } = merged;
+        const logs = {
+            ...systemLogs,
+            ...additionalLogs,
+        };
+        this.color = new Color();
+        this.typeOptions = {};
+        // create direct convenience methods for logging
+        for (const type of Object.keys(logs)) {
+            this.defineType(type, logs[type]);
+        }
+    }
+    // records setting and options for log type, and creates convenience method ie: log.info()
+    defineType(type, setting, options = null) {
+        this.color.setLogColor(type, setting);
+        // create convenience method if it doesn't exist
+        if (!this[type])
+            this.createConvenienceMethod(type);
+        if (!options)
+            return;
+        if (typeof options !== 'object')
+            throw new Error('The options param must be an object.');
+        for (const option of Object.keys(options)) {
+            if (!optionKeys.includes(option)) {
+                throw new Error(`${option} is not a valid configuration object.`
+                    + '\n For a list of available options, see https://github.com/abofs/stonyx-logs#configuration');
+            }
+            // sanitize path input
+            if (option === 'path') {
+                options[option] = this.sanitizePath(options[option]);
+            }
+        }
+        this.typeOptions[type] = options;
+    }
+    // proxy through `logAction` method in order to set defaults based on argument presence
+    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
+     */
+    logAction(type, content, logToFile, overwrite) {
+        // set logToFile default based on class options when not set
+        if (logToFile === undefined)
+            logToFile = this.getOptionForType(type, 'logToFileByDefault');
+        // treat overwrite default as true for log type "debug"
+        if (type === 'debug' && overwrite === undefined)
+            overwrite = true;
+        return this.log(content, type, logToFile, overwrite ?? false);
+    }
+    // retrieves option setting for given type, default to global
+    getOptionForType(type, option) {
+        const options = this.typeOptions[type];
+        if (!options || !options[option])
+            return this.options[option];
+        return options[option];
+    }
+    // exposes chalk for custom color options via defineType
+    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.
+     */
+    async log(content, type, logToFile, overwrite) {
+        const logTimestamp = this.getOptionForType(type, 'logTimestamp');
+        const timestamp = `[${new Date().toLocaleString('en-US')}]`;
+        const chalkColorFunction = this.color.getLogColor(type);
+        let prefix = this.getOptionForType(type, 'prefix');
+        let suffix = this.getOptionForType(type, 'suffix');
+        if (logTimestamp)
+            prefix += `${timestamp} `;
+        if (prefix)
+            prefix = chalkColorFunction(prefix);
+        if (suffix)
+            suffix = chalkColorFunction(suffix);
+        const coloredLog = chalkColorFunction(content);
+        console.log(`${prefix}${coloredLog}${suffix}`); // eslint-disable-line no-console
+        if (!logToFile)
+            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.
+     */
+    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);
+        };
+        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();
+            });
+        }
+        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,
+            });
+        }
+    }
+    /**
+     * 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
+        if (!template)
+            return `${type}.log`;
+        const now = new Date();
+        const yyyy = now.getFullYear();
+        const mm = String(now.getMonth() + 1).padStart(2, '0');
+        const dd = String(now.getDate()).padStart(2, '0');
+        const variables = {
+            date: `${yyyy}-${mm}-${dd}`,
+            type,
+            pid: process.pid,
+            hostname: hostname(),
+        };
+        const resolved = template.replace(/\{(\w+)\}/g, (match, key) => {
+            return variables[key] !== undefined ? String(variables[key]) : match;
+        });
+        // 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.
+     */
+    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));
+        }
+        return pending;
+    }
+    // method to conditionally sanitize user configuration input
+    sanitizePath(path) {
+        const moduleDir = projectPath.dirname(fileURLToPath(import.meta.url));
+        const delim = moduleDir.includes('node_modules') ? 'node_modules' : 'src';
+        const splitDir = moduleDir.split(delim);
+        if (splitDir.length < 2)
+            throw new Error('Failed to locate your project\'s root directory.');
+        // use project root directory behind path
+        path = projectPath.resolve(splitDir[0], path);
+        // force path property to contain a trailing "/"
+        if (path[path.length - 1] !== '/') {
+            path += '/';
+        }
+        return path;
+    }
+}

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "@stonyx/logs",
-  "version": "1.0.1-alpha.2",
+  "version": "1.0.1-alpha.20",
   "description": "Simplified logging for node applications",
   "type": "module",
-  "main": "src/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./color": "./src/color.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./color": {
+      "types": "./dist/color.d.ts",
+      "default": "./dist/color.js"
+    }
   },
   "files": [
-    "src",
+    "dist",
     "README.md"
   ],
   "publishConfig": {
@@ -24,7 +31,7 @@
     "log",
     "logging",
     "color-coding",
-    "chronicle",
+    "stonyx",
     "history",
     "documentation",
     "document",
@@ -43,13 +50,20 @@
     "chalk": "^5.3.0"
   },
   "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "eslint": "^8.27.0",
     "eslint-plugin-node": "^11.1.0",
     "qunit": "^2.19.3",
-    "sinon": "^17.0.0"
+    "sinon": "^17.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
-    "test": "qunit 'test/unit/**/*-test.js'",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "node --import tsx node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'",
     "lint": "eslint . --fix"
   }
 }

package/src/color.js

@@ -1,50 +0,0 @@
-import chalk from 'chalk';
-
-export default class Color {
-  constructor() {
-    this.types = [];
-  }
-
-  // retrieves configured color function for log type
-  getLogColor(type) {
-    return this.types[type];
-  }
-
-  getChalkInstance() {
-    return chalk;
-  }
-
-  setLogColor(type, setting) {
-    const chalkColorFunction = this.settingToChalkColorFunction(setting);
-    this.types[type] = chalkColorFunction;
-  }
-
-  // retrieves chalk color function, and fully validates output
-  settingToChalkColorFunction(setting) {
-    const errorMessage = 'Invalid chalk color function.'
-      + 'For help with color settings, see https://github.com/abofs/chronicle#defining-logs--colors';
-
-    switch (typeof setting) {
-    case 'string':
-      const chalkColorFunction = (setting[0] === '#') ? chalk.hex(setting) : chalk[setting];
-      if (!chalkColorFunction
-          || typeof chalkColorFunction !== 'function'
-          || typeof chalkColorFunction('') !== 'string') {
-        throw errorMessage;
-      }
-
-      return chalkColorFunction;
-
-    case 'function':
-      // validate that given function returns a string
-      if (typeof setting('') !== 'string') {
-        throw errorMessage;
-      }
-
-      return setting;
-
-    default:
-      throw errorMessage;
-    }
-  }
-}

package/src/index.js

@@ -1,172 +0,0 @@
-import { mkdirSync, promises as fsp } from 'fs';
-import { fileURLToPath } from 'url';
-import projectPath from 'path';
-import Color from './color.js';
-
-const defaultOptions = {
-  logToFileByDefault: false, // default setting (overridable by logToFile param)
-  logTimestamp: false, // option to include timestamp in console logs
-  path: 'logs/', // default log directory (relative to main project root directory)
-  prefix: '',
-  suffix: '',
-
-  // log types with corresponding color settings
-  additionalLogs: {},
-  systemLogs: {
-    info: 'cyan',
-    warn: 'yellow',
-    error: 'red',
-  },
-};
-
-// used to sanitize defineType() options input
-const optionKeys = Object.keys(defaultOptions);
-
-export default class Chronicle {
-  constructor(options = defaultOptions) {
-    options = {
-      ...defaultOptions,
-      ...options,
-    };
-    this.options = options;
-    this.options.path = this.sanitizePath(this.options.path);
-
-    const { additionalLogs, systemLogs } = options;
-    const logs = {
-      ...systemLogs,
-      ...additionalLogs,
-    };
-
-    this.color = new Color();
-    this.typeOptions = [];
-
-    // create direct convenience methods for logging
-    for (const type of Object.keys(logs)) {
-      this.defineType(type, logs[type]);
-    }
-  }
-
-  // records setting and options for log type, and crates convenience method ie: chronicle.info()
-  defineType(type, setting, options = null) {
-    this.color.setLogColor(type, setting);
-
-    // create convenience method if it doesn't exist
-    if (!this[type]) this.createConvenienceMethod(type);
-
-    if (!options) return;
-    if (typeof options !== 'object') throw 'The options param must be an object.';
-
-    for (let option of Object.keys(options)) {
-      if (!optionKeys.includes(option)) {
-        throw `${option} is not a valid configuration object.`
-        + '\n For a list of available options, see https://github.com/abofs/chronicle#configuration';
-      }
-
-      // sanitize path input
-      if (option === 'path') options[option] = this.sanitizePath(options[option]);
-    }
-
-    this.typeOptions[type] = options;
-  }
-
-  // proxy through `logAction` method in order to set defaults based on argument presence
-  createConvenienceMethod(type) {
-    this[type] = (content, logToFile, overwrite = false) =>
-      this.logAction(type, content, logToFile, overwrite);
-  }
-
-  // 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 (arguments[2] === undefined) logToFile = this.getOptionForType(type, 'logToFileByDefault');
-
-    // treat overwrite default as true for log type "debug"
-    if (type === 'debug' && arguments[3] === undefined) overwrite = true;
-
-    return this.log(content, type, logToFile, overwrite);
-  }
-
-  // retrieves option setting for given type, default to global
-  getOptionForType(type, option) {
-    const options = this.typeOptions[type];
-    if (!options || !options[option]) return this.options[option];
-
-    return options[option];
-  }
-
-  // exposes chalk for custom color options via defineType
-  chalk() {
-    return this.color.getChalkInstance();
-  }
-
-  // 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')}]`;
-    const chalkColorFunction = this.color.getLogColor(type);
-    let prefix = this.getOptionForType(type, 'prefix');
-    let suffix = this.getOptionForType(type, 'suffix');
-    if (logTimestamp) prefix += `${timestamp} `;
-    if (prefix) prefix = chalkColorFunction(prefix);
-    if (suffix) suffix = chalkColorFunction(suffix);
-    const coloredLog = chalkColorFunction(content);
-
-    console.log(`${prefix}${coloredLog}${suffix}`); // eslint-disable-line no-console
-
-    if (!logToFile) return;
-
-    return this.writeToFile(type, `${timestamp} ${content}\n`, overwrite);
-  }
-
-  // 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;
-
-    return this.writeToFile('debug', JSON.stringify(content, null, 2), overwrite);
-  }
-
-  async writeToFile(type, content, overwrite) {
-    const path = this.getOptionForType(type, 'path');
-    const targetLog = `${path}${type}.log`;
-    await this.validateFileAndDirectory(path, targetLog);
-
-    const fileAction = overwrite ? fsp.writeFile : fsp.appendFile;
-
-    return fileAction(targetLog, content);
-  }
-
-  // attempts to create file and/or directory if they don't already exist
-  async validateFileAndDirectory(path, targetLog) {
-    const errorMethod = this.error || console.error; // prefer native method unless removed by user
-
-    mkdirSync(path, { recursive: true });
-
-    await fsp.access(targetLog).catch(() => {
-      fsp.writeFile(targetLog, '').catch(() => {
-        errorMethod(`Failed to create log file: ${targetLog}.`
-          + '\n Verify that the application runner has write permissions');
-      });
-    });
-  }
-
-  // method to conditionally sanitize user configuration input
-  sanitizePath(path) {
-    const moduleDir = projectPath.dirname(fileURLToPath(import.meta.url));
-    const delim = moduleDir.includes('node_modules') ? 'node_modules' : 'src';
-    const splitDir = moduleDir.split(delim);
-
-    if (splitDir.length < 2) throw ('Failed to locate your project\'s root directory.');
-
-    // use project root directory behind path
-    path = projectPath.resolve(splitDir[0], path);
-
-    // force path property to contain a trailing "/"
-    if (path[path.length - 1] !== '/') {
-      path += '/';
-    }
-
-    return path;
-  }
-}