@tclohm/yoban 1.0.0 → 1.0.2

package/README.MD

@@ -1,20 +1,26 @@
 # @tclohm/yoban
+> Lightweight, universal middleware for real-time API performance monitoring and SLA alerting.
 
-> Lightweight Express middleware for real-time API performance monitoring and SLA alerting.
+[![npm version](https://badge.fury.io/js/%40tclohm%2Fyoban.svg)](https://www.npmjs.com/package/@tclohm/yoban)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
 
 ## Install
-```
-npm install @tclohm/yoban 
+```bash
+npm install @tclohm/yoban
 ```
 
-## Usage
+---
+
+## Quick Start
 ```javascript
-import { yoban } from '@tclohm/yoban';
+import { Yoban } from '@tclohm/yoban';
 
-const metrics = new yoban({
+const yoban = new Yoban({
   service: "payments",
-  flushInterval: 10000,       // flush every 10s
-  violationThreshold: 0.5,    // alert if >50% of requests violate SLA
+  flushInterval: 10000,
+  violationThreshold: 0.5,
   sla: { premium: 400, standard: 800 },
   notify: {
     slack: process.env.SLACK_WEBHOOK,
@@ -24,20 +30,86 @@ const metrics = new yoban({
     tier: req.user?.tier ?? 'standard'
   })
 });
+```
 
-app.use(metrics.middleware());
+---
+
+## Framework Support
+
+### Express
+```javascript
+app.use(yoban.middleware());
 ```
 
+### Fastify
+```javascript
+fastify.addHook('onRequest', yoban.fastify().onRequest);
+fastify.addHook('onResponse', yoban.fastify().onResponse);
+```
+
+### Koa
+```javascript
+app.use(yoban.koa());
+```
+
+### Hapi
+```javascript
+await server.register(yoban.hapi());
+```
+
+---
+
 ## Config
+
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `service` | string | required | Name of your service |
 | `flushInterval` | number | 10000 | How often to flush in ms |
-| `violationThreshold` | number | 0.5 | Violation rate to trigger alert |
+| `violationThreshold` | number | 0.5 | Violation rate to trigger alert (0-1) |
 | `sla` | object | — | SLA thresholds per tier in ms |
 | `notify.slack` | string | — | Slack webhook URL |
 | `notify.pagerduty` | string | — | PagerDuty routing key |
-| `enrichEvent` | function | — | Add custom metadata per request |
+| `enrichEvent` | function | — | Attach custom metadata per request |
+
+---
+
+## How It Works
+```
+Request → Adapter (Express/Fastify/Koa/Hapi)
+        → Buffer
+        → Flush every N seconds
+        → Aggregate (mean, median, violation rate)
+        → Alert if violation rate exceeds threshold
+        → Notify (Slack, PagerDuty)
+```
+
+---
+
+## Roadmap
+
+### v1.1
+- [ ] TypeScript support
+- [ ] Config file support (`.yobanrc`)
+
+### v1.2
+- [ ] p50 / p90 / p95 percentiles in output
+- [ ] Email notifications via SendGrid
+- [ ] SMS notifications via Twilio
+- [ ] Discord webhook support
+
+### v2.0
+- [ ] Persistent storage — keep metrics across restarts
+- [ ] Dashboard UI to visualize metrics and violation rates
+- [ ] Anomaly detection — alert when something is unusually slow
+- [ ] Trend detection — "this endpoint has been getting slower over 24 hours"
+- [ ] Auto-tune SLA thresholds based on historical baselines
+
+### v2.1
+- [ ] Export to Datadog, Prometheus, Grafana
+- [ ] Kubernetes health check endpoint
+- [ ] CLI tool to replay and analyze log files
+
+---
 
 ## License
-MIT © tclohm
+MIT © [tclohm](https://github.com/tclohm)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tclohm/yoban",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Lightweight middleware for real-time API performance monitoring and SLA alerting",
   "keywords": [
     "monitoring",

package/src/yoban.js

@@ -1,7 +1,7 @@
 import { notifySlack } from './notifiers/slack.js';
 import { notifyPagerDuty } from './notifiers/pagerduty.js';
 
-export class yoban {
+export class Yoban {
   #buffer = [];
   #aggregated = [];
 
@@ -9,25 +9,17 @@ export class yoban {
     this.config = config;
     this.#startFlushing();
   }
-
-  middleware() {
-    return (req, res, next) => {
-      const start = Date.now();
-      res.on('finish', () => {
-        const duration = Date.now() - start;
-        const extra = this.config.enrichEvent ? this.config.enrichEvent(req) : {};
-        this.#buffer.push({
-          service: this.config.service,
-          method: req.method,
-          route: req.route?.path ?? req.path,
-          status: res.statusCode,
-          duration,
-          timestamp: Date.now(),
-          ...extra
-        });
-      });
-      next();
-    };
+  // --- Core ---
+  #record({ route, method, status, duration, extra = {} }) {
+    this.#buffer.push({
+      server: this.config.service,
+      method,
+      route,
+      status,
+      duration,
+      timestamp: Date.now(),
+      ...extra
+    });
   }
 
   #startFlushing() {
@@ -68,7 +60,7 @@ export class yoban {
       const violationRate = violations / entry.durations.length;
 
       if (violationRate > (this.config.violationThreshold ?? 0.5)) {
-        console.log(`[ yoban ALERT ]: ${entry.service} ${entry.route} (${entry.tier}) violation rate ${(violationRate * 100).toFixed(2)}%`);
+        console.log(`[ YOBAN ALERT ]: ${entry.service} ${entry.route} (${entry.tier}) violation rate ${(violationRate * 100).toFixed(2)}%`);
 
         if (this.config.notify?.slack) {
           await notifySlack(this.config.notify.slack, entry, violationRate);
@@ -79,4 +71,50 @@ export class yoban {
       }
     }
   }
+
+  // --- Framework Adapters ---
+  middleware() {
+    return (req, res, next) => {
+      const start = Date.now();
+      res.on('finish', () => {
+        const extra = this.config.enrichEvent ? this.config.enrichEvent(req) : {};
+        this.#record({ route: req.route?.path ?? req.path, method: req.method, status: res.statusCode, duration: Date.now() - start, extra });
+      });
+      next();
+    };
+  }
+
+  fastify() {
+    return {
+      onRequest:  (request, reply, done) => { requet.startTime = Date.now(); done(); },
+      onResponse: (request, reply, done) => {
+        const extra = this.config.enrichEvent ? this.config.enrichEvent(request) : {};
+        this.#record({ route: request.routerPath, method: request.method, status: reply.statusCode, duration: Date.now() - request.startTime, extra });
+        done();
+      }
+    };
+  }
+
+  koa() {
+    return async (ctx, next) => {
+      const start = Date.now();
+      await next();
+      const extra = this.config.enrichEvent ? this.config.enrichEvent(ctx) : {};
+      this.#record({ route: ctx.path , method: ctx.method, status: ctx.status, duration: Date.now() - start, extra });
+    };
+  }
+
+  hapi() {
+    return {
+      name: 'yoban',
+      register: (server) => {
+        server.ext('onPreResponse', (request, h) => {
+          const extra = this.config.enrichEvent > this.config.enrichEvent(request) : {};
+          this.#record({ route: request.method, status: request.response.statusCode, duration: Date.now() - request.infor.received, extra });
+          return h.continue;
+        })
+      }
+    }
+  }
+
 }