monten 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,231 @@
+<p align="center">
+  <img src="./banner.png" alt="monten observability banner" width="100%" />
+</p>
+
+<h1 align="center">monten</h1>
+
+<p align="center">
+  <strong>Lightweight, production-ready observability for Node.js backends</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-blue" alt="Version" />
+  <img src="https://img.shields.io/badge/status-experimental-orange" alt="Status" />
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="License" />
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node Version" />
+  <img src="https://img.shields.io/npm/v/monten?color=red" alt="npm" />
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#technologies">Technologies</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+> ⚠️ **Experimental:** APIs and behavior may change in minor versions. Use with caution in critical systems.
+
+## Features
+
+| Feature                   | Description                                           |
+| ------------------------- | ----------------------------------------------------- |
+| 🕐 **HTTP Timing**        | Measure total request latency with drop-in middleware |
+| 📊 **Error Tracking**     | Automatic error rate tracking with stack traces       |
+| 🗄️ **DB Timing**          | Explicit instrumentation via `withDbTiming` helper    |
+| 🔗 **Request Context**    | Per-request scoping with `AsyncLocalStorage`          |
+| 📝 **Structured Logging** | JSON-only logs with requestId correlation             |
+| 📦 **Metrics Batching**   | In-memory buffer with periodic flushing               |
+| 🔌 **Zero Coupling**      | Fully removable without breaking your app             |
+
+## Technologies
+
+<p align="center">
+  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/Express-000000?style=for-the-badge&logo=express&logoColor=white" alt="Express" />
+</p>
+
+| Technology            | Purpose                                              |
+| --------------------- | ---------------------------------------------------- |
+| **TypeScript**        | Type-safe implementation with full declaration files |
+| **Node.js**           | Runtime environment (v18+)                           |
+| **AsyncLocalStorage** | Native request-scoped context propagation            |
+| **Express**           | Compatible middleware architecture                   |
+| **JSON**              | Structured logging format                            |
+
+## Installation
+
+```bash
+npm install monten
+```
+
+```bash
+yarn add monten
+```
+
+```bash
+pnpm add monten
+```
+
+## Quick Start
+
+```ts
+import express from 'express'
+import { initObservability, httpObservabilityMiddleware } from 'monten'
+
+const app = express()
+
+// Initialize observability
+initObservability({
+  serviceName: 'users-service',
+  enableLogging: true,
+  enableMetrics: true,
+})
+
+// Add middleware (single line!)
+app.use(httpObservabilityMiddleware())
+
+app.get('/health', (_req, res) => {
+  res.status(200).json({ ok: true })
+})
+
+app.listen(3000)
+```
+
+## Database Timing
+
+Use `withDbTiming` to measure any async operation — works with Prisma, Sequelize, raw SQL, Redis, HTTP calls, etc.
+
+```ts
+import { withDbTiming } from 'monten'
+import { prisma } from './prismaClient'
+
+app.get('/users/:id', async (req, res, next) => {
+  try {
+    const user = await withDbTiming(() =>
+      prisma.user.findUnique({ where: { id: req.params.id } })
+    )
+
+    if (!user) {
+      return res.status(404).json({ error: 'Not found' })
+    }
+
+    res.json(user)
+  } catch (err) {
+    next(err)
+  }
+})
+```
+
+## API Reference
+
+### `initObservability(config)`
+
+Initialize the observability system. Call once at app startup.
+
+```ts
+initObservability({
+  serviceName: 'my-service', // Service identifier in logs/metrics
+  enableLogging: true, // Enable structured JSON logging
+  enableMetrics: true, // Enable metrics collection & flushing
+  metricsFlushIntervalMs: 10000, // Optional: flush interval (default: 10s)
+})
+```
+
+### `httpObservabilityMiddleware()`
+
+Express middleware that captures request timing, errors, and emits logs/metrics.
+
+```ts
+app.use(httpObservabilityMiddleware())
+```
+
+### `withDbTiming<T>(fn: () => Promise<T>): Promise<T>`
+
+Wrap any async function to measure its duration and accumulate it in the request context.
+
+```ts
+const result = await withDbTiming(() => db.query('SELECT * FROM users'))
+```
+
+## Log Output
+
+Each request produces a structured JSON log entry:
+
+```json
+{
+  "level": "info",
+  "message": "http_request",
+  "timestamp": 1704307200000,
+  "serviceName": "users-service",
+  "requestId": "550e8400-e29b-41d4-a716-446655440000",
+  "fields": {
+    "method": "GET",
+    "path": "/users/123",
+    "statusCode": 200,
+    "latencyMs": 45,
+    "dbTimeMs": 12
+  }
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Express App                          │
+├─────────────────────────────────────────────────────────┤
+│  httpObservabilityMiddleware()                          │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │  AsyncLocalStorage Context                        │  │
+│  │  • requestId                                      │  │
+│  │  • startTimeMs                                    │  │
+│  │  • dbTimeMs (accumulated)                         │  │
+│  └───────────────────────────────────────────────────┘  │
+├─────────────────────────────────────────────────────────┤
+│  Route Handlers                                         │
+│  └─> withDbTiming(() => prisma.user.find(...))         │
+├─────────────────────────────────────────────────────────┤
+│  On Response Finish:                                    │
+│  • Structured JSON log → stdout                         │
+│  • Metric record → in-memory buffer                     │
+├─────────────────────────────────────────────────────────┤
+│  Background Flusher (setInterval)                       │
+│  • Drains buffer periodically                           │
+│  • Sends to pluggable sink                              │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Removing the Library
+
+This library is designed to be fully removable:
+
+1. Remove `initObservability()` call
+2. Remove `app.use(httpObservabilityMiddleware())`
+3. Remove `withDbTiming()` wrappers (just call the inner function directly)
+
+Your application will continue to function normally.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feat/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feat/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT © 2026
+
+---
+
+<p align="center">
+  <sub>Built with ❤️ for the Node.js community</sub>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monten",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Lightweight observability utilities for Express-based Node.js backends (experimental).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",