{"id":12240,"library":"typescript-logging-category-style","title":"TypeScript Logging Category Style","description":"This package provides the \"category style\" flavor for the `typescript-logging` library, enabling hierarchical and topological logging structures. It allows applications to create a tree of loggers, where each `Category` can have child categories, facilitating fine-grained control over logging levels and output for specific application modules or concerns. For instance, a \"Performance\" category can have subcategories, and logging can be enabled/disabled at any level of this hierarchy. The current stable version is 2.2.0, with frequent minor and patch releases, typically driven by feature additions (like file logging support in 2.2.0 via `typescript-logging-node-channel`) or bug fixes. It differentiates itself by offering this unique tree-based categorization over other flat logging approaches, built specifically for TypeScript projects to leverage its type system.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/vauxite-org/typescript-logging","tags":["javascript","typescript-logging","typescript logging","typescript-logging category","typescript logging category","typescript-logging category style","typescript logging category style","typescript logger","category","typescript"],"install":[{"cmd":"npm install typescript-logging-category-style","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-logging-category-style","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-logging-category-style","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core logging functionality; required peer dependency for all `typescript-logging` style packages.","package":"typescript-logging","optional":false}],"imports":[{"note":"LogLevel is part of the core `typescript-logging` package, not the style package.","wrong":"import { LogLevel } from 'typescript-logging-category-style';","symbol":"LogLevel","correct":"import { LogLevel } from 'typescript-logging';"},{"note":"Primary way to configure and retrieve categories. While CommonJS might work with transpilation, ESM imports are the idiomatic approach for this TypeScript-first library.","wrong":"const { CategoryProvider } = require('typescript-logging-category-style');","symbol":"CategoryProvider","correct":"import { CategoryProvider } from 'typescript-logging-category-style';"},{"note":"Represents a logger instance within the topological structure, belonging to the specific category style.","wrong":"import { Category } from 'typescript-logging';","symbol":"Category","correct":"import { Category } from 'typescript-logging-category-style';"}],"quickstart":{"code":"import {LogLevel} from \"typescript-logging\";\nimport {CategoryProvider, Category} from \"typescript-logging-category-style\";\n\n// --- Configuration (LogConfig.ts logic) ---\nconst provider = CategoryProvider.createProvider(\"ExampleProvider\", {\n  level: LogLevel.Debug,\n  // Optional: Add a simple appender for console output if not already configured globally\n  // appenders: { default: { type: 'console' } }\n});\n\n// Create some root categories for this example\nconst rootModel = provider.getCategory(\"model\");\nconst rootService = provider.getCategory(\"service\");\nconst rootMain = provider.getCategory(\"main\");\n\n// --- Model (Account.ts logic) ---\nconst modelLog = rootModel.getChildCategory(\"Account\");\n\ninterface Account {\n  name: string;\n}\n\nfunction createAccount(name: string): Account {\n  modelLog.debug(() => `Creating new account with name '${name}'.`);\n  return {name};\n}\n\n// --- Service (AccountService.ts logic) ---\nconst serviceLog = rootService.getChildCategory(\"AccountService\");\n\n// Mock function for demonstration\nasync function someExternalApiCall(): Promise<void> {\n    return new Promise(resolve => setTimeout(resolve, 50)); // Simulate async work\n}\n\nasync function saveAccount(account: Account) {\n  serviceLog.debug(() => `Will save account '${account.name}'.`);\n  try {\n    await someExternalApiCall();\n    serviceLog.info(() => `Account '${account.name}' saved successfully.`);\n  }\n  catch (e) {\n    serviceLog.error(() => `Failed to save account '${account.name}'.`, e);\n    throw e;\n  }\n}\n\n// --- Main Application Logic (Main.ts logic) ---\n(async () => {\n  rootMain.info(() => \"Application starting...\");\n  const newAccount = createAccount(\"JaneDoe\");\n  try {\n    await saveAccount(newAccount);\n  } catch (error) {\n    rootMain.error(() => \"Error during account operations.\", error);\n  }\n  rootMain.info(() => \"Application finished.\");\n})();\n","lang":"typescript","description":"Demonstrates configuring a `CategoryProvider`, creating root and child categories, and logging messages at different levels, including error handling, to build a hierarchical logging structure."},"warnings":[{"fix":"Consult the `typescript-logging` v2 documentation and migration guides. Re-evaluate your logging configuration and category instantiation patterns.","message":"Upgrading from `typescript-logging` version 1.x to 2.x involves significant changes. The API for configuration and category creation has evolved. Review the official migration guide for specific details.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure both `typescript-logging` and `typescript-logging-category-style` are installed: `npm install --save typescript-logging typescript-logging-category-style`.","message":"This package (`typescript-logging-category-style`) is a 'flavor' and requires the core `typescript-logging` package as a peer dependency. Forgetting to install `typescript-logging` will lead to runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `typescript-logging` version 2.1.0 or newer if you intend to use `LogLevel.Off`.","message":"The `LogLevel.Off` enum member was introduced in version 2.1.0. If you are using `LogLevel.Off` (e.g., for disabling a logger) and targeting an older version or have mixed versions, it might not be recognized or behave as expected.","severity":"gotcha","affected_versions":"<2.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install --save typescript-logging typescript-logging-category-style` to install both packages.","cause":"One of the required packages (`typescript-logging` or `typescript-logging-category-style`) is not installed.","error":"Error: Cannot find module 'typescript-logging' or 'typescript-logging-category-style'"},{"fix":"Ensure you are using ES Module `import` syntax (`import { CategoryProvider } from 'typescript-logging-category-style';`) and that your project is configured for ESM, especially in Node.js environments (e.g., `\"type\": \"module\"` in `package.json`).","cause":"This error typically occurs when trying to use CommonJS `require()` syntax with an ES Module, or if the module is not correctly imported/transpiled in your environment (e.g., Node.js without proper ESM setup or bundler issues).","error":"TypeError: (0 , typescript_logging_1.CategoryProvider).createProvider is not a function"},{"fix":"Check the `level` option in `CategoryProvider.createProvider` (e.g., `level: LogLevel.Debug`). Ensure at least one appender is configured for your `CategoryProvider` or globally in `typescript-logging` to output logs (e.g., a console appender).","cause":"The configured log level for a `CategoryProvider` or individual `Category` is too high, or no appender is configured to process the log events.","error":"No log messages appear in the console/output."}],"ecosystem":"npm"}