logaro/README.md

Structured logging middleware for Express. Tracks request timing, IP, status, method, and endpoint. Supports colorized console and JSON log files.

# 📝 Logaro - Modern Express Logger

**Logaro** is a lightweight, structured logging middleware for Node.js & Express applications. It provides beautiful colorized output for development and structured JSON logs for production, powered by `winston`.

### It automatically tracks:
* ⏱️ Request Duration (High precision)
* 📡 HTTP Method & Status Codes
* 🌍 User IP Address
* 🛡️ Error Stack Traces (with request context)

## ✨ Features
* **Pretty Console Logs:** Clean, readable, and color-coded output for developers.
* **Structured JSON Files:** Production-ready logs saved in a dedicated `Logaro/` folder.
* **Smart File Management** Logs are only saved to files if you enable them via environment variables.
* **Crash Reporting:** Automatically captures `Uncaught Exceptions` and `Unhandled Rejections` in separate files.
* **Error Utility:** Built-in helper to log custom errors inside `try...catch` blocks with route context.

---

## 📦 Installation
You can install this package in your React project using `npm` or `yarn`.


```bash
npm install logaro
# or
yarn add logaro
```


## 🛠️ Quick Start

### 1. Basic Setup (Middleware)
Add `requestLogger` at the top of your middleware stack (before routes).

```js
const express = require('express');
const { requestLogger } = require('logaro');

const app = express();

// Mount Middleware
app.use(requestLogger());

app.get('/', (req, res) => {
  res.send('Logaro is active!');
});

app.listen(3000, () => console.log('Server running...'));
```
### 2. Logging Errors (Utility)
Use `logError` inside your `catch` blocks. This attaches the User IP and Route Path to the error log, making debugging easier.

```ts
const { logError } = require('logaro');

app.get('/database-query', async (req, res) => {
  try {
    // ... logic that might fail
    throw new Error('Database connection failed');
  } catch (error) {
    // Log error with context
    logError(error, req);
    
    res.status(500).json({ error: 'Internal Server Error' });
  }
});
```

## ⚙️ Configuration (Environment Variables)
By default, Logaro only logs to the Console. To save logs to files, you must configure your .env file or set environment variables.
| Variable | Value | Description |
| :--- | :--- |  :--- |
| **`LOGARO_SAVE_LOGS`** | `true`  | Required to enable file logging. Creates a `Logaro/` folder. |
| **`LOG_LEVEL`** | `info` / `warn` / `error`  | Min level to log (Default: `info`) |

### Example .env file:
```ts
LOGARO_SAVE_LOGS=true
LOG_LEVEL=info
```

## 📂 Log Files Structure
When `LOGARO_SAVE_LOGS=true` is set, a folder named `Logaro` is created in your project root containing:
| File Name | Purpose |
| :--- | :--- |
| **`app-combined.log`** | Contains all traffic logs (Success, 404s, 500s) and handled errors. |
| **`exceptions.log`** | ☠️ Critical Crashes: Contains "Uncaught Exceptions" that crashed the process. |
| **`rejections.log`** | ⚠️ Promise Failures: Contains "Unhandled Rejections" (Promises without `.catch`) |

### 🎨 Output Examples
### Development (Console)
```ts
12:30:45 info: GET /api/users 200 12.50ms - Request Completed
12:31:10 warn: POST /auth/login 401 5.20ms - Unauthorized Access
12:32:00 error: GET /db-down 500 8.10ms - Server Error Occurred
```
### Production (JSON File)
```ts
{
  "level": "info",
  "message": "Request Completed Successfully",
  "method": "GET",
  "endpoint": "/api/users",
  "status": 200,
  "durationMs": "12.50",
  "ip": "::1",
  "timestamp": "2025-01-01 12:30:45"
}
```


## 👤 Author & Contributor

This package is maintained and developed by **Hamza Tayyab**. I am passionate about creating clean, efficient, and secure frontend tools. Feel free to connect or check out my other projects!

| Platform | Link |
| :--- | :--- |
| **🌐 Portfolio** | https://linktr.ee/hm.za |
| **📧 Email** | hmzatayab@gmail.com  |
| **💻 GitHub** | Follow me on GitHub https://github.com/hmzatayab |
| **🎁 Other Packages** | Check out my other open-source projects https://www.npmjs.com/~hamzatayab |

## 📄 License
MIT License

Copyright (c) [2025] [Hamza Tayyab]

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.