@bymax-one/nest-logger 1.1.0 → 1.2.0

package/dist/shared/index.cjs

@@ -14,14 +14,28 @@ var RESERVED_LOG_KEYS = Object.freeze({
   HTTP_REQUEST_CLIENT_ERROR: "HTTP_REQUEST_CLIENT_ERROR",
   HTTP_REQUEST_SERVER_ERROR: "HTTP_REQUEST_SERVER_ERROR",
   HTTP_REQUEST_COMPLETED: "HTTP_REQUEST_COMPLETED",
+  HTTP_REQUEST_ABORTED: "HTTP_REQUEST_ABORTED",
   HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
   HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
   METHOD_EXECUTION: "METHOD_EXECUTION",
   METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
   LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",
   LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED",
-  LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED"
+  LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED",
+  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED"
+});
+var RESERVED_LOG_KEYS_NOT_EMITTED = Object.freeze({
+  /**
+   * Superseded before it was ever used. The request lifecycle terminates in one
+   * of `HTTP_REQUEST_SUCCESS` / `_REDIRECT` / `_CLIENT_ERROR` / `_SERVER_ERROR`,
+   * each carrying the same `duration` a generic "completed" entry would. Emitting
+   * it as well would double the terminal access-log volume to say nothing new.
+   * It stays claimed so an application cannot repurpose a name that reads like a
+   * library event.
+   */
+  HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys"
 });
 
 exports.LOG_KEYS_CONVENTION_REGEX = LOG_KEYS_CONVENTION_REGEX;
 exports.RESERVED_LOG_KEYS = RESERVED_LOG_KEYS;
+exports.RESERVED_LOG_KEYS_NOT_EMITTED = RESERVED_LOG_KEYS_NOT_EMITTED;

package/dist/shared/index.d.cts

@@ -30,15 +30,31 @@ interface ServiceMetadata {
 /**
  * Shape of a single log entry as serialized to JSON output.
  *
- * Used by destinations and downstream parsers (Datadog, Loki, Elastic).
+ * Used by destinations and downstream parsers (Loki, Elastic, Datadog).
  * The trailing index signature `[key: string]: unknown` covers arbitrary
  * structured fields injected by application logs.
+ *
+ * `level` and `time` describe what the library ACTUALLY writes. Before `1.2.0`
+ * they were declared `number`, which the runtime never produced: the Pino
+ * instance is built with `formatters.level` returning the string label and a
+ * `timestamp` function emitting an ISO 8601 string. A destination written
+ * against the old declaration type-checked and then failed at runtime — the
+ * README's own Loki example called `BigInt(entry.time)` on an ISO string, which
+ * throws. See `log-entry-contract.e2e-spec.ts`, which asserts the declaration
+ * against a real serialized record so the two can never drift again.
  */
 interface LogEntry {
-    /** Pino numeric level (30 = info, 50 = error, etc.). */
-    level: number;
-    /** ISO 8601 UTC timestamp string OR epoch milliseconds (numeric). */
-    time: string | number;
+    /**
+     * Severity as the Pino string label (`'info'`, `'error'`, …) — NOT the numeric
+     * code. Convert with `PINO_LEVEL_NUMBERS` when a numeric column is needed.
+     */
+    level: LogLevel;
+    /**
+     * ISO 8601 UTC timestamp string, e.g. `'2026-08-12T09:25:46.520Z'`. Parse with
+     * `Date.parse(entry.time)` for epoch milliseconds. A consumer-supplied
+     * `timestamp` option may change the format, but never the type.
+     */
+    time: string;
     /** Human-readable message. */
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
@@ -92,6 +108,12 @@ declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
  *
  * Consumer apps SHOULD NOT use these names for application-level events
  * to avoid collision in log aggregation queries (Datadog, Loki, Elastic).
+ *
+ * Every key here is emitted by some code path, EXCEPT the ones listed in
+ * {@link RESERVED_LOG_KEYS_NOT_EMITTED}, which are reserved-only and carry the
+ * reason they stay that way. `reserved-log-keys.constants.spec.ts` enforces the
+ * split, so a key can never again be declared, documented as a signal, and then
+ * silently never written.
  */
 declare const RESERVED_LOG_KEYS: Readonly<{
     readonly LOGGER_BOOTSTRAP_OK: "LOGGER_BOOTSTRAP_OK";
@@ -103,6 +125,7 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly HTTP_REQUEST_CLIENT_ERROR: "HTTP_REQUEST_CLIENT_ERROR";
     readonly HTTP_REQUEST_SERVER_ERROR: "HTTP_REQUEST_SERVER_ERROR";
     readonly HTTP_REQUEST_COMPLETED: "HTTP_REQUEST_COMPLETED";
+    readonly HTTP_REQUEST_ABORTED: "HTTP_REQUEST_ABORTED";
     readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
     readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
     readonly METHOD_EXECUTION: "METHOD_EXECUTION";
@@ -110,6 +133,25 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
     readonly LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED";
     readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
+    readonly LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED";
+}>;
+/**
+ * Keys that are reserved but intentionally never emitted, each with the reason.
+ *
+ * A name in this map is claimed so no application event can take it, but the
+ * library commits to not writing it. Anything NOT listed here must be reachable
+ * from some code path — the spec asserts both directions.
+ */
+declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
+    /**
+     * Superseded before it was ever used. The request lifecycle terminates in one
+     * of `HTTP_REQUEST_SUCCESS` / `_REDIRECT` / `_CLIENT_ERROR` / `_SERVER_ERROR`,
+     * each carrying the same `duration` a generic "completed" entry would. Emitting
+     * it as well would double the terminal access-log volume to say nothing new.
+     * It stays claimed so an application cannot repurpose a name that reads like a
+     * library event.
+     */
+    readonly HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys";
 }>;
 /**
  * Strongly-typed union of every reserved log key value, derived from
@@ -117,4 +159,4 @@ declare const RESERVED_LOG_KEYS: Readonly<{
  */
 type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
-export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, type ReservedLogKey, type ServiceMetadata };
+export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ServiceMetadata };

package/dist/shared/index.d.ts

@@ -30,15 +30,31 @@ interface ServiceMetadata {
 /**
  * Shape of a single log entry as serialized to JSON output.
  *
- * Used by destinations and downstream parsers (Datadog, Loki, Elastic).
+ * Used by destinations and downstream parsers (Loki, Elastic, Datadog).
  * The trailing index signature `[key: string]: unknown` covers arbitrary
  * structured fields injected by application logs.
+ *
+ * `level` and `time` describe what the library ACTUALLY writes. Before `1.2.0`
+ * they were declared `number`, which the runtime never produced: the Pino
+ * instance is built with `formatters.level` returning the string label and a
+ * `timestamp` function emitting an ISO 8601 string. A destination written
+ * against the old declaration type-checked and then failed at runtime — the
+ * README's own Loki example called `BigInt(entry.time)` on an ISO string, which
+ * throws. See `log-entry-contract.e2e-spec.ts`, which asserts the declaration
+ * against a real serialized record so the two can never drift again.
  */
 interface LogEntry {
-    /** Pino numeric level (30 = info, 50 = error, etc.). */
-    level: number;
-    /** ISO 8601 UTC timestamp string OR epoch milliseconds (numeric). */
-    time: string | number;
+    /**
+     * Severity as the Pino string label (`'info'`, `'error'`, …) — NOT the numeric
+     * code. Convert with `PINO_LEVEL_NUMBERS` when a numeric column is needed.
+     */
+    level: LogLevel;
+    /**
+     * ISO 8601 UTC timestamp string, e.g. `'2026-08-12T09:25:46.520Z'`. Parse with
+     * `Date.parse(entry.time)` for epoch milliseconds. A consumer-supplied
+     * `timestamp` option may change the format, but never the type.
+     */
+    time: string;
     /** Human-readable message. */
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
@@ -92,6 +108,12 @@ declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
  *
  * Consumer apps SHOULD NOT use these names for application-level events
  * to avoid collision in log aggregation queries (Datadog, Loki, Elastic).
+ *
+ * Every key here is emitted by some code path, EXCEPT the ones listed in
+ * {@link RESERVED_LOG_KEYS_NOT_EMITTED}, which are reserved-only and carry the
+ * reason they stay that way. `reserved-log-keys.constants.spec.ts` enforces the
+ * split, so a key can never again be declared, documented as a signal, and then
+ * silently never written.
  */
 declare const RESERVED_LOG_KEYS: Readonly<{
     readonly LOGGER_BOOTSTRAP_OK: "LOGGER_BOOTSTRAP_OK";
@@ -103,6 +125,7 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly HTTP_REQUEST_CLIENT_ERROR: "HTTP_REQUEST_CLIENT_ERROR";
     readonly HTTP_REQUEST_SERVER_ERROR: "HTTP_REQUEST_SERVER_ERROR";
     readonly HTTP_REQUEST_COMPLETED: "HTTP_REQUEST_COMPLETED";
+    readonly HTTP_REQUEST_ABORTED: "HTTP_REQUEST_ABORTED";
     readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
     readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
     readonly METHOD_EXECUTION: "METHOD_EXECUTION";
@@ -110,6 +133,25 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
     readonly LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED";
     readonly LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED";
+    readonly LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED";
+}>;
+/**
+ * Keys that are reserved but intentionally never emitted, each with the reason.
+ *
+ * A name in this map is claimed so no application event can take it, but the
+ * library commits to not writing it. Anything NOT listed here must be reachable
+ * from some code path — the spec asserts both directions.
+ */
+declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
+    /**
+     * Superseded before it was ever used. The request lifecycle terminates in one
+     * of `HTTP_REQUEST_SUCCESS` / `_REDIRECT` / `_CLIENT_ERROR` / `_SERVER_ERROR`,
+     * each carrying the same `duration` a generic "completed" entry would. Emitting
+     * it as well would double the terminal access-log volume to say nothing new.
+     * It stays claimed so an application cannot repurpose a name that reads like a
+     * library event.
+     */
+    readonly HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys";
 }>;
 /**
  * Strongly-typed union of every reserved log key value, derived from
@@ -117,4 +159,4 @@ declare const RESERVED_LOG_KEYS: Readonly<{
  */
 type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
-export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, type ReservedLogKey, type ServiceMetadata };
+export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ServiceMetadata };

package/dist/shared/index.mjs

@@ -12,13 +12,26 @@ var RESERVED_LOG_KEYS = Object.freeze({
   HTTP_REQUEST_CLIENT_ERROR: "HTTP_REQUEST_CLIENT_ERROR",
   HTTP_REQUEST_SERVER_ERROR: "HTTP_REQUEST_SERVER_ERROR",
   HTTP_REQUEST_COMPLETED: "HTTP_REQUEST_COMPLETED",
+  HTTP_REQUEST_ABORTED: "HTTP_REQUEST_ABORTED",
   HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
   HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
   METHOD_EXECUTION: "METHOD_EXECUTION",
   METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
   LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",
   LOGGER_DESTINATION_WRITE_FAILED: "LOGGER_DESTINATION_WRITE_FAILED",
-  LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED"
+  LOGGER_ENTRY_TRUNCATED: "LOGGER_ENTRY_TRUNCATED",
+  LOGGER_REDACTION_FAILED: "LOGGER_REDACTION_FAILED"
+});
+var RESERVED_LOG_KEYS_NOT_EMITTED = Object.freeze({
+  /**
+   * Superseded before it was ever used. The request lifecycle terminates in one
+   * of `HTTP_REQUEST_SUCCESS` / `_REDIRECT` / `_CLIENT_ERROR` / `_SERVER_ERROR`,
+   * each carrying the same `duration` a generic "completed" entry would. Emitting
+   * it as well would double the terminal access-log volume to say nothing new.
+   * It stays claimed so an application cannot repurpose a name that reads like a
+   * library event.
+   */
+  HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys"
 });
 
-export { LOG_KEYS_CONVENTION_REGEX, RESERVED_LOG_KEYS };
+export { LOG_KEYS_CONVENTION_REGEX, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-logger",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Structured JSON logging for NestJS based on Pino 10, with optional OpenTelemetry correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",