# winston-cfg

> Enables [winston](https://github.com/winstonjs/winston) configuration via [node-config](https://github.com/lorenwest/node-config)

Latest version **1.0.12** (published 2018-05-07) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install winston-cfg
pnpm add winston-cfg
yarn add winston-cfg
bun add winston-cfg
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.12 |
| Published | 2018-05-07 |
| First published | 2017-03-09 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=6.0.0 |
| Dependencies | 7 |
| Unpacked size | 28.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | yes |
| Author | Shishir Ramam |
| Maintainers | sramam |
| Keywords | TypeScript, winston, config, file |

## Links

- npm: https://www.npmjs.com/package/winston-cfg
- Repository: https://github.com/sramam/winston-cfg
- Homepage: https://github.com/sramam/winston-cfg#readme
- Issues: https://github.com/sramam/winston-cfg/issues
- npm.io page: https://npm.io/package/winston-cfg

## Dependencies (7)

- [chalk](https://npm.io/package/chalk.md) ^2.4.1
- [config](https://npm.io/package/config.md) ^1.30.0
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1
- [semver](https://npm.io/package/semver.md) ^5.5.0
- [winston](https://npm.io/package/winston.md) ^2.4.0
- [lodash.merge](https://npm.io/package/lodash.merge.md) ^4.6.1
- [parse-git-config](https://npm.io/package/parse-git-config.md) ^2.0.2

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 1.0.12 (latest) — 2018-05-07
- 1.0.11 — 2017-11-12
- 1.0.10 — 2017-08-25
- 1.0.9 — 2017-08-24
- 1.0.8 — 2017-08-23
- 1.0.7 — 2017-03-19
- 1.0.6 — 2017-03-19
- 1.0.5 — 2017-03-10
- 1.0.4 — 2017-03-10
- 1.0.3 — 2017-03-09
- 1.0.2 — 2017-03-09
- 1.0.1 — 2017-03-09
- 1.0.0 — 2017-03-09

## README

# winston-cfg

<!-- badge -->
[![npm license](https://img.shields.io/npm/l/winston-cfg.svg)](https://www.npmjs.com/package/winston-cfg)
[![travis status](https://img.shields.io/travis/sramam/winston-cfg.svg)](https://travis-ci.org/sramam/winston-cfg)
[![Build status](https://ci.appveyor.com/api/projects/status/g7ev07vefgqxl70x?svg=true)](https://ci.appveyor.com/project/sramam/winston-cfg)
[![Coverage Status](https://coveralls.io/repos/github/sramam/winston-cfg/badge.svg?branch=master)](https://coveralls.io/github/sramam/winston-cfg?branch=master)
[![David](https://david-dm.org/sramam/winston-cfg/status.svg)](https://david-dm.org/sramam/winston-cfg)
[![David](https://david-dm.org/sramam/winston-cfg/dev-status.svg)](https://david-dm.org/sramam/winston-cfg?type=dev)
<br/>
[![NPM](https://nodei.co/npm/winston-cfg.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/winston-cfg/)
<!-- endbadge -->

A simple utility that enables [winston](https://github.com/winstonjs/winston) configuration via [node-config](https://github.com/lorenwest/node-config)

## Usage

### A brief introduction to winston internals

For most common use cases, there are three things that one needs to configure with winston:

1. _transports_: the destination(s) for the logs. Winston provides a few out of the box. Transports with external dependencies,  with external dependencies are supported as 3rd party modules. Depending on the actual transport, some have pretty involved configuration.
1. _loggers_: an ability to segment logging capability, for example by application layer (app, http, db etc). Each logger can have multiple transports - either the global or a custom set.
1. _default logger_: `winston` instantiate a default logger that is configured with a 'Console' transport and set to 'info' level. This can be configured in exactly the same manner as any logger.

```bash
                 +-------------------------------------------+
                 |            winston configuration          |
+-------------+  |                                           |
| APPLICATION    |       +----------+                        |
|             |  |  +--> | Default  +--+                     |
|             |  |  |    +----------+  |                     |
| +---------+ |  |  |    +----------+  |   +-------------+   |
| | Layer 1 +----------> | Logger 1 +-+--> | Transport A +--------->
| +---------+ |  |       +----------+ |    +-------------+   |
|     ...     |  |                    |                      |
| +---------+ |  |       +----------+ +--> +-------------+   |
| | Layer N +----------> | Logger 1 +----> | Transport B +--------->
| +---------+ |  |       +----------+      +-------------+   |
+-------------+  |                                           |
                 |                                           |
                 +-------------------------------------------+

```

### Simple Configuraton

Please see the interface definition in [src/index.ts:Config](https://github.com/sramam/winston-cfg/blob/master/src/index.ts#L10) for details
on valid config settings.

And [node-config](https://github.com/lorenwest/node-config) for use of the config module.

```json
// in config/defaults.json
{
  "winston": {
    "level": "info",
    "transports": [{
      "type": "Console"
    }]
  }
}
```

```javascript
const log = require('winston-cfg').winstonCfg();
```

```typescript
import { winstonCfg } from 'winston-cfg';
const log = winstongCfg();
```

### Advanced Configuration

#### transportMap

Since transports may be external modules, `winston` expects to be provided
instances of transports associated with a logger - global or custom.

We are however attempting to expose only the config capability. As a compromise, `winston-cfg` adds a 'type' property to the config. The application also has to instantiate a `transportMap`, which allows the `winston-cfg` to create
appropriate transports before instantiating loggers.

By default, `winston-core` supports four transports: `Console`, `File`, `Http` & `Memory`. Additionally, [3rd-party transports](https://github.com/winstonjs/winston/blob/master/docs/transports.md)
extend support for other storage mechanisms.

##### Config file

Please see the interface definition in [src/index.ts:Config](https://github.com/sramam/winston-cfg/blob/master/src/index.ts#L10) for details
on valid config settings.

And [node-config](https://github.com/lorenwest/node-config) for use of the config module.

```json
{
  "winston": {
    "level": "info",
    "transports": [
      {
        "type": "Console"
      },
      {
        "type": "File",
        "filename": "./winston.log"
      },
      {
        "type": "CouchDB",
        // ... CouchDb Config.
      }
    ],
    "loggers": [{
      "id": "app",
      "level": "info",
      "transports": [{
        "type": "SimpleDB",
        // ...
      }],
    }, {
      "id": "http"
    }]
  }
}
```

##### TypeScript boilerplate

```typescript

// do this in your application startup

import { winstonCfg } from 'winston-cfg';

// import custom transports
import { Couchdb as CouchDB } from 'winston-couchdb';
import { SimpleDB } from 'winston-simpledb';

// prepare a transport map for initialization
const transportMap = {
  'CouchDB': CouchDB,
  'SimpleDB': SimpleDB
};

// read config and initialize winston appropriately.
// See [node-config](https://github.com/lorenwest/node-config) for details.
const winston = winstonCfg(transportMap);

// get handles to individual loggers
const log = winston; // default logger
const app_log = winston.loggers.get('app');
const http_log = winston.loggers.get('http');

// use log, app_log & http_log as needed.
```

##### JavaScript boilerplate

```js
const logger = 'winston-cfg';

// import custom transports
const CouchDB = require('winston-couchdb').CouchDb;
const SimpleDB = require('winston-simpledb').SimpleDB;

// prepare a transport map for initialization
const transportMap = {
  'CouchDB': CouchDB,
  'SimpleDB': SimpleDB
};

// read config and initialize winston appropriately.
// See [node-config](https://github.com/lorenwest/node-config) for details.
const winston = winstonCfg(transportMap);

// get handles to individual loggers
const log = winston; // default logger
const app_log = winston.loggers.get('app');
const http_log = winston.loggers.get('http');

// use log, app_log & http_log as needed.
```

## License

Apache 2.0

## Code of Conduct

Please note that this project is released with a [Contributor Code of Conduct](code-of-conduct.md).
By participating in this project you agree to abide by its terms.

## Support

Bugs, PRs, comments, suggestions are all welcomed!

---
_Source: https://npm.io/package/winston-cfg · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._