❀Noisy Pterodactyl Melodies

    rxjs-debug-operator
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0Β β€’Β PublicΒ β€’Β Published

    RxJS Debug Operator πŸ›



    We've all had occasions where we've felt the need to simply pipe a tap(console.log) to our Observables to get some insight into what is occuring at a certain time.

    This operator aims to reduce the amount of typing you'll have to do!

    Usage

    Installation

    Install the package:
    npm install rxjs-debug-operator

    Adding it to your code

    It's super simple to add and use:

    Use your prefered import method:

    import { debug } from 'rxjs-debug-operator';
    // OR
    const { debug } = require('rxjs-debug-operator');

    Then pipe it to your Observables:

    const obs$ = source.pipe(debug());

    You can add a label to help identify the Observable:

    const obs$ = source.pipe(debug('My Observable'));
    // OUTPUT
    // My Observable    {value}

    It even allows you to turn it off if you are in a production environment, or for any other reason you wouldn't want to log to the console:

    const obs$ = source.pipe(debug({ shouldIgnore: true }));

    Examples

    We can use it on its own to simply log out values to the console

    const obs$ = of('my test value');
    obs$.pipe(debug()).subscribe();
    
    // OUTPUT:
    // my test value

    We can add a label to the logs:

    const obs$ = of('my test value');
    obs$.pipe(debug('Obserable A')).subscribe();
    
    // OUTPUT:
    // Obserable A    my test value
    
    // We can label it using the config object syntax:
    const obs$ = of('my test value');
    obs$.pipe(debug({ label: 'Obserable A' })).subscribe();
    
    // OUTPUT:
    // Obserable A    my test value
    
    // However, if we add a label and custom notification handlers,
    // we will not get the label in the logs by default:
    const obs$ = of('my test value');
    obs$
      .pipe(
        debug({
          label: 'Obserable A',
          next: (value) => console.log(value),
        })
      )
      .subscribe();
    
    // OUTPUT:
    // my test value

    We can also set up our own notification handlers if we prefer:

    const obs$ = of('my test value');
    obs$
      .pipe(debug({ next: (value) => console.log('my custom handler:', value) }))
      .subscribe();
    
    // OUTPUT:
    // my custom handler:   my test value
    
    const obs$ = throwError('uh oh');
    obs$
      .pipe(debug({ error: (value) => console.log('my error handler:', value) }))
      .subscribe();
    
    // OUTPUT:
    // my error handler:   uh oh
    
    const obs$ = of('my test value');
    obs$
      .pipe(debug({ complete: (value) => console.log('I completed') }))
      .subscribe();
    
    // OUTPUT:
    // I completed

    We can access the default logger for more flexibility:

    const obs$ = of('my test value');
    
    obs$
      .pipe(
        debug((logger) => ({
          next: (v) => logger.warn('Warning!', v),
        }))
      )
      .subscribe();
    
    // OUTPUT
    // WARN: Warning!   my test value

    Setting Global Config

    You can set some globals that make it more convenient to change:

    • the default logger
    • a global prefix to be appended to all logs
    • a global-level ignore flag

    Change the Default Logger

    You can change the default logger by creating an object that matches the DebugLogger interface, which can be seen below:

    export interface DebugLogger {
      log: (...args: unknown[]) => void;
      error: (...args: unknown[]) => void;
      warn?: (...args: unknown[]) => void;
      debug?: (...args: unknown[]) => void;
      info?: (...args: unknown[]) => void;
    }

    Once you have created your new logger, you can set it to be used as the default logger using setGlobalDebugConfig()

    setGlobalDebugConfig({
      logger: myNewLogger,
    });

    Now all your debug() operators will use your new logger to log the values it receives.

    Adding a Global Prefix

    You can also add a string prefix to all your logs at a global level, which can be useful to help identify logs.

    setGlobalDebugConfig({
      prefix: 'My Prefix',
    });

    Setting whether to ignore logging

    You can also set whether all debug() should not log at the global level. This can be useful for turning it off in production environments.

    setGlobalDebugConfig({
      shouldIgnore: isProduction,
    });

    Example Winston Usage

    import { DebugLogger, setGlobalDebugConfig } from 'rxjs-debug-operator';
    const winston = require('winston');
    
    const sysLogger = winston.createLogger({
      level: 'info',
      format: winston.format.json(),
      transports: [
        //
        // - Write all logs with level `error` and below to `error.log`
        // - Write all logs with level `info` and below to `combined.log`
        //
        new winston.transports.File({ filename: 'error.log', level: 'error' }),
        new winston.transports.File({ filename: 'combined.log' }),
      ],
    });
    
    const debugLogger: DebugLogger = {
      log: (v) => sysLogger.info(v),
      error: (e) => sysLogger.error(e),
    };
    
    setGlobalDebugConfig({ logger: debugLogger });
    
    const obs$ = of('my test value');
    obs$.pipe(debug()).subscribe();
    
    // OUTPUT
    // 'my test value' written to `combined.log`

    NOTES

    It should be noted that local config options passed to the debug() operator will take precedence over any global values

    API

    Debug

    debug(config?: Partial<DebugOperatorConfig>)

    DebugOperatorConfig

    See the list of options available to configure the operator below

    Option Description Type Default
    shouldIgnore Do not perform the Debug actions boolean false
    label Add a label to the logs to help identify the Observable string null
    next Action to perform when Observer receives a Next notification (value: T) => void console.log
    error Action to perform when Observer receives an Error notification (value: unknown) => void console.error
    complete Action to perform when Observer receives a Completion notification () => void () => null

    Global Debug Config

    setGlobalDebugConfig(config: Partial<GlobalDebugConfig>)

    GlobalDebugConfig

    Option Description Type Default
    shouldIgnore Do not perform the Debug actions boolean false
    prefix Add a label to the logs to help identify the Observable string null
    logger Logger to use to log values recieved by debug() DebugLogger console

    DebugLogger

    Option Description Type Default
    log Basic log (...args: unknown[]) => void console.log
    error Error log (...args: unknown[]) => void console.error
    info? Info log (...args: unknown[]) => void console.info
    warn? Warn log (...args: unknown[]) => void console.warn
    debug? Debug log (...args: unknown[]) => void console.debug

    Keywords

    Install

    npm i rxjs-debug-operator

    DownloadsWeekly Downloads

    42

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    16.1 kB

    Total Files

    17

    Last publish

    Collaborators

    • coly010