edogawa
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.4 • Public • Published

    Edogawa

    Browser utility library to report uncaught errors in your app in the DOM. The library creates a Report object that contains the exception, event trails and the user browser. See an example of a report object here.

    Installation

    npm

    npm install edogawa
    

    yarn

    yarn add edogawa
    

    Usage

    Initialize an Edogawa instance in your client entry code (or wherever you prefer)

    import { init } from 'edogawa';
    
    init({ endpoint: 'https://yourapp.com/reports' });

    Voila, you're done. No further steps are needed on the client. The library will now listen to uncaught errors and send the report to the given endpoint.

    You can setup your server endpoint as you like - to accept the report object.

    Edogawa init API

    Edogawa accepts parameters that could be helpful for your debugging

    init = (
      /* See Config object below */
      config: Config,
      /* for your custom client side callback */
      exceptionCallback?: (report: Report) => void,
      /* See DevConfig object below */
      devConfig?: DevConfig,
    ) => void;
    
    // Config Object accepted in init
    interface Config {
      /* Your server endpoint that accepts an Edogawa report.
      See the structure of the report below */
      endpoint: string;
    
       /* Endpoint rest token, if needed */
      restToken?: string;
    
      /* maximum size of the trail size array */
      maxTrailSize?: number;
    
      /* you might want to ignore some common errors that are caused by browser extensions, etc. */
    
      ignore?: RegExp[];
      additionalInfo?: {
        [key in string]: any;
      };
    }
    
    // DevConfig Object accepted in init
    export interface DevConfig {
      /* mostly for development,
      this just skips the part of sending a push to the endpoint */
      clientSideDebug?: boolean;
    }

    Edogawa Report object

    Edogawa returns a Report object when an exception is caught. See example generated report below. The structure is:

    export type Report = {
      exception: {
        name?: string,
        stackTrace?: string,
        message?: string,
        source?: string,
        lineno?: number,
        colno?: number,
      },
      userInfo?: UserInfo,
      /* See EventTrail object structure below */
      trail?: EventTrail[],
    };
    
    /* Taken from Parsed result of Bowser( https://github.com/lancedikson/bowser)*/
    interface UserInfo {
      userInfo: {
        browser: { name: string, version: string },
        os: { name: string, version: string, versionName: string },
        platform: { type: string, vendor: string },
        engine: { name: string },
      };
    }
    
    /* EventTrail object:
    - basically properties of an Element in an event that happened before the exception
    - plus the event type */
    interface EventTrail {
      tag: string;
      id: string;
      class: string;
      type: string;
      partialInnerText: string;
    }

    Sample Report Object

    const report: Report = {
      // the uncaught exception (obv.)
      exception: {
        message: 'Uncaught Error: custom error',
        name: 'Error',
        stackTrace:
          'Error: custom error↵    at HTMLButtonElement.<anonymous> (http://yourapp.com/app.77de5100.js)',
        source: 'http://yourapp.com/app.77de5100.js',
        lineno: 468,
        colno: 9,
      },
      // user info (obv.)
      userInfo: {
        browser: { name: 'Chrome', version: '80.0.3987.149' },
        os: { name: 'macOS', version: '10.14.5', versionName: 'Mojave' },
        platform: { type: 'desktop', vendor: 'Apple' },
        engine: { name: 'Blink' },
      },
      // the events that happened before the exception
      trail: [
        {
          id: 'id-button-2',
          class: 'class-button-2',
          tag: 'BUTTON',
          type: 'click',
          partialInnerText: 'Click to throw an error',
        },
      ],
    };

    Example

    See the example. To run it locally, clone this repo. Then:

    yarn && yarn start
    

    Inspiration

    This library is heavily influenced by most error reporting apps available in the market. My aim here is to provide a basic client-side error reporting API that can be used in any logging service you desire.

    License

    MIT

    Install

    npm i edogawa

    DownloadsWeekly Downloads

    19

    Version

    1.1.4

    License

    MIT

    Unpacked Size

    24.5 kB

    Total Files

    28

    Last publish

    Collaborators

    • undrafted