use-term 1.0.0 → 2.0.0

package/README.md

@@ -35,6 +35,57 @@ npm install use-term
 
 ---
 
+## ⚙️ Configuration
+
+You can customize the logger behavior by passing options when creating a new instance:
+
+```javascript
+import { Logger } from "use-term";
+
+// Disable all logs (useful for testing or production overrides)
+const silentLogger = new Logger({ silent: true });
+silentLogger.info("This won't be logged");
+
+// Disable logs in specific environments (defaults to ["production"])
+const logger = new Logger({
+  silentEnvironments: ["production", "staging"],
+  environment: process.env.NODE_ENV,
+});
+
+// Custom configuration
+const customLogger = new Logger({
+  silent: false,
+  silentEnvironments: ["prod"],
+  environment: process.env.APP_ENV || "development",
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `silent` | boolean | `false` | If `true`, all logs are disabled |
+| `silentEnvironments` | string[] | `["production"]` | Array of environments where logging is disabled |
+| `environment` | string | `process.env.NODE_ENV \|\| "development"` | Current environment name |
+
+**Example: Disable logs only in production**
+
+```javascript
+const logger = new Logger(); // By default, logs are disabled when NODE_ENV=production
+logger.info("This won't appear in production"); // Silent in production
+```
+
+**Example: Disable logs in multiple environments**
+
+```javascript
+const logger = new Logger({
+  silentEnvironments: ["production", "staging", "testing"],
+});
+// Logs will be silenced in any of these environments
+```
+
+---
+
 ## 🚀 Usage
 
 Since `use-term` is built with universal Node.js compatibility in mind, it works seamlessly in both modern **ES Modules (ESM)** and legacy **CommonJS** environments out-of-the-box without requiring separate bundles or transpilation.
@@ -44,37 +95,51 @@ Since `use-term` is built with universal Node.js compatibility in mind, it works
 For modern Node.js environments (projects with `"type": "module"` in `package.json`), TypeScript, Next.js, or Vite:
 
 ```javascript
-import term from "use-term";
+import { Logger } from "use-term";
+
+// Create a logger instance with default options
+// Logs are disabled in production by default
+const logger = new Logger();
+
+// For custom environments:
+const customLogger = new Logger({
+  environment: process.env.NODE_ENV,
+  silentEnvironments: ["production", "staging"],
+});
 
 // --- A. Using inside a class (automatically gets class name) ---
 class AuthService {
   login() {
-    term.info(this, "Starting login process...");
+    logger.info("Starting login process...", undefined, this);
 
     const user = { id: 42, name: "Alex", roles: ["admin", "billing"] };
-    term.success(this, "Credentials validated successfully", user);
+    logger.success("Credentials validated successfully", user, this);
   }
 }
 
 // --- B. Using inside a function (automatically gets function name) ---
 function processPayment() {
-  term.warn(processPayment, "Payment gateway is responding slowly", {
-    delayMs: 1500,
-  });
-  term.error(processPayment, "Payment gateway connection timeout", {
-    code: "ETIMEDOUT",
-  });
+  logger.warn(
+    "Payment gateway is responding slowly",
+    { delayMs: 1500 },
+    processPayment,
+  );
+  logger.error(
+    "Payment gateway connection timeout",
+    { code: "ETIMEDOUT" },
+    processPayment,
+  );
 }
 
 // --- C. Using custom string scopes ---
-term.info("Server", "Server initialized on port 3000", { env: "production" });
+logger.info("Server initialized on port 3000", { env: "production" }, "Server");
 
 // --- D. Visual titles ---
-term.title("Authentication Flow");
+logger.title("Authentication Flow");
 const auth = new AuthService();
 auth.login();
 
-term.title("Payment Flow");
+logger.title("Payment Flow");
 processPayment();
 ```
 
@@ -85,20 +150,30 @@ processPayment();
 For traditional Node.js applications:
 
 ```javascript
-const term = require("use-term");
+const { Logger } = require("use-term");
+
+// Create a logger instance with default options
+// Logs are disabled in production by default
+const logger = new Logger();
+
+// For custom environments:
+const customLogger = new Logger({
+  environment: process.env.NODE_ENV,
+  silentEnvironments: ["prod"],
+});
 
 // Easily log with CommonJS:
-term.info("CJS", "Logging using standard require() syntax!");
+logger.info("Logging using standard require() syntax!", undefined, "CJS");
 
 class AuthService {
   login() {
-    term.info(this, "Starting login process...");
+    logger.info("Starting login process...", undefined, this);
     const user = { id: 42, name: "Alex", roles: ["admin", "billing"] };
-    term.success(this, "Credentials validated successfully", user);
+    logger.success("Credentials validated successfully", user, this);
   }
 }
 
-term.title("CommonJS Demo");
+logger.title("CommonJS Demo");
 const auth = new AuthService();
 auth.login();
 ```
@@ -129,27 +204,27 @@ When you run your scripts, your terminal will light up with premium, high-visibi
 
 ## 🛠️ API Reference
 
-### `term.info(context, message, [data])`
+### `logger.info(message, [data], [context])`
 
 Logs an informational message.
 
-- `context` `(any)`: `this` inside a class, a function name, or a plain string.
 - `message` `(string)`: The description text of the log.
 - `data` `(any, optional)`: Any object, array, or metadata to inspect and format below.
+- `context` `(any, optional)`: `this` inside a class, a function name, or a plain string.
 
-### `term.error(context, message, [data])`
+### `logger.error(message, [data], [context])`
 
 Logs an error message. Same signature as `info()`.
 
-### `term.success(context, message, [data])`
+### `logger.success(message, [data], [context])`
 
 Logs a success message. Same signature as `info()`.
 
-### `term.warn(context, message, [data])`
+### `logger.warn(message, [data], [context])`
 
 Logs a warning message. Same signature as `info()`.
 
-### `term.title(message)`
+### `logger.title(message)`
 
 Prints a highlighted, uppercase section divider to demarcate different stages in your runtime.
 
@@ -162,9 +237,11 @@ Prints a highlighted, uppercase section divider to demarcate different stages in
 Autocompletion works out of the box in VS Code and modern IDEs. If you are using TypeScript:
 
 ```typescript
-import term from "use-term";
+import { Logger } from "use-term";
+
+const logger = new Logger();
 
-term.info("TypeScript", "Fully typed logger out of the box!");
+logger.info("Fully typed logger out of the box!", undefined, "TypeScript");
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-term",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "A zero-dependency, ultra-lightweight, and beautiful terminal logging library for Node.js with smart context detection, colored outputs, and automatic timestamps.",
   "main": "src/term.js",
   "types": "src/term.d.ts",

package/src/term.d.ts

@@ -1,45 +1,82 @@
+/**
+ * Configuration options for the Logger.
+ */
+export interface LoggerOptions {
+  /**
+   * If true, no logs will be printed regardless of environment.
+   * @default false
+   */
+  silent?: boolean;
+  /**
+   * Array of environments where logging should be disabled.
+   * @default ["production"]
+   */
+  silentEnvironments?: string[];
+  /**
+   * Current environment (defaults to NODE_ENV or "development").
+   * @default process.env.NODE_ENV || "development"
+   */
+  environment?: string;
+}
+
 /**
  * A beautiful, simple, and dependency-free terminal logger for Node.js.
+ * Instantiate with `new Logger()` to create a logger instance with optional configuration.
+ *
+ * @example
+ * const logger = new Logger();
+ * logger.info("Hello world");
+ *
+ * @example
+ * const logger = new Logger({ silent: true });
+ * logger.info("This won't be logged");
+ *
+ * @example
+ * const logger = new Logger({ silentEnvironments: ["production", "staging"] });
+ * // Logs will be disabled if NODE_ENV is "production" or "staging"
  */
-declare class Term {
-    /**
-     * Logs an informational message.
-     * @param context The context of the log (e.g. `this`, a class instance, a function reference, or a string).
-     * @param msg The message to log.
-     * @param data Optional metadata or object to inspect.
-     */
-    info(context: any, msg: string, data?: any): void;
+export class Logger {
+  constructor(options?: LoggerOptions);
 
-    /**
-     * Logs an error message.
-     * @param context The context of the log (e.g. `this`, a class instance, a function reference, or a string).
-     * @param msg The message to log.
-     * @param data Optional metadata or object to inspect.
-     */
-    error(context: any, msg: string, data?: any): void;
+  /**
+   * Logs an informational message.
+   * @param msg The message to log.
+   * @param data Optional metadata or object to inspect.
+   * @param context Optional scope or location for the log (e.g. `this`, a function, or a string).
+   */
+  info(msg: string, data?: any, context?: any): void;
+  info(context: any, msg: string, data?: any): void;
 
-    /**
-     * Logs a success message.
-     * @param context The context of the log (e.g. `this`, a class instance, a function reference, or a string).
-     * @param msg The message to log.
-     * @param data Optional metadata or object to inspect.
-     */
-    success(context: any, msg: string, data?: any): void;
+  /**
+   * Logs an error message.
+   * @param msg The message to log.
+   * @param data Optional metadata or object to inspect.
+   * @param context Optional scope or location for the log (e.g. `this`, a function, or a string).
+   */
+  error(msg: string, data?: any, context?: any): void;
+  error(context: any, msg: string, data?: any): void;
 
-    /**
-     * Logs a warning message.
-     * @param context The context of the log (e.g. `this`, a class instance, a function reference, or a string).
-     * @param msg The message to log.
-     * @param data Optional metadata or object to inspect.
-     */
-    warn(context: any, msg: string, data?: any): void;
+  /**
+   * Logs a success message.
+   * @param msg The message to log.
+   * @param data Optional metadata or object to inspect.
+   * @param context Optional scope or location for the log (e.g. `this`, a function, or a string).
+   */
+  success(msg: string, data?: any, context?: any): void;
+  success(context: any, msg: string, data?: any): void;
 
-    /**
-     * Prints a bold, beautifully stylized title separator in the console.
-     * @param msg The section title to display.
-     */
-    title(msg: string): void;
-}
+  /**
+   * Logs a warning message.
+   * @param msg The message to log.
+   * @param data Optional metadata or object to inspect.
+   * @param context Optional scope or location for the log (e.g. `this`, a function, or a string).
+   */
+  warn(msg: string, data?: any, context?: any): void;
+  warn(context: any, msg: string, data?: any): void;
 
-declare const term: Term;
-export = term;
+  /**
+   * Prints a bold, beautifully stylized title separator in the console.
+   * @param msg The section title to display.
+   */
+  title(msg: string): void;
+}

package/src/term.js

@@ -1,66 +1,134 @@
-const util = require('util');
+const util = require("util");
+
+const DEFAULT_OPTIONS = {
+  silent: false,
+  silentEnvironments: ["production"],
+  environment: process.env.NODE_ENV || "development",
+};
 
 const COLORS = {
-    info: '\x1b[36m',
-    error: '\x1b[31m',
-    success: '\x1b[32m',
-    warn: '\x1b[33m',
-    blue: '\x1b[34m',
-    gray: '\x1b[90m',
-    magenta: '\x1b[35m',
-    reset: '\x1b[0m',
-    bold: '\x1b[1m'
+  info: "\x1b[36m",
+  error: "\x1b[31m",
+  success: "\x1b[32m",
+  warn: "\x1b[33m",
+  blue: "\x1b[34m",
+  gray: "\x1b[90m",
+  magenta: "\x1b[35m",
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
 };
 
 class Term {
-    _timestamp() {
-        const now = new Date();
-        const time = `${now.getHours().toString().padStart(2, '0')}:${now.getMinutes().toString().padStart(2, '0')}:${now.getSeconds().toString().padStart(2, '0')}`;
-        return `${COLORS.gray}${time}${COLORS.reset}`;
-    }
+  constructor(options = {}) {
+    this.config = {
+      ...DEFAULT_OPTIONS,
+      ...options,
+    };
+  }
 
-    _getContextName(ctx) {
-        if (!ctx) return 'App';
-        if (typeof ctx === 'string') return ctx;
-        if (typeof ctx === 'function') return ctx.name || 'AnonymousFn';
-        if (typeof ctx === 'object' && ctx.constructor) return ctx.constructor.name;
-        return 'Unknown';
+  _shouldLog() {
+    if (this.config.silent) return false;
+    if (this.config.silentEnvironments.includes(this.config.environment)) {
+      return false;
     }
+    return true;
+  }
 
-    _log(type, color, icon, context, msg, data) {
-        const ctxName = this._getContextName(context);
-        const timestamp = this._timestamp();
-        const tag = `${color}${icon} ${type}${COLORS.reset}`;
-        const scope = `${COLORS.blue}[${ctxName}]${COLORS.reset}`;
-        
-        console.log(`${timestamp} ${tag} ${scope} ${msg}`);
-        
-        if (data !== undefined && data !== null) {
-            const formatted = util.inspect(data, { colors: true, depth: null });
-            const indented = formatted.split('\n').map(l => l).join('\n');
-            console.log(indented);
-        }
-    }
+  _timestamp() {
+    const now = new Date();
+    const time = `${now.getHours().toString().padStart(2, "0")}:${now.getMinutes().toString().padStart(2, "0")}:${now.getSeconds().toString().padStart(2, "0")}`;
+    return `${COLORS.gray}${time}${COLORS.reset}`;
+  }
 
-    info(context, msg, data) {
-        this._log('INFO', COLORS.info, 'ℹ️ ', context, msg, data);
-    }
+  _getContextName(ctx) {
+    if (!ctx) return "App";
+    if (typeof ctx === "string") return ctx;
+    if (typeof ctx === "function") return ctx.name || "AnonymousFn";
+    if (typeof ctx === "object" && ctx.constructor) return ctx.constructor.name;
+    return "Unknown";
+  }
 
-    error(context, msg, data) {
-        this._log('ERROR', COLORS.error, '❌', context, msg, data);
-    }
- 
-    success(context, msg, data) {
-        this._log('SUCCESS', COLORS.success, '✅', context, msg, data);
+  _resolveLogArgs(first, second, third) {
+    if (typeof first === "string" && typeof second !== "string") {
+      const msg = first;
+      if (third !== undefined) {
+        return { context: third, msg, data: second };
+      }
+      if (second === undefined) {
+        return { context: undefined, msg, data: undefined };
+      }
+      if (typeof second === "function" || typeof second === "string") {
+        return { context: second, msg, data: undefined };
+      }
+      return { context: undefined, msg, data: second };
     }
 
-    warn(context, msg, data) {
-        this._log('WARN', COLORS.warn, '⚠️ ', context, msg, data);
-    }
+    return { context: first, msg: second, data: third };
+  }
+
+  _log(type, color, icon, context, msg, data) {
+    if (!this._shouldLog()) return;
 
-    title(msg) {
-        console.log(`\n${COLORS.magenta}${COLORS.bold}━━━ ${msg.toUpperCase()} ━━━${COLORS.reset}`);
+    const ctxName = this._getContextName(context);
+    const timestamp = this._timestamp();
+    const tag = `${color}${icon} ${type}${COLORS.reset}`;
+    const scope = `${COLORS.blue}[${ctxName}]${COLORS.reset}`;
+
+    console.log(`${timestamp} ${tag} ${scope} ${msg}`);
+
+    if (data !== undefined && data !== null) {
+      const formatted = util.inspect(data, { colors: true, depth: null });
+      const indented = formatted
+        .split("\n")
+        .map((l) => l)
+        .join("\n");
+      console.log(indented);
     }
+  }
+
+  info(msgOrContext, dataOrMsg, context) {
+    const {
+      context: ctx,
+      msg,
+      data,
+    } = this._resolveLogArgs(msgOrContext, dataOrMsg, context);
+    this._log("INFO", COLORS.info, "ℹ️ ", ctx, msg, data);
+  }
+
+  error(msgOrContext, dataOrMsg, context) {
+    const {
+      context: ctx,
+      msg,
+      data,
+    } = this._resolveLogArgs(msgOrContext, dataOrMsg, context);
+    this._log("ERROR", COLORS.error, "❌", ctx, msg, data);
+  }
+
+  success(msgOrContext, dataOrMsg, context) {
+    const {
+      context: ctx,
+      msg,
+      data,
+    } = this._resolveLogArgs(msgOrContext, dataOrMsg, context);
+    this._log("SUCCESS", COLORS.success, "✅", ctx, msg, data);
+  }
+
+  warn(msgOrContext, dataOrMsg, context) {
+    const {
+      context: ctx,
+      msg,
+      data,
+    } = this._resolveLogArgs(msgOrContext, dataOrMsg, context);
+    this._log("WARN", COLORS.warn, "⚠️ ", ctx, msg, data);
+  }
+
+  title(msg) {
+    if (!this._shouldLog()) return;
+
+    console.log(
+      `\n${COLORS.magenta}${COLORS.bold}━━━ ${msg.toUpperCase()} ━━━${COLORS.reset}`,
+    );
+  }
 }
 
-module.exports = new Term();
+module.exports = Term;