@stonyx/logs 1.0.1-beta.11 → 1.0.1-beta.13

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,29 @@
+import Color, { type ColorSetting } from './color.js';
+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>>;
+    [key: string]: unknown;
+    constructor(options?: Partial<LogOptions>);
+    defineType(type: string, setting: ColorSetting, options?: Partial<LogOptions> | null): void;
+    createConvenienceMethod(type: string): void;
+    logAction(type: string, content: string, logToFile?: boolean, overwrite?: boolean): Promise<void>;
+    getOptionForType(type: string, option: keyof LogOptions): LogOptions[keyof LogOptions];
+    chalk(): ReturnType<Color['getChalkInstance']>;
+    log(content: string, type: string, logToFile: boolean, overwrite: boolean): Promise<void>;
+    debug(content: unknown, logToFile?: boolean, overwrite?: boolean): Promise<void>;
+    writeToFile(type: string, content: string, overwrite: boolean): Promise<void>;
+    resolveFilename(template: string, type: string): string;
+    validateFileAndDirectory(path: string, targetLog: string): Promise<void>;
+    sanitizePath(path: string): string;
+}

package/dist/index.js

@@ -0,0 +1,174 @@
+import { mkdirSync, 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 = {};
+    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 sets configuration-based defaults for logging
+    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
+    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 (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);
+    }
+    async writeToFile(type, content, overwrite) {
+        const path = this.getOptionForType(type, 'path');
+        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;
+        await 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 ? String(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;
+        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 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-beta.11",
+  "version": "1.0.1-beta.13",
   "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": {
@@ -43,13 +50,19 @@
     "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",
+    "typescript": "^5.8.3"
   },
   "scripts": {
-    "test": "qunit 'test/unit/**/*-test.js'",
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "pnpm build && pnpm build:test && qunit 'dist-test/test/unit/**/*-test.js'",
     "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/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 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,201 +0,0 @@
-import { mkdirSync, 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, // 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: '',
-  filename: '', // template for log file name (e.g. 'error-{date}.log'), defaults to '{type}.log'
-
-  // 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 Log {
-  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 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 '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/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 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 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;
-
-    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
-
-    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;
-  }
-}