use-term 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hansm7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# use-term 🚀
+
+[![NPM Version](https://img.shields.io/npm/v/use-term.svg?style=flat-rounded&color=blue)](https://www.npmjs.com/package/use-term)
+[![License](https://img.shields.io/npm/l/use-term.svg?style=flat-rounded&color=green)](https://github.com/hansm7/use-term/blob/main/LICENSE)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-rounded)](https://www.npmjs.com/package/use-term)
+[![NodeJS Version](https://img.shields.io/badge/node-%3E%3D%2012.0.0-blue.svg?style=flat-rounded)](https://nodejs.org/)
+
+A **zero-dependency**, ultra-lightweight, and beautiful terminal logging library for Node.js. It features smart context detection (classes, functions, or text), automatic subtle timestamps, beautiful emojis, and colored object inspection.
+
+---
+
+## ✨ Features
+
+- 🔋 **Zero Dependencies:** Pure vanilla Node.js using native ANSI color escapes and `util.inspect`. High performance and 100% secure.
+- 🧠 **Smart Context Detection:** Automatically extracts scopes/context names from class instances (`this`), function references, or plain strings.
+- ⏱️ **Automatic Timestamps:** Every line starts with a subtle, gray-colored time stamp `HH:MM:SS` that keeps your logs tidy and organized.
+- 🎨 **Visual Styling:** Beautifully formatted log categories with color-coded tags and emojis:
+  - ℹ️ `INFO` (Cyan)
+  - ❌ `ERROR` (Red)
+  - ✅ `SUCCESS` (Green)
+  - ⚠️ `WARN` (Yellow)
+- 📦 **Rich Object/Data Inspection:** Automatically colorizes and formats nested metadata, objects, and arrays.
+- 📝 **Title Dividers:** Easily print prominent section headers using the `.title()` function.
+- 🎯 **TypeScript Ready:** Ships with full `.d.ts` declaration files for autocomplete and TypeScript projects.
+
+---
+
+## 📦 Installation
+
+Install the package via npm:
+
+```bash
+npm install use-term
+```
+
+---
+
+## 🚀 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.
+
+### 1. Modern ES Modules (ESM) — _Recommended_
+
+For modern Node.js environments (projects with `"type": "module"` in `package.json`), TypeScript, Next.js, or Vite:
+
+```javascript
+import term from "use-term";
+
+// --- A. Using inside a class (automatically gets class name) ---
+class AuthService {
+  login() {
+    term.info(this, "Starting login process...");
+
+    const user = { id: 42, name: "Alex", roles: ["admin", "billing"] };
+    term.success(this, "Credentials validated successfully", user);
+  }
+}
+
+// --- 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",
+  });
+}
+
+// --- C. Using custom string scopes ---
+term.info("Server", "Server initialized on port 3000", { env: "production" });
+
+// --- D. Visual titles ---
+term.title("Authentication Flow");
+const auth = new AuthService();
+auth.login();
+
+term.title("Payment Flow");
+processPayment();
+```
+
+---
+
+### 2. CommonJS (require)
+
+For traditional Node.js applications:
+
+```javascript
+const term = require("use-term");
+
+// Easily log with CommonJS:
+term.info("CJS", "Logging using standard require() syntax!");
+
+class AuthService {
+  login() {
+    term.info(this, "Starting login process...");
+    const user = { id: 42, name: "Alex", roles: ["admin", "billing"] };
+    term.success(this, "Credentials validated successfully", user);
+  }
+}
+
+term.title("CommonJS Demo");
+const auth = new AuthService();
+auth.login();
+```
+
+---
+
+## 🎨 Log Outputs Preview
+
+When you run your scripts, your terminal will light up with premium, high-visibility, clean styling:
+
+```text
+14:23:05 ℹ️  INFO [Server] Server initialized on port 3000
+{ env: 'production' }
+
+━━━ AUTHENTICATION FLOW ━━━
+14:23:05 ℹ️  INFO [AuthService] Starting login process...
+14:23:05 ✅ SUCCESS [AuthService] Credentials validated successfully
+{ id: 42, name: 'Alex', roles: [ 'admin', 'billing' ] }
+
+━━━ PAYMENT FLOW ━━━
+14:23:05 ⚠️  WARN [processPayment] Payment gateway is responding slowly
+{ delayMs: 1500 }
+14:23:05 ❌ ERROR [processPayment] Payment gateway connection timeout
+{ code: 'ETIMEDOUT' }
+```
+
+---
+
+## 🛠️ API Reference
+
+### `term.info(context, message, [data])`
+
+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.
+
+### `term.error(context, message, [data])`
+
+Logs an error message. Same signature as `info()`.
+
+### `term.success(context, message, [data])`
+
+Logs a success message. Same signature as `info()`.
+
+### `term.warn(context, message, [data])`
+
+Logs a warning message. Same signature as `info()`.
+
+### `term.title(message)`
+
+Prints a highlighted, uppercase section divider to demarcate different stages in your runtime.
+
+- `message` `(string)`: The header text.
+
+---
+
+## 🦾 TypeScript Support
+
+Autocompletion works out of the box in VS Code and modern IDEs. If you are using TypeScript:
+
+```typescript
+import term from "use-term";
+
+term.info("TypeScript", "Fully typed logger out of the box!");
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "use-term",
+  "version": "1.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",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hansm7/use-term.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hansm7/use-term/issues"
+  },
+  "homepage": "https://github.com/hansm7/use-term#readme",
+  "keywords": [
+    "logger",
+    "terminal",
+    "console",
+    "color",
+    "ansi",
+    "beautiful",
+    "zero-dependency",
+    "context",
+    "lightweight",
+    "term-logger",
+    "success",
+    "info",
+    "error",
+    "warn"
+  ],
+  "author": "hansm7",
+  "license": "MIT",
+  "engines": {
+    "node": ">=12.0.0"
+  }
+}

package/src/term.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A beautiful, simple, and dependency-free terminal logger for Node.js.
+ */
+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;
+
+    /**
+     * 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 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 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;
+
+    /**
+     * Prints a bold, beautifully stylized title separator in the console.
+     * @param msg The section title to display.
+     */
+    title(msg: string): void;
+}
+
+declare const term: Term;
+export = term;

package/src/term.js

@@ -0,0 +1,66 @@
+const util = require('util');
+
+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'
+};
+
+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}`;
+    }
+
+    _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';
+    }
+
+    _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);
+        }
+    }
+
+    info(context, msg, data) {
+        this._log('INFO', COLORS.info, 'ℹ️ ', context, msg, data);
+    }
+
+    error(context, msg, data) {
+        this._log('ERROR', COLORS.error, '❌', context, msg, data);
+    }
+ 
+    success(context, msg, data) {
+        this._log('SUCCESS', COLORS.success, '✅', context, msg, data);
+    }
+
+    warn(context, msg, data) {
+        this._log('WARN', COLORS.warn, '⚠️ ', context, msg, data);
+    }
+
+    title(msg) {
+        console.log(`\n${COLORS.magenta}${COLORS.bold}━━━ ${msg.toUpperCase()} ━━━${COLORS.reset}`);
+    }
+}
+
+module.exports = new Term();