@bitfinex/lib-util-err-js 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# 1.0.0
+- breaking: require Node.js >= 22
+- chore: commit package-lock.json and disable install scripts via .npmrc
+- chore: replace standard with @bitfinex/lint-js
+- chore: replace mocha/chai/sinon/nyc with brittle
+
+# 0.2.0
+- feature: prevent adding prefix more than once
+
+# 0.1.0
+- feature: user error
+- feature: generic error
+- feature: api error handler

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# lib-util-err-js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The lib includes the utilities that help on resolving errors that should be shown to the endusers.
+
+## Installing
+
+Requires Node.js >= 22.
+
+```console
+npm i @bitfinex/lib-util-err-js
+```
+
+## Testing
+
+```console
+npm test
+npm run coverage
+```
+
+## Usage
+
+```javascript
+const { apiErrorHandler, GrcUserError, constants: { ERR_CODES } } = require('..')
+
+const err = new Error('ERR_CONNECTION_FAILED')
+const userErr = new GrcUserError('ERR_INVALID_CREDENTIALS', 'AUTH_ACTION', ERR_CODES.ERR_AUTH_FAIL)
+
+const cb = (err) => {
+  console.error('- Response from action')
+  console.error(err)
+}
+
+apiErrorHandler(err, 'AUTH_FUNCTION', cb)
+apiErrorHandler(userErr, 'AUTH_FUNC', cb)
+
+```
+
+## Authors
+- vigan.abd

package/examples/index.js

@@ -0,0 +1,14 @@
+'use strict'
+
+const { apiErrorHandler, GrcUserError, constants: { ERR_CODES } } = require('..')
+
+const err = new Error('ERR_CONNECTION_FAILED')
+const userErr = new GrcUserError('ERR_INVALID_CREDENTIALS', 'AUTH_ACTION', ERR_CODES.ERR_AUTH_FAIL)
+
+const cb = (err) => {
+  console.error('- Response from action')
+  console.error(err)
+}
+
+apiErrorHandler(err, 'AUTH_FUNCTION', cb)
+apiErrorHandler(userErr, 'AUTH_FUNC', cb)

package/index.js

@@ -0,0 +1,11 @@
+'use strict'
+
+const GrcUserError = require('./src/errors/grc.user.error')
+const GrcGenericError = require('./src/errors/grc.generic.error')
+const apiErrorHandler = require('./src/api.error.handler')
+
+module.exports = {
+  GrcUserError,
+  GrcGenericError,
+  apiErrorHandler
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@bitfinex/lib-util-err-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Bitfinex lib utility for handling error messages",
+  "main": "index.js",
+  "engines": {
+    "node": ">=22.0"
+  },
+  "scripts": {
+    "lint": "bfx-lint-js",
+    "lint:fix": "bfx-lint-js --fix",
+    "test": "npm run lint && npm run test:unit",
+    "test:unit": "brittle-node test/*.test.js",
+    "coverage": "npm run lint && npm run coverage:unit",
+    "coverage:unit": "brittle-node --coverage test/*.test.js"
+  },
+  "keywords": [
+    "bitfinex",
+    "utils",
+    "error"
+  ],
+  "author": {
+    "name": "vigan.abd",
+    "email": "vigan.abdurrahmani@bitfinex.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitfinexcom/lib-util-err-js.git"
+  },
+  "maintainers": [
+    {
+      "name": "prdn",
+      "email": "paolo@bitfinex.com"
+    },
+    {
+      "name": "vigan.abd",
+      "email": "vigan.abdurrahmani@bitfinex.com"
+    }
+  ],
+  "bugs": {
+    "url": "https://github.com/bitfinexcom/lib-util-err-js/issues"
+  },
+  "homepage": "https://github.com/bitfinexcom/lib-util-err-js#readme",
+  "devDependencies": {
+    "@bitfinex/lint-js": "^1.1.0",
+    "brittle": "^4.5.0"
+  }
+}

package/src/api.error.handler.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const GrcUserError = require('./errors/grc.user.error')
+const GrcGenericError = require('./errors/grc.generic.error')
+
+/**
+ * @callback ErrorCallbackFunction
+ * @param {Error} err
+ * @returns {void}
+ */
+
+/**
+ * Error handler utility that is useful for hiding internal errors from endusers
+ *
+ * @param {Error} err - Original error
+ * @param {string} [basename] - Optional, error base message
+ * @param {Object} [opts] - Optional, error handling options
+ * @param {boolean} [opts.force] - Optional, force original error message
+ * @param {ErrorCallbackFunction} cb - Callback function in format: `(err) => void`
+ */
+
+const apiErrorHandler = (err, basename, opts, cb) => {
+  if (typeof basename === 'function') {
+    cb = basename
+    basename = null
+    opts = { force: false }
+  }
+
+  if (typeof opts === 'function') {
+    cb = opts
+    opts = { force: false }
+  }
+
+  console.error(new Date().toISOString(), basename, err)
+
+  if (err instanceof GrcUserError || opts.force) {
+    // in case if force flag is used, debugging purposes
+    let message = err.message || err.toString()
+    const prefix = basename && !message.startsWith(basename) ? `${basename}: ` : ''
+    message = prefix + message // wrap error with basename
+    const code = err.code || null
+
+    cb(new GrcUserError(message, code))
+  } else {
+    cb(new GrcGenericError(basename))
+  }
+}
+
+module.exports = apiErrorHandler

package/src/errors/grc.generic.error.js

@@ -0,0 +1,20 @@
+'use strict'
+
+const GrcUserError = require('./grc.user.error')
+
+/**
+ * Generic api error, useful for hiding errors like connection failures
+ */
+class GrcGenericError extends GrcUserError {
+  /**
+   * @param {string} [basename] - Optional, error message prefix
+   */
+  constructor (basename = null) {
+    super((basename ? `${basename}: ` : '') + 'generic error')
+
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+  }
+}
+
+module.exports = GrcGenericError

package/src/errors/grc.user.error.js

@@ -0,0 +1,33 @@
+'use strict'
+
+/**
+ * User friendly error that is shown directly to endusers
+ */
+class GrcUserError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {number} [code] - Optional, error code
+   */
+  constructor (message, code = null) {
+    super(message)
+
+    this.name = this.constructor.name
+    this.code = code
+
+    Error.captureStackTrace(this, this.constructor)
+  }
+
+  /**
+   * This method is called from JSON.stringify function when serializing object
+   * @returns {{ message: string, code: number, name: string }}
+   */
+  toJSON () {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code
+    }
+  }
+}
+
+module.exports = GrcUserError

package/test/api.error.handler.test.js

@@ -0,0 +1,93 @@
+'use strict'
+
+const test = require('brittle')
+const { format } = require('util')
+const { GrcGenericError, GrcUserError, apiErrorHandler } = require('../')
+
+// Captures console.error output for the test and restores it afterwards
+const stubConsoleError = (t) => {
+  const logs = []
+  const original = console.error
+  console.error = (...params) => logs.push(format(...params))
+  t.teardown(() => { console.error = original })
+  return logs
+}
+
+test('it should hide original error message in case if it\'s not instance of GrcUserError', (t) => {
+  t.plan(3)
+  stubConsoleError(t)
+  apiErrorHandler(new Error('Critical error in db'), 'MY_FUNCTION', {}, (err) => {
+    t.ok(err instanceof GrcGenericError)
+    t.is(err.message, 'MY_FUNCTION: generic error')
+    t.is(err.code, null)
+  })
+})
+
+test('it should return original error message in case if it\'s instance of GrcUserError', (t) => {
+  t.plan(3)
+  stubConsoleError(t)
+  apiErrorHandler(new GrcUserError('invalid field', 10001), 'MY_FUNCTION', {}, (err) => {
+    t.ok(err instanceof GrcUserError)
+    t.is(err.message, 'MY_FUNCTION: invalid field')
+    t.is(err.code, 10001)
+  })
+})
+
+test('it should return original error message in case if it has force flag', (t) => {
+  t.plan(3)
+  stubConsoleError(t)
+  apiErrorHandler(new Error('Critical error in db'), 'MY_FUNCTION', { force: true }, (err) => {
+    t.ok(err instanceof GrcUserError)
+    t.is(err.message, 'MY_FUNCTION: Critical error in db')
+    t.is(err.code, null) // since it's missing add default one!
+  })
+})
+
+test('it should work without optional params', (t) => {
+  t.plan(3)
+  stubConsoleError(t)
+  apiErrorHandler(new Error('Critical error in db'), (err) => {
+    t.ok(err instanceof GrcGenericError)
+    t.is(err.message, 'generic error')
+    t.is(err.code, null)
+  })
+})
+
+test('it should work without opts param', (t) => {
+  t.plan(3)
+  stubConsoleError(t)
+  apiErrorHandler(new Error('Critical error in db'), 'MY_FUNCTION', (err) => {
+    t.ok(err instanceof GrcGenericError)
+    t.is(err.message, 'MY_FUNCTION: generic error')
+    t.is(err.code, null)
+  })
+})
+
+test('it should always log original error', (t) => {
+  t.plan(2)
+  const logs = stubConsoleError(t)
+  apiErrorHandler(new GrcUserError('invalid field', 10001), () => {
+    t.is(logs.length, 1)
+    t.ok(logs[0].includes('GrcUserError: invalid field'))
+  })
+})
+
+test('it should use toString method when error does not have message field', (t) => {
+  t.plan(3)
+  stubConsoleError(t)
+  apiErrorHandler('Critical error in db', 'MY_FUNCTION', { force: true }, (err) => {
+    t.ok(err instanceof GrcUserError)
+    t.is(err.message, 'MY_FUNCTION: Critical error in db')
+    t.is(err.code, null)
+  })
+})
+
+test('it should avoid adding prefix more than once', (t) => {
+  t.plan(3)
+  stubConsoleError(t)
+  apiErrorHandler(new GrcUserError('MY_FUNCTION: invalid field'), 'MY_FUNCTION', (err) => {
+    t.ok(err instanceof GrcUserError)
+    t.is(err.message, 'MY_FUNCTION: invalid field')
+    t.is(err.code, null)
+  })
+})

package/test/generic.error.test.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const test = require('brittle')
+const { GrcGenericError } = require('../')
+
+test('GenericError: it should parse fields properly', (t) => {
+  const err = new GrcGenericError('MY_FUNCTION')
+  t.ok(err instanceof Error)
+  t.is(err.name, 'GrcGenericError')
+  t.is(err.message, 'MY_FUNCTION: generic error')
+  t.is(err.code, null)
+  t.is(typeof err.stack, 'string')
+  t.ok(err.stack.startsWith('GrcGenericError: MY_FUNCTION: generic error'))
+  t.ok(err.stack.includes(' at '))
+})
+
+test('GenericError: it should work also without optional params', (t) => {
+  const err = new GrcGenericError()
+
+  t.is(err.message, 'generic error')
+  t.is(err.code, null)
+  t.ok(err.stack.startsWith('GrcGenericError: generic error'))
+})
+
+test('GenericError: it should serialize only specific fields', (t) => {
+  const serialized = JSON.stringify(new GrcGenericError('MY_FUNC'))
+  const deserialized = JSON.parse(serialized)
+  const expected = {
+    name: 'GrcGenericError',
+    message: 'MY_FUNC: generic error',
+    code: null
+  }
+
+  t.alike(deserialized, expected)
+})

package/test/user.error.test.js

@@ -0,0 +1,36 @@
+'use strict'
+
+const test = require('brittle')
+const { GrcUserError } = require('../')
+
+test('GrcUserError: it should parse fields properly', (t) => {
+  const err = new GrcUserError('invalid user input', 10001)
+
+  t.ok(err instanceof Error)
+  t.is(err.name, 'GrcUserError')
+  t.is(err.message, 'invalid user input')
+  t.is(err.code, 10001)
+  t.is(typeof err.stack, 'string')
+  t.ok(err.stack.startsWith('GrcUserError: invalid user input'))
+  t.ok(err.stack.includes(' at '))
+})
+
+test('GrcUserError: it should work also without optional params', (t) => {
+  const err = new GrcUserError('invalid user input')
+
+  t.is(err.message, 'invalid user input')
+  t.is(err.code, null)
+  t.ok(err.stack.startsWith('GrcUserError: invalid user input'))
+})
+
+test('GrcUserError: it should serialize only specific fields', (t) => {
+  const serialized = JSON.stringify(new GrcUserError('invalid user input', 10001))
+  const deserialized = JSON.parse(serialized)
+  const expected = {
+    name: 'GrcUserError',
+    message: 'invalid user input',
+    code: 10001
+  }
+
+  t.alike(deserialized, expected)
+})