@zamatica/logger-configuration 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @zamatica/logger-configuration
+
+Configuration parameters and parsing for log levels, prefix, and color toggle. Built on `@zamatica/configuration`. Framework-agnostic core; NestJS-specific helpers behind the `/nestjs` subpath.
+
+## Install
+
+```bash
+bun add @zamatica/logger-configuration
+# Optional: install only if you want the NestJS helper
+bun add @nestjs/common
+```
+
+## Registered configuration parameters
+
+Importing `LoggerConfiguration` (decorator side-effect) registers three parameters with `ConfigurationService`:
+
+| Key                    | Type    | Default                       | Purpose                                            |
+|------------------------|---------|-------------------------------|----------------------------------------------------|
+| `LOG_LEVELS`           | string  | `"fatal,error,warn,info"`     | Comma-separated list of visible levels.            |
+| `LOG_PREFIX`           | string  | _falls back to env-var prefix_ | Prefix string for structured loggers.              |
+| `DISABLE_LOG_COLORING` | boolean | `false`                       | Strip ANSI color codes from console output.        |
+
+Canonical levels: `fatal`, `error`, `warn`, `info`, `debug`, `verbose`. Unknown levels in `LOG_LEVELS` are silently dropped.
+
+## Quick example (framework-agnostic)
+
+```ts
+import { LoggerConfiguration } from '@zamatica/logger-configuration';
+import { ConfigurationService } from '@zamatica/configuration';
+
+ConfigurationService.setAppEnvVarPrefix('MYAPP');
+ConfigurationService.initialize();
+
+const settings = LoggerConfiguration.parseLogSettings();
+// settings.levels          → ['fatal', 'error', 'warn', 'info']
+// settings.prefix          → 'myapp'
+// settings.disableColoring → false
+```
+
+## NestJS subpath
+
+For NestJS apps, map canonical levels to NestJS's `LogLevel` (note: NestJS uses `'log'` for info-level):
+
+```ts
+import { ConsoleLogger } from '@nestjs/common';
+import { mapToNestJsLogLevels } from '@zamatica/logger-configuration/nestjs';
+
+const settings = LoggerConfiguration.parseLogSettings();
+const nestLevels = mapToNestJsLogLevels(settings.levels);
+const logger = new ConsoleLogger({
+  prefix: settings.prefix,
+  logLevels: nestLevels,
+  colors: !settings.disableColoring,
+});
+```
+
+The `/nestjs` subpath is the only place `NestJsLogLevel` types appear, so non-NestJS consumers don't pull NestJS-shaped names into their type graph.
+
+## Testing the library
+
+Tests that use this library should re-register its parameters after `ConfigurationService.__resetForTesting()`:
+
+```ts
+import {
+  LOGGER_CONFIGURATION_PARAMETERS,
+} from '@zamatica/logger-configuration';
+
+beforeEach(() => {
+  ConfigurationService.__resetForTesting();
+  ConfigurationService.setAppEnvVarPrefix('TESTAPP');
+  ConfigurationService.register(
+    [...LOGGER_CONFIGURATION_PARAMETERS],
+    'LoggerConfiguration',
+  );
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { LoggerConfiguration, LOGGER_CONFIGURATION_PARAMETERS, } from './logger-configuration.js';
+export { CANONICAL_LOG_LEVELS, type CanonicalLogLevel, type LogSettings, } from './log-settings.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { LoggerConfiguration, LOGGER_CONFIGURATION_PARAMETERS, } from './logger-configuration.js';
+export { CANONICAL_LOG_LEVELS, } from './log-settings.js';
+// NOTE: The NestJS-specific helpers (`mapToNestJsLogLevels`, `NestJsLogLevel`)
+// are intentionally NOT re-exported. Import them from
+// `@zamatica/logger-configuration/nestjs` — that subpath is the only place
+// pulling NestJS-shaped names into a consumer's type graph.

package/dist/log-settings.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Canonical log levels recognized by `@zamatica/logger-configuration`.
+ *
+ * Frameworks that use different names (e.g. NestJS uses `'log'` for info-level
+ * messages) provide a mapping helper in their respective subpath export
+ * (`@zamatica/logger-configuration/nestjs`).
+ */
+export type CanonicalLogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+export declare const CANONICAL_LOG_LEVELS: readonly CanonicalLogLevel[];
+export interface LogSettings {
+    /** Visible levels in declared (priority) order. */
+    levels: CanonicalLogLevel[];
+    /** Prefix string used by structured loggers. Defaults to the app env-var prefix lowercased. */
+    prefix: string;
+    /** Whether to strip ANSI color codes from console output. */
+    disableColoring: boolean;
+}
+//# sourceMappingURL=log-settings.d.ts.map

package/dist/log-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-settings.d.ts","sourceRoot":"","sources":["../src/log-settings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,OAAO,GACP,SAAS,CAAC;AAEd,eAAO,MAAM,oBAAoB,EAAE,SAAS,iBAAiB,EAOnD,CAAC;AAEX,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,eAAe,EAAE,OAAO,CAAC;CAC1B"}

package/dist/log-settings.js

@@ -0,0 +1,8 @@
+export const CANONICAL_LOG_LEVELS = [
+    'fatal',
+    'error',
+    'warn',
+    'info',
+    'debug',
+    'verbose',
+];

package/dist/logger-configuration.d.ts

@@ -0,0 +1,24 @@
+import { type ConfigurationParameterDefinition } from '@zamatica/configuration';
+import { type LogSettings } from './log-settings.js';
+/**
+ * The three configuration parameters owned by this library, exported so that
+ * tests can re-register them after `ConfigurationService.__resetForTesting()`
+ * clears the registry. The decorator below registers the same list at
+ * class-load time for normal runtime use.
+ */
+export declare const LOGGER_CONFIGURATION_PARAMETERS: readonly ConfigurationParameterDefinition[];
+/**
+ * Registers `LOG_LEVELS`, `LOG_PREFIX`, and `DISABLE_LOG_COLORING` at module
+ * load time. Consumers call `LoggerConfiguration.parseLogSettings()` after
+ * `ConfigurationService.initialize()` runs (or any time after registration if
+ * the defaults are acceptable).
+ *
+ * The returned object is plain — frameworks adapt it to their own log-level
+ * types via subpath helpers (e.g. the NestJS adapter at
+ * `@zamatica/logger-configuration/nestjs`).
+ */
+export declare class LoggerConfiguration {
+    /** Reads the registered parameters and returns a normalized settings object. */
+    static parseLogSettings(): LogSettings;
+}
+//# sourceMappingURL=logger-configuration.d.ts.map

package/dist/logger-configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-configuration.d.ts","sourceRoot":"","sources":["../src/logger-configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gCAAgC,EAEtC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,EAAE,SAAS,gCAAgC,EAsBtF,CAAC;AAEF;;;;;;;;;GASG;AACH,qBACa,mBAAmB;IAC9B,gFAAgF;IAChF,MAAM,CAAC,gBAAgB,IAAI,WAAW;CAcvC"}

package/dist/logger-configuration.js

@@ -0,0 +1,65 @@
+import { __decorate } from "tslib";
+import { Configuration, ConfigurationParameter, ConfigurationService, } from '@zamatica/configuration';
+import { CANONICAL_LOG_LEVELS, } from './log-settings.js';
+/**
+ * The three configuration parameters owned by this library, exported so that
+ * tests can re-register them after `ConfigurationService.__resetForTesting()`
+ * clears the registry. The decorator below registers the same list at
+ * class-load time for normal runtime use.
+ */
+export const LOGGER_CONFIGURATION_PARAMETERS = [
+    ConfigurationParameter.named('LOG_LEVELS')
+        .string()
+        .default('fatal,error,warn,info')
+        .description('Comma-separated list of visible log levels: fatal, error, warn, info, debug, verbose')
+        .required()
+        .build(),
+    ConfigurationParameter.named('LOG_PREFIX')
+        .string()
+        .description('Prefix string used by structured loggers; defaults to the app env-var prefix lowercase')
+        .optional()
+        .build(),
+    ConfigurationParameter.named('DISABLE_LOG_COLORING')
+        .boolean()
+        .default(false)
+        .description('Strip ANSI color codes from console output')
+        .optional()
+        .build(),
+];
+/**
+ * Registers `LOG_LEVELS`, `LOG_PREFIX`, and `DISABLE_LOG_COLORING` at module
+ * load time. Consumers call `LoggerConfiguration.parseLogSettings()` after
+ * `ConfigurationService.initialize()` runs (or any time after registration if
+ * the defaults are acceptable).
+ *
+ * The returned object is plain — frameworks adapt it to their own log-level
+ * types via subpath helpers (e.g. the NestJS adapter at
+ * `@zamatica/logger-configuration/nestjs`).
+ */
+let LoggerConfiguration = class LoggerConfiguration {
+    /** Reads the registered parameters and returns a normalized settings object. */
+    static parseLogSettings() {
+        const rawLevels = ConfigurationService.get('LOG_LEVELS');
+        const levels = parseCanonicalLevels(rawLevels);
+        const explicitPrefix = ConfigurationService.get('LOG_PREFIX');
+        const prefix = explicitPrefix && explicitPrefix.length > 0
+            ? explicitPrefix
+            : ConfigurationService.getAppEnvVarPrefix().toLowerCase();
+        const disableColoring = ConfigurationService.get('DISABLE_LOG_COLORING') ?? false;
+        return { levels, prefix, disableColoring };
+    }
+};
+LoggerConfiguration = __decorate([
+    Configuration('LoggerConfiguration', ...LOGGER_CONFIGURATION_PARAMETERS)
+], LoggerConfiguration);
+export { LoggerConfiguration };
+function parseCanonicalLevels(raw) {
+    if (raw === undefined || raw.length === 0)
+        return [];
+    const tokens = raw
+        .split(',')
+        .map((token) => token.trim().toLowerCase())
+        .filter((token) => token.length > 0);
+    const validSet = new Set(CANONICAL_LOG_LEVELS);
+    return tokens.filter((token) => validSet.has(token));
+}

package/dist/nestjs-helpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Subset of `@nestjs/common`'s `LogLevel` we map to. Defined locally so this
+ * file compiles even when `@nestjs/common` isn't installed (it's an optional
+ * peer dep). Structurally compatible with NestJS's actual `LogLevel`.
+ */
+export type NestJsLogLevel = 'fatal' | 'error' | 'warn' | 'log' | 'debug' | 'verbose';
+/**
+ * Maps canonical log levels to NestJS's level naming. The only non-identity
+ * mapping is `'info'` → `'log'`. Unknown level strings are silently dropped.
+ */
+export declare function mapToNestJsLogLevels(levels: readonly string[]): NestJsLogLevel[];
+//# sourceMappingURL=nestjs-helpers.d.ts.map

package/dist/nestjs-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nestjs-helpers.d.ts","sourceRoot":"","sources":["../src/nestjs-helpers.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC;AAWtF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,EAAE,CAOhF"}

package/dist/nestjs-helpers.js

@@ -0,0 +1,21 @@
+const CANONICAL_TO_NEST = {
+    fatal: 'fatal',
+    error: 'error',
+    warn: 'warn',
+    info: 'log', // NestJS uses 'log' for info-level messages.
+    debug: 'debug',
+    verbose: 'verbose',
+};
+/**
+ * Maps canonical log levels to NestJS's level naming. The only non-identity
+ * mapping is `'info'` → `'log'`. Unknown level strings are silently dropped.
+ */
+export function mapToNestJsLogLevels(levels) {
+    const result = [];
+    for (const level of levels) {
+        const mapped = CANONICAL_TO_NEST[level];
+        if (mapped !== undefined)
+            result.push(mapped);
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@zamatica/logger-configuration",
+  "version": "0.1.0",
+  "description": "Configuration parameters and parsing for log levels, prefix, and color toggle. Framework-agnostic core; NestJS-specific helpers behind the /nestjs subpath.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zamatica/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./nestjs": {
+      "@zamatica/source": "./src/nestjs-helpers.ts",
+      "types": "./dist/nestjs-helpers.d.ts",
+      "import": "./dist/nestjs-helpers.js",
+      "default": "./dist/nestjs-helpers.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/*.tsbuildinfo",
+    "!**/*.spec.*",
+    "!**/*.test.*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoobroker/zamatica-libs.git",
+    "directory": "libs/logger-configuration"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zamatica/configuration": "workspace:^",
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export {
+  LoggerConfiguration,
+  LOGGER_CONFIGURATION_PARAMETERS,
+} from './logger-configuration.js';
+export {
+  CANONICAL_LOG_LEVELS,
+  type CanonicalLogLevel,
+  type LogSettings,
+} from './log-settings.js';
+
+// NOTE: The NestJS-specific helpers (`mapToNestJsLogLevels`, `NestJsLogLevel`)
+// are intentionally NOT re-exported. Import them from
+// `@zamatica/logger-configuration/nestjs` — that subpath is the only place
+// pulling NestJS-shaped names into a consumer's type graph.

package/src/log-settings.ts

@@ -0,0 +1,32 @@
+/**
+ * Canonical log levels recognized by `@zamatica/logger-configuration`.
+ *
+ * Frameworks that use different names (e.g. NestJS uses `'log'` for info-level
+ * messages) provide a mapping helper in their respective subpath export
+ * (`@zamatica/logger-configuration/nestjs`).
+ */
+export type CanonicalLogLevel =
+  | 'fatal'
+  | 'error'
+  | 'warn'
+  | 'info'
+  | 'debug'
+  | 'verbose';
+
+export const CANONICAL_LOG_LEVELS: readonly CanonicalLogLevel[] = [
+  'fatal',
+  'error',
+  'warn',
+  'info',
+  'debug',
+  'verbose',
+] as const;
+
+export interface LogSettings {
+  /** Visible levels in declared (priority) order. */
+  levels: CanonicalLogLevel[];
+  /** Prefix string used by structured loggers. Defaults to the app env-var prefix lowercased. */
+  prefix: string;
+  /** Whether to strip ANSI color codes from console output. */
+  disableColoring: boolean;
+}

package/src/logger-configuration.ts

@@ -0,0 +1,81 @@
+import {
+  Configuration,
+  ConfigurationParameter,
+  type ConfigurationParameterDefinition,
+  ConfigurationService,
+} from '@zamatica/configuration';
+
+import {
+  CANONICAL_LOG_LEVELS,
+  type CanonicalLogLevel,
+  type LogSettings,
+} from './log-settings.js';
+
+/**
+ * The three configuration parameters owned by this library, exported so that
+ * tests can re-register them after `ConfigurationService.__resetForTesting()`
+ * clears the registry. The decorator below registers the same list at
+ * class-load time for normal runtime use.
+ */
+export const LOGGER_CONFIGURATION_PARAMETERS: readonly ConfigurationParameterDefinition[] = [
+  ConfigurationParameter.named('LOG_LEVELS')
+    .string()
+    .default('fatal,error,warn,info')
+    .description(
+      'Comma-separated list of visible log levels: fatal, error, warn, info, debug, verbose',
+    )
+    .required()
+    .build(),
+  ConfigurationParameter.named('LOG_PREFIX')
+    .string()
+    .description(
+      'Prefix string used by structured loggers; defaults to the app env-var prefix lowercase',
+    )
+    .optional()
+    .build(),
+  ConfigurationParameter.named('DISABLE_LOG_COLORING')
+    .boolean()
+    .default(false)
+    .description('Strip ANSI color codes from console output')
+    .optional()
+    .build(),
+];
+
+/**
+ * Registers `LOG_LEVELS`, `LOG_PREFIX`, and `DISABLE_LOG_COLORING` at module
+ * load time. Consumers call `LoggerConfiguration.parseLogSettings()` after
+ * `ConfigurationService.initialize()` runs (or any time after registration if
+ * the defaults are acceptable).
+ *
+ * The returned object is plain — frameworks adapt it to their own log-level
+ * types via subpath helpers (e.g. the NestJS adapter at
+ * `@zamatica/logger-configuration/nestjs`).
+ */
+@Configuration('LoggerConfiguration', ...LOGGER_CONFIGURATION_PARAMETERS)
+export class LoggerConfiguration {
+  /** Reads the registered parameters and returns a normalized settings object. */
+  static parseLogSettings(): LogSettings {
+    const rawLevels = ConfigurationService.get<string>('LOG_LEVELS');
+    const levels = parseCanonicalLevels(rawLevels);
+
+    const explicitPrefix = ConfigurationService.get<string>('LOG_PREFIX');
+    const prefix =
+      explicitPrefix && explicitPrefix.length > 0
+        ? explicitPrefix
+        : ConfigurationService.getAppEnvVarPrefix().toLowerCase();
+
+    const disableColoring = ConfigurationService.get<boolean>('DISABLE_LOG_COLORING') ?? false;
+
+    return { levels, prefix, disableColoring };
+  }
+}
+
+function parseCanonicalLevels(raw: string | undefined): CanonicalLogLevel[] {
+  if (raw === undefined || raw.length === 0) return [];
+  const tokens = raw
+    .split(',')
+    .map((token) => token.trim().toLowerCase())
+    .filter((token) => token.length > 0);
+  const validSet = new Set<string>(CANONICAL_LOG_LEVELS);
+  return tokens.filter((token): token is CanonicalLogLevel => validSet.has(token));
+}

package/src/nestjs-helpers.ts

@@ -0,0 +1,30 @@
+import type { CanonicalLogLevel } from './log-settings.js';
+
+/**
+ * Subset of `@nestjs/common`'s `LogLevel` we map to. Defined locally so this
+ * file compiles even when `@nestjs/common` isn't installed (it's an optional
+ * peer dep). Structurally compatible with NestJS's actual `LogLevel`.
+ */
+export type NestJsLogLevel = 'fatal' | 'error' | 'warn' | 'log' | 'debug' | 'verbose';
+
+const CANONICAL_TO_NEST: Readonly<Record<CanonicalLogLevel, NestJsLogLevel>> = {
+  fatal: 'fatal',
+  error: 'error',
+  warn: 'warn',
+  info: 'log', // NestJS uses 'log' for info-level messages.
+  debug: 'debug',
+  verbose: 'verbose',
+};
+
+/**
+ * Maps canonical log levels to NestJS's level naming. The only non-identity
+ * mapping is `'info'` → `'log'`. Unknown level strings are silently dropped.
+ */
+export function mapToNestJsLogLevels(levels: readonly string[]): NestJsLogLevel[] {
+  const result: NestJsLogLevel[] = [];
+  for (const level of levels) {
+    const mapped = CANONICAL_TO_NEST[level as CanonicalLogLevel];
+    if (mapped !== undefined) result.push(mapped);
+  }
+  return result;
+}