@wireio/shared 1.0.0

package/src/logging/LoggingManager.ts

@@ -0,0 +1,306 @@
+import { isNumber, isObject, isString } from "../guards/index.js"
+import { Option } from "prelude-ts"
+import { flatten, isEmpty, min, negate } from "lodash"
+import type { Appender } from "./Appender.js"
+import { ConsoleAppender } from "./appenders/ConsoleAppender.js"
+import { Level, LevelKind, LevelThresholds } from "./Level.js"
+import { Logger, LoggerOptions } from "./Logger.js"
+import type { LogRecord } from "./LogRecord.js"
+import { LogContext, LogContextContainer } from "./context/index.js"
+import { flow, get, nth } from "lodash/fp.js"
+
+export type CategoryMatch = RegExp | string
+
+export type ThresholdOverride = [match: CategoryMatch, level: LevelKind]
+
+export interface LoggingManagerState<Record extends LogRecord> {
+  rootLevel: LevelKind
+  appenders: Array<Appender<Record>>
+  thresholdOverrides: Array<ThresholdOverride>
+}
+
+export type LoggingManagerOptions<Record extends LogRecord> = Partial<
+  LoggingManagerState<Record>
+>
+
+function parseThresholdOverridePatterns(
+  value: string,
+  level: LevelKind = "debug"
+): ThresholdOverride[] {
+  return value
+    .split(",")
+    .map((s) => [new RegExp(s), level] as ThresholdOverride)
+}
+
+export const kEnvThresholdOverrides = Option.ofNullable(typeof process !== "undefined" && process.env.DEBUG_PATTERNS)
+  .filter(negate(isEmpty))
+  .map(parseThresholdOverridePatterns)
+  .getOrElse([])
+
+/**
+ * Logging manager
+ */
+export class LoggingManager<Record extends LogRecord = any> {
+  private readonly loggers = new Map<string, Logger>()
+
+  private readonly state: LoggingManagerState<Record> = {
+    appenders: [],
+    rootLevel: Level.info,
+    thresholdOverrides: kEnvThresholdOverrides
+  }
+
+  get rootLevel() {
+    return this.state.rootLevel
+  }
+
+  set rootLevel(newRootLevel: LevelKind) {
+    this.state.rootLevel = newRootLevel
+  }
+
+  get rootThreshold() {
+    return LevelThresholds[this.rootLevel]
+  }
+
+  /**
+   * Get the current handler
+   *
+   * @returns {Appender<Record>}
+   */
+  get appenders(): Array<Appender<Record>> {
+    return Option.ofNullable(this.state.appenders)
+      .filter((appenders) => appenders.length > 0)
+      .getOrCall(() => {
+        this.state.appenders.push(new ConsoleAppender())
+        return this.state.appenders
+      })
+  }
+  
+  /**
+   * Global threshold overrides
+   */
+  get thresholdOverrides() {
+    return this.state.thresholdOverrides
+  }
+  
+  /**
+   * Update the overrides
+   *
+   * @param newOverrides
+   */
+  set thresholdOverrides(newOverrides:ThresholdOverride[]) {
+    this.state.thresholdOverrides = newOverrides
+  }
+  
+  /**
+   * Set global appenders
+   *
+   * @param {Array<Appender<Record>>} newAppenders
+   */
+  setAppenders(...newAppenders: Array<Appender<Record> | Appender<Record>[]>) {
+    // WE MUTATE DO TO THE LIKELIHOOD OF SOMEONE HOLDING A REF TO THE ARRAY,
+    // CONVERT TO OBSERVABLE AT SOME POINT
+    const persistentAppenders = this.state.appenders
+    persistentAppenders.length = 0
+    persistentAppenders.push(...flatten(newAppenders))
+
+    return this
+  }
+  
+  /**
+   * Add one or more appenders to existing appender set
+   *
+   * @param {Appender<Record> | Appender<Record>[]} newAppenders
+   * @returns {this<Record>}
+   */
+  addAppenders(...newAppenders: Array<Appender<Record> | Appender<Record>[]>): this {
+    this.state.appenders.push(...flatten(newAppenders))
+    return this
+  }
+  
+  /**
+   * Clear threshold overrides
+   *
+   * @returns {this<Record>}
+   */
+  clearThresholdOverrides(): this {
+    this.state.thresholdOverrides.length = 0
+    return this
+  }
+
+  setThresholdOverrides(...overrides: Array<ThresholdOverride>) {
+    this.state.thresholdOverrides.length = 0
+    this.state.thresholdOverrides.push(...overrides)
+    return this
+  }
+
+  addThresholdOverrides(...overrides: Array<ThresholdOverride>) {
+    this.state.thresholdOverrides.push(...overrides)
+    return this
+  }
+
+  /**
+   * Get applicable current contexts
+   *
+   * @param {string} category
+   * @returns {LogContext[]}
+   */
+  getApplicableCurrentContexts(category: string): LogContext[] {
+    return LogContextContainer.currentContext().filter(
+      ({ pattern }) => !pattern || pattern.test(category)
+    )
+  }
+
+  /**
+   * Check for any matching threshold overrides
+   *
+   * @param category
+   */
+  determineThresholdOverride(category: string): number {
+    const contexts = this.getApplicableCurrentContexts(category),
+      
+    // FIND CONFIGURED OVERRIDE LEVEL
+      overrideThreshold = Option.ofNullable(
+        this.thresholdOverrides.find(([match]) =>
+          isString(match) ? match === category : (match as RegExp).test(category)
+        )
+      )
+        .map(nth(1))
+        .map((level) => LevelThresholds[level as Level])
+        .getOrNull(),
+      // FIND `LogContext` OVERRIDE LEVEL
+      contextThresholds = contexts
+        .filter(flow(get("thresholdLevel"), isString))
+        .map(({ thresholdLevel }) => LevelThresholds[thresholdLevel]),
+      // IF ANY OVERRIDES, GET THE MOST VERBOSE LEVEL
+      override = Option.ofNullable(
+        [...contextThresholds, overrideThreshold].filter(isNumber)
+      )
+        .filter(negate(isEmpty))
+        .map(min)
+        .getOrNull()
+
+    return override as number
+  }
+  
+  /**
+   * Set the root logging level
+   *
+   * @param {LevelKind} newLevel
+   * @returns {this<Record>}
+   */
+  setRootLevel(newLevel: LevelKind): this {
+    this.state.rootLevel = newLevel
+    return this
+  }
+  
+  /**
+   * Fire a log event, eventually
+   * invert this by making `Logger` an
+   * `EventEmitter3` and having the `LoggingManager`
+   * subscribe to `record` event
+   *
+   * @param {LogRecord<Record>} record
+   * @internal
+   */
+  fire(record: LogRecord<Record>) {
+    const { category } = record,
+      contexts = this.getApplicableCurrentContexts(category),
+      contextAppenders = contexts.flatMap(get("appenders")),
+      appenders = [...this.appenders, ...contextAppenders]
+
+    appenders.forEach((appender) => appender.append(record as Record))
+  }
+  
+  /**
+   * Get a logger from cache, if the category
+   * does not have an existing logger, then create one.
+   *
+   * @param {string} categoryOrFilename
+   * @param {Partial<LoggerOptions>} inOptions
+   * @returns {Logger}
+   */
+  getLogger(
+    categoryOrFilename: string,
+    inOptions: Partial<LoggerOptions> = {}
+  ): Logger {
+    const options = Logger.hydrateOptions(inOptions)
+    const category = Logger.interoplateCategory(categoryOrFilename, options)
+
+    return Option.ofNullable(category)
+      .map((category) => this.loggers.get(category))
+      .getOrCall(() => {
+        const logger = new Logger(this, category, options)
+        this.loggers.set(category, logger)
+        return logger
+      })
+  }
+
+  /**
+   * Configure the logging manager,
+   * this function is additive, so simply calling
+   * `configure` with a single option `rootLevel`,
+   * will not affect other options like `appenders`   *
+   *
+   * @param {LoggingManagerOptions<any>} options
+   * @returns {this<Record>}
+   */
+  configure(options: LoggingManagerOptions<any>): this {
+    if (Level[options?.rootLevel]) {
+      this.setRootLevel(options.rootLevel)
+    }
+
+    if (options?.appenders) {
+      this.setAppenders(options.appenders)
+    }
+
+    if (options?.thresholdOverrides) {
+      this.addThresholdOverrides(...options.thresholdOverrides)
+    }
+
+    return this
+  }
+
+  private constructor() {
+    this.configure({})
+  }
+  
+  /**
+   * Singleton instance
+   *
+   * @type {LoggingManager}
+   * @private
+   */
+  private static manager: LoggingManager
+  
+  /**
+   * Get logging manager and optionally provided
+   * configuration options
+   *
+   * @param {LoggingManagerOptions<Record>} options
+   * @returns {LoggingManager<Record>}
+   */
+  static get<Record extends LogRecord = any>(
+    options: LoggingManagerOptions<Record> = null
+  ): LoggingManager<Record> {
+    if (!this.manager) {
+      this.manager = new LoggingManager<Record>()
+    }
+
+    if (options) {
+      this.manager.configure(options)
+    }
+
+    return this.manager
+  }
+}
+
+export function getLoggingManager(): LoggingManager {
+  return LoggingManager.get()
+}
+
+if (Option.try_(() => process.env.NODE_ENV === "development").getOrElse(false)) {
+  [typeof window !== "undefined" && window, typeof global !== "undefined" && global].filter(isObject)
+    .map(target => Object.assign(target, {
+      loggingManager: getLoggingManager()
+    }))
+}

package/src/logging/appenders/ConsoleAppender.ts

@@ -0,0 +1,110 @@
+import type { LogRecord } from "../LogRecord"
+import type { Appender } from "../Appender"
+import { Option } from "prelude-ts"
+import type { LevelKind } from "../Level"
+import type { Formatter } from "../Formatter"
+
+const consoleLogBindings = new Map<LevelKind, (...args: any[]) => any>()
+
+function getBoundConsoleFn(level: LevelKind) {
+  return (console[level] ?? console.log).bind(console)
+}
+
+/**
+ * Get a cached console bound log function
+ *
+ * @param {LevelKind} level
+ * @returns {(...args: any[]) => any}
+ */
+export function getConsoleLogBinding(level: LevelKind) {
+  if (!consoleLogBindings.has(level)) {
+    consoleLogBindings.set(level, getBoundConsoleFn(level))
+  }
+
+  return consoleLogBindings.get(level)
+}
+
+/**
+ * ConsoleAppender Configuration
+ */
+export interface ConsoleAppenderConfig<Record extends LogRecord = any> {
+  cacheEnabled: boolean
+  prettyPrint: boolean
+  formatter?: Formatter<string | Array<any>>
+}
+
+/**
+ * Partial of config, used for shortening instead of Partial<...>
+ */
+export type ConsoleAppenderOptions<Record extends LogRecord> = Partial<
+  ConsoleAppenderConfig<Record>
+>
+
+export const consoleFormatter: Formatter<Array<any>> = ({
+  level,
+  message,
+  data,
+  args,
+  category,
+  timestamp
+}) => [
+  `[${category}]  (${level})  ${message}`,
+  ...(Array.isArray(args) ? args : [args])
+]
+
+/**
+ * Default console config
+ * @type {ConsoleAppenderConfig}
+ */
+export const kDefaultConsoleAppenderConfig: ConsoleAppenderConfig = {
+  cacheEnabled: true,
+  prettyPrint: true,
+  formatter: consoleFormatter
+}
+
+/**
+ * Console appender, the simple default appender used
+ * everywhere OOB
+ */
+export class ConsoleAppender<Record extends LogRecord>
+  implements Appender<Record>
+{
+  readonly config: ConsoleAppenderConfig
+
+  /**
+   * Handle log records, transform, push to ES
+   *
+   * @param record
+   */
+  append(record: Record): void {
+    const { level, message, data, args, category, timestamp } = record
+    const { formatter = consoleFormatter } = this.config
+    Option.ofNullable(formatter(record)).map((result) => {
+      const args = Array.isArray(result) ? result : [result]
+      this.write(level, ...args)
+    })
+  }
+
+  /**
+   * Write args to console
+   * 
+   * @param level 
+   * @param args 
+   */
+  protected write(level: LevelKind, ...args: any[]) {
+    Option.ofNullable(console[level])
+        .orCall(() => Option.ofNullable(console.log))
+        .map((fn: Function) => fn.apply(console, args))
+  }
+
+  /**
+   *
+   * @param {Partial<ConsoleAppenderOptions<Record>>} options
+   */
+  constructor(options: Partial<ConsoleAppenderOptions<Record>> = {}) {
+    this.config = {
+      ...kDefaultConsoleAppenderConfig,
+      ...options
+    }
+  }
+}

package/src/logging/appenders/DebugAppender.ts

@@ -0,0 +1,254 @@
+import type { LogRecord } from "../LogRecord"
+import type { Appender } from "../Appender"
+import type { LevelKind } from "../Level"
+import Debug from "debug"
+import {
+  ConsoleAppender, ConsoleAppenderConfig, kDefaultConsoleAppenderConfig
+} from "./ConsoleAppender.js"
+import type { Formatter } from "../Formatter"
+import { isEmpty, negate } from "lodash"
+
+
+// let chalk: any = null
+// if (
+//   typeof process !== "undefined" &&
+//   (process as any).type !== "renderer" &&
+//   (process as any).browser !== true
+// ) {
+//   chalk = require("chalk")
+// }
+
+const useColors = false
+
+const makeColorFn = (fn: (chalk: any, s: string) => string) => {
+  // if (!useColors) {
+  //   return (s: string) => s
+  // }
+  //
+  // return (s: string) => fn(chalk, s)
+  return (s: string) => s
+}
+
+const colorFns: Record<LevelKind, (s: string) => string> = {
+  debug: makeColorFn((c, s) => c.green(s)),
+  error: makeColorFn((c, s) => c.red(s)),
+  fatal: makeColorFn((c, s) => c.bgRed.black(s)),
+  info: makeColorFn((c, s) => c.blue(s)),
+  trace: makeColorFn((c, s) => c.gray(s)),
+  warn: makeColorFn((c, s) => c.yellow(s))
+}
+
+/**
+ * DebugAppender Configuration
+ */
+export interface DebugAppenderConfig extends ConsoleAppenderConfig {
+  hideDate: boolean
+  timeOnly: boolean
+  useConsole: boolean
+  useStdout: boolean
+  categoryPrefix: string
+}
+
+/**
+ * Partial of config, used for shortening instead of Partial<...>
+ */
+export type DebugAppenderOptions = Partial<DebugAppenderConfig>
+
+const debuggers = new Map<string, Debug.Debugger>()
+
+//const debugAppPrefix = "app"
+
+function getDebug({categoryPrefix}: DebugAppenderConfig, cat: string) {
+  let debug = debuggers.get(cat)
+  if (!debug) {
+    debug = Debug([categoryPrefix, cat].filter(negate(isEmpty)).join(":"))
+    debuggers.set(cat, debug)
+  }
+
+  return debug
+}
+
+// const timeFormatter = new Intl.DateTimeFormat('en-US', {
+//   timeStyle: "short"
+// })
+
+/**
+ *
+ * Get ISO date if `hideDate !== true`
+ *
+ * @param {DebugFormatterContext}
+ * @returns
+ */
+function getDate({ debugConfig: config }: DebugFormatterContext) {
+  if (config.hideDate) {
+    return ""
+  }
+
+  const date = new Date()
+  return config.timeOnly
+    ? date.toLocaleTimeString("default", {
+        hour12: false
+      })
+    : date.toISOString()
+}
+
+/**
+ *
+ * Formats args for output, directly based on Debug.formatArgs
+ *
+ * @param {DebugFormatterContext} context
+ * @param {any[]} args
+ */
+function formatArgs(
+  context: DebugFormatterContext,
+  record: LogRecord,
+  args: any[]
+) {
+  const { debug } = context
+  const { namespace: name } = debug as any
+
+  const prefix = colorFns[record.level](
+    [
+      getDate(context),
+      Debug.humanize(debug.diff),
+      `(` + record.level.toUpperCase() + `)`,
+      `[${name}]`
+    ]
+      .filter(negate(isEmpty))
+      .join(" ")
+  )
+  const msg = [prefix, args[0]].filter(negate(isEmpty)).join(" ")
+
+  args[0] = msg
+}
+
+/**
+ * Context for using `debugFormatter`
+ */
+export type DebugFormatterContext = {
+  debugConfig: DebugAppenderConfig
+  debug: Debug.Debugger
+}
+
+/**
+ * Uses `debug` package for logging, very useful
+ *
+ * @param {LogRecord} record to format
+ * @param {DebugFormatterContext} context for this formatter
+ * @returns
+ */
+export const debugFormatter: Formatter<Array<any>, DebugFormatterContext> = (
+  record,
+  { debug, debugConfig: config }
+): any[] => {
+  const { level, message, data, args: argsIn, category, timestamp } = record
+  const args = [message, ...argsIn]
+  args[0] = Debug.coerce(args[0])
+
+  if (typeof args[0] !== "string") {
+    // Anything else let's inspect with %O
+    args.unshift("%O")
+  }
+
+  // Apply any `formatters` transformations
+  let index = 0
+  args[0] = args[0].replace(/%([a-zA-Z%])/g, (match, format) => {
+    // If we encounter an escaped % then don't increase the array index
+    if (match === "%%") {
+      return "%"
+    }
+    index++
+    const formatter = Debug.formatters[format]
+    if (typeof formatter === "function") {
+      const val = args[index]
+      match = formatter.call(debug, val)
+
+      // Now we need to remove `args[index]` since it's inlined in the `format`
+      args.splice(index, 1)
+      index--
+    }
+    return match
+  })
+
+  // Apply env-specific formatting (colors, etc.)
+  formatArgs({ debug, debugConfig: config }, record, args)
+
+  return args
+}
+// [
+//   `[${category}]  (${level})  ${message}`,
+//   ...(Array.isArray(args) ? args : [args])
+// ]
+
+/**
+ * Default console config
+ * @type {DebugAppenderConfig}
+ */
+const defaultConfig: DebugAppenderConfig = {
+  hideDate: false,
+  timeOnly: true,
+  useConsole: false,
+  useStdout: true,
+  categoryPrefix: null,
+  ...kDefaultConsoleAppenderConfig,
+  formatter: debugFormatter
+}
+/**
+ * Debug appender, the simple default appender used
+ * everywhere OOB
+ */
+export class DebugAppender<Record extends LogRecord>
+  extends ConsoleAppender<Record>
+  implements Appender<Record>
+{
+  readonly debugConfig: DebugAppenderConfig
+
+
+  /**
+   * Handle log records, transform, push to ES
+   *
+   * @param record
+   */
+  append(record: Record): void {
+    const { level, message, args: argsIn, category } = record
+
+    // if (!this.levels.includes(level)) {
+    //   super.append(record)
+    //   return
+    // }
+
+    const debug = getDebug(this.debugConfig, category) as any
+    let prevTime = debug.prevTime
+    // Set `diff` timestamp
+    const curr = Number(new Date())
+    const ms = curr - (prevTime || curr)
+    debug.diff = ms
+    debug.prev = prevTime
+    debug.curr = curr
+    debug.prevTime = curr
+    const logFn = debug.log || Debug.log
+    const args = debugFormatter!(record, { debug, debugConfig: this.debugConfig })
+    
+    if (this.debugConfig.useConsole) {
+      super.write(level, ...args)
+    }
+
+    if (this.debugConfig.useStdout) {
+      logFn.apply(debug, args) 
+    }
+  }
+
+  /**
+   *
+   * @param {Partial<DebugAppenderOptions>} options
+   */
+  constructor(options: Partial<Omit<DebugAppenderOptions, "formatter">> = {}) {
+    super({
+      ...defaultConfig,
+      ...options,
+      formatter: debugFormatter
+    })
+
+    this.debugConfig = this.config as DebugAppenderConfig
+  }
+}