@wing-logger/logger/README.md

wing logger

# @wing-logger/logger

## Install

```shell
$ npm i @wing-logger/logger
```

## Usage

```ts
import Logger, { ConsoleAppender } from '@wing-logger/logger';

const logger = new Logger('MY_CATEGORY');
logger.addAppender(new ConsoleAppender(logger));

logger.fatal('Fatal', { name: 'fatal' }); // √
logger.error('Error', { name: 'error' }); // √
logger.warn('Warn', { name: 'warn' }); // √
logger.info('Info', { name: 'info' }); // √
logger.debug('Debug', { name: 'debug' }); // √
logger.trace('Trace', { name: 'trace' }); // √

// all 6 of the above will be output to the console
```

### Level

The log level of the logger instance.
Default with `Level.ALl` both in `instance` and `global`.

#### Instance Level

```ts
import Logger, { ConsoleAppender, Level } from '@wing-logger/logger';

const logger = new Logger('MY_CATEGORY', Level.Info);
logger.addAppender(new ConsoleAppender(logger));

logger.fatal('Fatal', { name: 'fatal' }); // √
logger.error('Error', { name: 'error' }); // √
logger.warn('Warn', { name: 'warn' }); // √
logger.info('Info', { name: 'info' }); // √

// `debug` and `trace` will `not` be output to the console when level set as `Level.Info`
logger.debug('Debug', { name: 'debug' }); // ×
logger.trace('Trace', { name: 'trace' }); // ×
```

#### Global Level

The global level will affect all instances.

```ts
import Logger, { ConsoleAppender, Level } from '@wing-logger/logger';

const logger = new Logger('MY_CATEGORY', Level.All);
logger.addAppender(new ConsoleAppender(logger));

// set global level as `Level.Error`
Logger.globalLevel = Level.Error;
// only `fatal` and `error` will be output to the console when global level set as `Level.Error`
logger.fatal('Fatal', { name: 'fatal' }); // √
logger.error('Error', { name: 'error' }); // √

logger.warn('Warn', { name: 'warn' }); // ×
logger.info('Info', { name: 'info' }); // ×
logger.debug('Debug', { name: 'debug' }); // ×
logger.trace('Trace', { name: 'trace' }); // ×
```

### Appender

```shell
$ npm i @wing-logger/appender
```

> Tips
>
> - Synchronization precedes asynchronization
> - Synchronization is performed on a first-come-first-served basis.

#### ConsoleAppender

The default console appender

```ts
import Logger, { ConsoleAppender, Level } from '@wing-logger/logger';
const logger = new Logger('MY_CATEGORY');
logger.addAppender(new ConsoleAppender(logger));

logger.fatal('Fatal', { name: 'fatal' });
logger.error('Error', { name: 'error' });
logger.warn('Warn', { name: 'warn' });
logger.info('Info', { name: 'info' });
logger.debug('Debug', { name: 'debug' });
logger.trace('Trace', { name: 'trace' });
```

#### Sync Appender

- Generate a class that `implements` IAppender.

  ```ts
  import { type IAppender } from '@wing-logger/appender';
  import Logger, { Level } from '@wing-logger/logger';

  class SyncAppender1 implements IAppender {
    execute(level: Level, ...args: any[]) {
      console.log(`[Sync Appender_1] level=${level}`, ...args);
    }
  }

  class SyncAppender2 implements IAppender {
    execute(level: Level, ...args: any[]) {
      console.log(`[Sync Appender_2] level=${level}`, ...args);
    }
  }
  const logger = new Logger('MY_CATEGORY');

  logger.addAppender(new SyncAppender1());
  logger.addAppender(new SyncAppender2());

  logger.fatal('Fatal', { name: 'fatal' });
  logger.error('Error', { name: 'error' });
  logger.warn('Warn', { name: 'warn' });
  logger.info('Info', { name: 'info' });
  logger.debug('Debug', { name: 'debug' });
  logger.trace('Trace', { name: 'trace' });
  ```

#### Async Appender

- Generate a class that `extends` Appender.

  ```ts
  class AsyncAppender1 extends Appender {
    constructor() {
      super((level: Level, ...args: any[]): Promise<boolean> => {
        return new Promise((resolve) => {
          const label = `[Async Appender] level=${level} ${JSON.stringify(args)} took`;
          console.time(label);
          setTimeout(() => {
            console.timeEnd(label);
            resolve(true);
          }, 0);
        });
      });
    }
  }
  ```

  ```ts
  class AsyncAppender2 extends Appender {
    constructor() {
      super((level: Level, ...args: any[]): Promise<boolean> => {
        console.log(`[Async Appender_2] level=${level}`, ...args);
        return Promise.resolve(true);
      });
    }
  }
  ```

- Create an instance of `Appender`.

  ```ts
  function asyncExecuteHandler(level: Level, ...args: any[]): Promise<boolean> {
    console.log(`[Async ExecuteHandler] level=${level}`, ...args);
    return Promise.resolve(true);
  }
  ```

Async Appender Example:

```ts
import Appender from '@wing-logger/appender';
import Logger, { Level } from '@wing-logger/logger';
class AsyncAppender1 extends Appender {
  constructor() {
    super((level: Level, ...args: any[]): Promise<boolean> => {
      return new Promise((resolve) => {
        const label = `[Async Appender] level=${level} ${JSON.stringify(args)} took`;
        console.time(label);
        setTimeout(() => {
          console.timeEnd(label);
          resolve(true);
        }, 0);
      });
    });
  }
}
class AsyncAppender2 extends Appender {
  constructor() {
    super((level: Level, ...args: any[]): Promise<boolean> => {
      console.log(`[Async Appender_2] level=${level}`, ...args);
      return Promise.resolve(true);
    });
  }
}
function asyncExecuteHandler(level: Level, ...args: any[]): Promise<boolean> {
  console.log(`[Async ExecuteHandler] level=${level}`, ...args);
  return Promise.resolve(true);
}
const logger = new Logger('MY_CATEGORY');

logger.addAppender(new AsyncAppender1());
logger.addAppender(new AsyncAppender2());
logger.addAppender(new Appender(asyncExecuteHandler));

logger.fatal('Fatal', { name: 'fatal' });
logger.error('Error', { name: 'error' });
logger.warn('Warn', { name: 'warn' });
logger.info('Info', { name: 'info' });
logger.debug('Debug', { name: 'debug' });
logger.trace('Trace', { name: 'trace' });
```