From 9fa8e5854c93984b7389958af193bd51ac5d77ff Mon Sep 17 00:00:00 2001 From: FoxxMD Date: Fri, 8 Mar 2024 12:27:50 -0500 Subject: [PATCH] docs: Add more annotations --- README.md | 2 +- src/destinations.ts | 36 +++++++++++++++++++++++++++--------- src/funcs.ts | 6 ++++-- src/loggers.ts | 22 ++++++++++++++++++++++ src/pretty.ts | 15 +++++++++------ src/types.ts | 8 ++++++++ 6 files changed, 71 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 62675e1..b216c21 100644 --- a/README.md +++ b/README.md @@ -187,7 +187,7 @@ export interface FileOptions { ### Additional App Logger Configuration -`loggerApp` and `loggerAppRolling` accept an optional second parameter, [`LoggerAppExtras`](https://foxxmd.github.io/logging/types/index.LoggerAppExtras.html) that allows adding additional log destinations or pino-pretty customization: +`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 { diff --git a/src/destinations.ts b/src/destinations.ts index 020a8fe..82bf712 100644 --- a/src/destinations.ts +++ b/src/destinations.ts @@ -13,6 +13,9 @@ import path from "path"; import {ErrorWithCause} from "pony-cause"; const pRoll = pinoRoll as unknown as typeof pinoRoll.default; +/** + * Creates a `LogLevelStreamEntry` stream that writes to a rolling file at or above the minimum `level` + * */ export const buildDestinationRollingFile = async (level: LogLevel | false, options: FileDestination): Promise => { if (level === false) { return undefined; @@ -73,6 +76,9 @@ export const buildDestinationRollingFile = async (level: LogLevel | false, optio }; } +/** + * Creates a `LogLevelStreamEntry` stream that writes to a static file at or above the minimum `level` + * */ export const buildDestinationFile = (level: LogLevel | false, options: FileDestination): LogLevelStreamEntry | undefined => { if (level === false) { return undefined; @@ -94,6 +100,11 @@ export const buildDestinationFile = (level: LogLevel | false, options: FileDesti } } +/** + * Creates a `LogLevelStreamEntry` stream that writes to a `NodeJs.WriteableStream` or [Sonic Boom `DestinationStream`](https://github.com/pinojs/sonic-boom) at or above the minimum `level` + * + * @see DestinationStream + * */ export const buildDestinationStream = (level: LogLevel, options: StreamDestination): LogLevelStreamEntry => { return { level: level, @@ -101,17 +112,24 @@ export const buildDestinationStream = (level: LogLevel, options: StreamDestinati } } +/** + * Creates a `LogLevelStreamEntry` stream that writes to STDOUT at or above the minimum `level` + * + * @source + * @see buildDestinationStream + * */ export const buildDestinationStdout = (level: LogLevel, options: Omit = {}): LogLevelStreamEntry => { - const opts = {...prettyConsole, ...options, destination: destination({dest: 1, sync: true})} - return { - level: level, - stream: prettyDef.default(opts) - } + const opts = {...options, destination: destination({dest: 1, sync: true})} + return buildDestinationStream(level, opts); } +/** + * Creates a `LogLevelStreamEntry` stream that writes to STDERR at or above the minimum `level` + * + * @source + * @see buildDestinationStream + * */ export const buildDestinationStderr = (level: LogLevel, options: Omit = {}): LogLevelStreamEntry => { - return { - level: level, - stream: prettyDef.default({...prettyConsole, ...options, destination: destination({dest: 2, sync: true})}) - } + const opts = {...options, destination: destination({dest: 2, sync: true})}; + return buildDestinationStream(level, opts); } diff --git a/src/funcs.ts b/src/funcs.ts index 73b72a3..0165d1f 100644 --- a/src/funcs.ts +++ b/src/funcs.ts @@ -1,9 +1,11 @@ import process from "process"; -import {FileLogOptions, FileLogOptionsParsed, isLogOptions, LogLevel, LogOptions, LogOptionsParsed} from "./types.js"; +import {FileLogOptionsParsed, isLogOptions, LogLevel, LogOptions, LogOptionsParsed} from "./types.js"; import {logPath, projectDir} from "./constants.js"; import {isAbsolute, resolve} from 'node:path'; -import {MarkRequired} from "ts-essentials"; +/** + * Takes an object and parses it into a fully-populated LogOptions object based on opinionated defaults + * */ export const parseLogOptions = (config: LogOptions = {}): LogOptionsParsed => { if (!isLogOptions(config)) { throw new Error(`Logging levels were not valid. Must be one of: 'silent', 'fatal', 'error', 'warn', 'info', 'verbose', 'debug', -- 'file' may be false.`) diff --git a/src/loggers.ts b/src/loggers.ts index bb657ea..becaaac 100644 --- a/src/loggers.ts +++ b/src/loggers.ts @@ -3,6 +3,13 @@ import {Logger, LoggerAppExtras, LogLevel, LogLevelStreamEntry, LogOptions} from import {buildDestinationFile, buildDestinationRollingFile, buildDestinationStdout} from "./destinations.js"; import {pino} from "pino"; +/** + * Builds a Logger object for use in your application + * + * `defaultLevel` must the minimum level ANY stream can log from IE it should be the lowest level any of your streams will possibly log. Recommended to always use `debug`. + * + * @see Logger + * */ export const buildLogger = (defaultLevel: LogLevel, streams: LogLevelStreamEntry[]): Logger => { const plogger = pino({ // @ts-ignore @@ -37,6 +44,15 @@ export const buildLogger = (defaultLevel: LogLevel, streams: LogLevelStreamEntry } return plogger; } + +/** + * Returns a new logger with the given properties appended to all log objects created by it + * + * @param parent Logger Parent logger to inherit from + * @param labelsVal (any | any[]) Labels to always apply to logs from this logger + * @param context object Additional properties to always apply to logs from this logger + * @param options object + * */ export const childLogger = (parent: Logger, labelsVal: any | any[] = [], context: object = {}, options = {}): Logger => { const newChild = parent.child(context, options) as Logger; const labels = Array.isArray(labelsVal) ? labelsVal : [labelsVal]; @@ -64,6 +80,9 @@ export const loggerTest = buildLogger('silent', [buildDestinationStdout('debug') * */ export const loggerDebug = buildLogger('debug', [buildDestinationStdout('debug')]); +/** + * A Logger that logs to console and a static file + * */ export const loggerApp = (config: LogOptions | object = {}, extras?: LoggerAppExtras) => { const { @@ -96,6 +115,9 @@ export const loggerApp = (config: LogOptions | object = {}, extras?: LoggerAppEx return logger; } +/** + * A Logger that logs to console and a rolling file + * */ export const loggerAppRolling = async (config: LogOptions | object = {}, extras?: LoggerAppExtras) => { const { diff --git a/src/pretty.ts b/src/pretty.ts index 8e8df4c..95e93e9 100644 --- a/src/pretty.ts +++ b/src/pretty.ts @@ -4,7 +4,7 @@ import {CWD} from "./util.js"; /** * Additional levels included in @foxxmd/logging as an object * - * These are always applied when using prettyOptsFactory() but can be overridden + * These are always applied when using `prettyOptsFactory` but can be overridden * */ export const PRETTY_LEVELS: Extract = { verbose: 25, @@ -13,20 +13,20 @@ export const PRETTY_LEVELS: Extract = { /** * Additional levels included in @foxxmd/logging as a string * - * These are always applied when using prettyOptsFactory() but can be overridden + * These are always applied when using `prettyOptsFactory` but can be overridden * */ export const PRETTY_LEVELS_STR: Extract = 'verbose:25,log:21'; /** * Additional level colors included in @foxxmd/logging as an object * - * These are always applied when using prettyOptsFactory() but can be overridden + * These are always applied when using `prettyOptsFactory` but can be overridden * */ export const PRETTY_COLORS_STR: Extract = 'verbose:magenta,log:greenBright'; /** * Additional level colors included in @foxxmd/logging as a string * - * These are always applied when using prettyOptsFactory() but can be overridden + * These are always applied when using `prettyOptsFactory` but can be overridden * */ export const PRETTY_COLORS: Extract = { 'verbose': 'magenta', @@ -38,6 +38,9 @@ export const PRETTY_COLORS: Extract = { * */ export const PRETTY_ISO8601 = 'SYS:yyyy-mm-dd"T"HH:MM:ssp'; +/** + * Builds the opinionated `@foxxmd/logging` defaults for pino-pretty `PrettyOptions` and merges them with an optional user-provided `PrettyOptions` object + * */ export const prettyOptsFactory = (opts: PrettyOptions = {}): PrettyOptions => { const {customLevels = {}, customColors = {}, ...rest} = opts; @@ -99,13 +102,13 @@ const buildColors = (userColors: PrettyOptions['customColors'] = {}): PrettyOpti } /** - * Pre-defined pretty options for use with console/stream output + * Pre-defined pino-pretty `PrettyOptions` for use with console/stream output * * @source * */ export const prettyConsole: PrettyOptions = prettyOptsFactory({sync: true}) /** - * Pre-defined pretty options for use with file output + * Pre-defined pino-pretty `PrettyOptions` for use with file output * * @source * */ diff --git a/src/types.ts b/src/types.ts index f7fe4f2..b5470ec 100644 --- a/src/types.ts +++ b/src/types.ts @@ -49,8 +49,16 @@ export type Logger = PinoLogger & { addLabel: (value: any) => void } +/** + * An object with a `write` function that can be used by pino as a [Transport](https://getpino.io/#/docs/transports) + * + * All `buildDestination*` functions return this type as well as any [Pino Transport](https://getpino.io/#/docs/transports?id=known-transports) + * */ export type LogLevelStreamEntry = StreamEntry +/** + * The structure of a Log object when returned by a stream `data` event + * */ export type LogData = Record & { level: number time: number -- 2.51.2