@mhmdhammoud/meritt-utils 1.5.3 → 1.5.5

package/dist/__tests__/logger.test.js

@@ -94,17 +94,19 @@ describe('route and format logs', () => {
         key0: 'val0',
         key1: 'val1',
     };
-    test('log info with details', () => {
+    test('log info with structured context (single object flattened)', () => {
         //@ts-ignore
         jest.spyOn(pino_1.pino, 'destination').mockReturnValue(PINO_DESTINATION);
         //@ts-ignore
         pino_1.pino.mockReturnValue(PINO);
         const logger = new logger_1.default(LOGGER_NAME);
         logger.info(LOG_EVENT, DETAILS);
-        expect(PINO.info).toHaveBeenCalledWith({
+        expect(PINO.info).toHaveBeenCalledWith(expect.objectContaining({
             component: LOGGER_NAME,
-            ...LOG_EVENT,
-            detail: [DETAILS],
-        });
+            code: LOG_EVENT.code,
+            msg: LOG_EVENT.msg,
+            key0: 'val0',
+            key1: 'val1',
+        }));
     });
 });

package/dist/lib/index.d.ts

@@ -4,3 +4,4 @@ export { default as Pdf } from './formatter';
 export { default as Colorful } from './colorful';
 export { default as ImageFull } from './imagefull';
 export { default as Logger } from './logger';
+export { runWithTrace, runWithTraceSync, getTraceContext, type TraceContext, } from './trace-store';

package/dist/lib/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logger = exports.ImageFull = exports.Colorful = exports.Pdf = exports.Formatter = exports.Crypto = void 0;
+exports.getTraceContext = exports.runWithTraceSync = exports.runWithTrace = exports.Logger = exports.ImageFull = exports.Colorful = exports.Pdf = exports.Formatter = exports.Crypto = void 0;
 var cypto_1 = require("./cypto");
 Object.defineProperty(exports, "Crypto", { enumerable: true, get: function () { return __importDefault(cypto_1).default; } });
 var formatter_1 = require("./formatter");
@@ -16,3 +16,7 @@ var imagefull_1 = require("./imagefull");
 Object.defineProperty(exports, "ImageFull", { enumerable: true, get: function () { return __importDefault(imagefull_1).default; } });
 var logger_1 = require("./logger");
 Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return __importDefault(logger_1).default; } });
+var trace_store_1 = require("./trace-store");
+Object.defineProperty(exports, "runWithTrace", { enumerable: true, get: function () { return trace_store_1.runWithTrace; } });
+Object.defineProperty(exports, "runWithTraceSync", { enumerable: true, get: function () { return trace_store_1.runWithTraceSync; } });
+Object.defineProperty(exports, "getTraceContext", { enumerable: true, get: function () { return trace_store_1.getTraceContext; } });

package/dist/lib/logger.d.ts

@@ -23,6 +23,13 @@ declare class Logger {
      * @param elasticConfig - Optional Elasticsearch configuration.
      */
     constructor(name: string, elasticConfig?: ElasticConfig);
+    /**
+     * Build ECS-aligned and structured log payload.
+     * - ECS: log.level, log.logger, event.code, service.name, service.environment, message
+     * - Structured: Single plain object flattened as top-level snake_case fields (Kibana filterable)
+     * - Trace: trace.id when running inside runWithTrace
+     */
+    private buildPayload;
     private log;
     /**
      * Logs an error message.
@@ -54,5 +61,15 @@ declare class Logger {
      * @param args - Additional arguments to include in the log.
      */
     trace(logEvent: LogEvent, ...args: unknown[]): void;
+    /**
+     * Runs an async operation and logs its duration.
+     * Adds event.duration (ms) for Kibana performance dashboards and alerts.
+     *
+     * @param logEvent - The event to log on completion
+     * @param fn - Async function to execute
+     * @param context - Optional context object (flattened as top-level fields)
+     * @returns Result of fn
+     */
+    withDuration<T>(logEvent: LogEvent, fn: () => Promise<T>, context?: Record<string, unknown>): Promise<T>;
 }
 export default Logger;

package/dist/lib/logger.js

@@ -36,8 +36,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isValidLogLevel = isValidLogLevel;
 const pino_1 = require("pino");
 const dotenv = __importStar(require("dotenv"));
+const os_1 = require("os");
 const elastic_transport_1 = require("./elastic-transport");
+const trace_store_1 = require("./trace-store");
 dotenv.config();
+/** Convert camelCase to snake_case for Kibana/ECS-friendly field names */
+const toSnakeCase = (str) => str.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+/** Check if value is a plain object (not Error, Date, Array, null) */
+const isPlainObject = (v) => v !== null &&
+    typeof v === 'object' &&
+    !Array.isArray(v) &&
+    !(v instanceof Error) &&
+    !(v instanceof Date);
 /**
  * Pino logger backend - singleton
  */
@@ -240,19 +250,64 @@ class Logger {
         this._name = name;
         this._logger = getLogger(elasticConfig);
     }
-    log(logLevel, logEvent, ...args) {
+    /**
+     * Build ECS-aligned and structured log payload.
+     * - ECS: log.level, log.logger, event.code, service.name, service.environment, message
+     * - Structured: Single plain object flattened as top-level snake_case fields (Kibana filterable)
+     * - Trace: trace.id when running inside runWithTrace
+     */
+    buildPayload(logLevel, logEvent, args) {
+        var _a, _b;
+        const isLocal = process.env.NODE_ENV === 'local' || process.env.NODE_ENV === 'test';
+        // ECS-aligned fields for Kibana Discover, Lens, alerts
+        const ecs = {
+            'log.level': logLevel,
+            'log.logger': this._name,
+            'event.code': logEvent.code,
+            message: logEvent.msg,
+            service: {
+                name: (_a = process.env.SERVER_NICKNAME) !== null && _a !== void 0 ? _a : 'unknown',
+                environment: (_b = process.env.NODE_ENV) !== null && _b !== void 0 ? _b : 'development',
+            },
+            host: {
+                name: (0, os_1.hostname)(),
+            },
+        };
+        // Trace context for request-scoped correlation
+        const trace = (0, trace_store_1.getTraceContext)();
+        if (trace) {
+            ;
+            ecs.trace = { id: trace.traceId };
+        }
+        // Structured context: flatten single plain object as top-level fields
         let detail;
-        if (process.env.NODE_ENV === 'local' || process.env.NODE_ENV === 'test') {
-            detail = args;
+        if (args.length === 1 &&
+            isPlainObject(args[0]) &&
+            Object.keys(args[0]).length > 0) {
+            const obj = args[0];
+            for (const [k, v] of Object.entries(obj)) {
+                const key = toSnakeCase(k);
+                ecs[key] = v;
+            }
         }
         else {
-            detail = JSON.stringify(args);
+            detail = isLocal ? args : JSON.stringify(args);
         }
-        this._logger[logLevel]({
+        // Legacy fields for backward compatibility (component, code, msg)
+        const base = {
+            ...ecs,
             component: this._name,
-            ...logEvent,
-            detail,
-        });
+            code: logEvent.code,
+            msg: logEvent.msg,
+        };
+        if (detail !== undefined) {
+            base.detail = detail;
+        }
+        return base;
+    }
+    log(logLevel, logEvent, ...args) {
+        const payload = this.buildPayload(logLevel, logEvent, args);
+        this._logger[logLevel](payload);
     }
     /**
      * Logs an error message.
@@ -294,5 +349,37 @@ class Logger {
     trace(logEvent, ...args) {
         this.log('trace', logEvent, ...args);
     }
+    /**
+     * Runs an async operation and logs its duration.
+     * Adds event.duration (ms) for Kibana performance dashboards and alerts.
+     *
+     * @param logEvent - The event to log on completion
+     * @param fn - Async function to execute
+     * @param context - Optional context object (flattened as top-level fields)
+     * @returns Result of fn
+     */
+    async withDuration(logEvent, fn, context) {
+        const start = Date.now();
+        try {
+            const result = await fn();
+            const durationMs = Date.now() - start;
+            const payload = this.buildPayload('info', logEvent, [
+                { ...context, duration_ms: durationMs, success: true },
+            ]);
+            this._logger.info(payload);
+            return result;
+        }
+        catch (error) {
+            const durationMs = Date.now() - start;
+            const errObj = error instanceof Error
+                ? { error_message: error.message, error_type: error.constructor.name }
+                : {};
+            const payload = this.buildPayload('error', logEvent, [
+                { ...context, ...errObj, duration_ms: durationMs, success: false },
+            ]);
+            this._logger.error(payload);
+            throw error;
+        }
+    }
 }
 exports.default = Logger;

package/dist/lib/trace-store.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Trace context for request-scoped correlation in Kibana.
+ * Enables filtering all logs from a single request/job by trace.id.
+ */
+export interface TraceContext {
+    /** Unique ID for the entire request/job flow */
+    traceId: string;
+    /** Optional span ID for sub-operations */
+    spanId?: string;
+}
+/**
+ * Run an async function with a new trace context.
+ * All Logger calls within the callback will automatically include trace.id.
+ *
+ * @param fn - Async function to run within the trace context
+ * @param traceId - Optional trace ID (defaults to random UUID)
+ * @returns Result of fn
+ */
+export declare const runWithTrace: <T>(fn: () => Promise<T>, traceId?: string) => Promise<T>;
+/**
+ * Run a sync function with a new trace context.
+ */
+export declare const runWithTraceSync: <T>(fn: () => T, traceId?: string) => T;
+/**
+ * Get the current trace context (if running inside runWithTrace).
+ */
+export declare const getTraceContext: () => TraceContext | undefined;

package/dist/lib/trace-store.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTraceContext = exports.runWithTraceSync = exports.runWithTrace = void 0;
+const async_hooks_1 = require("async_hooks");
+const crypto_1 = require("crypto");
+const traceStorage = new async_hooks_1.AsyncLocalStorage();
+/**
+ * Run an async function with a new trace context.
+ * All Logger calls within the callback will automatically include trace.id.
+ *
+ * @param fn - Async function to run within the trace context
+ * @param traceId - Optional trace ID (defaults to random UUID)
+ * @returns Result of fn
+ */
+const runWithTrace = async (fn, traceId) => {
+    const id = traceId !== null && traceId !== void 0 ? traceId : (0, crypto_1.randomUUID)();
+    return traceStorage.run({ traceId: id }, () => fn());
+};
+exports.runWithTrace = runWithTrace;
+/**
+ * Run a sync function with a new trace context.
+ */
+const runWithTraceSync = (fn, traceId) => {
+    const id = traceId !== null && traceId !== void 0 ? traceId : (0, crypto_1.randomUUID)();
+    return traceStorage.run({ traceId: id }, () => fn());
+};
+exports.runWithTraceSync = runWithTraceSync;
+/**
+ * Get the current trace context (if running inside runWithTrace).
+ */
+const getTraceContext = () => {
+    return traceStorage.getStore();
+};
+exports.getTraceContext = getTraceContext;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mhmdhammoud/meritt-utils",
-	"version": "1.5.3",
+	"version": "1.5.5",
 	"description": "",
 	"main": "./dist/index.js",
 	"private": false,
@@ -44,7 +44,7 @@
 	"author": "Mhmdhammoud",
 	"license": "ISC",
 	"dependencies": {
-		"@elastic/elasticsearch": "^9.3.2",
+		"@elastic/elasticsearch": "^8.17.0",
 		"axios": "^1.4.0",
 		"dotenv": "^16.4.1",
 		"imagesloaded": "^5.0.0",

package/src/__tests__/logger.test.ts

@@ -70,7 +70,7 @@ describe('route and format logs', () => {
 		key0: 'val0',
 		key1: 'val1',
 	}
-	test('log info with details', () => {
+	test('log info with structured context (single object flattened)', () => {
 		//@ts-ignore
 		jest.spyOn(pino, 'destination').mockReturnValue(PINO_DESTINATION)
 		//@ts-ignore
@@ -79,10 +79,14 @@ describe('route and format logs', () => {
 
 		logger.info(LOG_EVENT, DETAILS)
 
-		expect(PINO.info).toHaveBeenCalledWith({
-			component: LOGGER_NAME,
-			...LOG_EVENT,
-			detail: [DETAILS],
-		})
+		expect(PINO.info).toHaveBeenCalledWith(
+			expect.objectContaining({
+				component: LOGGER_NAME,
+				code: LOG_EVENT.code,
+				msg: LOG_EVENT.msg,
+				key0: 'val0',
+				key1: 'val1',
+			})
+		)
 	})
 })

package/src/lib/index.ts

@@ -4,3 +4,9 @@ export { default as Pdf } from './formatter'
 export { default as Colorful } from './colorful'
 export { default as ImageFull } from './imagefull'
 export { default as Logger } from './logger'
+export {
+	runWithTrace,
+	runWithTraceSync,
+	getTraceContext,
+	type TraceContext,
+} from './trace-store'

package/src/lib/logger.ts

@@ -1,10 +1,24 @@
-import { Logger as PinoLogger, pino, stdTimeFunctions } from 'pino'
+import {Logger as PinoLogger, pino, stdTimeFunctions} from 'pino'
 import * as dotenv from 'dotenv'
-import { createElasticTransport } from './elastic-transport'
-import { LOG_LEVEL, LogEvent, ElasticConfig } from '../types'
+import {hostname} from 'os'
+import {createElasticTransport} from './elastic-transport'
+import {getTraceContext} from './trace-store'
+import {LOG_LEVEL, LogEvent, ElasticConfig} from '../types'
 
 dotenv.config()
 
+/** Convert camelCase to snake_case for Kibana/ECS-friendly field names */
+const toSnakeCase = (str: string): string =>
+	str.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`)
+
+/** Check if value is a plain object (not Error, Date, Array, null) */
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+	v !== null &&
+	typeof v === 'object' &&
+	!Array.isArray(v) &&
+	!(v instanceof Error) &&
+	!(v instanceof Date)
+
 /**
  * Pino logger backend - singleton
  */
@@ -288,18 +302,69 @@ class Logger {
 		this._logger = getLogger(elasticConfig)
 	}
 
-	private log(logLevel: LOG_LEVEL, logEvent: LogEvent, ...args: unknown[]) {
-		let detail
-		if (process.env.NODE_ENV === 'local' || process.env.NODE_ENV === 'test') {
-			detail = args
+	/**
+	 * Build ECS-aligned and structured log payload.
+	 * - ECS: log.level, log.logger, event.code, service.name, service.environment, message
+	 * - Structured: Single plain object flattened as top-level snake_case fields (Kibana filterable)
+	 * - Trace: trace.id when running inside runWithTrace
+	 */
+	private buildPayload(logLevel: LOG_LEVEL, logEvent: LogEvent, args: unknown[]) {
+		const isLocal =
+			process.env.NODE_ENV === 'local' || process.env.NODE_ENV === 'test'
+
+		// ECS-aligned fields for Kibana Discover, Lens, alerts
+		const ecs: Record<string, unknown> = {
+			'log.level': logLevel,
+			'log.logger': this._name,
+			'event.code': logEvent.code,
+			message: logEvent.msg,
+			service: {
+				name: process.env.SERVER_NICKNAME ?? 'unknown',
+				environment: process.env.NODE_ENV ?? 'development',
+			},
+			host: {
+				name: hostname(),
+			},
+		}
+
+		// Trace context for request-scoped correlation
+		const trace = getTraceContext()
+		if (trace) {
+			;(ecs as Record<string, unknown>).trace = {id: trace.traceId}
+		}
+
+		// Structured context: flatten single plain object as top-level fields
+		let detail: unknown
+		if (
+			args.length === 1 &&
+			isPlainObject(args[0]) &&
+			Object.keys(args[0]).length > 0
+		) {
+			const obj = args[0] as Record<string, unknown>
+			for (const [k, v] of Object.entries(obj)) {
+				const key = toSnakeCase(k)
+				;(ecs as Record<string, unknown>)[key] = v
+			}
 		} else {
-			detail = JSON.stringify(args)
+			detail = isLocal ? args : JSON.stringify(args)
 		}
-		this._logger[logLevel]({
+
+		// Legacy fields for backward compatibility (component, code, msg)
+		const base: Record<string, unknown> = {
+			...ecs,
 			component: this._name,
-			...logEvent,
-			detail,
-		})
+			code: logEvent.code,
+			msg: logEvent.msg,
+		}
+		if (detail !== undefined) {
+			base.detail = detail
+		}
+		return base
+	}
+
+	private log(logLevel: LOG_LEVEL, logEvent: LogEvent, ...args: unknown[]) {
+		const payload = this.buildPayload(logLevel, logEvent, args)
+		this._logger[logLevel](payload)
 	}
 
 	/**
@@ -346,6 +411,43 @@ class Logger {
 	trace(logEvent: LogEvent, ...args: unknown[]) {
 		this.log('trace', logEvent, ...args)
 	}
+
+	/**
+	 * Runs an async operation and logs its duration.
+	 * Adds event.duration (ms) for Kibana performance dashboards and alerts.
+	 *
+	 * @param logEvent - The event to log on completion
+	 * @param fn - Async function to execute
+	 * @param context - Optional context object (flattened as top-level fields)
+	 * @returns Result of fn
+	 */
+	async withDuration<T>(
+		logEvent: LogEvent,
+		fn: () => Promise<T>,
+		context?: Record<string, unknown>
+	): Promise<T> {
+		const start = Date.now()
+		try {
+			const result = await fn()
+			const durationMs = Date.now() - start
+			const payload = this.buildPayload('info', logEvent, [
+				{...context, duration_ms: durationMs, success: true},
+			])
+			this._logger.info(payload)
+			return result
+		} catch (error) {
+			const durationMs = Date.now() - start
+			const errObj =
+				error instanceof Error
+					? {error_message: error.message, error_type: error.constructor.name}
+					: {}
+			const payload = this.buildPayload('error', logEvent, [
+				{...context, ...errObj, duration_ms: durationMs, success: false},
+			])
+			this._logger.error(payload)
+			throw error
+		}
+	}
 }
 
 export default Logger

package/src/lib/trace-store.ts

@@ -0,0 +1,46 @@
+import {AsyncLocalStorage} from 'async_hooks'
+import {randomUUID} from 'crypto'
+
+/**
+ * Trace context for request-scoped correlation in Kibana.
+ * Enables filtering all logs from a single request/job by trace.id.
+ */
+export interface TraceContext {
+	/** Unique ID for the entire request/job flow */
+	traceId: string
+	/** Optional span ID for sub-operations */
+	spanId?: string
+}
+
+const traceStorage = new AsyncLocalStorage<TraceContext>()
+
+/**
+ * Run an async function with a new trace context.
+ * All Logger calls within the callback will automatically include trace.id.
+ *
+ * @param fn - Async function to run within the trace context
+ * @param traceId - Optional trace ID (defaults to random UUID)
+ * @returns Result of fn
+ */
+export const runWithTrace = async <T>(
+	fn: () => Promise<T>,
+	traceId?: string
+): Promise<T> => {
+	const id = traceId ?? randomUUID()
+	return traceStorage.run({traceId: id}, () => fn())
+}
+
+/**
+ * Run a sync function with a new trace context.
+ */
+export const runWithTraceSync = <T>(fn: () => T, traceId?: string): T => {
+	const id = traceId ?? randomUUID()
+	return traceStorage.run({traceId: id}, () => fn())
+}
+
+/**
+ * Get the current trace context (if running inside runWithTrace).
+ */
+export const getTraceContext = (): TraceContext | undefined => {
+	return traceStorage.getStore()
+}