Novice, Practiced, Mastered

    auto-trace

    3.3.0 • Public • Published

    auto-trace

    A library that fixes all your stack trace problems.

    This library helps transform garbage errors into beautiful objects filled with insight and understanding. This is especially useful for apps that use an error reporting service such as bug-snag or sentry.

    • Provide a meaningful Stack Trace (for optimum error blameage)
    • Prevent irresponsible throwing of Non-Error objects (which result in Error:[object Object])
    • Attach extra context to errors
    • Encourage a consistent pattern for error handling

    Resource File

    return $http
      .get()
      .then()
      .catch(catchAsyncStacktrace(extraContext))

    Observable

    return observable
      .then()
      .catch(catchAsyncStacktrace(extraContext))

    Error Life cycle

    There are two parts to the error life cycle

    • Error Created new Error()
    • Error Thrown throw err

    These events do not always occur at the same time. $http is an example of this. Since $http makes an async request, an error stacktrace will contain the call stack of the invoker as the request comes in (this is the syncStacktrace). Often the more useful stacktrace is the call stack as the request went out Controller->Service->Resource (this is the asyncStacktrace).

    API

    catchError

    catchError is a wrapper around asyncStacktrace which returns a method that will handle error processing and throwing. Pass this as your onError arg in RxJS subscriptions or as a callback in catch.

    RxJS Subscription example: myObs.subscribe(onComplete, catchError())

    If a callback is provided then that will be called and the error will have to be thrown manually:

    myObs.subscribe(onComplete, catchError((error, throwError) => {
      error.showToast = false
      throwError(error)
    }))
    

    Asynchronous Stack-Trace

    The asynchronous stacktrace is often the most useful, in the case of http requests, this is the stacktrace as the request is going out.

    asyncStacktrace(callback, extraContext)

    Returns a function that will wrap the caught response in an error object that contains the asynchronous stacktrace. Will append extraContext and call callback with wrapped error. This should be called as a function so that return value function will be passed into the catch statement.

    • callback (optional) function that will be called with the wrapped error
    • extraContext (optional) String or Object that will be stringified and appended to the error message
    return $http
      .get()
      .then()
      .catch(asyncStacktrace(callback, {state: 'extra info'}))

    catchAsyncStacktrace(extraContext)

    Returns a function that will wrap caught response in an error object that contains the asynchronous stacktrace. Will append extraContext and throw the wrapped error. This should be called as a function so that return value function will be passed into the catch statement (see example).

    • extraContext (optional) String or Object that will be stringified and appended to the error message

    This function uses setTimeout(() => {throw err}) to throw the error.

    The error will be caught be window.onerror and can be logged by reporting services like sentry and bugsnag, but will not disrupt normal code execution (and cannot be caught elsewhere within the app).

    This is especially helpful when working in angular land - as throwing an error within a promise catch handler will cause a rootScope:digest Error.

    return $http
      .get()
      .then()
      .catch(catchAsyncStacktrace({state: 'extra info'}))

    Synchronous Stack-Trace

    In the case of http requests, the synchronous stacktrace is the stacktrace as the request is response comes in. This is the normal, but less useful, stack-trace included by response errors. Often this trace follows the application function that serviced the request.

    syncStacktrace

    First order function, will wrap caught response in an error object that contains the asynchronous stacktrace and return the wrapped error. This should be passed (not called) as a function into the catch statement.

    return $http
      .get()
      .then()
      .catch(syncStacktrace)

    catchSyncStacktrace

    First order function, will wrap caught response in an error object that contains the asynchronous stacktrace and throw the wrapped error. This should be passed (not called) as a function into the catch statement (see example).

    This function uses setTimeout(() => {throw err}) to throw the error.

    The error will be caught be window.onerror and can be logged by reporting services like sentry and bugsnag, but will not disrupt normal code execution (and cannot be caught elsewhere within the app).

    This is especially helpful when working in angular land - as throwing an error within a promise catch handler will cause a rootScope:digest Error.

    return $http
      .get()
      .then()
      .catch(catchSyncStacktrace)

    Middleware

    Looking for more useful information about your errors? Wish you had the data from both parts of the error life cycle. Look no further! Middlewares allow you to create higher order functions that will execute in both life cycle contexts.

    addGlobalMiddleware(middlewareFn)

    Adds global middleware function that will be called on all autoTrace errors.

    Middlewares must be of the form asyncErr => syncRawErr => errToReturn

    • asyncErr is an Error object with the Async stacktrace
    • syncRawErr is the rawError passed to the handler, this could be any type of object (make sure to perform a type check).
    • errToReturn will passed as the syncRawErr to the next middleware, and finally wrapped in an error object (if needed) and thrown (or passed into a callback).

    removeAllGlobalMiddlewares()

    Deletes all global middleware functions.

    Middleware Examples

    Let's say you want to record how long it takes for a request to fail. This requires context surrounding when the error was created and when the error was thrown.

    const middleware = asyncErr => {
      const startTime = new Date()
      return syncErr => {
        const errorTime = new Date() - startTime;
        if(typeof syncErr === Error)
          syncErr.message += ' -TimeToFail: ' + errorTime
        else
          syncErr = new Error(JSON.stringify(syncErr) + ' -TimeToFail: ' + errorTime)
        return syncErr
      }
    }
    
    addGlobalMiddleware(middleware);

    Resource File

    const extraContext = '-More info'
    
    return $http
      .get()
      .then()
      .catch(throwAsyncStacktrace(extraContext))

    This will create Error: {message: 'original error message -TimeToFail: 10s -More info', trace: ...}

    installation

    npm install auto-trace

    Install

    npm i auto-trace

    DownloadsWeekly Downloads

    180

    Version

    3.3.0

    License

    Apache-2.0

    Unpacked Size

    29.5 kB

    Total Files

    5

    Last publish

    Collaborators

    • parkm
    • greenjeffreym
    • mmemory
    • ron.douglas
    • miracastillo
    • geoctrl
    • tannerrigby
    • rchilds
    • joeldenning
    • blittle
    • kentmclean
    • keithhalterman
    • alanandersen