feat(interruptsource): allow interrupts to use an ssr option

README.md

@@ -94,6 +94,49 @@ For example, consider an email application. For increased security, the applicat
 
 `@ng-idle/core` can detect that the user is clicking, typing, touching, scrolling, etc. and know that the user is still active. It can work with `@ng-idle/keepalive` to ping the server every few minutes to keep them logged in. In this case, as long as the user is doing something, they stay logged in. If they step away from the computer, we can present a warning dialog, and then after a countdown, log them out.
 
+## Server-Side Rendering/Universal
+
+@ng-idle/core uses DOM events on various targets to detect user activity. However, when using SSR/Universal Rendering the app is not always running in the browser and thus may not have access to these DOM targets, causing your app to potentially crash or throw errors as it tries to use browser globals like `document` and `window` through @ng-idle.
+
+`EventTargetInterruptSource` and all the interrupt sources that derive from it (such as `DocumentInterruptSource`, `WindowInterruptSource`, and `StorageInterruptSource`) can receive an option when they are created called `ssr`. It will be your app's responsibility to detect whether your app is running in the browser or on the server by using [`isPlatformServer`](https://angular.io/api/common/isPlatformServer) (or inverting [`isPlatformBrowser`](https://angular.io/api/common/isPlatformBrowser), if you'd prefer) when creating your interrupt sources.
+
+```
+import { Component, PLATFORM_ID, Inject } from '@angular/core';
+import { isPlatformBrowser, isPlatformServer } from '@angular/common';
+
+import { Idle, DocumentInterruptSource, createDefaultInterruptSources } from '@ng-idle/core';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './postfeed.component.html',
+  styleUrls: ['./postfeed.component.css']
+})
+export class AppComponent implements OnInit {
+
+  constructor(@Inject(PLATFORM_ID) private platform: Object, private idle: Idle) { }
+
+  ngOnInit() {
+    // configure idle normally
+    this.idle.setIdle(60 * 10);
+
+    // create your interrupts. DO NOT use DEFAULT_INTERRUPTSOURCES for ssr/univeral apps!
+    const myInterrupts = new DocumentInterruptSource('mousedown', { ssr: isPlatformServer(platform) });
+    // OR, you can use createDefaultInterruptSources and pass in the ssr option
+    // const myInterrupts = createDefaultInterruptSources({ ssr: isPlatformServer(platform) });
+
+    // now set the interrupt sources
+    this.idle.setInterrupts(myInterrupts);
+
+    if (isPlatformBrowser(this.platform)) {
+      // only need to start watching if we're in the browser
+      this.idle.watch()
+    }
+  }
+}
+```
+
+**Note** `DEFAULT_INTERRUPTSOURCES` should NOT be used by ssr/universal apps. The value of this constant is equivalent to `createDefaultInterruptSources({ssr: false})` and thus will not work in your SSR app. You _may_ continue to use DEFAULT_INTERRUPTSOURCES` if you are **not** using SSR/universal rendering.
+
 ## Developing
 
 This project was developed using the NodeJS version found in the `.nvmrc` file. You may experience problems using older versions. Try [NVM](https://github.com/creationix/nvm) or similar to manage different versions of Node concurrently. If using NVM, you can execute `nvm install` to download and switch to the correct version.

projects/core/src/lib/defaultinterruptsources.ts

@@ -10,8 +10,8 @@ export function createDefaultInterruptSources(
       'mousemove keydown DOMMouseScroll mousewheel mousedown touchstart touchmove scroll',
       options
     ),
-    new StorageInterruptSource()
+    new StorageInterruptSource(options)
   ];
 }
 
-export const DEFAULT_INTERRUPTSOURCES: any[] = createDefaultInterruptSources();
+export const DEFAULT_INTERRUPTSOURCES = createDefaultInterruptSources();

projects/core/src/lib/documentinterruptsource.spec.ts

@@ -16,6 +16,19 @@ describe('core/DocumentInterruptSource', () => {
     source.detach();
   }));
 
+  it('does not emit events when ssr option is true', fakeAsync(() => {
+    const source = new DocumentInterruptSource('click', { ssr: true });
+    spyOn(source.onInterrupt, 'emit').and.callThrough();
+    source.attach();
+
+    const expected = new Event('click');
+    document.documentElement.dispatchEvent(expected);
+
+    expect(source.onInterrupt.emit).not.toHaveBeenCalled();
+
+    source.detach();
+  }));
+
   it('does not emit onInterrupt event when detached and event is fired', fakeAsync(() => {
     const source = new DocumentInterruptSource('click');
     spyOn(source.onInterrupt, 'emit').and.callThrough();

projects/core/src/lib/documentinterruptsource.ts

@@ -1,3 +1,6 @@
+import { Inject, PLATFORM_ID } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+
 import {
   EventTargetInterruptOptions,
   EventTargetInterruptSource
@@ -8,7 +11,13 @@ import {
  */
 export class DocumentInterruptSource extends EventTargetInterruptSource {
   constructor(events: string, options?: number | EventTargetInterruptOptions) {
-    super(document.documentElement, events, options);
+    const target =
+      options && (options as EventTargetInterruptOptions).ssr
+        ? null
+        : document.documentElement;
+
+    options = !options || typeof options === 'number' ? {} : options;
+    super(target, events, options);
   }
 
   /*

projects/core/src/lib/eventtargetinterruptsource.spec.ts

@@ -43,6 +43,36 @@ describe('core/EventTargetInterruptSource', () => {
     expect(source.onInterrupt.emit).not.toHaveBeenCalled();
   }));
 
+  it('does not emit onInterrupt event when ssr is true', fakeAsync(() => {
+    const source = new EventTargetInterruptSource(document.body, 'click', {
+      ssr: true
+    });
+    spyOn(source.onInterrupt, 'emit').and.callThrough();
+
+    source.attach();
+
+    const expected = new Event('click');
+    document.body.dispatchEvent(expected);
+
+    expect(source.onInterrupt.emit).not.toHaveBeenCalled();
+
+    source.detach();
+  }));
+
+  it('does not emit onInterrupt event when target is null', fakeAsync(() => {
+    const source = new EventTargetInterruptSource(null, 'click');
+    spyOn(source.onInterrupt, 'emit').and.callThrough();
+
+    source.attach();
+
+    const expected = new Event('click');
+    document.body.dispatchEvent(expected);
+
+    expect(source.onInterrupt.emit).not.toHaveBeenCalled();
+
+    source.detach();
+  }));
+
   it('should throttle target events using the specified throttleDelay value', fakeAsync(() => {
     const source = new EventTargetInterruptSource(document.body, 'click', 500);
     spyOn(source.onInterrupt, 'emit').and.callThrough();
@@ -97,43 +127,48 @@ describe('core/EventTargetInterruptSource', () => {
   it('should set default options', () => {
     const target = {};
     const source = new EventTargetInterruptSource(target, 'click');
-    const { throttleDelay, passive } = source.options;
+    const { throttleDelay, passive, ssr } = source.options;
 
     expect(passive).toBeFalsy();
     expect(throttleDelay).toBe(500);
+    expect(ssr).toBeFalsy();
   });
 
   it('should set passive flag', () => {
     const target = {};
     const source = new EventTargetInterruptSource(target, 'click', {
       passive: true
     });
-    const { throttleDelay, passive } = source.options;
+    const { throttleDelay, passive, ssr: isBrowser } = source.options;
 
     expect(passive).toBeTruthy();
     expect(throttleDelay).toBe(500);
+    expect(isBrowser).toBeFalsy();
   });
 
   it('should set throttleDelay', () => {
     const target = {};
     const source = new EventTargetInterruptSource(target, 'click', {
       throttleDelay: 1000
     });
-    const { throttleDelay, passive } = source.options;
+    const { throttleDelay, passive, ssr } = source.options;
 
     expect(passive).toBeFalsy();
     expect(throttleDelay).toBe(1000);
+    expect(ssr).toBeFalsy();
   });
 
-  it('should set both options', () => {
+  it('should set all options', () => {
     const target = {};
     const source = new EventTargetInterruptSource(target, 'click', {
-      throttleDelay: 1000,
-      passive: true
+      passive: true,
+      ssr: true,
+      throttleDelay: 1000
     });
-    const { throttleDelay, passive } = source.options;
+    const { throttleDelay, passive, ssr } = source.options;
 
     expect(passive).toBeTruthy();
     expect(throttleDelay).toBe(1000);
+    expect(ssr).toBeTruthy();
   });
 });

projects/core/src/lib/eventtargetinterruptsource.ts

@@ -18,6 +18,12 @@ export interface EventTargetInterruptOptions {
    * Note: you need to detect if the browser supports passive listeners, and only set this to true if it does.
    */
   passive?: boolean;
+
+  /**
+   * Whether or not the app is running on the server side or non-browser context where access
+   * to browser globals and user input is not possible.
+   */
+  ssr?: boolean;
 }
 
 const defaultThrottleDelay = 500;
@@ -30,6 +36,7 @@ export class EventTargetInterruptSource extends InterruptSource {
   private eventSubscription: Subscription = new Subscription();
   protected throttleDelay: number;
   protected passive: boolean;
+  protected ssr: boolean;
 
   constructor(
     protected target: any,
@@ -39,12 +46,13 @@ export class EventTargetInterruptSource extends InterruptSource {
     super(null, null);
 
     if (typeof options === 'number') {
-      options = { throttleDelay: options, passive: false };
+      options = { throttleDelay: options, passive: false, ssr: false };
     }
 
     options = options || {
-      throttleDelay: defaultThrottleDelay,
-      passive: false
+      passive: false,
+      ssr: false,
+      throttleDelay: defaultThrottleDelay
     };
 
     if (options.throttleDelay === undefined || options.throttleDelay === null) {
@@ -53,6 +61,11 @@ export class EventTargetInterruptSource extends InterruptSource {
 
     this.throttleDelay = options.throttleDelay;
     this.passive = !!options.passive;
+    this.ssr = !!options.ssr;
+
+    if (this.ssr || !target) {
+      return;
+    }
 
     const opts = this.passive ? { passive: true } : null;
     const fromEvents = events
@@ -89,6 +102,10 @@ export class EventTargetInterruptSource extends InterruptSource {
    * @return The current option values.
    */
   get options(): EventTargetInterruptOptions {
-    return { throttleDelay: this.throttleDelay, passive: this.passive };
+    return {
+      passive: this.passive,
+      ssr: this.ssr,
+      throttleDelay: this.throttleDelay
+    };
   }
 }

projects/core/src/lib/storageinterruptsource.spec.ts

@@ -57,4 +57,18 @@ describe('core/StorageInterruptSource', () => {
 
     source.detach();
   }));
+
+  it('does not emit onInterrupt event when ssr is true', fakeAsync(() => {
+    const source = new StorageInterruptSource({ ssr: true });
+    spyOn(source.onInterrupt, 'emit').and.callThrough();
+
+    source.attach();
+
+    const expected = new StorageEvent('storage');
+    window.dispatchEvent(expected);
+
+    expect(source.onInterrupt.emit).not.toHaveBeenCalled();
+
+    source.detach();
+  }));
 });

projects/core/src/lib/storageinterruptsource.ts

@@ -1,11 +1,12 @@
 import { WindowInterruptSource } from './windowinterruptsource';
+import { EventTargetInterruptOptions } from './eventtargetinterruptsource';
 
 /*
  * An interrupt source on the storage event of Window.
  */
 export class StorageInterruptSource extends WindowInterruptSource {
-  constructor(throttleDelay = 500) {
-    super('storage', throttleDelay);
+  constructor(options: number | EventTargetInterruptOptions = 500) {
+    super('storage', options);
   }
 
   /*

projects/core/src/lib/windowinterruptsource.spec.ts

@@ -29,4 +29,18 @@ describe('core/WindowInterruptSource', () => {
 
     expect(source.onInterrupt.emit).not.toHaveBeenCalled();
   }));
+
+  it('does not emit onInterrupt event when ssr is true', fakeAsync(() => {
+    const source = new WindowInterruptSource('focus', { ssr: true });
+    spyOn(source.onInterrupt, 'emit').and.callThrough();
+
+    source.attach();
+
+    const expected = new Event('focus');
+    window.dispatchEvent(expected);
+
+    expect(source.onInterrupt.emit).not.toHaveBeenCalled();
+
+    source.detach();
+  }));
 });

projects/core/src/lib/windowinterruptsource.ts

@@ -8,6 +8,9 @@ import {
  */
 export class WindowInterruptSource extends EventTargetInterruptSource {
   constructor(events: string, options?: number | EventTargetInterruptOptions) {
-    super(window, events, options);
+    const target =
+      options && (options as EventTargetInterruptOptions).ssr ? null : window;
+
+    super(target, events, options);
   }
 }