https://github.com/flex-development/log
:knot: a small logging library
https://github.com/flex-development/log
log log-util logging
Last synced: 2 months ago
JSON representation
:knot: a small logging library
- Host: GitHub
- URL: https://github.com/flex-development/log
- Owner: flex-development
- License: bsd-3-clause
- Created: 2021-08-21T13:18:38.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-10-02T23:06:03.000Z (3 months ago)
- Last Synced: 2025-10-03T01:14:38.708Z (3 months ago)
- Topics: log, log-util, logging
- Language: TypeScript
- Homepage: https://github.com/flex-development/log
- Size: 4.72 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# \:knot: log
[](https://github.com/flex-development/log/actions/workflows/ci.yml)
[](https://github.com/flex-development/log/releases/latest)
[](https://npmjs.com/package/@flex-development/log)
[](https://www.npmcharts.com/compare/@flex-development/log?interval=30)
[](https://packagephobia.now.sh/result?p=@flex-development/log)
[](https://codecov.io/gh/flex-development/log)
[](https://github.com/voxpelli/badges-cjs-esm)
[](LICENSE.md)
[](https://conventionalcommits.org)
[](https://typescriptlang.org)
[](https://vitest.dev)
[](https://yarnpkg.com)
Log messages in the terminal and browser
## Contents
- [What is this?](#what-is-this)
- [Why this package?](#why-this-package)
- [Install](#install)
- [Use](#use)
- [API](#api)
- [`logger`](#logger)
- [`createLogger`](#createloggeroptions)
- [`logLevels`](#loglevels)
- [`Reporter`](#reporter)
- [`BaseReporter`](#basereporter)
- [`FancyReporter`](#fancyreporter)
- [Types](#types)
- [`Logger`](#logger-1)
- [`Create`](#create)
- [`InputLogObject`](#inputlogobject)
- [`Inspect`](#inspect)
- [`InspectOptions`](#inspectoptions)
- [`LogFormatOptions`](#logformatoptions)
- [`LogFunction`](#logfunction)
- [`LogFunctions`](#logfunctions)
- [`LogLevel`](#loglevel)
- [`LogLevelMap`](#loglevelmap)
- [`LogLevelOption`](#logleveloption)
- [`LogLevelType`](#logleveltype)
- [`LogObject`](#logobject)
- [`LogType`](#logtype)
- [`LogTypeFunctions`](#logtypefunctions)
- [`LogTypeMap`](#logtypemap)
- [`LoggerOptions`](#loggeroptions)
- [`ReportersOption`](#reportersoption)
- [`WithDefaults`](#withdefaults)
- [`WithTag`](#withtag)
- [`Write`](#write)
- [`WriteStream`](#writestream)
- [Contribute](#contribute)
## What is this?
This is a small, but useful, library for logging messages in the terminal and browser consoles.
Colorful messages can be logged in the terminal and browser consoles that support ANSI colors.
## Why this package?
\:ok\_hand: Easy to use\
\:electric\_plug: Pluggable reporters\
\:computer: Consistent terminal experience\
\:bookmark: Tag support\
\:globe\_with\_meridians: Browser support
## Install
This package is [ESM only][esm].
In Node.js (20+) with [yarn][]:
```sh
yarn add @flex-development/log
```
See Git - Protocols | Yarn
for details regarding installing from Git.
In Deno with [`esm.sh`][esmsh]:
```ts
import { createLogger } from 'https://esm.sh/@flex-development/log'
```
In browsers with [`esm.sh`][esmsh]:
```html
import { logger } from 'https://esm.sh/@flex-development/log'
```
With [bun][]:
```sh
bun add @flex-development/log
```
See bun add for more details.
## Use
```js
import { logger } from '@flex-development/log'
logger.info('Using @flex-development/log 5.0.0')
logger.start('Building project...')
logger.warn('A new version of @flex-development/log is available: 5.0.1')
logger.success('Project built!')
logger.fail(new Error('This is an example error. Everything is fine!'))
```
Will display in the terminal:
## API
This package exports the following identifiers:
- [`logger`](#logger)
- [`createLogger`](#createloggeroptions)
- [`logLevels`](#loglevels)
- [`Reporter`](#reporter)
- [`BaseReporter`](#basereporter)
- [`FancyReporter`](#fancyreporter)
The default export is `logger`.
### `logger`
([`Logger`](#logger-1)) The default, pre-configured logger.
Logs are written using the [`FancyReporter`](#fancyreporter).
### `createLogger([options])`
Create a new logger.
#### Parameters
- `options` ([`LogLevelOption`](#logleveloption) | [`LoggerOptions`](#loggeroptions), optional)
— Log level or configuration options
#### Returns
([`Logger`](#logger-1)) Logger object
### `logLevels`
(`Readonly>`) Map where each key is a [log type](#logtype)
and each value is a [log level](#loglevel).
### `Reporter`
Log reporter (`abstract class`).
#### Properties
- `logger` ([`Logger`](#logger-1))
— the logger `this` reporter writes to
#### Methods
##### `init(logger)`
Initialize the reporter.
###### Parameters
- `logger` ([`Logger`](#logger-1))
— the logger `this` reporter writes to
###### Returns
(`this`) `this` reporter
##### `abstract report(info)`
Define how a log message is processed and displayed by `this` reporter.
###### Parameters
- `info` ([`LogObject`](#logobject))
— the log information to process
###### Returns
(`undefined | void`) Nothing.
### `BaseReporter`
Log reporter with basic utilities (`abstract class`).
#### Extends
- [`Reporter`](#reporter)
### `FancyReporter`
Fancy log reporter (`class`).
#### Extends
- [`BaseReporter`](#basereporter)
## Types
This package is fully typed with [TypeScript][].
### `Logger`
Logger API (TypeScript interface).
#### Extends
- [`LogFunctions`](#logfunctions)
#### Properties
- `browser` (`boolean`, `readonly`)
— whether the logger is operating in a browser environment
- `get color(): boolean`
— whether color logs are enabled
- `set color(color: boolean | null | undefined)`
— enable or disable color log. color will be disabled if not supported
- `color` (`boolean | null | undefined`)
— color logs enabled?
- `get colors():` [`Colors`][colors-color]
— get a colorizer based on the current `color` configuration
- `create` ([`Create`](#create))
— create a new logger, inheriting options from the current instance, with possible overrides
- `defaults` ([`InputLogObject`](#inputlogobject))
— properties to apply to all logs, regardless of log type or level
- `eol` (`string`)
— the character, or characters, used to signify the end of a line
- `format` ([`LogFormatOptions`](#logformatoptions))
— formatting options
- `get level():` [`LogLevel`](#loglevel)
— get the current log level
- `set level(level: LogLevelOption | null | undefined)`
— set the maximum log level to output
- `level` ([`LogLevelOption`](#logleveloption) | `null` | `undefined`)
— maximum log level (inclusive)
- `levels` ([`Readonly`](#loglevelmap), `readonly`)
— log level map
- `reporters` ([`Set`](#reporter), `readonly`)
— list of reporter instances used to handle and output log messages
- `stderr` ([`WriteStream`](#writestream))
— the writeable stream for standard error output
- `stdout` ([`WriteStream`](#writestream))
— the writeable stream for standard output
- `types` (`Record`)
— record, where each key is a [`LogType`](#logtype) and each value is an [`InputLogObject`](#inputlogobject) defining
the configuration for the log type
- `unicode` (`boolean`)
— whether unicode is supported
- `withDefaults` ([`WithDefaults`](#withdefaults))
— create a new logger with the specified default log object properties
- `withTag` ([`WithTag`](#withtag))
— create a new logger with the specified tag. the tag will be included in any logs sent from the new logger
### `Create`
Create a new logger, inheriting options from the current instance, with possible overrides (TypeScript interface).
Plain objects (i.e. `options.format`, `options.types`) are merged recursively.
#### Parameters
- `options` ([`LoggerOptions`](#loggeroptions), optional)
— overrides for the new logger
#### Returns
([`Logger`](#logger-1)) The new logger.
### `InputLogObject`
Input log data object (TypeScript interface).
#### Properties
- `additional?` (`string | string[]`, optional)
— an additional line, or list of lines, to be logged with the message
- `args?` (`unknown[]`, optional)
— format arguments
- `color?` ([`Color`][colors-color], optional)
— color associated with the log
- `date?` (`Date`, optional)
— timestamp
- `format?` ([`LogFormatOptions`](#logformatoptions), optional)
— format options
- `icon?` (`string`, optional)
— icon to display
- `level?` ([`LogLevelOption`](#logleveloption), optional)
— log level
- `message?` (`unknown`, optional)
— log message; inserted into `args` as the first format argument if defined
- `stack?` (`string`, optional)
— stack trace
- `tag?` (`string`, optional)
— a string to categorize or identify the log
- `type?` ([`LogType`](#logtype), optional)
— log type
### `Inspect`
Use [`util.inspect`][util] on `value` and print its string representation (TypeScript type).
#### Parameters
- `value` (`unknown`)
— the thing to inspect
- `options` ([`InspectOptions`](#inspectoptions), optional)
— inspection options
#### Returns
(`undefined`) Nothing.
### `InspectOptions`
Options for inspecting a value (TypeScript interface).
#### Extends
- [`Omit`][util]
#### Properties
- `colors` (`boolean`, optional)
— whether to use color
### `LogFormatOptions`
Log formatting options (TypeScript interface).
#### Extends
- [`InspectOptions`](#inspectoptions)
#### Properties
- `badge?` (`boolean`, optional)
— whether to display the log type as a badge
- `columns?` (`number`, optional)
— the maximum number of columns to output
- `date?` (`boolean`, optional)
— whether to include timestamp information in log messages
- `icon?` (`boolean`, optional)
— whether to display the icon associated with the log
### `LogFunction`
Send a message to all reporter instances (TypeScript interface).
#### Overloads
- `(message: InputLogObject | string, ...args: unknown[]) => undefined | void`
- `(message: unknown, ...args: unknown[]) => undefined | void`
#### Parameters
- `message` ([`InputLogObject`](#inputlogobject) | `unknown`)
— the message to write
- `...args` (`unknown[]`, optional)
— message arguments
#### Returns
(`undefined | void`) Nothing.
### `LogFunctions`
Log formatting options (TypeScript interface).
#### Extends
- [`LogTypeFunctions`](#logtypefunctions)
#### Properties
- `inspect` ([`Inspect`](#inspect))
— use [`util.inspect`][util] on a value and print its string representation
### `LogLevel`
Union of log levels (TypeScript type).
To register custom log levels, augment [`LogLevelMap`](#loglevelmap).
They will be added to the union automatically.
```ts
type LogLevel = LogLevelMap[keyof LogLevelMap]
```
### `LogLevelMap`
Registry of log levels (TypeScript interface).
```ts
interface LogLevelMap {/* see code */}
```
When developing extensions that use additional levels, augment `LogLevelMap` to register custom log levels:
```ts
declare module '@flex-development/log' {
interface LogLevelMap {
box: 3
}
}
```
### `LogLevelOption`
Union of log level options (TypeScript type).
```ts
type LogLevelOption = LogLevel | LogLevelType
```
### `LogLevelType`
Union of log level types (TypeScript type).
To register custom log level types, augment [`LogLevelMap`](#loglevelmap).
They will be added to the union automatically.
```ts
type LogLevelType = Extract
```
### `LogObject`
Log data object (TypeScript interface).
#### Extends
- [`InputLogObject`](#inputlogobject)
#### Properties
- `additional?` (`string[]`, optional)
— additional lines to be logged with the message
- `args` (`unknown[]`)
— format arguments
- `date` (`Date`)
— timestamp
- `level` ([`LogLevel`](#loglevel))
— log level
- `message?` (`null | undefined`, optional)
— log message
- `type` ([`LogType`](#logtype))
— log type
### `LogType`
Union of log types (TypeScript type).
To register custom log types, augment [`LogTypeMap`](#logtypemap).
They will be added to the union automatically.
```ts
type LogType = LogTypeMap[keyof LogTypeMap]
```
### `LogTypeFunctions`
Dictionary of log type functions (TypeScript type).
To register custom log type functions, augment [`LogTypeMap`](#logtypemap).
They will be added to the union automatically.
```ts
type LogTypeFunctions = { [T in LogType]: LogFunction }
```
### `LogTypeMap`
Registry of log types (TypeScript interface).
```ts
interface LogTypeMap {/* see code */}
```
When developing extensions that use additional types, augment `LogTypeMap` to register custom log types:
```ts
declare module '@flex-development/log' {
interface LogTypeMap {
box: 'box'
}
}
```
### `LoggerOptions`
Logger configuration options (TypeScript interface).
#### Properties
- `defaults?` ([`InputLogObject`](#inputlogobject), optional)
— properties to apply to all logs, regardless of log type or level.
defaults can be overridden per log type using `types`
- `eol?` (`string`, optional)
— the character, or characters, used to signify the end of a line
- `color?` ([`Color`][colors-color])
— color associated with the log
- `format?` ([`LogFormatOptions`](#logformatoptions), optional)
— formatting options
- `level?` ([`LogLevelOption`](#logleveloption), optional)
— the maximum log level to output
- `reporters?` ([`ReportersOption`](#reportersoption), optional)
— reporter instances used to handle and output log messages
- `stderr?` ([`WriteStream`](#writestream), optional)
— the writeable stream for standard error output
- `stdout?` ([`WriteStream`](#writestream), optional)
— the writeable stream for standard output
- `types?` (`Partial>`, optional)
— record, where each key is a [`LogType`](#logtype) and each value is an [`InputLogObject`](#inputlogobject) defining
the configuration for the log type
### `ReportersOption`
Union of values used to configure reporters (TypeScript type).
```ts
type ReportersOption =
| Reporter
| Set
| readonly (Reporter | false | null | undefined)[]
```
### `Write`
Write data to the stream (TypeScript type).
#### Parameters
- `buffer` (`string`)
— the data to write
#### Returns
(`boolean | undefined | void`) `true` if all data was flushed successfully, `false` if all or part of the data was
queued in user memory, or nothing.
### `WithDefaults`
Create a new logger with the specified default log object properties (TypeScript interface).
#### Parameters
- `defaults` ([`InputLogObject`](#inputlogobject), optional)
— default properties to apply to any log reported from the new logger
#### Returns
([`Logger`](#logger-1)) The new logger.
### `WithTag`
Create a new logger with the specified `tag` (TypeScript interface).
#### Parameters
- `tag` (`string`)
— the tag to include in each log reported from the new logger
- `separator` (`string`, optional)
— the string to used separate tags
- default: `':'`
#### Returns
([`Logger`](#logger-1)) The new logger.
### `WriteStream`
Write stream API (TypeScript interface).
#### Properties
- `columns?` (`number`, optional)
— number of columns the tty currently has
- `write` ([`Write`](#write))
— write data to the stream
## Contribute
See [`CONTRIBUTING.md`](CONTRIBUTING.md).
This project has a [code of conduct](./CODE_OF_CONDUCT.md). By interacting with this repository, organization, or
community you agree to abide by its terms.
[bun]: https://bun.sh
[colors-color]: https://github.com/flex-development/colors#color
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh
[typescript]: https://www.typescriptlang.org
[util]: https://github.com/hildjj/node-inspect-extracted
[yarn]: https://yarnpkg.com