TypeScript Logging Log4TS Style

Common errors

• Cannot find module 'typescript-logging-log4ts-style' or its corresponding type declarations.

  cause The package was not installed or installed incorrectly, or TypeScript cannot locate its types.
  fix Ensure both `typescript-logging` and `typescript-logging-log4ts-style` are installed: `npm install --save typescript-logging typescript-logging-log4ts-style`.

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

  cause The `log4TSProvider` was not initialized or imported correctly, leading to an attempt to call a method on an `undefined` object.
  fix Verify that `Log4TSProvider.createProvider` is called before any `getLogger` calls, and that the provider object is correctly exported and imported across modules.

• Logging statements (e.g., `log.debug()`) are not appearing in the console or output.

  cause The configured `LogLevel` for the provider or a specific group is set too high (e.g., `LogLevel.Error`), effectively filtering out lower-level messages.
  fix Adjust the `level` property in your `Log4TSProvider` configuration (e.g., to `LogLevel.Debug` or `LogLevel.Trace`) and ensure group expressions match your logger names.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax in an ESM project, or trying to import an ESM-only library with `require()`.
  fix Use ES Module `import` syntax (e.g., `import { Log4TSProvider } from 'typescript-logging-log4ts-style';`) and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

Warnings

• breaking Major architectural changes occurred between version 1.x and 2.x of `typescript-logging`. Code written for 1.x is not directly compatible with 2.x and requires a migration.
  Fix: Refer to the migration guide available in the `typescript-logging` repository for 1.x releases (e.g., `https://github.com/vauxite-org/typescript-logging/tree/release-1.x`) and rewrite logging configuration and calls for the 2.x API.
• gotcha The `typescript-logging-log4ts-style` package is an add-on 'flavor' and requires the core `typescript-logging` package to be installed as a separate dependency.
  Fix: Always install both packages: `npm install --save typescript-logging typescript-logging-log4ts-style`.
• gotcha The `LogLevel.Off` enumeration was introduced in version 2.1.0. While minor, there is a small chance this could affect existing code if custom log level handling or comparisons were in place.
  Fix: Review existing code that interacts directly with `LogLevel` values or performs custom comparisons to ensure compatibility with the new `LogLevel.Off` value.
• gotcha To enable file logging and rollover support, the separate `typescript-logging-node-channel` package must be installed and configured in addition to the core and style packages.
  Fix: Install `npm install --save typescript-logging-node-channel` and consult its documentation for configuration details to enable file output.

Install

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

Imports

• Log4TSProvider
  wrong:

  const Log4TSProvider = require('typescript-logging-log4ts-style');

  correct:

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

  The library primarily uses ESM imports for its public API since version 2.x. CommonJS require() is not supported.
• LogLevel
  wrong:

  import { LogLevel } from 'typescript-logging-log4ts-style';

  correct:

  import { LogLevel } from 'typescript-logging';

  LogLevel is part of the core `typescript-logging` package, not the style package itself.
• Logger

  import { Logger } from 'typescript-logging';

  The `Logger` interface and type definitions are exposed by the core `typescript-logging` package, though you primarily interact with it via `provider.getLogger()`.

Quickstart

This quickstart demonstrates setting up a Log4TSProvider, configuring log levels and groups, creating named loggers, and using them across different modules for debugging and error logging.

/*--- config/LogConfig.ts ---*/
import { LogLevel } from "typescript-logging";
import { Log4TSProvider } from "typescript-logging-log4ts-style";

export const log4TSProvider = Log4TSProvider.createProvider("AwesomeLog4TSProvider", {
  level: LogLevel.Debug,
  groups: [{
    expression: new RegExp(".+")
  }]
});

/*--- model/Account.ts ---*/
import { log4TSProvider } from "../config/LogConfig";

const log = log4TSProvider.getLogger("model.Account");

export interface Account {
  name: string;
}

export function createAccount(name: string): Account {
  log.debug(() => `Creating new account with name '${name}'.`);
  return {name};
}

/*--- service/AccountService.ts ---*/
import { log4TSProvider } from "../config/LogConfig";
import { Account } from "../model/Account";

const log = log4TSProvider.getLogger("service.AccountService");

async function someUpdateHere() {
  return new Promise(resolve => setTimeout(resolve, 100)); // Simulate async operation
}

export async function saveAccount(account: Account) {
  log.debug(() => `Will save account '${account.name}'.`);
  try {
    await someUpdateHere();
  }
  catch (e) {
    log.error(() => `Failed to save account '${account.name}'.`, e);
    throw e;
  }
}

/*--- Main.ts ---*/
import { log4TSProvider } from "../config/LogConfig";
import { createAccount } from "./model/Account";
import { saveAccount } from "./service/AccountService"; // Corrected import path

const log = log4TSProvider.getLogger("main");

/* Create an account and save it - log on success/error */
const account = createAccount("My Account");
saveAccount(account)
  .then(() => {
    log.debug("Successfully created account.", account.name);
  })
  .catch(e => {
    log.error("Ooops...", e);
  });