monten 0.1.0

package/dist/config/observability.config.d.ts

@@ -0,0 +1,3 @@
+import type { ObservabilityConfig, ObservabilityInitConfig } from '../types';
+export declare function initObservabilityInternal(config: ObservabilityInitConfig): void;
+export declare function getObservabilityConfig(): ObservabilityConfig;

package/dist/config/observability.config.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initObservabilityInternal = initObservabilityInternal;
+exports.getObservabilityConfig = getObservabilityConfig;
+const metricsFlusher_1 = require("../metrics/metricsFlusher");
+let currentConfig = {
+    serviceName: 'unknown-service',
+    enableLogging: true,
+    enableMetrics: false,
+    metricsFlushIntervalMs: 10000,
+};
+function initObservabilityInternal(config) {
+    var _a;
+    currentConfig = {
+        serviceName: config.serviceName,
+        enableLogging: config.enableLogging,
+        enableMetrics: config.enableMetrics,
+        metricsFlushIntervalMs: (_a = config.metricsFlushIntervalMs) !== null && _a !== void 0 ? _a : currentConfig.metricsFlushIntervalMs,
+    };
+    if (currentConfig.enableMetrics) {
+        (0, metricsFlusher_1.startMetricsFlusher)();
+    }
+    else {
+        (0, metricsFlusher_1.stopMetricsFlusher)();
+    }
+}
+function getObservabilityConfig() {
+    return currentConfig;
+}

package/dist/context/requestContext.d.ts

@@ -0,0 +1,5 @@
+import type { RequestContext } from '../types';
+export declare function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T;
+export declare function getRequestContext(): RequestContext | undefined;
+export declare function addDbTimeMs(deltaMs: number): void;
+export declare function setRequestError(error: unknown): void;

package/dist/context/requestContext.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithRequestContext = runWithRequestContext;
+exports.getRequestContext = getRequestContext;
+exports.addDbTimeMs = addDbTimeMs;
+exports.setRequestError = setRequestError;
+const async_hooks_1 = require("async_hooks");
+const storage = new async_hooks_1.AsyncLocalStorage();
+function runWithRequestContext(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+function getRequestContext() {
+    return storage.getStore();
+}
+function addDbTimeMs(deltaMs) {
+    const ctx = storage.getStore();
+    if (!ctx)
+        return;
+    ctx.dbTimeMs += deltaMs;
+}
+function setRequestError(error) {
+    const ctx = storage.getStore();
+    if (!ctx)
+        return;
+    ctx.error = error;
+}

package/dist/db/dbTimer.d.ts

@@ -0,0 +1 @@
+export declare function withDbTiming<T>(fn: () => Promise<T>): Promise<T>;

package/dist/db/dbTimer.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withDbTiming = withDbTiming;
+const requestContext_1 = require("../context/requestContext");
+const time_1 = require("../utils/time");
+async function withDbTiming(fn) {
+    const start = (0, time_1.monotonicNowMs)();
+    try {
+        const result = await fn();
+        return result;
+    }
+    finally {
+        const durationMs = (0, time_1.monotonicNowMs)() - start;
+        if (durationMs >= 0) {
+            (0, requestContext_1.addDbTimeMs)(durationMs);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { ObservabilityInitConfig } from './types';
+export declare function initObservability(config: ObservabilityInitConfig): void;
+export declare function httpObservabilityMiddleware(): (req: any, res: any, next: (err?: any) => void) => void;
+export declare function withDbTiming<T>(fn: () => Promise<T>): Promise<T>;

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initObservability = initObservability;
+exports.httpObservabilityMiddleware = httpObservabilityMiddleware;
+exports.withDbTiming = withDbTiming;
+const observability_config_1 = require("./config/observability.config");
+const httpMiddleware_1 = require("./middleware/httpMiddleware");
+const dbTimer_1 = require("./db/dbTimer");
+function initObservability(config) {
+    (0, observability_config_1.initObservabilityInternal)(config);
+}
+function httpObservabilityMiddleware() {
+    return (0, httpMiddleware_1.httpObservabilityMiddleware)();
+}
+function withDbTiming(fn) {
+    return (0, dbTimer_1.withDbTiming)(fn);
+}

package/dist/logger/format.d.ts

@@ -0,0 +1,2 @@
+import type { LogEntry } from '../types';
+export declare function formatLog(entry: LogEntry): string;

package/dist/logger/format.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatLog = formatLog;
+function formatLog(entry) {
+    return JSON.stringify(entry);
+}

package/dist/logger/logger.d.ts

@@ -0,0 +1,8 @@
+import type { LogLevel } from '../types';
+export declare function log(level: LogLevel, message: string, fields?: Record<string, unknown>): void;
+export declare const logger: {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+};

package/dist/logger/logger.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+exports.log = log;
+const observability_config_1 = require("../config/observability.config");
+const requestContext_1 = require("../context/requestContext");
+const format_1 = require("./format");
+const time_1 = require("../utils/time");
+function write(line) {
+    // Structured logging only, no console.log
+    process.stdout.write(line + '\n');
+}
+function createLogEntry(level, message, fields) {
+    const cfg = (0, observability_config_1.getObservabilityConfig)();
+    const ctx = (0, requestContext_1.getRequestContext)();
+    const base = {
+        level,
+        message,
+        timestamp: (0, time_1.nowMs)(),
+        serviceName: cfg.serviceName,
+    };
+    if (ctx === null || ctx === void 0 ? void 0 : ctx.requestId) {
+        base.requestId = ctx.requestId;
+    }
+    if (fields && Object.keys(fields).length > 0) {
+        base.fields = fields;
+    }
+    return base;
+}
+function log(level, message, fields) {
+    const cfg = (0, observability_config_1.getObservabilityConfig)();
+    if (!cfg.enableLogging)
+        return;
+    const entry = createLogEntry(level, message, fields);
+    write((0, format_1.formatLog)(entry));
+}
+exports.logger = {
+    debug(message, fields) {
+        log('debug', message, fields);
+    },
+    info(message, fields) {
+        log('info', message, fields);
+    },
+    warn(message, fields) {
+        log('warn', message, fields);
+    },
+    error(message, fields) {
+        log('error', message, fields);
+    },
+};

package/dist/metrics/metricsBuffer.d.ts

@@ -0,0 +1,3 @@
+import type { MetricRecord } from './metricsTypes';
+export declare function pushMetric(metric: MetricRecord): void;
+export declare function drainMetrics(): MetricRecord[];

package/dist/metrics/metricsBuffer.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushMetric = pushMetric;
+exports.drainMetrics = drainMetrics;
+const buffer = [];
+function pushMetric(metric) {
+    buffer.push(metric);
+}
+function drainMetrics() {
+    if (buffer.length === 0)
+        return [];
+    const copy = buffer.slice();
+    buffer.length = 0;
+    return copy;
+}

package/dist/metrics/metricsFlusher.d.ts

@@ -0,0 +1,6 @@
+import type { MetricsSink } from './metricsTypes';
+export declare function setMetricsSink(sink: MetricsSink | undefined): void;
+declare function flushOnce(): Promise<void>;
+export declare function startMetricsFlusher(): void;
+export declare function stopMetricsFlusher(): void;
+export { flushOnce as flushMetricsOnce };

package/dist/metrics/metricsFlusher.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setMetricsSink = setMetricsSink;
+exports.startMetricsFlusher = startMetricsFlusher;
+exports.stopMetricsFlusher = stopMetricsFlusher;
+exports.flushMetricsOnce = flushOnce;
+const observability_config_1 = require("../config/observability.config");
+const logger_1 = require("../logger/logger");
+const time_1 = require("../utils/time");
+const metricsBuffer_1 = require("./metricsBuffer");
+let flushTimer = null;
+let customSink;
+function defaultSink(batch) {
+    if (batch.length === 0)
+        return;
+    logger_1.logger.info('metrics_flush', {
+        count: batch.length,
+        flushedAt: (0, time_1.nowMs)(),
+        metrics: batch,
+    });
+}
+function setMetricsSink(sink) {
+    customSink = sink;
+}
+async function flushOnce() {
+    const cfg = (0, observability_config_1.getObservabilityConfig)();
+    if (!cfg.enableMetrics)
+        return;
+    const batch = (0, metricsBuffer_1.drainMetrics)();
+    if (batch.length === 0)
+        return;
+    const sink = customSink !== null && customSink !== void 0 ? customSink : defaultSink;
+    try {
+        await sink(batch);
+    }
+    catch (err) {
+        logger_1.logger.error('metrics_flush_failed', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+function startMetricsFlusher() {
+    const cfg = (0, observability_config_1.getObservabilityConfig)();
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+    if (!cfg.enableMetrics)
+        return;
+    flushTimer = setInterval(() => {
+        void flushOnce();
+    }, cfg.metricsFlushIntervalMs);
+}
+function stopMetricsFlusher() {
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+}

package/dist/metrics/metricsTypes.d.ts

@@ -0,0 +1,19 @@
+export type MetricType = 'http_request';
+export interface MetricBase {
+    type: MetricType;
+    timestamp: number;
+    serviceName: string;
+}
+export interface HttpRequestMetric extends MetricBase {
+    type: 'http_request';
+    method: string;
+    path: string;
+    statusCode: number;
+    latencyMs: number;
+    dbTimeMs: number;
+    success: boolean;
+    errorName?: string;
+    errorMessage?: string;
+}
+export type MetricRecord = HttpRequestMetric;
+export type MetricsSink = (batch: MetricRecord[]) => void | Promise<void>;

package/dist/metrics/metricsTypes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/middleware/httpMiddleware.d.ts

@@ -0,0 +1 @@
+export declare function httpObservabilityMiddleware(): (req: any, res: any, next: (err?: any) => void) => void;

package/dist/middleware/httpMiddleware.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpObservabilityMiddleware = httpObservabilityMiddleware;
+const observability_config_1 = require("../config/observability.config");
+const requestContext_1 = require("../context/requestContext");
+const logger_1 = require("../logger/logger");
+const metricsBuffer_1 = require("../metrics/metricsBuffer");
+const time_1 = require("../utils/time");
+const uuid_1 = require("../utils/uuid");
+function httpObservabilityMiddleware() {
+    return function httpMiddleware(req, res, next) {
+        const cfg = (0, observability_config_1.getObservabilityConfig)();
+        const requestId = (0, uuid_1.generateRequestId)();
+        const startTimeMs = (0, time_1.monotonicNowMs)();
+        const ctx = {
+            requestId,
+            startTimeMs,
+            dbTimeMs: 0,
+            error: undefined,
+        };
+        const wrappedNext = (err) => {
+            if (err) {
+                (0, requestContext_1.setRequestError)(err);
+            }
+            try {
+                next(err);
+            }
+            catch (error) {
+                (0, requestContext_1.setRequestError)(error);
+                throw error;
+            }
+        };
+        (0, requestContext_1.runWithRequestContext)(ctx, () => {
+            const method = req.method || 'UNKNOWN';
+            const path = req.path || req.url || 'UNKNOWN';
+            const onFinish = () => {
+                var _a;
+                res.removeListener('finish', onFinish);
+                res.removeListener('close', onFinish);
+                const endTimeMs = (0, time_1.monotonicNowMs)();
+                const latencyMs = endTimeMs - startTimeMs;
+                const statusCode = res.statusCode || 0;
+                const currentCtx = (_a = (0, requestContext_1.getRequestContext)()) !== null && _a !== void 0 ? _a : ctx;
+                const dbTimeMs = currentCtx.dbTimeMs;
+                const error = currentCtx.error;
+                const success = statusCode < 500;
+                if (cfg.enableLogging) {
+                    const logFields = {
+                        method,
+                        path,
+                        statusCode,
+                        latencyMs,
+                        dbTimeMs,
+                    };
+                    if (error) {
+                        logFields.errorName = error.name;
+                        logFields.errorMessage = error.message;
+                        logFields.errorStack = error.stack;
+                    }
+                    const level = success && !error ? 'info' : 'error';
+                    logger_1.logger[level]('http_request', logFields);
+                }
+                if (cfg.enableMetrics) {
+                    const metric = {
+                        type: 'http_request',
+                        timestamp: (0, time_1.nowMs)(),
+                        serviceName: cfg.serviceName,
+                        method,
+                        path,
+                        statusCode,
+                        latencyMs,
+                        dbTimeMs,
+                        success,
+                        errorName: error === null || error === void 0 ? void 0 : error.name,
+                        errorMessage: error === null || error === void 0 ? void 0 : error.message,
+                    };
+                    (0, metricsBuffer_1.pushMetric)(metric);
+                }
+            };
+            res.on('finish', onFinish);
+            res.on('close', onFinish);
+            wrappedNext();
+        });
+    };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,27 @@
+export interface ObservabilityInitConfig {
+    serviceName: string;
+    enableLogging: boolean;
+    enableMetrics: boolean;
+    metricsFlushIntervalMs?: number;
+}
+export interface ObservabilityConfig {
+    serviceName: string;
+    enableLogging: boolean;
+    enableMetrics: boolean;
+    metricsFlushIntervalMs: number;
+}
+export interface RequestContext {
+    requestId: string;
+    startTimeMs: number;
+    dbTimeMs: number;
+    error?: unknown;
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: number;
+    serviceName: string;
+    requestId?: string;
+    fields?: Record<string, unknown>;
+}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/time.d.ts

@@ -0,0 +1,2 @@
+export declare function nowMs(): number;
+export declare function monotonicNowMs(): number;

package/dist/utils/time.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nowMs = nowMs;
+exports.monotonicNowMs = monotonicNowMs;
+function nowMs() {
+    return Date.now();
+}
+function monotonicNowMs() {
+    // Uses high-resolution monotonic clock for durations
+    return Number(process.hrtime.bigint() / BigInt(1000000));
+}

package/dist/utils/uuid.d.ts

@@ -0,0 +1 @@
+export declare function generateRequestId(): string;

package/dist/utils/uuid.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRequestId = generateRequestId;
+const crypto_1 = require("crypto");
+function generateRequestId() {
+    var _a;
+    if (typeof ((_a = global.crypto) === null || _a === void 0 ? void 0 : _a.randomUUID) === 'function') {
+        return global.crypto.randomUUID();
+    }
+    const buf = (0, crypto_1.randomBytes)(16);
+    const hex = buf.toString('hex');
+    return [
+        hex.substring(0, 8),
+        hex.substring(8, 12),
+        hex.substring(12, 16),
+        hex.substring(16, 20),
+        hex.substring(20),
+    ].join('-');
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "monten",
+  "version": "0.1.0",
+  "description": "Lightweight observability utilities for Express-based Node.js backends (experimental).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "private": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "observability",
+    "logging",
+    "metrics",
+    "express",
+    "nodejs"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}