@bymax-one/nest-logger 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -11,6 +11,27 @@ heading here.
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-08-13
+
+### Added
+
+- **`EmittedServiceResource` and `EmittedDeploymentResource` are exported.** `LogEntry['service']`
+  and `LogEntry['deployment']` have been typed by these interfaces since 1.2.1, but neither was
+  reexported from `@bymax-one/nest-logger/shared`, so a consumer could hold `entry.service` and had
+  no way to write its type — a function taking one had to inline the shape or reach for
+  `LogEntry['service']`. Reported by a consumer adopting 1.2.1.
+- **Every shared type is now reexported from the server subpath, not a subset.** `LogEntry` was
+  already there while the types of its own properties were not, which is the same defect one level
+  up. `ResolvedServiceMetadata` and `ReservedLogKey` join them for the same reason.
+- **`LogEntry` declares `'event.name'`.** The field has been emitted since 1.2.1 and documented as
+  part of the entry, but only the index signature covered it — so a consumer reading
+  `entry['event.name']` got `unknown` and needed a cast. A documented field that cannot be read
+  without a cast is not really published. The declaration describes the default key; a renamed
+  `eventNameField` still arrives through the index signature.
+
+Type-only change: `dist/*.mjs` and `dist/*.cjs` are byte-identical to 1.2.1, since `export type`
+erases at compile time. Only the `.d.ts` files differ.
+
 ## [1.2.1] - 2026-08-13
 
 ### Security
@@ -793,7 +814,8 @@ published `dist/` is identical — no runtime behaviour changes for consumers.
 - Professional CI suite: `ci.yml`, `bench.yml`, `codeql.yml`, `scorecard.yml`,
   `release.yml`, Dependabot, and issue templates
 
-[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.1...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.2.2...HEAD
+[1.2.2]: https://github.com/bymaxone/nest-logger/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/bymaxone/nest-logger/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/bymaxone/nest-logger/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/bymaxone/nest-logger/compare/v1.0.8...v1.1.0

package/README.md

@@ -101,10 +101,10 @@ pnpm add @bymax-one/nest-logger
 
 One package, two entry points — import only what your app needs:
 
-| Subpath    | Import                          | Purpose                                                                         |              Dependencies               |
-| ---------- | ------------------------------- | ------------------------------------------------------------------------------- | :-------------------------------------: |
-| **Server** | `@bymax-one/nest-logger`        | NestJS module, logger service, interceptor, filter, decorators, destinations    | NestJS 11, pino, rxjs, reflect-metadata |
-| **Shared** | `@bymax-one/nest-logger/shared` | Types, constants, the log-key regex — `LogLevel`, `LogEntry`, `ServiceMetadata` |                  None                   |
+| Subpath    | Import                          | Purpose                                                                                                                                                           |              Dependencies               |
+| ---------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------: |
+| **Server** | `@bymax-one/nest-logger`        | NestJS module, logger service, interceptor, filter, decorators, destinations                                                                                      | NestJS 11, pino, rxjs, reflect-metadata |
+| **Shared** | `@bymax-one/nest-logger/shared` | Types, constants, the log-key regex — `LogLevel`, `LogEntry`, `ServiceMetadata`, `ResolvedServiceMetadata`, `EmittedServiceResource`, `EmittedDeploymentResource` |                  None                   |
 
 ```
 shared (zero deps)
@@ -1093,7 +1093,28 @@ PINO_LEVEL_NAMES[30] // 'info' — numeric code → label
 ```typescript
 type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
 
-type ServiceMetadata = { name: string; version: string }
+// What you CONFIGURE.
+type ServiceMetadata = {
+  readonly name: string
+  readonly version: string
+  readonly namespace?: string
+  readonly instanceId?: string
+  readonly environment?: string
+}
+
+// What is EMITTED. Deliberately a different type: `instanceId` nests as
+// `service.instance.id`, and the environment is not under `service` at all.
+// Reusing the configuration type here would advertise `entry.service.instanceId`,
+// which no entry carries.
+type EmittedServiceResource = {
+  readonly name: string
+  readonly version: string
+  readonly namespace?: string
+  readonly instance?: { readonly id: string }
+  readonly [key: string]: unknown
+}
+
+type EmittedDeploymentResource = { readonly environment: { readonly name: string } }
 
 type LogEntry = {
   /** Pino string label — `'info'`, not `30`. Convert with `PINO_LEVEL_NUMBERS`. */
@@ -1102,7 +1123,12 @@ type LogEntry = {
   time: string
   msg: string
   logKey?: string
-  service?: ServiceMetadata
+  /** Present under `resourceFormat: 'nested'` (the default). */
+  service?: EmittedServiceResource
+  /** Present when an environment resolved — `deployment.environment.name`. */
+  deployment?: EmittedDeploymentResource
+  /** Derived from `logKey` unless `eventNameField: false`. */
+  'event.name'?: string
   context?: string
   requestId?: string
   tenantId?: string
@@ -1113,6 +1139,41 @@ type LogEntry = {
 }
 ```
 
+Under `resourceFormat: 'flat'` there is no `service` object at all — the values arrive as dotted
+top-level keys (`"service.instance.id"`), which the index signature already admits.
+
+The emitted types are exported, so a helper that receives one can be typed without inlining its
+shape:
+
+```typescript
+import type {
+  EmittedDeploymentResource,
+  EmittedServiceResource,
+  LogEntry
+} from '@bymax-one/nest-logger/shared'
+
+/** Build the identity triplet a backend joins on, from a parsed entry. */
+function identityOf(entry: LogEntry): string {
+  const service: EmittedServiceResource | undefined = entry.service
+  const deployment: EmittedDeploymentResource | undefined = entry.deployment
+  if (service === undefined) {
+    return 'unknown'
+  }
+  // `service.namespace` is part of the identity, not decoration: OTel allows two
+  // services to share a name when their namespaces differ, so a key built without
+  // it collapses them into one.
+  const namespace = service.namespace ?? 'no-namespace'
+  const instance = service.instance?.id ?? 'no-instance'
+  const environment = deployment?.environment.name ?? 'no-environment'
+  return `${namespace}/${service.name}@${service.version}/${instance}/${environment}`
+}
+
+/** `event.name` is declared, so it reads as a string without a cast. */
+function eventOf(entry: LogEntry): string | undefined {
+  return entry['event.name']
+}
+```
+
 ### `ILogDestination`
 
 ```typescript

package/dist/server/index.d.cts

@@ -125,6 +125,26 @@ interface ServiceMetadata {
      */
     readonly environment?: string;
 }
+/**
+ * Service identity after precedence has been applied.
+ *
+ * Distinct from {@link ServiceMetadata} because the optional fields here mean
+ * "resolved to nothing" rather than "not configured": every source — options,
+ * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, `NODE_ENV` — has already been
+ * consulted, and a field still absent will not appear on any entry.
+ */
+interface ResolvedServiceMetadata {
+    /** `service.name`, always present. */
+    name: string;
+    /** `service.version`, always present. */
+    version: string;
+    /** `service.namespace`, when any source supplied one. */
+    namespace?: string;
+    /** `service.instance.id`, when any source supplied one. */
+    instanceId?: string;
+    /** `deployment.environment.name`, when any source supplied one. */
+    environment?: string;
+}
 /**
  * The `service` block as it appears in an EMITTED record, under the default
  * `resourceFormat: 'nested'`.
@@ -512,6 +532,11 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
      */
     readonly HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys";
 }>;
+/**
+ * Strongly-typed union of every reserved log key value, derived from
+ * {@link RESERVED_LOG_KEYS}. Use this type to constrain log-key arguments.
+ */
+type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
 /**
  * Name-based recursive redaction.
@@ -1287,6 +1312,17 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
     /**
      * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
      * configuration shape: `service.instance.id` nests, and the environment lives
@@ -1337,4 +1373,4 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, applyRequestIdMiddleware };

package/dist/server/index.d.ts

@@ -125,6 +125,26 @@ interface ServiceMetadata {
      */
     readonly environment?: string;
 }
+/**
+ * Service identity after precedence has been applied.
+ *
+ * Distinct from {@link ServiceMetadata} because the optional fields here mean
+ * "resolved to nothing" rather than "not configured": every source — options,
+ * `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`, `NODE_ENV` — has already been
+ * consulted, and a field still absent will not appear on any entry.
+ */
+interface ResolvedServiceMetadata {
+    /** `service.name`, always present. */
+    name: string;
+    /** `service.version`, always present. */
+    version: string;
+    /** `service.namespace`, when any source supplied one. */
+    namespace?: string;
+    /** `service.instance.id`, when any source supplied one. */
+    instanceId?: string;
+    /** `deployment.environment.name`, when any source supplied one. */
+    environment?: string;
+}
 /**
  * The `service` block as it appears in an EMITTED record, under the default
  * `resourceFormat: 'nested'`.
@@ -512,6 +532,11 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
      */
     readonly HTTP_REQUEST_COMPLETED: "reserved: superseded by the four status-specific terminal keys";
 }>;
+/**
+ * Strongly-typed union of every reserved log key value, derived from
+ * {@link RESERVED_LOG_KEYS}. Use this type to constrain log-key arguments.
+ */
+type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
 /**
  * Name-based recursive redaction.
@@ -1287,6 +1312,17 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
     /**
      * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
      * configuration shape: `service.instance.id` nests, and the environment lives
@@ -1337,4 +1373,4 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ResolvedBymaxLoggerModuleOptions, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, applyRequestIdMiddleware };

package/dist/shared/index.d.cts

@@ -152,6 +152,17 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
     /**
      * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
      * configuration shape: `service.instance.id` nests, and the environment lives
@@ -258,4 +269,4 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
  */
 type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
-export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };
+export { type EmittedDeploymentResource, type EmittedServiceResource, LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };

package/dist/shared/index.d.ts

@@ -152,6 +152,17 @@ interface LogEntry {
     msg: string;
     /** Convention key — `MODULE_ACTION_RESULT` format. */
     logKey?: string;
+    /**
+     * OTel event name derived from {@link logKey} (`PAYMENT_FAILED` →
+     * `payment.failed`), emitted on structured calls unless `eventNameField` is
+     * `false`. Declared explicitly because the index signature below would type
+     * it `unknown`: a documented field a consumer cannot read without a cast is
+     * not really published.
+     *
+     * The key is configurable, so a renamed field arrives through the index
+     * signature instead — this declaration describes the default only.
+     */
+    'event.name'?: string;
     /**
      * Service identity as EMITTED — see {@link EmittedServiceResource}. Not the
      * configuration shape: `service.instance.id` nests, and the environment lives
@@ -258,4 +269,4 @@ declare const RESERVED_LOG_KEYS_NOT_EMITTED: Readonly<{
  */
 type ReservedLogKey = (typeof RESERVED_LOG_KEYS)[keyof typeof RESERVED_LOG_KEYS];
 
-export { LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };
+export { type EmittedDeploymentResource, type EmittedServiceResource, LOG_KEYS_CONVENTION_REGEX, type LogEntry, type LogLevel, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, type ReservedLogKey, type ResolvedServiceMetadata, type ServiceMetadata };

package/package.json

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