@onlineapps/infra-logger 1.0.0 → 2.0.0

package/index.js

@@ -10,7 +10,7 @@
  * - serviceName for lifecycle logs
  * 
  * NOTE: Health checks are NOT logged (too verbose). All other infrastructure
- * operations should be logged with appropriate detail (input, output, process, fail).
+ * operations should be logged with appropriate detail (input, output, fail, lifecycle).
  * 
  * Usage:
  *   const { createLogger } = require('@onlineapps/infra-logger');
@@ -40,19 +40,23 @@
 
 /**
  * Sanitize input/output for logging (keep it concise, not full payload)
+ *
+ * The depth limit exists to stop DEEP STRUCTURES from filling the log line. It
+ * therefore applies to objects and arrays only: a scalar has no depth, and
+ * replacing one with `{_truncated: true}` deletes the very value the record was
+ * written to carry (queue names, output keys, statuses). Scalars are handled
+ * before the guard for exactly that reason — the length limit still applies to
+ * strings at any depth.
+ *
  * @param {*} value - Value to sanitize
- * @param {number} maxDepth - Maximum depth for nested objects
+ * @param {number} maxDepth - Maximum depth for nested objects and arrays
  * @returns {*} Sanitized value
  */
 function sanitizeValue(value, maxDepth = 2) {
-  if (maxDepth <= 0) {
-    return { _truncated: true };
-  }
-  
   if (value === null || value === undefined) {
     return value;
   }
-  
+
   if (typeof value === 'string') {
     // Truncate long strings
     if (value.length > 500) {
@@ -60,15 +64,26 @@ function sanitizeValue(value, maxDepth = 2) {
     }
     return value;
   }
-  
+
   if (typeof value === 'number' || typeof value === 'boolean') {
     return value;
   }
-  
+
+  if (maxDepth <= 0) {
+    return { _truncated: true };
+  }
+
   if (Buffer.isBuffer(value)) {
     return { type: 'Buffer', size: value.length };
   }
-  
+
+  if (value instanceof Date) {
+    // Object.keys(date) is empty, so without this branch a timestamp reaches the
+    // record as `{}` — the value is gone and nothing says so. An invalid Date is
+    // named rather than thrown: a logger must not raise from a logging call.
+    return Number.isNaN(value.getTime()) ? 'Invalid Date' : value.toISOString();
+  }
+
   if (Array.isArray(value)) {
     if (value.length > 10) {
       return { type: 'array', length: value.length, first_3: value.slice(0, 3).map(v => sanitizeValue(v, maxDepth - 1)) };
@@ -91,13 +106,131 @@ function sanitizeValue(value, maxDepth = 2) {
   return String(value);
 }
 
+/** Every message this package throws or writes carries the same context tag. */
+const CONTEXT = '[infra-logger]';
+
+/** The one usage example every constructor error points at. */
+const FIX = 'Fix: createLogger(\'api_gateway\', \'router\').';
+
+/**
+ * Reject a missing, non-string or empty logger identity at construction time.
+ *
+ * `service` and `layer` are what make a log line attributable; a record that
+ * carries `null` for either is unsearchable, and the defect surfaces far from
+ * the call that caused it (`architecture-principles.md` §4).
+ *
+ * @param {string} name - Argument name, as written in the signature.
+ * @param {*} value - Argument value as received.
+ * @throws {Error} Never returns for an invalid value.
+ */
+function requireIdentity(name, value) {
+  if (value === undefined || value === null) {
+    throw new Error(
+      `${CONTEXT} createLogger received no ${name} name - "${name}" must be a non-empty string. ${FIX}`
+    );
+  }
+  if (typeof value !== 'string') {
+    throw new Error(
+      `${CONTEXT} createLogger received a non-string ${name} - "${name}" must be a non-empty string, ` +
+      `got ${typeof value}. ${FIX}`
+    );
+  }
+  if (value.length === 0) {
+    throw new Error(
+      `${CONTEXT} createLogger received an empty ${name} - "${name}" must be a non-empty string. ${FIX}`
+    );
+  }
+}
+
+/**
+ * Serialize a record, and never throw out of a logging call.
+ *
+ * `JSON.stringify` throws on a circular reference and on a BigInt. Only
+ * `input`/`output` pass through the sanitizer; every other key of `data` reaches
+ * the record untouched, so an unserializable value there would propagate a
+ * TypeError out of a line whose only job was to describe the work. That kills
+ * the operation the logger was watching.
+ *
+ * The replacement is explicit, not silent: the frame — which is built from
+ * values known to be serializable — still ships, and the record states that the
+ * payload was dropped and why. A record that quietly shrank would be worse than
+ * a crash, because nobody would ever notice.
+ *
+ * Shape taken from the module-local copy in
+ * `api/shared/mq-client-core/src/transports/rabbitmqClient.js:64` (which had the
+ * try/catch the original lacked); the frame is kept here rather than discarded,
+ * so the line stays attributable.
+ *
+ * @param {Object} logEntry - The assembled record.
+ * @returns {string} JSON text, always.
+ */
+function serializeEntry(logEntry) {
+  try {
+    return JSON.stringify(logEntry);
+  } catch (error) {
+    const frame = { timestamp: logEntry.timestamp };
+    if ('workflow_id' in logEntry) {
+      frame.workflow_id = String(logEntry.workflow_id);
+    }
+    frame.context = String(logEntry.context);
+    frame.service = logEntry.service;
+    frame.layer = logEntry.layer;
+    frame.action = String(logEntry.action);
+    frame._serialization_failed = true;
+    frame._serialization_error = error.message;
+    return JSON.stringify(frame);
+  }
+}
+
+/**
+ * Describe a failure for the `error` field of a `fail()` record.
+ *
+ * Replaces `error?.message || error || 'Unknown error'`, a chain that collapsed
+ * three different situations — no error, an Error with an empty message, and a
+ * non-Error value — into one indistinguishable string
+ * (`architecture-principles.md` §3). A missing error is a defect in the CALLER,
+ * so it is named in the record; a logger must not throw at log time.
+ *
+ * @param {*} error - Whatever the caller passed as `data.error`.
+ * @returns {string} The message to record.
+ */
+function describeError(error) {
+  if (error === undefined || error === null) {
+    return `${CONTEXT} fail() called without an error - "data.error" must be an Error instance.`;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+/**
+ * Classify what the caller passed as `data.error`.
+ *
+ * @param {*} error - Whatever the caller passed as `data.error`.
+ * @returns {string} Constructor name, or 'missing' when nothing was passed.
+ */
+function describeErrorType(error) {
+  if (error === undefined || error === null) {
+    return 'missing';
+  }
+  if (error.constructor && typeof error.constructor.name === 'string') {
+    return error.constructor.name;
+  }
+  return typeof error;
+}
+
 /**
  * Create a structured logger for an infrastructure service
  * @param {string} service - Service name (e.g., 'api_gateway', 'api_monitoring')
  * @param {string} layer - Layer name (e.g., 'router', 'consumer', 'dispatcher')
- * @returns {Object} Logger with input, output, process, fail, lifecycle methods
+ * @returns {Object} Logger with input, output, fail, lifecycle methods
+ * @throws {Error} When service or layer is missing, not a string, or empty.
  */
 function createLogger(service, layer) {
+  requireIdentity('service', service);
+  requireIdentity('layer', layer);
+
   const formatLog = (contextId, action, data = {}) => {
     const logEntry = {
       timestamp: new Date().toISOString(),
@@ -127,7 +260,7 @@ function createLogger(service, layer) {
         input: sanitizeValue(input),
         ...rest
       });
-      console.log(prefix, JSON.stringify(logEntry));
+      console.log(prefix, serializeEntry(logEntry));
     },
     
     /**
@@ -145,25 +278,7 @@ function createLogger(service, layer) {
         output: sanitizeValue(output),
         ...rest
       });
-      console.log(prefix, JSON.stringify(logEntry));
-    },
-    
-    /**
-     * Log process (transformation/processing)
-     * @param {string} contextId - Workflow ID or service name
-     * @param {string} action - Action name
-     * @param {Object} data - Data with handler, function, input, output
-     */
-    process: (contextId, action, data = {}) => {
-      const { handler, function: fn, input, output, ...rest } = data;
-      const { prefix, logEntry } = formatLog(contextId, action, {
-        handler,
-        function: fn,
-        input: sanitizeValue(input),
-        output: sanitizeValue(output),
-        ...rest
-      });
-      console.log(prefix, JSON.stringify(logEntry));
+      console.log(prefix, serializeEntry(logEntry));
     },
     
     /**
@@ -177,14 +292,14 @@ function createLogger(service, layer) {
       const { prefix, logEntry } = formatLog(contextId, action, {
         handler,
         function: fn,
-        error: error?.message || error || 'Unknown error',
-        error_type: error?.constructor?.name || typeof error,
+        error: describeError(error),
+        error_type: describeErrorType(error),
         expected,
         received,
         input: sanitizeValue(input),
         ...rest
       });
-      console.error(prefix, JSON.stringify(logEntry));
+      console.error(prefix, serializeEntry(logEntry));
     },
     
     /**
@@ -208,63 +323,12 @@ function createLogger(service, layer) {
         ...rest
       };
       const prefix = `[${serviceName}:${service}:${layer}:${action}]`;
-      console.log(prefix, JSON.stringify(logEntry));
-    },
-    
-    /**
-     * Generic log (backward compatibility)
-     * @param {string} contextId - Workflow ID or service name
-     * @param {string} action - Action name
-     * @param {Object} data - Additional data
-     */
-    info: (contextId, action, data = {}) => {
-      const { prefix, logEntry } = formatLog(contextId, action, data);
-      console.log(prefix, JSON.stringify(logEntry));
-    },
-    
-    warn: (contextId, action, data = {}) => {
-      const { prefix, logEntry } = formatLog(contextId, action, data);
-      console.warn(prefix, JSON.stringify(logEntry));
-    },
-    
-    error: (contextId, action, data = {}) => {
-      const { prefix, logEntry } = formatLog(contextId, action, data);
-      console.error(prefix, JSON.stringify(logEntry));
+      console.log(prefix, serializeEntry(logEntry));
     }
   };
 }
 
-/**
- * Standalone structured log function (for inline use without creating logger)
- * @param {string} workflowId - Workflow ID
- * @param {string} service - Service name
- * @param {string} layer - Layer name
- * @param {string} action - Action name
- * @param {Object} data - Additional data
- * @param {string} level - Log level (info, warn, error)
- */
-function structuredLog(workflowId, service, layer, action, data = {}, level = 'info') {
-  const logEntry = {
-    timestamp: new Date().toISOString(),
-    workflow_id: workflowId,
-    service,
-    layer,
-    action,
-    ...data
-  };
-  const prefix = `[${workflowId}:${service}:${layer}:${action}]`;
-  
-  if (level === 'error') {
-    console.error(prefix, JSON.stringify(logEntry));
-  } else if (level === 'warn') {
-    console.warn(prefix, JSON.stringify(logEntry));
-  } else {
-    console.log(prefix, JSON.stringify(logEntry));
-  }
-}
-
 module.exports = {
-  createLogger,
-  structuredLog
+  createLogger
 };
 

package/package.json

@@ -1,16 +1,23 @@
 {
   "name": "@onlineapps/infra-logger",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Structured logging helper for infrastructure services",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"No tests yet\""
+    "test": "jest"
   },
-  "keywords": ["logging", "infrastructure", "structured"],
+  "keywords": [
+    "logging",
+    "infrastructure",
+    "structured"
+  ],
   "author": "OnlineApps",
   "license": "UNLICENSED",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
-  }
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "dependencies": {}
 }
-