docs: Move some examples interfaces from README to typedocs

Simplify README by moving some examples to annotations and replace all interface blocks with links to typedoc pages
FoxxMD · Mar 28, 2024 · 8fcf116 · 8fcf116
1 parent 072c24c
commit 8fcf116
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 61 deletions.
diff --git a/README.md b/README.md
@@ -80,38 +80,7 @@ These loggers are pre-defined for specific use cases:
 
 ## Configuring
 
-The [App Loggers](#app-loggers) take an optional config object [`LogOptions`](https://foxxmd.github.io/logging/interfaces/index.LogOptions.html):
-
-```ts
-interface LogOptions {
-  /**
-   *  Specify the minimum log level for all log outputs without their own level specified.
-   *
-   *  Defaults to env `LOG_LEVEL` or `info` if not specified.
-   *
-   *  @default 'info'
-   * */
-  level?: LogLevel
-  /**
-   * Specify the minimum log level streamed to the console (or docker container)
-   * */
-  console?: LogLevel
-  /**
-   * Specify the minimum log level to output for files or a log file options object. If `false` no log files will be created.
-   * */
-  file?: LogLevel | false | FileLogOptions
-}
-```
-Available [`LogLevel`](https://foxxmd.github.io/logging/types/index.LogLevel.html) levels, from lowest to highest:
-
-* `debug`
-* `verbose`
-* `log`
-* `info`
-* `warn`
-* `error`
-* `fatal`
-* `silent`
+The [App Loggers](#app-loggers) take an optional [`LogOptions`](https://foxxmd.github.io/logging/interfaces/index.LogOptions.html) to configure [`LogLevel`](https://foxxmd.github.io/logging/types/index.LogLevel.html) globally or individually for **Console** and **File** outputs. [`file` in `LogOptions`](https://foxxmd.github.io/logging/interfaces/index.FileLogOptions.html) may also be an object that specifies more behavior for log file output.
 
 ```ts
 const infoLogger = loggerApp({
@@ -122,48 +91,38 @@ const logger = loggerApp({
   console: 'debug', // console will log `debug` and higher
   file: 'warn' // file will log `warn` and higher
 });
-```
-
-[`file` in `LogOptions`](https://foxxmd.github.io/logging/interfaces/index.FileLogOptions.html) may also be an object that specifies more behavior.
-
-### Additional App Logger Configuration
 
-`loggerApp` and `loggerAppRolling` accept an optional second parameter, [`LoggerAppExtras`](https://foxxmd.github.io/logging/interfaces/index.LoggerAppExtras.html) that allows adding additional log destinations or pino-pretty customization:
-
-```ts
-export interface LoggerAppExtras {
-  /**
-   * Additional pino-pretty options that are applied to the built-in console/log streams (including CWD redaction)
-   * */
-  pretty?: PrettyOptionsExtra
-  /**
-   * Additional logging destinations to use alongside the built-in console/log stream. These can be any created by buildDestination* functions or other Pino Transports
-   * */
-  destinations?: LogLevelStreamEntry[]
-  /**
-   * Additional Pino Log options that are passed to `pino()` on logger creation
-   * */
-  pino?: PinoLoggerOptions
-}
+const fileLogger = loggerRollingApp({
+  // no level specified => console defaults to `info` level
+  file: {
+      level: 'warn', // file will log `warn` and higher
+      path: '/my/cool/path/output.log', // output to log file at this path
+      frequency: 'daily', // rotate hourly
+      size: '20MB', // rotate if file size grows larger than 20MB
+      timestamp: 'unix' // use unix epoch timestamp instead of iso8601 in rolling file
+  }
+});
 ```
 
-Some defaults and convenience variables for pino-pretty options are available in `@foxxmd/logging/factory` prefixed with `PRETTY_`. See [factory variables docs](https://foxxmd.github.io/logging/modules/factory.html) for all options.
-
-An example using the extras parameter:
+An optional second parameter, [`LoggerAppExtras`](https://foxxmd.github.io/logging/interfaces/index.LoggerAppExtras.html), may be passed that allows adding additional log destinations or pino-pretty customization to the [App Loggers](#app-loggers). Some defaults and convenience variables for pino-pretty options are also available in [`@foxxmd/logging/factory`]((https://foxxmd.github.io/logging/modules/factory.html)) prefixed with `PRETTY_`.
 
+An example using `LoggerAppExtras`:
 ```ts
 import { loggerApp } from '@foxxmd/logging';
 import {
-    PRETTY_ISO8601, // replaces standard timestamp with ISO8601 format
+    PRETTY_ISO8601,
     buildDestinationFile 
 } from "@foxxmd/logging/factory";
 
+// additional file logging but only at `warn` or higher
 const warnFileDestination = buildDestinationFile('warn', {path: './myLogs/warn.log'});
 
-const logger = loggerApp({}, {
+const logger = loggerApp({
+  level: 'debug', // console AND built-in file logging will log `debug` and higher
+  }, {
    destinations: [warnFileDestination],
    pretty: {
-     translateTime: PRETTY_ISO8601
+     translateTime: PRETTY_ISO8601 // replaces standard timestamp with ISO8601 format
    }
 });
 logger.debug('Test');
@@ -243,7 +202,7 @@ const causeErr = new ErrorWithCause('A top-level error', {cause: er});
 logger.debug(causeErr, 'Test');
 /*
 [2024-03-07 11:43:27.453 -0500] DEBUG: Test
-ErrorWithCause: A top-level error
+Error: A top-level error
     at <anonymous> (/my/dir/src/index.ts:55:18)
 caused by: Error: This is the original error
     at <anonymous> (/my/dir/src/index.ts:54:12)

diff --git a/src/types.ts b/src/types.ts
@@ -2,6 +2,22 @@ import {DestinationStream, Logger as PinoLogger, LoggerOptions, StreamEntry, Lev
 import {PrettyOptions} from "pino-pretty";
 import {MarkRequired} from "ts-essentials";
 
+/**
+ * Names of log levels that can be invoked on the logger
+ *
+ * From lowest to highest:
+ *
+ * * `debug`
+ * * `verbose`
+ * * `log`
+ * * `info`
+ * * `warn`
+ * * `error`
+ * * `fatal`
+ * * `silent` (will never output anything)
+ *
+ * When used in `LogOptions` specifies the **minimum** level the output should log at.
+ * */
 export type LogLevel = typeof LOG_LEVEL_NAMES[number];
 
 /**
@@ -34,6 +50,29 @@ const CUSTOM_LEVEL_NAMES = Object.keys(CUSTOM_LEVELS);
 
 export const LOG_LEVEL_NAMES= ['silent', 'fatal', 'error', 'warn', 'info', 'log', 'verbose', 'debug'] as const;
 
+/**
+ * Configure log levels and file options for an AppLogger.
+ *
+ * ```ts
+ * const infoLogger = loggerApp({
+ *  level: 'info' // console and file will log any levels `info` and above
+ * });
+ *
+ * const logger = loggerApp({
+ *   console: 'debug', // console will log `debug` and higher
+ *   file: 'warn' // file will log `warn` and higher
+ * });
+ *
+ * const fileLogger = loggerRollingApp({
+ *   console: 'debug', // console will log `debug` and higher
+ *   file: {
+ *       level: 'warn', // file will log `warn` and higher
+ *       path: '/my/cool/path/output.log', // optionally, output to log file at this path
+ *       frequency: 'hourly', // optionally, rotate hourly
+ *   }
+ * });
+ * ```
+ * */
 export interface LogOptions {
     /**
      *  Specify the minimum log level for all log outputs without their own level specified.
@@ -125,6 +164,21 @@ export interface RollOptions {
     timestamp?: 'unix' | 'iso' | 'auto'
 }
 
+/**
+ * Specify and override default log file options
+ *
+ * ```ts
+ * const fileLogger = loggerRollingApp({
+ *   file: {
+ *       level: 'warn', // file will log `warn` and higher
+ *       path: '/my/cool/path/output.log', // output to log file at this path
+ *       frequency: 'daily', // rotate hourly
+ *       size: '20MB', // rotate if file size grows larger than 20MB
+ *       timestamp: 'unix' // use unix epoch timestamp instead of iso8601 in rolling file
+ *   }
+ * });
+ * ```
+ * */
 export interface FileOptions extends PinoRollOptions, RollOptions {
     /**
      * The path and filename to use for log files.
@@ -168,6 +222,9 @@ export type JsonPrettyDestination =  StreamDestination & {
 
 export type LogOptionsParsed = Omit<Required<LogOptions>, 'file'> & { file: FileLogOptionsParsed }
 
+/**
+ * Additional settings and Pino Transports to apply to the returned Logger.
+ * */
 export interface LoggerAppExtras {
     /**
      * Additional pino-pretty options that are applied to the built-in console/log streams