standard-log 7.1.0 → 9.0.0

package/ts/logger.ts

@@ -0,0 +1,85 @@
+import type { StackTraceMeta } from '@just-func/types'
+import { RequiredPick } from 'type-plus'
+import { InvalidId } from './errors.js'
+import { logLevels } from './logLevels.js'
+import { LogStore } from './logStore.js'
+import type { LogEntry, LogFunction, Logger, LoggerOptions, LogMethodNames, LogReporter } from './types.js'
+import { LogLevel } from './types.js'
+
+export function createLogger<T extends string = LogMethodNames>(
+  [store, id, { level, writeTo = () => true }]: [LogStore, string, RequiredPick<LoggerOptions, 'level'>],
+  meta?: StackTraceMeta
+): Logger {
+  validateId(id, meta)
+  const [filter, reporters]: [(reporterId: string) => boolean, LogReporter[]] = typeof writeTo === 'string'
+    ? [id => id === writeTo, store.reporters]
+    : writeTo instanceof RegExp
+      ? [id => writeTo.test(id), store.reporters]
+      : typeof writeTo === 'function'
+        ? [writeTo, store.reporters]
+        : [() => true, [writeTo]]
+
+  function write(entry: LogEntry) {
+    writeToReporters(reporters, entry, filter)
+  }
+
+  const logger = {
+    level,
+    write
+  } as any
+
+  Object.defineProperties(logger, {
+    id: { value: id, writable: false },
+    count: {
+      writable: false,
+      value: ((counter) => (...args: any[]) => {
+        const level = logLevels.debug
+        if (shouldLog(store, level, logger.level))
+          write({
+            id,
+            level,
+            args: [++counter, ...args],
+            timestamp: new Date()
+          })
+      })(0)
+    },
+    on: {
+      writable: false,
+      value: (level: number | T, logFn: LogFunction) => {
+        const logLevel = typeof level === 'string' ? store.logLevelStore.getLevel(level)! : level
+        if (shouldLog(store, logLevel, logger.level)) {
+          const methodName = store.logLevelStore.getName(logLevel)
+          const bindedMethod = logger[methodName].bind(logger)
+          const result = logFn(bindedMethod)
+          if (result) bindedMethod(result)
+        }
+      }
+    }
+  })
+  store.logLevelStore.getAllLevels().forEach(function addMethod({ name, level }) {
+    Object.defineProperty(logger, name, {
+      writable: false,
+      value: (...args: any[]) => {
+        if (shouldLog(store, level, logger.level)) write({ id, level, args, timestamp: new Date() })
+      }
+    })
+  })
+  return logger
+}
+
+function validateId(id: string, meta?: StackTraceMeta) {
+  if (/[`~!#$%^&*()=+[\]{},|<>?]/.test(id)) throw new InvalidId(id, meta)
+}
+
+function writeToReporters(reporters: LogReporter[], logEntry: LogEntry, filter: (reporterId: string) => boolean) {
+  reporters.filter(r => filter(r.id)).forEach(r => r.write(logEntry!))
+}
+
+/**
+ * Determines should you log.
+ * @param loggerLevel Log level of the logger.
+ * It can be undefined which the global log level will be used.
+ */
+function shouldLog(store: LogStore, targetLevel: LogLevel, loggerLevel: LogLevel | undefined) {
+  return targetLevel <= (loggerLevel !== undefined ? loggerLevel : store.logLevel)
+}

package/ts/memory.ts

@@ -0,0 +1,47 @@
+import { required } from 'type-plus'
+import { toInspectLogEntry } from './platform.js'
+import { formatLogLevel } from './formatter.js'
+import type { LogEntry, LogFormatter, LogReporter, LogReporterOptions } from './types.js'
+
+export type MemoryLogReporter = LogReporter<LogEntry> & {
+  logs: LogEntry[],
+  /**
+   * Gets a simple log message for testing.
+   * The message only contains arguments for each log entry.
+   */
+  getLogMessage(): string,
+  getLogMessageWithLevel(): string
+}
+
+export type MemoryLogFormatter = LogFormatter<LogEntry>
+
+export function toMessageWithLevel(logs: LogEntry[]) {
+  return logs.map(toInspectLogEntry)
+    .map(log => `${formatLogLevel(log.level)} ${log.args.join(' ')}`)
+    .join('\n')
+    // if it has more than this log,
+    // we assume it is running under tests,
+    // and remove this log to simplify testing.
+    .replace(/^\(WARN\) already configured for test, ignoring config\(\) call\n/, '')
+}
+
+export function createMemoryLogReporter(options?: LogReporterOptions<LogEntry>): MemoryLogReporter {
+  const { id, formatter, filter } = required({ id: 'memory', formatter: (e: LogEntry) => e }, options)
+  const logs: LogEntry[] = []
+  return Object.freeze({
+    id,
+    get formatter() { return formatter },
+    get filter() { return filter },
+    logs,
+    write(entry: LogEntry) {
+      if (filter && !filter(entry)) return
+      logs.push(formatter(entry))
+    },
+    getLogMessage() {
+      return logs.map(toInspectLogEntry)
+        .map(log => log.args.join(' '))
+        .join('\n')
+    },
+    getLogMessageWithLevel() { return toMessageWithLevel(logs) }
+  })
+}

package/ts/platform.browser.ts

@@ -0,0 +1,8 @@
+import type { ConsoleLike, LogEntry } from './types.js'
+
+export const toInspectLogEntry = (e: LogEntry) => e
+export function isConsoleDebugAvailable() {
+  return true
+}
+
+export const polyfill: { console?: ConsoleLike } = {}

package/ts/platform.ts

@@ -0,0 +1,25 @@
+import { inspect } from 'util'
+import type { ConsoleLike, LogEntry } from './types.js'
+
+export function semverGt(versionString: string, version: [number, number, number]) {
+  const actual = versionString.split('.').reverse().reduce((p, v, i) => {
+    p += Number.parseInt(v, 10) * Math.pow(100, i)
+    return p
+  }, 0)
+
+  return actual > (version[0] * 10000 + version[1] * 100 + version[2])
+}
+
+// istanbul ignore next
+export function isConsoleDebugAvailable() {
+  // without this, systemJs will complain `process is not defined`
+  if (!global.process) return true
+  const versionString = process.version.startsWith('v') ? process.version.slice(1) : process.version
+  return semverGt(versionString, [9, 3, 0])
+}
+
+export const toInspectLogEntry = (e: LogEntry) => (
+  e.args = e.args.map(value => typeof value === 'object' && value !== null ? inspect(value) : value),
+  e)
+
+export const polyfill: { console?: ConsoleLike } = {}

package/ts/standardLog.ts

@@ -0,0 +1,54 @@
+import { StackTraceMeta } from '@just-func/types'
+import { required } from 'type-plus'
+import { createLogger } from './logger.js'
+import { logLevels } from './logLevels.js'
+import { createLogStore } from './logStore.js'
+import { createMemoryLogReporter } from './memory.js'
+import type { Logger, LoggerOptions, LogLevel, LogMethodNames, StandardLogOptions } from './types.js'
+
+export interface StandardLog<N extends string = LogMethodNames> {
+  readonly logLevel: number,
+  toLogLevelName(level: number): string,
+  toLogLevel(name: N): number,
+  getLogger(params: [id: string, options?: LoggerOptions], meta?: StackTraceMeta): Logger<N>
+}
+
+export function createStandardLog<N extends string = LogMethodNames>(
+  options?: Partial<StandardLogOptions<N>>, _meta?: StackTraceMeta
+): Readonly<StandardLog<N>> {
+  const store = createLogStore(required({ logLevel: logLevels.info }, options))
+
+  return Object.freeze({
+    get logLevel() { return store.logLevel },
+
+    toLogLevelName(level: number) {
+      return store.logLevelStore.getName(level)
+    },
+    toLogLevel(name: string) {
+      return store.logLevelStore.getLevel(name)
+    },
+    getLogger([id, options]: [id: string, options?: LoggerOptions], meta?: StackTraceMeta): Logger<N> {
+      if (store.loggers[id]) return store.loggers[id] as any
+      const opt = required({ level: store.logLevel }, options)
+      return store.loggers[id] = createLogger([store, id, opt], { ssf: this.getLogger, ...meta }) as any
+    }
+  })
+}
+
+export function createStandardLogForTest(logLevel: LogLevel = logLevels.debug) {
+  const reporter = createMemoryLogReporter()
+  const standardLog = createStandardLog({ reporters: [reporter], logLevel })
+  return { ...standardLog, reporter }
+}
+
+/**
+ * Suppress logging within the code block.
+ */
+export function suppressLogs<R>(block: () => R, log: Logger, ...logs: Logger[]): R
+export function suppressLogs<R>(block: () => R, ...logs: Logger[]): R {
+  const origLevels = logs.map(l => l.level)
+  logs.forEach(l => l.level = logLevels.none)
+  const result = block()
+  logs.forEach((l, i) => l.level = origLevels[i])
+  return result
+}

package/{src → ts}/types.ts

@@ -1,16 +1,12 @@
+export type StandardLogOptions<CustomLevelNames extends string = string> = {
+  customLevels: Record<CustomLevelNames, number>,
+  logLevel: number,
+  reporters: LogReporter[]
+}
 
-export type LogMode = 'development' | 'production' | 'test'
-
-export type LogMethodNames = 'emergency' | 'alert' | 'critical' | 'error' | 'warn' | 'notice' | 'info' | 'debug' | 'trace' | 'planck'
-export type LogMethod = (...args: any[]) => void
-export type LogFunction = ((log: LogMethod) => void) | (() => string)
-
-export type LogEntry = {
-  id: string,
-  level: number,
-  // args instead of messages because it is `any[]` instead of `string[]`
-  args: any[],
-  timestamp: Date
+export interface LoggerOptions {
+  level?: number,
+  writeTo?: LogReporter | ReporterFilter
 }
 
 export type Logger<T extends string = LogMethodNames> = {
@@ -27,19 +23,33 @@ export type Logger<T extends string = LogMethodNames> = {
   on(level: number | T, logFunction: LogFunction): void,
   /**
    * Write custom log entries.
-   * This can be used along with `captureLogs()` to rewrite the logs at a later time.
    */
   write(entry: LogEntry): void
-} & {
-    [k in T]: LogMethod
-  }
+} & { [k in T]: LogMethod }
+
+/**
+ * Names of the standard log methods.
+ */
+export type LogMethodNames = 'emergency' | 'alert' | 'critical' | 'error' | 'warn' | 'notice' | 'info' | 'debug' | 'trace' | 'planck'
+
+export type LogEntry = {
+  id: string,
+  level: number,
+  // args instead of messages because it is `any[]` instead of `string[]`
+  args: any[],
+  timestamp: Date
+}
+
+export type LogMethod = (...args: any[]) => void
+
+export type LogFunction = ((log: LogMethod) => void) | (() => string)
 
 export type ReporterFilter = string | RegExp | ((reporterId: string) => boolean)
 
 /**
  * Formats a log entry.
  * Depends on the reporter, it can expect a different return type.
- * By default the return type is `any[]` which `console` accepts.
+ * By default the return type is `any[]` which the `console` accepts.
  */
 export type LogFormatter<T = any[]> = (entry: LogEntry) => T
 
@@ -50,30 +60,22 @@ export type LogFilter = (entry: LogEntry) => boolean
 
 export type LogLevelEntry = { name: string, level: number }
 
-export type LogLevelListener = (logLevelEntry: LogLevelEntry) => void
-
-export type LogReporter<T = any> = {
-  id: string,
+export interface LogReporter<T = any> {
+  readonly id: string,
   /**
    * Specifies the formatter to be used by the reporter.
    * Using this you can customize how the reporter writes the log entry.
-   * This is readonly in production mode.
    */
-  formatter: LogFormatter<T>,
+  readonly formatter: LogFormatter<T>,
   /**
    * Specifies a filter to determine should the log be written.
-   * This is readonly in production mode.
    */
-  filter?: LogFilter,
+  readonly filter?: LogFilter,
   /**
    * Indicate if this is a console reporter.
    * There is only one console reporter can be present in the system.
-   * If a new console reporter is added,
-   * it will be used in place of the existing one.
-   * However, existing filter will be carried over to ensure logs should not be shown remain not shown.
-   * If the new reporter also contains a filter, they will be combined.
    */
-  isConsoleReporter?: boolean,
+  readonly isConsoleReporter?: boolean,
   write(entry: LogEntry): void
 }
 
@@ -91,3 +93,10 @@ export type LogReporterOptions<T = any> = {
 }
 
 export type LogLevel = number
+
+export interface ConsoleLike {
+  debug(...args: any[]): void,
+  info(...args: any[]): void,
+  warn(...args: any[]): void,
+  error(...args: any[]): void,
+}