@xylabs/express 4.3.14

package/src/Logger/Transports/Rollbar/getDefaultRollbarTransport.ts

@@ -0,0 +1,10 @@
+import { assertEx } from '@xylabs/assert'
+import Rollbar from 'rollbar'
+
+import { RollbarTransport } from './RollbarTransport.ts'
+
+export const getDefaultRollbarTransport = (env: { [key: string]: string | undefined }): RollbarTransport => {
+  const accessToken = assertEx(env.ROLLBAR_ACCESS_TOKEN, 'Missing ROLLBAR_ACCESS_TOKEN ENV VAR')
+  const rollbar: Rollbar = new Rollbar({ accessToken })
+  return new RollbarTransport({}, rollbar)
+}

package/src/Logger/Transports/Rollbar/index.ts

@@ -0,0 +1,3 @@
+export * from './canGetDefaultRollbarTransport.ts'
+export * from './getDefaultRollbarTransport.ts'
+export * from './RollbarTransport.ts'

package/src/Logger/Transports/Rollbar/spec/RollbarTransport.spec.ts

@@ -0,0 +1,30 @@
+import '@xylabs/vitest-extended'
+
+import Rollbar from 'rollbar'
+import {
+  beforeEach,
+  describe, expect, it,
+  vi,
+} from 'vitest'
+import type { MockProxy } from 'vitest-mock-extended'
+import { mock } from 'vitest-mock-extended'
+
+import { RollbarTransport } from '../RollbarTransport.ts'
+
+const accessToken = process.env.ROLLBAR_ACCESS_TOKEN
+const unitTestSentinelLoggingString = 'error log from unit test'
+
+describe('RollbarTransport', () => {
+  let rollbar: MockProxy<Rollbar> | Rollbar
+  let sut: RollbarTransport
+  beforeEach(() => {
+    rollbar = accessToken ? new Rollbar({ accessToken, environment: 'development' }) : mock<Rollbar>()
+    sut = new RollbarTransport({}, rollbar)
+  })
+  it('logs', () => {
+    expect(sut).toBeObject()
+    const nextMock = vi.fn()
+    sut.log({ message: unitTestSentinelLoggingString }, nextMock)
+    expect(nextMock).toHaveBeenCalledOnce()
+  })
+})

package/src/Logger/Transports/Rollbar/spec/canGetDefaultRollbarTransport.spec.ts

@@ -0,0 +1,18 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import { canGetDefaultRollbarTransport } from '../canGetDefaultRollbarTransport.ts'
+
+describe('canGetDefaultRollbarTransport', () => {
+  it('returns true if the transport could be created', () => {
+    const env = { ROLLBAR_ACCESS_TOKEN: 'something' }
+    expect(canGetDefaultRollbarTransport(env)).toBeTrue()
+  })
+  it('returns false if the transport could not be crated', () => {
+    const env = { ROLLBAR_ACCESS_TOKEN: undefined }
+    expect(canGetDefaultRollbarTransport(env)).toBeFalse()
+  })
+})

package/src/Logger/Transports/Rollbar/spec/getDefaultRollbarTransport.spec.ts

@@ -0,0 +1,16 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import { getDefaultRollbarTransport } from '../getDefaultRollbarTransport.ts'
+
+describe('getDefaultRollbarTransport', () => {
+  it('returns the transport', () => {
+    const env = { ROLLBAR_ACCESS_TOKEN: 'something' }
+    const transport = getDefaultRollbarTransport(env)
+    expect(transport).toBeObject()
+    expect(transport.log).toBeFunction()
+  })
+})

package/src/Logger/Transports/index.ts

@@ -0,0 +1 @@
+export * from './Rollbar/index.ts'

package/src/Logger/WinstonVerbosity.ts

@@ -0,0 +1,5 @@
+/**
+ * Follows NPM log levels
+ * https://docs.npmjs.com/cli/v8/using-npm/logging#loglevel
+ */
+export type WinstonVerbosity = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly'

package/src/Logger/WrappedWinstonLogger.ts

@@ -0,0 +1,16 @@
+import type { Logger as Winston } from 'winston'
+
+import type { LogFunction, Logger } from './Logger'
+
+/**
+ * Wrap Winston logger methods to adapt to familiar
+ * console logging methods
+ */
+export class WrappedWinstonLogger implements Logger {
+  constructor(protected readonly winston: Winston) {}
+  debug: LogFunction = message => this.winston.debug(message)
+  error: LogFunction = message => this.winston.error(message)
+  info: LogFunction = message => this.winston.info(message)
+  log: LogFunction = message => this.winston.info(message)
+  warn: LogFunction = message => this.winston.warn(message)
+}

package/src/Logger/getDefaultLogger.ts

@@ -0,0 +1,13 @@
+import { getLogger } from './getLogger.ts'
+import type { Logger } from './Logger.ts'
+import type { WrappedWinstonLogger } from './WrappedWinstonLogger.ts'
+
+/**
+ * Static instance to prevent multiple instances of the same logger
+ * with the same config
+ */
+let defaultLogger: WrappedWinstonLogger
+export const getDefaultLogger = (): Logger => {
+  if (defaultLogger) return defaultLogger
+  return getLogger()
+}

package/src/Logger/getLogger.ts

@@ -0,0 +1,55 @@
+import { createLogger, transports as winstonTransports } from 'winston'
+import type TransportStream from 'winston-transport'
+
+import { logFormatLocalDev, logFormatStructured } from './LogFormats/index.ts'
+import type { Logger } from './Logger.ts'
+import type { LoggerVerbosity } from './LoggerVerbosity.ts'
+import { toWinstonVerbosity } from './toWinstonVerbosity.ts'
+import { canGetDefaultRollbarTransport, getDefaultRollbarTransport } from './Transports/index.ts'
+import type { WinstonVerbosity } from './WinstonVerbosity.ts'
+import { WrappedWinstonLogger } from './WrappedWinstonLogger.ts'
+
+const exitOnError = false
+const handleRejections = true
+
+const { Console } = winstonTransports
+const consoleTransport = new Console()
+const format = process.env.NODE_ENV === 'development' ? logFormatLocalDev : logFormatStructured
+const transports: TransportStream[] = [consoleTransport]
+if (canGetDefaultRollbarTransport(process.env)) {
+  try {
+    const rollbarTransport = getDefaultRollbarTransport(process.env)
+    transports.push(rollbarTransport)
+  } catch {
+    // NOTE: No error here, just gracefully adding logger if ENV VARs
+    // were preset
+  }
+}
+
+const loggers: Record<WinstonVerbosity, Logger | undefined> = {
+  debug: undefined,
+  error: undefined,
+  http: undefined,
+  info: undefined,
+  silly: undefined,
+  verbose: undefined,
+  warn: undefined,
+}
+
+export const getLogger = (minVerbosity: LoggerVerbosity = 'info'): Logger => {
+  const level = toWinstonVerbosity(minVerbosity)
+  const existing = loggers[level]
+  if (existing) return existing
+  const logger = new WrappedWinstonLogger(
+    createLogger({
+      exitOnError,
+      format,
+      handleRejections,
+      level,
+      rejectionHandlers: transports,
+      transports,
+    }),
+  )
+  loggers[level] = logger
+  return logger
+}

package/src/Logger/index.ts

@@ -0,0 +1,6 @@
+export * from './getDefaultLogger.ts'
+export * from './getLogger.ts'
+export * from './Logger.ts'
+export * from './LoggerMeta.ts'
+export * from './LoggerOptions.ts'
+export * from './LoggerVerbosity.ts'

package/src/Logger/spec/getDefaultLogger.spec.ts

@@ -0,0 +1,14 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import { getDefaultLogger } from '../getDefaultLogger.ts'
+
+describe('getDefaultLogger', () => {
+  it('provides a default logger', () => {
+    const logger = getDefaultLogger()
+    expect(logger).toBeObject()
+  })
+})

package/src/Logger/spec/getLogger.spec.ts

@@ -0,0 +1,25 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { mockDeep } from 'vitest-mock-extended'
+globalThis.console = mockDeep<Console>()
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, it,
+} from 'vitest'
+import type { Logger } from 'winston'
+
+import { getLogger } from '../getLogger.ts'
+
+type LoggerKey = keyof Logger
+const loggerKeys: LoggerKey[] = ['error', 'warn', 'log', 'info', 'debug']
+
+describe('getLogger', () => {
+  describe('verbosity', () => {
+    it.each(loggerKeys)('logs log with %s verbosity', (verbosity: LoggerKey) => {
+      const logger = getLogger('all')
+      const logMethod = (logger as any)[verbosity]
+      expect(logMethod).toBeFunction()
+      logMethod(`${new String(verbosity)} log from unit test`)
+    })
+  })
+})

package/src/Logger/spec/toWinstonVerbosity.spec.ts

@@ -0,0 +1,17 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import type { LoggerVerbosity } from '../LoggerVerbosity.ts'
+import { toWinstonVerbosity } from '../toWinstonVerbosity.ts'
+
+const loggerKeys: LoggerVerbosity[] = ['error', 'warn', 'info', 'debug', 'all']
+
+describe('toWinstonVerbosity', () => {
+  it.each(loggerKeys)('provides a default logger', (verbosity) => {
+    const actual = toWinstonVerbosity(verbosity)
+    expect(actual).toBeString()
+  })
+})

package/src/Logger/toWinstonVerbosity.ts

@@ -0,0 +1,6 @@
+import type { LoggerVerbosity } from './LoggerVerbosity.ts'
+import type { WinstonVerbosity } from './WinstonVerbosity.ts'
+
+export const toWinstonVerbosity = (loggerVerbosity: LoggerVerbosity): WinstonVerbosity => {
+  return loggerVerbosity === 'all' ? 'silly' : loggerVerbosity
+}

package/src/Model/ExpressError.ts

@@ -0,0 +1,3 @@
+export interface ExpressError extends Error {
+  statusCode?: number
+}

package/src/Model/index.ts

@@ -0,0 +1 @@
+export * from './ExpressError.ts'

package/src/Performance/Counters.ts

@@ -0,0 +1,36 @@
+export class Counters {
+  static counters: Record<string, number> = {}
+
+  static inc(name: string, count = 1) {
+    this.catchError(name, (name: string) => {
+      this.counters[name] = (this.counters[name] ?? 0) + count
+    })
+  }
+
+  static max(name: string, count: number) {
+    this.catchError(name, (name: string) => {
+      const currentValue = this.counters[name]
+      if (currentValue === undefined || count > currentValue) {
+        this.counters[name] = count
+      }
+    })
+  }
+
+  static min(name: string, count: number) {
+    this.catchError(name, (name: string) => {
+      const currentValue = this.counters[name]
+      if (currentValue === undefined || count < currentValue) {
+        this.counters[name] = count
+      }
+    })
+  }
+
+  private static catchError = (name: string, func: (name: string) => void) => {
+    try {
+      func(name)
+    } catch {
+      this.counters[name] = 0
+      this.inc('CountersErrors')
+    }
+  }
+}

package/src/Performance/Profiler.ts

@@ -0,0 +1,10 @@
+export class Profiler {
+  stats: Record<string, number> = {}
+
+  async profile<T>(name: string, promise: Promise<T>) {
+    const start = Date.now()
+    const result = await promise
+    this.stats[name] = Date.now() - start
+    return result
+  }
+}

package/src/Performance/index.ts

@@ -0,0 +1,2 @@
+export * from './Counters.ts'
+export * from './Profiler.ts'

package/src/Util/compactObject.ts

@@ -0,0 +1,9 @@
+export const compactObject = <T extends Record<string, unknown>>(obj: T) => {
+  const result: Record<string, unknown> = {}
+  for (const key in obj) {
+    if (obj[key] !== undefined && obj[key] !== null) {
+      result[key] = obj[key]
+    }
+  }
+  return result as T
+}

package/src/Util/index.ts

@@ -0,0 +1,2 @@
+export * from './compactObject.ts'
+export * from './tryParse.ts'

package/src/Util/tryParse.ts

@@ -0,0 +1,21 @@
+export type ParseFunc<T = number> = (value: string) => T
+
+export const tryParse = <T = number>(func: ParseFunc<T>, value?: string) => {
+  try {
+    const result = value ? func(value) : null
+    if (!Number.isNaN(result) && result !== null) {
+      return result
+    }
+  } catch {
+    return
+  }
+  return
+}
+
+export const tryParseFloat = (value?: string) => {
+  return tryParse(Number.parseFloat, value)
+}
+
+export const tryParseInt = (value?: string) => {
+  return tryParse(Number.parseInt, value)
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './AWS/index.ts'
+export * from './Handler/index.ts'
+export * from './HttpUtil/index.ts'
+export * from './Logger/index.ts'
+export * from './middleware/index.ts'
+export * from './Model/index.ts'
+export * from './Performance/index.ts'
+export * from './Util/index.ts'

package/src/middleware/caseInsensitiveRouting/caseInsensitiveRouting.ts

@@ -0,0 +1,21 @@
+import type { Express } from 'express'
+
+const setting = 'case sensitive routing'
+
+/**
+ * Enable case sensitivity. When enabled, "/Foo" and "/foo" are different
+ * routes. When disabled, "/Foo" and "/foo" are treated the same.
+ * @param app The Express app to disable the header on.
+ */
+export const enableCaseSensitiveRouting = (app: Express) => {
+  app.enable(setting)
+}
+
+/**
+ * Disable case sensitivity. When enabled, "/Foo" and "/foo" are different
+ * routes. When disabled, "/Foo" and "/foo" are treated the same.
+ * @param app The Express app to disable the header on.
+ */
+export const disableCaseSensitiveRouting = (app: Express) => {
+  app.disable(setting)
+}

package/src/middleware/caseInsensitiveRouting/index.ts

@@ -0,0 +1 @@
+export * from './caseInsensitiveRouting.ts'

package/src/middleware/customPoweredByHeader/customPoweredByHeader.ts

@@ -0,0 +1,29 @@
+import type {
+  Express, NextFunction, Request, Response,
+} from 'express'
+
+const header = 'X-Powered-By'
+const setting = 'x-powered-by'
+
+/**
+ * By default Express appends the `X-Powered-By: Express` header to
+ * all responses. Calling this method enables that behavior.
+ * @param app The Express app to disable the header on.
+ */
+export const enableExpressDefaultPoweredByHeader = (app: Express) => {
+  app.enable(setting)
+}
+
+/**
+ * By default Express appends the `X-Powered-By: Express` header to
+ * all responses. Calling this method disables that behavior.
+ * @param app The Express app to disable the header on.
+ */
+export const disableExpressDefaultPoweredByHeader = (app: Express) => {
+  app.disable(setting)
+}
+
+export const customPoweredByHeader = (req: Request, res: Response, next: NextFunction) => {
+  res.setHeader(header, 'XYO')
+  next()
+}

package/src/middleware/customPoweredByHeader/index.ts

@@ -0,0 +1 @@
+export * from './customPoweredByHeader.ts'

package/src/middleware/index.ts

@@ -0,0 +1,5 @@
+export * from './caseInsensitiveRouting/index.ts'
+export * from './customPoweredByHeader/index.ts'
+export * from './jsonBodyParser/index.ts'
+export * from './metrics/index.ts'
+export * from './standardResponses/index.ts'

package/src/middleware/jsonBodyParser/index.ts

@@ -0,0 +1 @@
+export * from './jsonBodyParser.ts'

package/src/middleware/jsonBodyParser/jsonBodyParser.ts

@@ -0,0 +1,57 @@
+import type { OptionsJson } from 'body-parser'
+import bodyParser from 'body-parser'
+import type { NextHandleFunction } from 'connect'
+
+/**
+ * The default maximum request body size for the JSON Body Parser
+ */
+export const DefaultJsonBodyParserOptionsLimit = '100kb'
+
+/**
+ * The default MIME types for the JSON Body Parser
+ */
+export const DefaultJsonBodyParserOptionsTypes = ['application/json', 'text/json']
+
+/**
+ * The default options for the JSON Body Parser
+ */
+export const DefaultJsonBodyParserOptions: OptionsJson = {
+  limit: DefaultJsonBodyParserOptionsLimit,
+  type: DefaultJsonBodyParserOptionsTypes,
+}
+
+/**
+ * Gets the default JSON Body Parser options merged with the supplied options
+ * with the supplied options taking precedence
+ * @param options The options to override the default JSON Body Parser options with
+ * @returns The combined JSON Body Parser options with the supplied values taking
+ * precedence over the default
+ */
+export const getJsonBodyParserOptions = (options?: Partial<OptionsJson>): OptionsJson => {
+  return options ? { ...DefaultJsonBodyParserOptions, ...options } : DefaultJsonBodyParserOptions
+}
+
+/**
+ * Get a JSON Body Parser connect middleware handler
+ * @param options The options for the JSON Body Parser
+ * @returns A middleware function that parses JSON bodies
+ */
+export const getJsonBodyParser = (options: OptionsJson = DefaultJsonBodyParserOptions): NextHandleFunction => {
+  // Create closed instance of bodyParser to prevent instantiation of new instance on every request
+  const parser = bodyParser.json(options)
+
+  return (req, res, next) => {
+    // If we do not trap this error, then it dumps too much to log, usually happens if request aborted
+    try {
+      parser(req, res, next)
+    } catch (ex) {
+      const error = ex as Error
+      console.log(`bodyParser failed [${error?.name}]: ${error?.message}`)
+    }
+  }
+}
+
+/**
+ * A JSON Body Parser middleware handler initialized with the default options
+ */
+export const jsonBodyParser = getJsonBodyParser()

package/src/middleware/jsonBodyParser/spec/jsonBodyParser.spec.ts

@@ -0,0 +1,26 @@
+import '@xylabs/vitest-extended'
+
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import { DefaultJsonBodyParserOptions, getJsonBodyParserOptions } from '../jsonBodyParser.ts'
+
+describe('jsonBodyParser', () => {
+  describe('getJsonBodyParserOptions', () => {
+    it('returns default options if none supplied', () => {
+      // Act
+      const result = getJsonBodyParserOptions()
+      // Assert
+      expect(result).toEqual(DefaultJsonBodyParserOptions)
+    })
+    it('returns merged options if options supplied', () => {
+      // Arrange
+      const options = { limit: '1mb' }
+      // Act
+      const result = getJsonBodyParserOptions(options)
+      // Assert
+      expect(result).toEqual({ ...DefaultJsonBodyParserOptions, ...options })
+    })
+  })
+})

package/src/middleware/metrics/counters.ts

@@ -0,0 +1,25 @@
+import type {
+  Application, NextFunction, Request, Response,
+} from 'express'
+
+import { Counters } from '../../Performance/index.ts'
+
+export const useRequestCounters = (app: Application): void => {
+  // Configure Global counters
+  app.use((req: Request, res: Response, next: NextFunction) => {
+    Counters.inc(req.path)
+    Counters.inc('_calls')
+    next()
+  })
+
+  app.get('/stats', (req: Request, res: Response, next: NextFunction) => {
+    /* #swagger.tags = ['Metrics'] */
+    /* #swagger.summary = 'Get the counters for single instance of diviner' */
+    res.json({
+      alive: true,
+      avgTime: `${((Counters.counters['_totalTime'] ?? 0) / (Counters.counters['_calls'] ?? 1)).toFixed(2)}ms`,
+      counters: Counters.counters,
+    })
+    next()
+  })
+}

package/src/middleware/metrics/index.ts

@@ -0,0 +1,2 @@
+export * from './counters.ts'
+export * from './responseProfiler.ts'

package/src/middleware/metrics/responseProfiler.ts

@@ -0,0 +1,23 @@
+import type {
+  NextFunction, Request, Response,
+} from 'express'
+
+/**
+ * Connect middleware to enable profiling of response lifecycle timing. To effectively profile
+ * the response timing, this middleware needs to be called first when initializing your Express
+ * App
+ * @example
+ * const app = express()
+ * app.use(responseProfiler)
+ * // other initialization ...
+ * @param _req The request
+ * @param res The response
+ * @param next The next function
+ */
+export const responseProfiler = (_req: Request, res: Response, next: NextFunction) => {
+  if (!res.locals?.meta) {
+    res.locals.meta = {}
+  }
+  res.locals.meta.profile = { startTime: Date.now() }
+  next()
+}

package/src/middleware/standardResponses/getResponseMetadata.ts

@@ -0,0 +1,18 @@
+import type { Response } from 'express'
+
+export const getResponseMetadata = (res: Response): Record<string, unknown> => {
+  const meta: Record<string, unknown> = res.locals?.meta || {}
+  // NOTE: We should do this somewhere else to better separate concerns
+  const profile = res.locals.meta?.profile
+  if (profile) {
+    const startTime = profile?.startTime
+    if (startTime) {
+      const endTime = Date.now()
+      const duration = endTime - startTime
+      res.locals.meta.profile = {
+        duration, endTime, startTime,
+      }
+    }
+  }
+  return meta
+}

package/src/middleware/standardResponses/index.ts

@@ -0,0 +1,4 @@
+export * from './getResponseMetadata.ts'
+export * from './jsonApi/index.ts'
+export * from './standardErrors.ts'
+export * from './standardResponses.ts'

package/src/middleware/standardResponses/jsonApi/README.md

@@ -0,0 +1,4 @@
+# JSON API
+
+The following interfaces/types attempt to capture the
+[JSON API 1.0](https://jsonapi.org/) specification as closely as possible

package/src/middleware/standardResponses/jsonApi/error.ts

@@ -0,0 +1,52 @@
+import type { ApiLinks } from './links.ts'
+
+/**
+ * An object containing references to the source of the error
+ */
+export interface Source {
+  /**
+   * A string indicating which URI query parameter caused the error.
+   */
+  parameter?: string
+  /**
+   * A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object,
+   * or "/data/attributes/title" for a specific attribute].
+   */
+  pointer?: string
+}
+
+export interface ApiError {
+  /**
+   *  An application-specific error code, expressed as a string value.
+   */
+  code?: string
+  /**
+   *  A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized.
+   */
+  detail?: string
+  /**
+   *  A unique identifier for this particular occurrence of the problem.
+   */
+  id?: string
+  /**
+   *  A links object containing the following members:
+   *    about: a link that leads to further details about this particular occurrence of the problem
+   */
+  links?: ApiLinks
+  /**
+   *  A meta object containing non-standard meta-information about the error.
+   */
+  meta?: Record<string, unknown>
+  /**
+   *  An object containing references to the source of the error, optionally including any of the following members:
+   */
+  source?: Source
+  /**
+   *  The HTTP status code applicable to this problem, expressed as a string value.
+   */
+  status?: string
+  /**
+   *  A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
+   */
+  title?: string
+}