@mhmdhammoud/meritt-utils 1.5.4 → 1.5.6

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/elastic-transport.js

@@ -56,7 +56,7 @@ function initializeBulkHandler(opts, client, splitter) {
         datasource: splitter,
         flushBytes: (_e = (_d = opts.flushBytes) !== null && _d !== void 0 ? _d : opts['flush-bytes']) !== null && _e !== void 0 ? _e : 1000,
         flushInterval: (_g = (_f = opts.flushInterval) !== null && _f !== void 0 ? _f : opts['flush-interval']) !== null && _g !== void 0 ? _g : 3000,
-        refreshOnCompletion: indexName(),
+        refreshOnCompletion: false,
         onDocument(doc) {
             var _a, _b;
             const d = doc;

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
  */
@@ -198,6 +208,13 @@ function getLogger(elasticConfig) {
             esTransport.on('insertError', (err) => {
                 console.error('[Logger] Elasticsearch insert error:', err.message);
                 console.error('[Logger] Some logs failed to index to Elasticsearch.');
+                if (err.document) {
+                    const docStr = JSON.stringify(err.document);
+                    const preview = docStr.length > 500
+                        ? `${docStr.substring(0, 500)}... (truncated)`
+                        : docStr;
+                    console.error('[Logger] Dropped document preview:', preview);
+                }
             });
             // Log successful connection (for debugging)
             esTransport.on('insert', () => {
@@ -240,19 +257,67 @@ 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';
+        // Defensive: missing Logs constant (undefined) crashes on logEvent.code
+        const event = logEvent && typeof logEvent === 'object' && 'code' in logEvent
+            ? logEvent
+            : { code: 'UNKNOWN', msg: 'Missing or invalid log event constant' };
+        // ECS-aligned fields for Kibana (flat names to avoid mapping conflicts with existing indices)
+        const ecs = {
+            log_level: logLevel,
+            log_logger: this._name,
+            event_code: event.code,
+            message: event.msg,
+            service_name: (_a = process.env.SERVER_NICKNAME) !== null && _a !== void 0 ? _a : 'unknown',
+            service_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
+        // Sanitize values to avoid ES mapping conflicts (e.g. Error objects → serializable shape)
         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 instanceof Error
+                        ? { message: v.message, type: v.constructor.name }
+                        : 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: event.code,
+            msg: event.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 +359,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.4",
+	"version": "1.5.6",
 	"description": "",
 	"main": "./dist/index.js",
 	"private": false,

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/elastic-transport.ts

@@ -107,7 +107,7 @@ function initializeBulkHandler(
 		datasource: splitter as unknown as Readable,
 		flushBytes: opts.flushBytes ?? opts['flush-bytes'] ?? 1000,
 		flushInterval: opts.flushInterval ?? opts['flush-interval'] ?? 3000,
-		refreshOnCompletion: indexName(),
+		refreshOnCompletion: false,
 		onDocument(doc: unknown) {
 			const d = doc as LogDocument
 			const date = d.time ?? d['@timestamp'] ?? new Date().toISOString()

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 * as dotenv from 'dotenv'
+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
  */
@@ -214,9 +228,17 @@ function getLogger(elasticConfig?: ElasticConfig): PinoLogger {
 			})
 
 			// Handle insert errors (document indexing failures)
-			esTransport.on('insertError', (err: Error) => {
+			esTransport.on('insertError', (err: Error & { document?: unknown }) => {
 				console.error('[Logger] Elasticsearch insert error:', err.message)
 				console.error('[Logger] Some logs failed to index to Elasticsearch.')
+				if (err.document) {
+					const docStr = JSON.stringify(err.document)
+					const preview =
+						docStr.length > 500
+							? `${docStr.substring(0, 500)}... (truncated)`
+							: docStr
+					console.error('[Logger] Dropped document preview:', preview)
+				}
 			})
 
 			// Log successful connection (for debugging)
@@ -288,18 +310,79 @@ 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'
+
+		// Defensive: missing Logs constant (undefined) crashes on logEvent.code
+		const event =
+			logEvent && typeof logEvent === 'object' && 'code' in logEvent
+				? logEvent
+				: { code: 'UNKNOWN', msg: 'Missing or invalid log event constant' }
+
+		// ECS-aligned fields for Kibana (flat names to avoid mapping conflicts with existing indices)
+		const ecs: Record<string, unknown> = {
+			log_level: logLevel,
+			log_logger: this._name,
+			event_code: event.code,
+			message: event.msg,
+			service_name: process.env.SERVER_NICKNAME ?? 'unknown',
+			service_environment: process.env.NODE_ENV ?? 'development',
+			host_name: hostname(),
+		}
+
+		// Trace context for request-scoped correlation
+		const trace = getTraceContext()
+		if (trace) {
+			ecs.trace_id = trace.traceId
+		}
+
+		// Structured context: flatten single plain object as top-level fields
+		// Sanitize values to avoid ES mapping conflicts (e.g. Error objects → serializable shape)
+		let detail: unknown
+		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 instanceof Error
+						? { message: v.message, type: v.constructor.name }
+						: 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: event.code,
+			msg: event.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 +429,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()
+}