@stonyx/logs 1.0.1-beta.8 → 1.0.1-beta.9

package/README.md

@@ -201,6 +201,7 @@ const chronicle = new Chronicle({
   path: 'logs/',
   prefix: '',
   suffix: '',
+  filename: '',
   additionalLogs: {},
   systemLogs: {
     info: 'cyan',
@@ -217,6 +218,7 @@ const chronicle = new Chronicle({
 | `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 |
 
@@ -270,6 +272,39 @@ chronicle.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
+chronicle.defineType('error', 'red', { filename: 'error-{date}.log' });
+// writes to: logs/error-2026-04-04.log
+
+// Per-type filename with multiple variables
+chronicle.defineType('info', 'cyan', { filename: '{type}-{hostname}-{date}.log' });
+// writes to: logs/info-my-server-2026-04-04.log
+
+// Global filename template via constructor
+const chronicle = new Chronicle({ 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. 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonyx/logs",
-  "version": "1.0.1-beta.8",
+  "version": "1.0.1-beta.9",
   "description": "Simplified logging for node applications",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -1,5 +1,6 @@
 import { mkdirSync, promises as fsp } from 'fs';
 import { fileURLToPath } from 'url';
+import { hostname } from 'os';
 import projectPath from 'path';
 import Color from './color.js';
 
@@ -9,6 +10,7 @@ const defaultOptions = {
   path: 'logs/', // default log directory (relative to main project root directory)
   prefix: '',
   suffix: '',
+  filename: '', // template for log file name (e.g. 'error-{date}.log'), defaults to '{type}.log'
 
   // log types with corresponding color settings
   additionalLogs: {},
@@ -129,7 +131,9 @@ export default class Chronicle {
 
   async writeToFile(type, content, overwrite) {
     const path = this.getOptionForType(type, 'path');
-    const targetLog = `${path}${type}.log`;
+    const filenameTemplate = this.getOptionForType(type, 'filename');
+    const resolvedName = this.resolveFilename(filenameTemplate, type);
+    const targetLog = `${path}${resolvedName}`;
     await this.validateFileAndDirectory(path, targetLog);
 
     const fileAction = overwrite ? fsp.writeFile : fsp.appendFile;
@@ -137,6 +141,31 @@ export default class Chronicle {
     return fileAction(targetLog, content);
   }
 
+  // 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 ? variables[key] : match;
+    });
+
+    // sanitize: prevent path traversal and disallow directory separators
+    return resolved.replace(/\.\./g, '').replace(/[/\\]/g, '');
+  }
+
   // 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