This library allows you to combine a success value, an error value, and a warning value into a single variable that can easily be returned from functions and allows easy array and object destructuring to extract the values.
This library uses the exception-tree package to generate errors and warnings.
In the below example the error and warning exceptions never get a message, so these values become undefined when passed into the Result object.
const { Exception, Result } = require('result-value-exception')
const err = new Exception('This operation failed')
const warn = new Exception('There are some warnings')
const result = new Result('the result', err, warn)
// destructure into new variable names
const [ a, b, c ] = result
console.log(a, b, c) // "the result" undefined undefined
// object destructure
const { value, error, warning } = result
console.log(value, error, warning) // "the result" undefined undefined
const { Exception, Result } = require('result-value-exception')
const err = new Exception('This operation failed')
err.message('I am a teapot')
const warn = new Exception('There are some warnings')
err.message('Warning 1')
err.message('Warning 2')
const result = new Result('the result', err, warn)
// destructure into new variable names
const [ a, b, c ] = result
console.log(a, b, c) // a is undefined because the error has messages
// object destructure
const { value, error, warning } = result
console.log(value, error, warning) // value is undefined because the error has messages
Result ( value [, error [, warning ] ] )
Create a Result instance.
Parameters:
Parameter | Description | Type | Default |
---|---|---|---|
value | The success value for the Result instance. | any | |
error | An Exception instance that may or may not have any messages. If an message does exist for this object then the Result value will be undefined . |
Exception | undefined |
warning | An Exception instance that may or may not have any messages. If a message does exist the Result value will not be converted to undefined . |
Exception | undefined |
Returns an Result instance.
A Result is an object that allows destructuring from an iterable or a plain object.
The object has the properties:
-
error - An Exception object. If the exception has no message then this value will be
undefined
. -
e - An alias for the
error
property. -
value - The success value. This value will be
undefined
if the error exception has a message. -
v - An alias for the
value
property. -
warning - An Exception object with warnings that do not prevent successful operation. If there is no warning message then this value will be
undefined
.
The iterable has the same values as the object in order of:
-
value
-
error
-
warning
Probably the most wellknown method for reading a result, you can get the entire object and then access the properties off of that object.
const result = new Result('value', error, warning)
console.log(result.error)
console.log(result.value)
console.log(result.warning)
Default destructuring requires the original property names to be used. You can specify as many or as few properties as you'd like to extract. It is also possible to specify the name of the extracted property.
Specify all Properties
const { error, value, warning } = new Result('value', error, warning)
console.log(error)
console.log(value)
console.log(warning)
Specify some Properties
const { value } = new Result('value', error, warning)
console.log(value)
Specify Properties with Different Name
In this example:
error
is renamed toe
value
is renamed toschema
warning
is not renamed
const { error: e, value: schema, warning } = new Result('value', error, warning)
console.log(e)
console.log(schema)
console.log(warning)
You can choose the names of the value, but the order is important. The order is 1) the value, 2) the error, 3) the warning.
It is not a requirement to get all three values.
Get All Three Properties
const [ val, err, warning ] = new Result('value', error, warning)
console.log(err)
console.log(val)
console.log(warning)
Get Just the Value
const [ value ] = new Result('value', error, warning)
console.log(value)
Get Just the Error
const [ , err ] = new Result('value', error, warning)
console.log(err)
Get Just the Warning
const [ , , warning ] = new Result('value', error, warning)
console.log(warning)