Noun/Pronoun Mix-up

    @adobe/aio-lib-core-errors

    3.1.1 • Public • Published

    aio-lib-core-errors

    Version Downloads/week Node.js CI License Codecov Coverage

    This contains the base class for all Adobe I/O Core Errors. Use this as an Error class subclass for all your SDK Errors.

    This module was inspired by how Node.js creates its own Error classes.

    Install

    npm install @adobe/aio-lib-core-errors

    Architecture

    Adobe I/O Core Error Library Architecture

    AioCoreSDKError

    This is the base class for all the Error classes, and it should not be instantiated directly. Create your own subclass (dynamic usage) or use the ErrorWrapper below (static usage).

    The message property of AioCoreSDKError outputs the Error in this format:

    [SDK:ERROR_CODE] ERROR_MESSAGE
    • SDK is the SDK name
    • ERROR_CODE is the error code
    • ERROR_MESSAGE is the error message

    Note that the sdk details is not displayed in the message. To see any sdk details, you will need to convert the Error object itself to JSON via .toJSON() (JSON.stringify will convert the Error object as well, via invoking .toJSON() on the Error object)

    Dynamic Errors Usage

    // Adobe I/O Campaign Standard Wrapper
    
    const { AioCoreSDKError } = require('@adobe/aio-lib-errors')
    
    const gSDKDetails = {
      // ... add your sdk details here
      tenantId,
      endpoint
    }
    const gSDKName = "AdobeIOCampaignStandard"
    
    export default class CampaignStandardCoreAPIError extends AioCoreSDKError {
      constructor(message, code) {
        // the sdk name and sdk details are curried in as the 3rd and 4th parameters
        super(message, code, gSDKName, gSDKDetails)
      }
    }

    So if we have this wrapper function, we change from:

    function getAllProfiles (parameters) {
        return new Promise((resolve, reject) => {
          const apiFunc = 'getAllProfiles'
          this.sdk.apis.profile[apiFunc]()
            .then(response => {
              resolve(response)
            })
            .catch(err => {
              debug(err)
              // >>>>>TO CHANGE<<<<<<<<<
              reject(new Error(`${apiFunc} ${err}`))
            })
        })
      }

    to this:

    function getAllProfiles (parameters) {
        return new Promise((resolve, reject) => {
          const apiFunc = 'getAllProfiles'
          this.sdk.apis.profile[apiFunc]()
            .then(response => {
              resolve(response)
            })
            .catch(err => {
              debug(err)
              // >>>>>NEW<<<<<<<<<
              reject(new CampaignStandardCoreAPIError(err.message /* error message */, apiFunc /* error code */))
            })
        })
    }

    As you can see, this is not very intuitive, and may be error-prone. We can do better with static errors (see below).

    Static Errors

    The example Usage above is for dynamic errors, for example API errors that we are wrapping. Static errors are much better: they are more intuitive to use, and much better for code readability.

    1. Create your Error Class via the ErrorWrapper

    We define our specialized Error class, and error codes in its own module like so:

    // SDKErrors.js
    const { ErrorWrapper, createUpdater } = require('@adobe/aio-lib-core-errors').AioCoreSDKErrorWrapper
    
    const codes = {}
    const messages = new Map()
    
    /**
     * Create an Updater for the Error wrapper
     */
    const Updater = createUpdater(
      // object that stores the error classes (to be exported)
      codes,
      // Map that stores the error strings (to be exported)
      messages
    )
    
    /**
     * Provides a wrapper to easily create classes of a certain name, and values
     */
    const E = ErrorWrapper(
      // The class name for your SDK Error. Your Error objects will be these objects
      'MySDKError',
      // The name of your SDK. This will be a property in your Error objects
      'MySDK',
      // the object returned from the CreateUpdater call above
      Updater
      // the base class that your Error class is extending. AioCoreSDKError is the default
      /* , AioCoreSDKError */
    )
    
    module.exports = {
      codes,
      messages
    }
    
    // Define your error codes with the wrapper
    E('UNKNOWN_THING_ID', 'There was a problem with that thing')
    E('UNKNOWN_ORDER_ID', 'There was a problem with that order id: %s.')

    Error Class Wrapper

    Let's parse what this line means:

    E('UNKNOWN_ORDER_ID', 'There was a problem with that order id: %s.')

    This will dynamically create a MySDKError class with the appropriate closures for values:

    • sdk name (MySDK, passed in to the ErrorWrapper constructor above)
    • sdk error class name (MySDKError, passed in to the ErrorWrapper constructor above)
    • error code (UNKNOWN_ORDER_ID, the first parameter passed in to E)
    • error message (There was a problem with that order id: %s., the second parameter passed in to E. If this is a string with format specifiers, you can pass in arguments for the format specifiers, when the Error is constructed. See example below).
    class MySDKError extends AioCoreSDKError { ... }

    The line will add the dynamically created MySDKError class to the exported codes object, with the first parameter to the wrapper (the error code) as the key.

    The constructor for the class created takes one parameter, an object:

    constructor(parameters)
    • parameters (optional) is an object
    • parameters.sdkDetails (optional) is an object that you want to pass in as additional data for the Error object. e.g. function parameters for an API call.
    • parameters.messageValues (optional) is a string, number, object or an array of the items that you want to apply to the error message, if the message has a format specifier.

    In the error specification line below, you can see it has one format specifier %s:

    E('UNKNOWN_ORDER_ID', 'There was a problem with that order id: %s.')

    2. Use Your Error Classes

    Import the static error code Error classes, and use directly.

     const { UNKNOWN_THING_ID, UNKNOWN_ORDER_ID } = require('./SDKErrors').codes
    // or, if you have too many codes to destructure:
    // const { codes } = require('./SDKErrors')
    
    const gSdkDetails = {
      tenantId: 'mytenant'
    }
    // convoluted examples, but demonstrates usage
    const unknownThing = true
    if (unknownThing) {
      throw new UNKNOWN_THING_ID({ sdkDetails: gSDKDetails })
    }
    
    const unknownOrderId = true
    if (unknownOrderId) {
      // messageValues can either be a string, object, etc or an array of them
      throw new UNKNOWN_ORDER_ID({ 
        sdkDetails: gSDKDetails,
        messageValues: ['ORDER-2125SFG']
      }) ) 
    }
    
    function getOrder(orderId) {
      // we just wrap the function arguments as the sdkDetails
      const sdkDetails = { orderId }
      const somethingWentWrong = true
    
      if (somethingWentWrong) {
      // messageValues can either be a string, object, etc or an array of them
        throw new UNKNOWN_ORDER_ID({ 
          sdkDetails: sDKDetails,
          messageValues: 'ORDER-2125SFGF'
        }) ) 
      }
    }
    
    getOrder('abc123')

    Example Console Output


    Print out a thrown UNKNOWN_ORDER_ID Error object to the console. console calls the .toString() method for the Error object, and the resulting data is not structured well, and will not expand nested objects:

    try {
      throw new UNKNOWN_ORDER_ID()
    } catch (e) {
      console.error(e)
    }

    Output:

     { MySDKError: [MySDK:UNKNOWN_ORDER_ID] There was a problem with that order id: ORDER-21241-FSFS.
              at new <anonymous> (/Users/obfuscated/aio-lib-core-errors/src/AioCoreSDKErrorWrapper.js:22:9)
              at Object.<anonymous>.test (/Users/obfuscated/aio-lib-core-errors/test/MySDKError.test.js:50:15)
              at Object.asyncJestTest (/Users/obfuscated/aio-lib-core-errors/node_modules/jest-jasmine2/build/jasmineAsyncInstall.js:102:37)
              at resolve (/Users/obfuscated/aio-lib-core-errors/node_modules/jest-jasmine2/build/queueRunner.js:43:12)
              at new Promise (<anonymous>)
              at mapper (/Users/obfuscated/aio-lib-core-errors/node_modules/jest-jasmine2/build/queueRunner.js:26:19)
              at promise.then (/Users/obfuscated/aio-lib-core-errors/node_modules/jest-jasmine2/build/queueRunner.js:73:41)
              at process._tickCallback (internal/process/next_tick.js:68:7)
            code: 'UNKNOWN_ORDER_ID',
            sdk: 'MySDK',
            sdkDetails: { tenantId: 'MYTENANT2' },
            name: 'MySDKError' }

    Simply print out a thrown UNKNOWN_ORDER_ID Error object's message property to the console:

    try {
      throw new UNKNOWN_ORDER_ID()
    } catch (e) {
      console.error(e.message)
    }

    Output:

    [MySDK:UNKNOWN_ORDER_ID] There was a problem with that order id: ORDER-21241-FSFS.

    Convert a thrown UNKNOWN_ORDER_ID Error object to JSON and print to the console. console calls the .toJSON() method of the Error object, and will expand nested objects:

    try {
      throw new UNKNOWN_ORDER_ID()
    } catch (e) {
      console.error(JSON.stringify(e, null, 2))
    }

    Output:

    {
    	"sdk": "MySDK",
    	"sdkDetails": { "tenantId": "MYTENANT2" },
    	"code": "UNKNOWN_ORDER_ID",
    	"message": "[MySDK:UNKNOWN_ORDER_ID] There was a problem with that order id: ORDER-21241-FSFS.",
    	"stacktrace": "MySDKError: [MySDK:UNKNOWN_ORDER_ID] There was a problem with that order id: ORDER-21241-FSFS.\n    at new <anonymous> (/Users/obfuscated/aio-lib-core-errors/src/AioCoreSDKErrorWrapper.js:22:9)\n    at Object.<anonymous>.test (/Users/obfuscated/aio-lib-core-errors/test/MySDKError.test.js:50:15)\n    at Object.asyncJestTest (/Users/obfuscated/aio-lib-core-errors/node_modules/jest-jasmine2/build/jasmineAsyncInstall.js:102:37)\n    at resolve (/Users/obfuscated/aio-lib-core-errors/node_modules/jest-jasmine2/build/queueRunner.js:43:12)\n    at new Promise (<anonymous>)\n    at mapper (/Users/obfuscated/aio-lib-core-errors/node_modules/jest-jasmine2/build/queueRunner.js:26:19)\n    at promise.then (/Users/obfuscated/aio-lib-core-errors/node_modules/jest-jasmine2/build/queueRunner.js:73:41)\n    at process._tickCallback (internal/process/next_tick.js:68:7)"
    }

    Explore

    goto API

    Contributing

    Contributions are welcomed! Read the Contributing Guide for more information.

    Licensing

    This project is licensed under the Apache V2 License. See LICENSE for more information.

    Keywords

    none

    Install

    npm i @adobe/aio-lib-core-errors

    DownloadsWeekly Downloads

    4,003

    Version

    3.1.1

    License

    Apache-2.0

    Unpacked Size

    29.9 kB

    Total Files

    6

    Last publish

    Collaborators

    • adobehalls
    • fullcolorcoder
    • marbec
    • tripod
    • garthdb
    • lazd
    • adobe-admin
    • patrickfulton
    • trieloff
    • shazron
    • krisnye
    • dcpfsdk
    • natebaldwin
    • devongovett
    • aspro83
    • symanovi
    • dpfister
    • stefan-guggisberg
    • korra
    • rofe
    • kptdobe