Add BaseError.toJSON()

Author: ehmicky

CHANGELOG.md

@@ -1,3 +1,10 @@
+# 2.2.0
+
+## Features
+
+- `error.toJSON()` has been renamed to
+  [`BaseError.toJSON(error)`](README.md#baseerrortojsonerror)
+
 # 2.1.0
 
 ## Features

README.md

@@ -15,7 +15,7 @@
 [plugin](https://github.com/ehmicky/modern-errors#-plugins) to serialize/parse
 errors.
 
-This adds [`error.toJSON()`](#errortojson) and
+This adds [`BaseError.toJSON()`](#baseerrortojsonerror) and
 [`BaseError.parse()`](#baseerrorparseerrorobject) to serialize/parse errors
 to/from plain objects.
 
@@ -46,11 +46,11 @@ export const BaseError = ModernError.subclass('BaseError', {
 // ...
 ```
 
-[Serializing](#errortojson) errors to plain objects.
+[Serializing](#baseerrortojsonerror) errors to plain objects.
 
 ```js
 const error = new InputError('Wrong file.', { props: { filePath } })
-const errorObject = error.toJSON()
+const errorObject = BaseError.toJSON(error)
 // { name: 'InputError', message: 'Wrong file', stack: '...', filePath: '...' }
 const errorString = JSON.stringify(error)
 // '{"name":"InputError",...}'
@@ -88,16 +88,21 @@ Plugin object to pass to the
 [`plugins` option](https://github.com/ehmicky/modern-errors#adding-plugins) of
 `ErrorClass.subclass()`.
 
-## error.toJSON()
+## BaseError.toJSON(error)
 
+`error`: `Error`\
 _Return value_: `ErrorObject`
 
 Converts errors to plain objects that are
 [serializable](https://github.com/ehmicky/error-serializer#json-safety) to JSON
 ([or YAML](https://github.com/ehmicky/error-serializer#custom-serializationparsing),
-etc.). This is
-[automatically called](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#tojson_behavior)
-by `JSON.stringify()`.
+etc.).
+
+This is also set as
+[`error.toJSON()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#tojson_behavior),
+so
+[`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
+automatically calls it.
 
 All
 [error properties](https://github.com/ehmicky/error-serializer#additional-error-properties)
@@ -125,7 +130,7 @@ const error = new InputError('Wrong file.')
 error.cycle = error
 
 // Cycles make `JSON.stringify()` throw, so they are removed
-console.log(error.toJSON().cycle) // undefined
+console.log(BaseError.toJSON(error).cycle) // undefined
 ```
 
 ## Deep serialization/parsing
@@ -153,7 +158,7 @@ serialization/parsing logic to be performed.
 import { dump, load } from 'js-yaml'
 
 const error = new InputError('Wrong file.')
-const errorObject = error.toJSON()
+const errorObject = BaseError.toJSON(error)
 const errorYamlString = dump(errorObject)
 // name: InputError
 // message: Wrong file.
@@ -166,7 +171,7 @@ const newError = BaseError.parse(newErrorObject) // InputError: Wrong file.
 
 ```js
 const error = new InputError('Wrong file.', { props: { prop: true } })
-const errorObject = error.toJSON()
+const errorObject = BaseError.toJSON(error)
 console.log(errorObject.prop) // true
 const newError = BaseError.parse(errorObject)
 console.log(newError.prop) // true
@@ -179,7 +184,7 @@ const error = new InputError('Wrong file.', {
   errors: [new ExampleError('one'), new ExampleError('two')],
 })
 
-const errorObject = error.toJSON()
+const errorObject = BaseError.toJSON(error)
 // {
 //   name: 'InputError',
 //   message: 'Wrong file.',
@@ -212,7 +217,7 @@ const InputError = BaseError.subclass('InputError', {
 })
 
 const error = new InputError('Wrong file.', {}, true)
-const errorObject = error.toJSON()
+const errorObject = BaseError.toJSON(error)
 // `constructor(message, options, prop)` is not called
 const newError = BaseError.parse(errorObject)
 // But properties set by that `constructor(...)` are kept

src/main.js

@@ -1,7 +1,7 @@
 import { serialize, parse as parseErrorObject } from 'error-serializer'
 import isPlainObject from 'is-plain-obj'
 
-// `error.toJSON()`
+// `ErrorClass.toJSON(error)` or `error.toJSON()`
 const toJSON = function ({ error, instancesData }) {
   return serialize(error, {
     beforeSerialize: beforeSerialize.bind(undefined, instancesData),

test/helpers/main.js

@@ -9,7 +9,7 @@ export const BaseError = ModernError.subclass('BaseError', {
 export const baseError = new BaseError('message')
 // eslint-disable-next-line fp/no-mutation
 baseError.one = true
-export const errorObject = baseError.toJSON()
+export const errorObject = BaseError.toJSON(baseError)
 
 export const nativeError = new TypeError('message')
 // eslint-disable-next-line fp/no-mutation
@@ -18,7 +18,7 @@ nativeError.one = true
 const parentNativeError = new BaseError('test')
 // eslint-disable-next-line fp/no-mutation
 parentNativeError.prop = nativeError
-export const nativeErrorObject = parentNativeError.toJSON().prop
+export const nativeErrorObject = BaseError.toJSON(parentNativeError).prop
 
 const testPlugin = {
   name: 'test',
@@ -34,4 +34,6 @@ export const PluginError = BaseError.subclass('PluginError', {
   plugins: [testPlugin],
 })
 export const pluginError = new PluginError('message', { test: true })
-export const pluginErrorObject = excludeKeys(pluginError.toJSON(), ['options'])
+export const pluginErrorObject = excludeKeys(PluginError.toJSON(pluginError), [
+  'options',
+])

test/parse.js

@@ -56,7 +56,9 @@ const InvalidError = BaseError.subclass('InvalidError', {
 
 test('ErrorClass.parse() handles constructors that throw', (t) => {
   const invalidError = new InvalidError('message', {}, Symbol('test'))
-  t.true(BaseError.parse(invalidError.toJSON()) instanceof BaseError)
+  t.true(
+    BaseError.parse(InvalidError.toJSON(invalidError)) instanceof BaseError,
+  )
 })
 
 test('ErrorClass.parse() keeps plugin options', (t) => {

test/serialize.js

@@ -15,47 +15,51 @@ const convertError = function ({ name, message, stack, one }) {
   return { name, message, stack, one }
 }
 
-test('error.toJSON() serializes', (t) => {
+test('ErrorClass.toJSON() serializes', (t) => {
   t.deepEqual(errorObject, convertError(baseError))
 })
 
 each([baseError, nativeError], ({ title }, deepError) => {
-  test(`error.toJSON() is deep | ${title}`, (t) => {
+  test(`ErrorClass.toJSON() is deep | ${title}`, (t) => {
     const error = new BaseError('test')
     error.prop = [deepError]
-    t.deepEqual(error.toJSON().prop[0], convertError(deepError))
+    t.deepEqual(BaseError.toJSON(error).prop[0], convertError(deepError))
   })
 })
 
-test('error.toJSON() is not enumerable', (t) => {
-  t.false(
-    Object.getOwnPropertyDescriptor(Object.getPrototypeOf(baseError), 'toJSON')
-      .enumerable,
-  )
-})
-
-test('error.toJSON() keeps plugin options', (t) => {
+test('ErrorClass.toJSON() keeps plugin options', (t) => {
   t.true(pluginErrorObject.pluginsOpts.test)
 })
 
-test('error.toJSON() keeps plugin options deeply', (t) => {
+test('ErrorClass.toJSON() keeps plugin options deeply', (t) => {
   const error = new PluginError('message')
   error.cause = new PluginError('causeMessage', { test: true })
-  t.true(error.toJSON().cause.pluginsOpts.test)
+  t.true(PluginError.toJSON(error).cause.pluginsOpts.test)
 })
 
-test('error.toJSON() does not keep plugin options of native errors', (t) => {
+test('ErrorClass.toJSON() does not keep plugin options of native errors', (t) => {
   const error = new PluginError('message')
   error.cause = new Error('causeMessage')
-  t.false('pluginsOpts' in error.toJSON().cause)
+  t.false('pluginsOpts' in PluginError.toJSON(error).cause)
 })
 
-test('error.toJSON() does not keep empty plugin options', (t) => {
+test('ErrorClass.toJSON() does not keep empty plugin options', (t) => {
   const error = new PluginError('message')
-  t.false('pluginsOpts' in error.toJSON())
+  t.false('pluginsOpts' in PluginError.toJSON(error))
 })
 
-test('error.toJSON() does not mutate error', (t) => {
-  pluginError.toJSON()
+test('ErrorClass.toJSON() does not mutate error', (t) => {
+  PluginError.toJSON(pluginError)
   t.false('pluginsOpts' in pluginError)
 })
+
+test('error.toJSON() serializes', (t) => {
+  t.deepEqual(baseError.toJSON(), convertError(baseError))
+})
+
+test('error.toJSON() is not enumerable', (t) => {
+  t.false(
+    Object.getOwnPropertyDescriptor(Object.getPrototypeOf(baseError), 'toJSON')
+      .enumerable,
+  )
+})

types/main.d.ts

@@ -7,8 +7,8 @@ export type { ErrorObject }
 /**
  * `modern-errors-serialize` plugin.
  *
- * This plugin adds `error.toJSON()` and `BaseError.parse()` to serialize/parse
- * errors to plain objects.
+ * This plugin adds `BaseError.toJSON()` and `BaseError.parse()` to
+ * serialize/parse errors to plain objects.
  */
 declare const plugin: {
   name: 'serialize'
@@ -18,9 +18,13 @@ declare const plugin: {
      * [serializable](https://github.com/ehmicky/error-serializer#json-safety)
      * to JSON
      * ([or YAML](https://github.com/ehmicky/error-serializer#custom-serializationparsing),
-     * etc.). This is
-     * [automatically called](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#tojson_behavior)
-     * by `JSON.stringify()`.
+     * etc.).
+     *
+     * This is also set as
+     * [`error.toJSON()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#tojson_behavior),
+     * so
+     * [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
+     * automatically calls it.
      *
      * All
      * [error properties](https://github.com/ehmicky/error-serializer#additional-error-properties)
@@ -31,7 +35,7 @@ declare const plugin: {
      * @example
      * ```js
      * const error = new InputError('Wrong file.', { props: { filePath } })
-     * const errorObject = error.toJSON()
+     * const errorObject = BaseError.toJSON(error)
      * // { name: 'InputError', message: 'Wrong file', stack: '...', filePath: '...' }
      * const errorString = JSON.stringify(error)
      * // '{"name":"InputError",...}'

types/main.test-d.ts

@@ -7,19 +7,20 @@ const BaseError = ModernError.subclass('BaseError', {
   plugins: [modernErrorsSerialize],
 })
 const error = new BaseError('')
-const errorObject = error.toJSON()
+const errorObject = BaseError.toJSON(error)
 
 expectError(
   ModernError.subclass('TestError', {
     plugins: [modernErrorsSerialize],
     serialize: undefined,
   }),
 )
-expectError(error.toJSON(undefined))
+expectError(BaseError.toJSON(error, undefined))
 expectError(BaseError.parse(errorObject, undefined))
 
 expectType<ErrorObject>(errorObject)
 expectType<string>(errorObject.name)
+expectType<ErrorObject>(error.toJSON())
 
 expectType<unknown>(BaseError.parse(errorObject))
 expectType<unknown>(BaseError.parse({ errorObject }))