TypeScript Logging Core

Common errors

• TypeError: Cannot read properties of undefined (reading 'createProvider')

  cause Attempting to instantiate a logging provider (e.g., CategoryProvider or Log4TSProvider) directly from the `typescript-logging` core package, which only exports interfaces and not concrete implementations.
  fix Ensure you are importing the provider from the correct 'flavor' package, e.g., `import {CategoryProvider} from 'typescript-logging-category-style';` and that the flavor package is installed.

• Module not found: Can't resolve 'typescript-logging-category-style'

  cause The specific logging flavor package (e.g., `typescript-logging-category-style` or `typescript-logging-log4ts-style`) has not been installed, or the import path is incorrect.
  fix Install the required flavor package using npm: `npm install --save typescript-logging-category-style` (or your chosen flavor) and verify the import statement correctly references the package name and export.

Warnings

• breaking Version 2.x of `typescript-logging` is a complete rewrite and is not backward compatible with version 1.x APIs. Existing code using v1 will break.
  Fix: Refer to the migration guide in the package documentation (`/migration` section) and update all logging logic to conform to the new v2 API structure. This typically involves updating imports and logger initialization.
• gotcha The `typescript-logging` core package provides only interfaces and basic types. To get functional logging, you must install and configure a specific 'flavor' package (e.g., `typescript-logging-category-style` or `typescript-logging-log4ts-style`) alongside the core library.
  Fix: Install your preferred flavor package (e.g., `npm install --save typescript-logging-category-style`) and follow its documentation to set up the logging provider and obtain logger instances.
• deprecated The `LogLevel.Off` value was introduced in version 2.1.0. While it provides an explicit way to disable logging for a category, it might subtly alter behavior or require adjustments in existing configurations that implicitly handled disabled logging.
  Fix: Review any log level configurations that might be impacted by the introduction of `LogLevel.Off`. Explicitly use `LogLevel.Off` where logging should be completely disabled, or other specific levels for active logging.

Install

• npm install typescript-logging npm
• yarn add typescript-logging yarn
• pnpm add typescript-logging pnpm

Imports

• LogLevel
  wrong:

  const { LogLevel } = require('typescript-logging');

  correct:

  import { LogLevel } from 'typescript-logging';

  Core enum for defining logging thresholds. The library is primarily designed for ESM usage in v2+.
• CategoryProvider, Category
  wrong:

  import CategoryProvider from 'typescript-logging-category-style';
  const { Category } = require('typescript-logging-category-style');

  correct:

  import { CategoryProvider, Category } from 'typescript-logging-category-style';

  Essential classes for setting up and utilizing the category-style hierarchical logging API. ESM-first.
• Log4TSProvider, Logger
  wrong:

  import Logger from 'typescript-logging-log4ts-style';
  const { Log4TSProvider } = require('typescript-logging-log4ts-style');

  correct:

  import { Log4TSProvider, Logger } from 'typescript-logging-log4ts-style';

  Primary classes for configuring and using the log4ts-compatible logging API. ESM-first.

Quickstart

Demonstrates how to configure the Category-style logging provider and obtain hierarchical loggers for different modules, logging messages at various levels.

/*--- LogConfig.ts ---*/
import {CategoryProvider, Category} from "typescript-logging-category-style";

const provider = CategoryProvider.createProvider("ExampleProvider");

export function getLogger(name: string): Category {
  return provider.getCategory(name);
}

/*--- Person.ts ---*/
import {getLogger} from "./LogConfig";

/* Root categories can and probably will be defined elsewhere, this is just an example */
const logModel = getLogger("model");

/* Create child categories based on a parent category, effectively allowing you to create a tree of loggers when needed */
const logPerson = logModel.getChildCategory("Person");

function example(value: string) {
  logPerson.debug(() => `Example function called with value ${value}`);
  try {
    // Awesome code here...
    logPerson.getChildCategory("example()").debug(() => "Child category again");
  }
  catch (e: any) {
    logPerson.error(() => "Awesome code failed unexpectedly", e);
  }
  finally {
    logPerson.debug(() => "Example function completed");
  }
}

// Example usage call
example("test-value");