@mhmdhammoud/meritt-utils 1.5.6 → 1.5.8

package/dist/__tests__/logger.test.js

@@ -109,4 +109,26 @@ describe('route and format logs', () => {
             key1: 'val1',
         }));
     });
+    test('remap reserved elastic field names and reduce objects to scalars', () => {
+        //@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, {
+            _id: 'abc123',
+            nested: {
+                _id: 'nested-1',
+                _index: 'bad-index',
+            },
+        });
+        // Top-level fields use scalars only (avoids ES document_parsing_exception)
+        expect(PINO.info).toHaveBeenCalledWith(expect.objectContaining({
+            mongo_id: 'abc123',
+            nested: 'nested-1',
+        }));
+        expect(PINO.info).not.toHaveBeenCalledWith(expect.objectContaining({
+            _id: expect.anything(),
+        }));
+    });
 });

package/dist/lib/logger.js

@@ -42,12 +42,138 @@ 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()}`);
+/**
+ * Elasticsearch reserves metadata fields (e.g. `_id`) and rejects documents
+ * containing them in payload body. Remap them to safe application fields.
+ */
+const RESERVED_ES_FIELD_ALIASES = {
+    _id: 'mongo_id',
+    _index: 'es_index',
+    _type: 'es_type',
+    _score: 'es_score',
+    _source: 'es_source',
+    _routing: 'es_routing',
+    _seq_no: 'es_seq_no',
+    _primary_term: 'es_primary_term',
+    _version: 'es_version',
+};
+/** Convert arbitrary field names into ES-safe flattened keys */
+const toSafeElasticFieldName = (key) => {
+    const normalized = toSnakeCase(key);
+    const mapped = RESERVED_ES_FIELD_ALIASES[normalized];
+    if (mapped) {
+        return mapped;
+    }
+    // Any leading underscore can conflict with ES internals, remap defensively.
+    return normalized.startsWith('_') ? `meta${normalized}` : normalized;
+};
+const isObjectIdLike = (v) => v !== null &&
+    typeof v === 'object' &&
+    'toHexString' in v &&
+    typeof v.toHexString === 'function';
 /** 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);
+/**
+ * Reduces object values to scalars for top-level ES fields.
+ * ES text/keyword fields reject nested objects; use _id or truncated JSON.
+ */
+const toScalarForTopLevel = (value) => {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean')
+        return value;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (isObjectIdLike(value))
+        return value.toHexString();
+    if (value instanceof Error)
+        return value.message;
+    if (isPlainObject(value) && '_id' in value) {
+        const id = value._id;
+        if (id != null) {
+            if (typeof id === 'string')
+                return id;
+            if (isObjectIdLike(id))
+                return id.toHexString();
+            if (typeof id === 'object' && id !== null && 'toString' in id)
+                return String(id.toString());
+        }
+    }
+    const str = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    return str.length > 200 ? `${str.slice(0, 200)}...` : str;
+};
+/**
+ * Recursively sanitize log values for Elasticsearch safety.
+ * - Remaps reserved key names (e.g. `_id` -> `mongo_id`)
+ * - Converts Error to a stable serializable shape
+ * - Converts ObjectId-like objects to hex strings
+ * - Prevents circular structure failures
+ */
+const sanitizeForElastic = (value, seen = new WeakSet()) => {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (value instanceof Error) {
+        return { message: value.message, type: value.constructor.name };
+    }
+    if (isObjectIdLike(value)) {
+        return value.toHexString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeForElastic(item, seen));
+    }
+    if (isPlainObject(value)) {
+        if (seen.has(value)) {
+            return '[Circular]';
+        }
+        seen.add(value);
+        const sanitizedObject = {};
+        for (const [k, v] of Object.entries(value)) {
+            sanitizedObject[toSafeElasticFieldName(k)] = sanitizeForElastic(v, seen);
+        }
+        return sanitizedObject;
+    }
+    // Fallback for class instances and non-plain objects.
+    return String(value);
+};
+/**
+ * Captures the call site from the stack when log event is missing.
+ * Returns file:line (e.g. product.service.ts:2266) for Kibana/Elasticsearch filtering.
+ */
+const getCallSiteForMissingLog = () => {
+    var _a;
+    try {
+        const stack = (_a = new Error().stack) !== null && _a !== void 0 ? _a : '';
+        const lines = stack.split('\n');
+        // First frame outside Logger / node_modules / meritt-utils
+        const appFrame = lines.find((line) => !line.includes('node_modules') &&
+            !line.includes('meritt-utils') &&
+            !line.includes('Logger.'));
+        if (!appFrame)
+            return undefined;
+        // Extract file:line e.g. "product.service.ts:2266"
+        const match = appFrame.match(/([^/\\]+\.(?:ts|js|tsx|jsx)):(\d+)/);
+        if (match) {
+            return `${match[1]}:${match[2]}`;
+        }
+        return appFrame.trim().slice(0, 100);
+    }
+    catch (_b) {
+        return undefined;
+    }
+};
 /**
  * Pino logger backend - singleton
  */
@@ -267,9 +393,10 @@ class Logger {
         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' };
+        const useFallback = !logEvent || typeof logEvent !== 'object' || !('code' in logEvent);
+        const event = useFallback
+            ? { code: 'UNKNOWN', msg: 'Missing or invalid log event constant' }
+            : logEvent;
         // ECS-aligned fields for Kibana (flat names to avoid mapping conflicts with existing indices)
         const ecs = {
             log_level: logLevel,
@@ -286,22 +413,19 @@ class Logger {
             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)
+        // Use scalars only for top-level ES fields; text/keyword mappings reject nested objects
         let detail;
         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;
+                const key = toSafeElasticFieldName(k);
+                ecs[key] = toScalarForTopLevel(v);
             }
         }
         else {
-            detail = isLocal ? args : JSON.stringify(args);
+            detail = isLocal ? args : JSON.stringify(sanitizeForElastic(args));
         }
         // Legacy fields for backward compatibility (component, code, msg)
         const base = {
@@ -313,6 +437,13 @@ class Logger {
         if (detail !== undefined) {
             base.detail = detail;
         }
+        // When fallback used: add call site for Kibana/Elasticsearch querying
+        if (useFallback) {
+            const callSite = getCallSiteForMissingLog();
+            if (callSite) {
+                base.missing_log_call_site = callSite;
+            }
+        }
         return base;
     }
     log(logLevel, logEvent, ...args) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mhmdhammoud/meritt-utils",
-	"version": "1.5.6",
+	"version": "1.5.8",
 	"description": "",
 	"main": "./dist/index.js",
 	"private": false,

package/src/__tests__/logger.test.ts

@@ -89,4 +89,33 @@ describe('route and format logs', () => {
 			})
 		)
 	})
+
+	test('remap reserved elastic field names and reduce objects to scalars', () => {
+		//@ts-ignore
+		jest.spyOn(pino, 'destination').mockReturnValue(PINO_DESTINATION)
+		//@ts-ignore
+		pino.mockReturnValue(PINO)
+		const logger = new Logger(LOGGER_NAME)
+
+		logger.info(LOG_EVENT, {
+			_id: 'abc123',
+			nested: {
+				_id: 'nested-1',
+				_index: 'bad-index',
+			},
+		})
+
+		// Top-level fields use scalars only (avoids ES document_parsing_exception)
+		expect(PINO.info).toHaveBeenCalledWith(
+			expect.objectContaining({
+				mongo_id: 'abc123',
+				nested: 'nested-1',
+			})
+		)
+		expect(PINO.info).not.toHaveBeenCalledWith(
+			expect.objectContaining({
+				_id: expect.anything(),
+			})
+		)
+	})
 })

package/src/lib/logger.ts

@@ -11,6 +11,39 @@ dotenv.config()
 const toSnakeCase = (str: string): string =>
 	str.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`)
 
+/**
+ * Elasticsearch reserves metadata fields (e.g. `_id`) and rejects documents
+ * containing them in payload body. Remap them to safe application fields.
+ */
+const RESERVED_ES_FIELD_ALIASES: Record<string, string> = {
+	_id: 'mongo_id',
+	_index: 'es_index',
+	_type: 'es_type',
+	_score: 'es_score',
+	_source: 'es_source',
+	_routing: 'es_routing',
+	_seq_no: 'es_seq_no',
+	_primary_term: 'es_primary_term',
+	_version: 'es_version',
+}
+
+/** Convert arbitrary field names into ES-safe flattened keys */
+const toSafeElasticFieldName = (key: string): string => {
+	const normalized = toSnakeCase(key)
+	const mapped = RESERVED_ES_FIELD_ALIASES[normalized]
+	if (mapped) {
+		return mapped
+	}
+	// Any leading underscore can conflict with ES internals, remap defensively.
+	return normalized.startsWith('_') ? `meta${normalized}` : normalized
+}
+
+const isObjectIdLike = (v: unknown): v is { toHexString: () => string } =>
+	v !== null &&
+	typeof v === 'object' &&
+	'toHexString' in v &&
+	typeof (v as { toHexString?: unknown }).toHexString === 'function'
+
 /** Check if value is a plain object (not Error, Date, Array, null) */
 const isPlainObject = (v: unknown): v is Record<string, unknown> =>
 	v !== null &&
@@ -19,6 +52,116 @@ const isPlainObject = (v: unknown): v is Record<string, unknown> =>
 	!(v instanceof Error) &&
 	!(v instanceof Date)
 
+/**
+ * Reduces object values to scalars for top-level ES fields.
+ * ES text/keyword fields reject nested objects; use _id or truncated JSON.
+ */
+const toScalarForTopLevel = (
+	value: unknown
+): string | number | boolean | null => {
+	if (value === null || value === undefined) return null
+	if (
+		typeof value === 'string' ||
+		typeof value === 'number' ||
+		typeof value === 'boolean'
+	)
+		return value
+	if (value instanceof Date) return value.toISOString()
+	if (isObjectIdLike(value)) return value.toHexString()
+	if (value instanceof Error) return value.message
+	if (isPlainObject(value) && '_id' in value) {
+		const id = (value as { _id?: unknown })._id
+		if (id != null) {
+			if (typeof id === 'string') return id
+			if (isObjectIdLike(id)) return id.toHexString()
+			if (typeof id === 'object' && id !== null && 'toString' in id)
+				return String((id as { toString: () => string }).toString())
+		}
+	}
+	const str = typeof value === 'object' ? JSON.stringify(value) : String(value)
+	return str.length > 200 ? `${str.slice(0, 200)}...` : str
+}
+
+/**
+ * Recursively sanitize log values for Elasticsearch safety.
+ * - Remaps reserved key names (e.g. `_id` -> `mongo_id`)
+ * - Converts Error to a stable serializable shape
+ * - Converts ObjectId-like objects to hex strings
+ * - Prevents circular structure failures
+ */
+const sanitizeForElastic = (
+	value: unknown,
+	seen: WeakSet<object> = new WeakSet<object>()
+): unknown => {
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'number' ||
+		typeof value === 'boolean'
+	) {
+		return value
+	}
+
+	if (value instanceof Date) {
+		return value.toISOString()
+	}
+
+	if (value instanceof Error) {
+		return { message: value.message, type: value.constructor.name }
+	}
+
+	if (isObjectIdLike(value)) {
+		return value.toHexString()
+	}
+
+	if (Array.isArray(value)) {
+		return value.map((item) => sanitizeForElastic(item, seen))
+	}
+
+	if (isPlainObject(value)) {
+		if (seen.has(value)) {
+			return '[Circular]'
+		}
+		seen.add(value)
+
+		const sanitizedObject: Record<string, unknown> = {}
+		for (const [k, v] of Object.entries(value)) {
+			sanitizedObject[toSafeElasticFieldName(k)] = sanitizeForElastic(v, seen)
+		}
+		return sanitizedObject
+	}
+
+	// Fallback for class instances and non-plain objects.
+	return String(value)
+}
+
+/**
+ * Captures the call site from the stack when log event is missing.
+ * Returns file:line (e.g. product.service.ts:2266) for Kibana/Elasticsearch filtering.
+ */
+const getCallSiteForMissingLog = (): string | undefined => {
+	try {
+		const stack = new Error().stack ?? ''
+		const lines = stack.split('\n')
+		// First frame outside Logger / node_modules / meritt-utils
+		const appFrame = lines.find(
+			(line) =>
+				!line.includes('node_modules') &&
+				!line.includes('meritt-utils') &&
+				!line.includes('Logger.')
+		)
+		if (!appFrame) return undefined
+		// Extract file:line e.g. "product.service.ts:2266"
+		const match = appFrame.match(/([^/\\]+\.(?:ts|js|tsx|jsx)):(\d+)/)
+		if (match) {
+			return `${match[1]}:${match[2]}`
+		}
+		return appFrame.trim().slice(0, 100)
+	} catch {
+		return undefined
+	}
+}
+
 /**
  * Pino logger backend - singleton
  */
@@ -325,10 +468,11 @@ class Logger {
 			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' }
+		const useFallback =
+			!logEvent || typeof logEvent !== 'object' || !('code' in logEvent)
+		const event = useFallback
+			? { code: 'UNKNOWN', msg: 'Missing or invalid log event constant' }
+			: logEvent
 
 		// ECS-aligned fields for Kibana (flat names to avoid mapping conflicts with existing indices)
 		const ecs: Record<string, unknown> = {
@@ -348,7 +492,7 @@ class Logger {
 		}
 
 		// Structured context: flatten single plain object as top-level fields
-		// Sanitize values to avoid ES mapping conflicts (e.g. Error objects → serializable shape)
+		// Use scalars only for top-level ES fields; text/keyword mappings reject nested objects
 		let detail: unknown
 		if (
 			args.length === 1 &&
@@ -357,14 +501,11 @@ class Logger {
 		) {
 			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
+				const key = toSafeElasticFieldName(k)
+				ecs[key] = toScalarForTopLevel(v)
 			}
 		} else {
-			detail = isLocal ? args : JSON.stringify(args)
+			detail = isLocal ? args : JSON.stringify(sanitizeForElastic(args))
 		}
 
 		// Legacy fields for backward compatibility (component, code, msg)
@@ -377,6 +518,13 @@ class Logger {
 		if (detail !== undefined) {
 			base.detail = detail
 		}
+		// When fallback used: add call site for Kibana/Elasticsearch querying
+		if (useFallback) {
+			const callSite = getCallSiteForMissingLog()
+			if (callSite) {
+				base.missing_log_call_site = callSite
+			}
+		}
 		return base
 	}