🧀 cheese-log

A colorful logger with browser-/environment-dependent formatting possibilities.

Features

• Colorize messages
• Custom formatting possible based on log level, browser name, OS, and other attributes
• Display or hide stack trace / origin, timestamp, log level, etc.
• Shorten arrays, shorten strings, limit object depth of deeply nested objects, etc.
• Print tables
• Set and forget mentality, but also allows overriding the logging config for individual logging messages later on
• Written in typescript

This logger is not intended to be highly performant, if you are looking for something like that, look somewhere else. This library aims to provide a flexible, versatile and simple logger, to make debugging etc. a slight bit easier.

README Overview

1. Install
2. Usage examples
   1. Simple usage
   2. Explore some initial config's props
   3. Override config for individual log messages
   4. Use built-in color functions
   5. Use context dependent config instead of a static one
   6. Use a custom formatMessage function
   7. Auto-colorized objects
   8. Shorten strings
   9. Shorten arrays
   10. Limit object depth
   11. Print tables
3. Config / options
4. Available functions
   1. Config function
   2. Basic logging functions
   3. Built-in table functions
   4. Built-in color functions
5. Open tasks / ideas

Install

npm install --save cheese-log

Or if you use Yarn:

yarn add cheese-log

Usage examples

The following subsections are showing different usage examples of varying complexity. For a full set of options and possibilities however, refer to the options sections here.

Example: Simple usage

import { cheese, CheeseConfig } from "cheese-log";

// it is mandatory to initialize the cheese logger like so:
const cheeseConfig: CheeseConfig = {};
cheese.config(cheeseConfig);

// now you can use it:
cheese.log("some log message");
cheese.info("some info message");
cheese.debug("some debug message");
cheese.warn("some warn message");
cheese.error("some error message");

The corresponding output in the Google Chrome browser's console:

The default configuration of cheese-log avoids color coding in certain browser, that don't support it. For instance, in Firefox, instead of seeing messed up logging messages like this...

...you will instead see un-colored messages like this:

You can always further adjust the mentioned default configuration to avoid colors (or other properties) in certain browsers, operating systems, etc. - see here.

Further optimizations are part of the implementation. So does it not use the white logging color for message headers in classical consoles - instead, my IDE would show the same messages like this for example:

My classical OS terminal would show the output like so:

Check out the live demo at https://stackblitz.com/edit/cheese-log-simple-usage.

Example: Explore some initial config's props:

import { cheese, CheeseConfig } from "cheese-log";

const cheeseConfig: CheeseConfig = {
  showDate: false, // is true by default
  showCheeseIcon: false, // is true by default
  showOrigin: true, // is false by default
};
cheese.config(cheeseConfig);

cheese.log("some log message");
cheese.info("some info message");
cheese.debug("some debug message");
cheese.warn("some warn message");
cheese.error("some error message");

The corresponding output would hide the timestamp and the icon, while showing some stacktrace info:

A full list of config options can be found here.

Check out the live demo at https://stackblitz.com/edit/cheese-log-explore-some-config-props.

Example: Override config for individual log messages

You can override the options for individual messages by using 2 kinds of functions as shown in the following example:

import { cheese, CheeseConfig } from "cheese-log";

const cheeseConfig: CheeseConfig = {};
cheese.config(cheeseConfig);

cheese.info("some standard info message");

// 1) _LOGLEVEL functions allow you to pass an option object as the 1st argument...
cheese._info(
  // note the leading underscore!
  { showCheeseIcon: false },
  "some info message where the cheese icon is hidden",
);

// 2) ...while LOGLEVEL_ functions allow you to pass an option object as the last argument:
cheese.info_("some info message where the timestamp is hidden", {
  // note the trailing underscore!
  showDate: false,
});
// ^ Note that you could pass multiple arguments to `._info()` - cheese-log assumes the last argument will be your option object.

The corresponding output would be:

Check out the live demo at https://stackblitz.com/edit/cheese-log-override-config.

Example: Use built-in color functions

Cheese-log offers some coloring possibilities. While certain coloring happens automatically for objects, you can always override the color by using the option colorOverride. On top of that, to make the coder's life easier, you can instead also use the predefined log functions in the shape [LOGLEVEL][COLOR](), like the following example shows:

import { cheese, CheeseConfig } from "cheese-log";

const cheeseConfig: CheeseConfig = {};
cheese.config(cheeseConfig);

cheese.logBlack("Some message in a black color");
cheese.logGray("Some message in a gray color");
cheese.logLightgray("Some message in a lightgray color");
cheese.logWhite("Some message in a white color");
cheese.logLightyellow("Some message in a lightyellow color");
cheese.logYellow("Some message in a yellow color");
cheese.logRed("Some message in a red color");
cheese.logLightred("Some message in a lightred color");
cheese.logMagenta("Some message in a magenta color");
cheese.logLightmagenta("Some message in a lightmagenta color");
cheese.logBlue("Some message in a blue color");
cheese.logLightblue("Some message in a lightblue color");
cheese.logCyan("Some message in a cyan color");
cheese.logLightcyan("Some message in a lightcyan color");
cheese.logGreen("Some message in a green color");
cheese.logLightgreen("Some message in a lightgreen color");

The corresponding output would be:

You can also use the color functions with leading and trailing underscores, to pass additional options, for instance:

cheese._logLightblue({ showCheeseIcon: false }, "hello world");
cheese.logMagenta_("foo bar", "1234", "mic check one two", { showDate: false });

Check out the live demo at https://stackblitz.com/edit/cheese-log-built-in-color-functions.

Example: Use context dependent config instead of a static one

Configs passed to cheese-log can be static option objects as described here OR you can also pass a function returning such an option object. Advantage of the latter is that you get access to the "context" / the "environment" - meaning, you can make the output and formatting dependent on the browser name (if any), the operating system and other attributes.

The following example should be self-explanatory:

import { cheese, CheeseConfig } from "cheese-log";

const contextDependentCheeseConfig: ContextDependentCheeseConfig = (
  who,
  logLevel,
) => {
  if (who.browserName === "Firefox" || who.osName === "Android") {
    return { allColorsDisabled: true, showCheeseIcon: false };
  }
  return {
    allColorsDisabled: true,
    showCheeseIcon: true,
  };
};
cheese.config(contextDependentCheeseConfig);

cheese.info("some info message");

The resulting output on Chrome would be...

...and on Firefox and/or Android it would be:

Check out the live demo at https://stackblitz.com/edit/cheese-log-context-dependent-config.

Example: Use a custom formatMessage function

If you want to change the format of logged messages, you can do it by passing a custom formatMessage function (either to the global cheese config at the beginning, or to individual log messages).

The function shown below is the default, used by this library. It can serve as a template when creating your own:

const formatMessageDefault: FormatMessageFn = (
  message: string,
  who: Who,
  showLogLevel: boolean,
  logLevel: LogLevel,
  millisecondsSince1970: number,
  showDate: boolean,
  dateFormat: string,
  showOrigin: boolean,
  autoColorizeObject: boolean,
  showCheeseIcon: boolean,
  allColorsDisabled: boolean,
  colorOverride: string,
  messagePrefix: string,
  messageSuffix: string,
) => {
  const cheeseIconPrepared = showCheeseIcon ? CHEESE_ICON + " " : "";
  const messagePrefixPrepared = messagePrefix ? messagePrefix + " " : "";
  const logLevelPrepared = showLogLevel
    ? "[" + logLevel + "]" + (showDate ? " " : "")
    : "";
  const datePrepared = showDate
    ? getTimestamp(dateFormat, millisecondsSince1970)
    : "";
  const originInfo = showOrigin ? getStackTrace() ?? "" : "";

  let prefixPrepared = `${cheeseIconPrepared}${messagePrefixPrepared}${logLevelPrepared}${datePrepared}`;
  if (!allColorsDisabled) {
    const textColorFn = who.isServerApp ? black : white;
    if (logLevel === LogLevel.error) {
      prefixPrepared = bgRed(textColorFn(prefixPrepared));
    } else if (logLevel === LogLevel.warn) {
      prefixPrepared = bgYellow(textColorFn(prefixPrepared));
    } else if (logLevel === LogLevel.info) {
      prefixPrepared = bgLightGray(textColorFn(prefixPrepared));
    } else if (logLevel === LogLevel.log) {
      prefixPrepared = bgDarkGray(textColorFn(prefixPrepared));
    } else if (logLevel === LogLevel.debug) {
      prefixPrepared = bgMagenta(textColorFn(prefixPrepared));
    }
  }

  const originInfoPrepared = originInfo ? `   ${originInfo}\n` : "";
  return `${prefixPrepared}\n${originInfoPrepared}${message}${messageSuffix}`;
};

Since version 1.10.0 you can also import getStackTrace, getTimestamp as well as the individual coloring functions via ansicolor, which can be helpful when building your own custom message format function.

Check out the live demo at https://stackblitz.com/edit/cheese-log-custom-msg-format-function.

Example: Auto-colorized objects

When logging (nested) objects, the library tries to automatically colorize individual props, according to their type (string would have different colors, than numbers etc.). See the following example:

import { cheese, CheeseConfig } from "cheese-log";

cheese.config({});

cheese.log({
  this: {
    is: { someNested: "object" },
    itHasNumbers: 112358,
    andArrays: ["hello", "world"],
  },
});

The result:

Example: Shorten strings

Cheese-log allows you to automatically truncate strings that exceed certain lengths.

import { cheese, CheeseConfig } from "cheese-log";

const cheeseConfig: CheeseConfig = { maxStringLength: 12 };
cheese.config(cheeseConfig);

cheese.logBlack("Some longer message - in a black color");
cheese.logGray("Some longer message - in a gray color");
cheese.logLightgray("Some longer message - in a lightgray color");
cheese.logWhite("Some longer message - in a white color");
cheese.logLightyellow("Some longer message - in a lightyellow color");
cheese.logYellow("Some longer message - in a yellow color");
cheese.logRed("Some longer message - in a red color");
cheese.logLightred("Some longer message - in a lightred color");
cheese.logMagenta("Some longer message - in a magenta color");
cheese.logLightmagenta("Some longer message - in a lightmagenta color");
cheese.logBlue("Some longer message - in a blue color");
cheese.logLightblue("Some longer message - in a lightblue color");
cheese.logCyan("Some longer message - in a cyan color");
cheese.logLightcyan("Some longer message - in a lightcyan color");
cheese.logGreen("Some longer message - in a green color");
cheese.logLightgreen("Some longer message - in a lightgreen color");

The corresonding output would be:

Check out the live demo at https://stackblitz.com/edit/cheese-log-shorten-strings.

The shortening/truncating of strings also works for values in (nested) objects:

cheese.logGreen({
  hello: "world",
  msg: "Some longer message inside an object",
});

It is allowed to pass maxStringLength: 0:

import { cheese, CheeseConfig } from "cheese-log";

const cheeseConfig: CheeseConfig = { maxStringLength: 0 };
cheese.config(cheeseConfig);

cheese.logGreen({
  hello: "world",
  msg: "Some longer message inside an object",
});

Even when using an uncolored function (which leads to auto-coloring an object), the truncating info in the output will always be highlighted green. The following example logs 2 arguments, a plain string and a nested object -> the latter will be auto-colored, while the plain string will not be auto-colored - see output:

cheese.log("a first log argument, which is simply a plain string", {
  hello: "world",
  someArray: [1, 2, 3, 4, 5],
  nested: { hi: "friends and family" },
});

Example: Shorten arrays

Similarly to string truncating, you can also let cheese-log automatically shorten arrays exceeding certain lengths:

import { cheese, CheeseConfig } from "cheese-log";

const cheeseConfig: CheeseConfig = { maxArrayLength: 5 };
cheese.config(cheeseConfig);

cheese.log("some arrays that will be shortened", [1, 2, 3, 4, 5, 6, 7, 8, 9], {
  my: "nested object",
  that: "also holds an array",
  here: ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"],
});

Array shortening messages are always highlighted with a red background, except for cases where colorOverride is being used.

Also for arrays, passing maxArrayLength: 0 is a valid option:

Check out the live demo at https://stackblitz.com/edit/cheese-log-shorten-arrays.

Example: Limit object depth

As developers, we often come across situations where we need to deal with deeply nested objects. Fortunately many browser consoles allow collapsing- and expanding-functionalities. For cases where this is not helpful or possible, cheese-log allows to limit the depth of printed objects:

import { cheese, CheeseConfig } from "cheese-log";

const cheeseConfig: CheeseConfig = { depth: 3 };
cheese.config(cheeseConfig);

cheese.info({ this: "is an object with 1 level" });
cheese.info({
  this: "is an object with 2 levels",
  here: { we: "have a 2nd level" },
});
cheese.info({
  this: "is an object with multiple levels",
  here: { we: "have a 2nd level" },
  and: { here: { we: "have a 3rd level" } },
  lets: { maybe: { even: { add: "a 4th level" } } },
  finally: {
    i: { would: { say: { five: "leves are enough for this example" } } },
  },
});

The corresponding depth-limited output would be:

Check out the live demo at https://stackblitz.com/edit/cheese-log-limit-object-depth.

Example: Print tables

If you need to show data in a row/colum way, you can easily print tables with cheese-log. Make sure you provide an array of objects, where every object features the same set of keys, like so:

import { cheese, CheeseConfig } from "cheese-log";

const cheeseConfig: CheeseConfig = { table: true };
cheese.config(cheeseConfig);

cheese.debug([
  { day: "monday", task: "clean house" },
  { day: "tuesday", task: "shopping" },
  { day: "wednesday", task: "write thesis" },
]);

The corresponding output would be:

Similarly to the built-in color functions you can also use built-in table functions, so you don't have to pass the table: true prop to the config. Another advantage is that it allows you to define the necessary table data structure via typescript, see the following example:

type TableData = { colum1: string, column2: string, someNumberColumn: number };

cheese.logTable<TableData>(...);
cheese._logTable<TableData>(...);
cheese.logTable_<TableData>(...);
cheese.infoTable<TableData>(...);
cheese._infoTable<TableData>(...);
// ... etc. -> all combinations of log-levels plus 'Table' exist!

You can adjust a few formatting options for tables, by setting a tableOptions prop:

import { cheese, CheeseConfig } from "cheese-log";

const cheeseConfig: CheeseConfig = {
  table: true,
  tableOptions: { rowSeparator: "-", headerSeparator: "=" },
  depth: 0,
};
cheese.config(cheeseConfig);

cheese.debug([
  { day: "monday", task: "clean house" },
  { day: "tuesday", task: ["shopping", "walk dog"] },
  { day: "wednesday", task: "write thesis" },
  { day: "thursday", task: { a: { nested: "object" } } },
]);

The corresponding output would be:

Note how the individual formatting functionalities also work inside individual table cells (the depth of object has been limited in this example).

Check out the live demo at https://stackblitz.com/edit/cheese-log-print-tables.

Config / options

While the section above shows various example, the following table aims to be a complete list of available options.

For now, every single prop is optional, not providing it will result in some default value being used - as shown in the table:

| name | type | default value | description | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | allColorsDisabled | boolean \| (who: Who, logLevel: LogLevel) => boolean | (who: Who) => who.browserName === "Firefox" \|\| who.browserName === "Safari" | If this is set to true no ansi colors are being used at all. This is helpful, if your environment is not supporting color codes, for instace. The default value is a function, checking if the logger is running on Firefox or Safari, in these cases returning false, since these browser don't natively support color codes. | | autoColorizeObject | boolean \| (who: Who, logLevel: LogLevel) => boolean | true | Logged objects would be automatically colored, as described here. You can turn this feature off. | | colorOverride | CheeseColors | undefined | This allows you to colorize entire messages. Using this as part of the global config might be a bit useless, you can however highlight individual messages when used on individual log statements. | | dateFormat | string \| (who: Who, logLevel: LogLevel) => string | "YYYY-MM-DD, HH:mm:ss.SSS" | The date format used for the log statements. | | depth | number \| (who: Who, logLevel: LogLevel) => number | 100 | The depth of logged objects can be limited, as described here. | | escapeWhitespaces | boolean \| (who: Who, logLevel: LogLevel) => boolean | false | If set to true, whitespace characters (to be more precise \t, \n, \r and \f) will be escaped, when logging. Note, this does not affect classical spaces " " though. | | forceNewlines | boolean \| (who: Who, logLevel: LogLevel) => boolean | false | If set to true every single logging argument will appear on a new line. If set to false, only arrays and objects appear on newlines, successive strings for instance would be printed on the same line though. | | formatMessage | (message: string, who: Who, showLogLevel: boolean, logLevel: LogLevel, millisecondsSince1970: number, showDate: boolean, dateFormat: string, showOrigin: boolean, autoColorizeObject: boolean, showCheeseIcon: boolean, allColorsDisabled: boolean, colorOverride: CheeseColors) => string | Check the corresponding code to see the default function. | This function is one of the centerpieces and determines how logged messages appear. Examples can be seen here. | | logLevelEnabled | (logLevel: LogLevel) => boolean | (logLevel: LogLevel) => process.env.NODE_ENV !== "production" | This function can be used to disable certain log messages in certain scenarios, for instance on production environments. | | maxArrayLength | number \| (who: Who, logLevel: LogLevel) => number | 10000 | Logging long arrays would truncate them automatically via this option. See more details. | | maxStringLength | number \| (who: Who, logLevel: LogLevel) => number | 10000 | Logging long strings would truncate them automatically via this option. See more details. | | messagePrefix | string \| (who: Who, logLevel: LogLevel) => string | "" | This message prefix allows you to prepend a certain string to every log message. Please be aware, that the cheese icon - if logged - will appear even before this prefix. | | messageSuffix | string \| (who: Who, logLevel: LogLevel) => string | "" | This message suffix allows you to append a certain string to every log message. | | reportGlobalConfigChange | boolean | true | Changing the global config after initialization might be a mistake, therefore a warning will be presented. This warning can be disabled via this option. | | reportInitialization | boolean | true | Successfully initializing the logger via cheese.config() will print some corresponding info messages. These info messages can be disabled via this option. | | showCheeseIcon | boolean \| (who: Who, logLevel: LogLevel) => boolean | true | Decides whether log messages show the 🧀 icon or not. | | showDate | boolean \| (who: Who, logLevel: LogLevel) => boolean | true | Decides whether log messages show date / timestamp or not. | | showLogLevel | boolean \| (who: Who, logLevel: LogLevel) => boolean | true | Decides whether log messages show the logLevel or not. | | showOrigin | boolean \| (who: Who, logLevel: LogLevel) => boolean | false | Decides whether log messages show the (stacktrace) origin or not. | | spaces | boolean \| (who: Who, logLevel: LogLevel) => boolean | true | Decides if there should be a space " " between individual log arguments or not. This only concerns args that would be printed on the same line. | | table | boolean \| (who: Who, logLevel: LogLevel) => boolean | false | Via this option you can print messages in a "table format". Details can be seen here. | | tableOptions | TableOptions \| (who: Who, logLevel: LogLevel) => TableOptions | undefined | Via this option you can control some formatting details for the table printing. The following options are allowed: outerBorder: string, innerBorder: string, rowSeparator: string and headerSeparator: string. |

Available functions

Config function

config(cheeseConfig: CheeseConfig | ContextDependentCheeseConfig)

Basic logging functions

• log(...args: any[])
• info(...args: any[])
• debug(...args: any[])
• warn(...args: any[])
• error(...args: any[])
• _log(cheeseConfig: CheeseConfig, ...args: any[])
• _info(cheeseConfig: CheeseConfig, ...args: any[])
• _debug(cheeseConfig: CheeseConfig, ...args: any[])
• _warn(cheeseConfig: CheeseConfig, ...args: any[])
• _error(cheeseConfig: CheeseConfig, ...args: any[])
• log_(...args: any[], cheeseConfig: CheeseConfig)
• info_(...args: any[], cheeseConfig: CheeseConfig)
• debug_(...args: any[], cheeseConfig: CheeseConfig)
• warn_(...args: any[], cheeseConfig: CheeseConfig)
• error_(...args: any[], cheeseConfig: CheeseConfig)

Built-in table functions

• logTable<T>(...args: T[])
• infoTable<T>(...args: T[])
• debugTable<T>(...args: T[])
• warnTable<T>(...args: T[])
• errorTable<T>(...args: T[])
• _logTable<T>(cheeseConfig: CheeseConfig, ...args: T[])
• _infoTable<T>(cheeseConfig: CheeseConfig, ...args: T[])
• _debugTable<T>(cheeseConfig: CheeseConfig, ...args: T[])
• _warnTable<T>(cheeseConfig: CheeseConfig, ...args: T[])
• _errorTable<T>(cheeseConfig: CheeseConfig, ...args: T[])
• logTable_<T>(...args: T[], cheeseConfig: CheeseConfig)
• infoTable_<T>(...args: T[], cheeseConfig: CheeseConfig)
• debugTable_<T>(...args: T[], cheeseConfig: CheeseConfig)
• warnTable_<T>(...args: T[], cheeseConfig: CheeseConfig)
• errorTable_<T>(...args: T[], cheeseConfig: CheeseConfig)

^ providing <T> is optional and allows you to define the required data structure as needed to avoid bugs. After all every object in the provided array(s) need to have the same props.

Built-in color functions

• logBlack(...args: any[])
• infoBlack(...args: any[])
• debugBlack(...args: any[])
• warnBlack(...args: any[])
• errorBlack(...args: any[])
• _logBlack(cheeseConfig: CheeseConfig, ...args: any[])
• _infoBlack(cheeseConfig: CheeseConfig, ...args: any[])
• _debugBlack(cheeseConfig: CheeseConfig, ...args: any[])
• _warnBlack(cheeseConfig: CheeseConfig, ...args: any[])
• _errorBlack(cheeseConfig: CheeseConfig, ...args: any[])
• logBlack_(...args: any[], cheeseConfig: CheeseConfig)
• infoBlack_(...args: any[], cheeseConfig: CheeseConfig)
• debugBlack_(...args: any[], cheeseConfig: CheeseConfig)
• warnBlack_(...args: any[], cheeseConfig: CheeseConfig)
• errorBlack_(...args: any[], cheeseConfig: CheeseConfig)
• logWhite(...args: any[])
• etc.

^ this works with the following colors: Black, White, Gray, Lightgray, Blue, Lightblue, Cyan, Lightcyan, Red, Lightred, Green, Lightgreen, Yellow, Lightyellow, Magenta, Lightmagenta

Live Demos

All the live demos shown above can be found collected here.

Another very basic usage example - this time as part of a react native app though - can be found in this expo snack. Open your browser console there to see the log output from cheese-log. Note that it is only visible if you run the snack for the web platform though!

Open tasks / ideas

• add unit tests
• grouping functionalities
• (async) hook functionality to allow sending logs to external services etc.

Miscellaneous

Various videos for this library can be found here. I am always happy if you pay me a visit on my channel!

If you enjoy using this...