[core] Add optional initial value arguments to useNetworkStatus, useSaveData; useMemoryStatus (#23)

* Update useNetworkStatus to accept initialEffectiveConnectionType arg and consistently return unsupported property; add tests

* Update useHardwareConcurrency to consistently return unsupported property; add tests

* Update useMemoryStatus to accept initialMemoryStatus arg and consistently return unsupported property; add tests

* Update useSaveData to accept initialSaveDataStatus; add tests

* Update package.json with test coverage script

* Update readme with documentation for new hook arguments and use cases

* Update readme and network spec to address CR comments

Author: mlampedx

README.md

@@ -68,6 +68,14 @@ const MyComponent = () => {
 };
 ```
 
+This hook accepts an optional `initialEffectiveConnectionType` string argument, which can be used to provide a `effectiveConnectionType` state value when the user's browser does not support the relevant [NetworkInformation API](https://wicg.github.io/netinfo/). Passing an initial value can also prove useful for server-side rendering, where the developer can pass an [ECT Client Hint](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/client-hints#ect) to detect the effective network connection type.
+
+```js
+// Inside of a functional React component
+const initialEffectiveConnectionType = '4g';
+const { effectiveConnectionType } = useNetworkStatus(initialEffectiveConnectionType);
+```
+
 ### Save Data
 
 `useSaveData` utility for adapting based on the user's browser Data Saver preferences.
@@ -87,6 +95,14 @@ const MyComponent = () => {
 };
 ```
 
+This hook accepts an optional `initialSaveDataStatus` boolean argument, which can be used to provide a `saveData` state value when the user's browser does not support the relevant [NetworkInformation API](https://wicg.github.io/netinfo/). Passing an initial value can also prove useful for server-side rendering, where the developer can pass a server [Save-Data Client Hint](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/client-hints#save-data) that has been converted to a boolean to detect the user's data saving preference.
+
+```js
+// Inside of a functional React component
+const initialSaveDataStatus = true;
+const { saveData } = useSaveData(initialSaveDataStatus);
+```
+
 ### CPU Cores / Hardware Concurrency
 
 `useHardwareConcurrency` utility for adapting to the number of logical CPU processor cores on the user's device.
@@ -125,6 +141,14 @@ const MyComponent = () => {
 };
 ```
 
+This hook accepts an optional `initialMemoryStatus` object argument, which can be used to provide a `deviceMemory` state value when the user's browser does not support the relevant [DeviceMemory API](https://github.com/w3c/device-memory). Passing an initial value can also prove useful for server-side rendering, where the developer can pass a server [Device-Memory Client Hint](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/client-hints#save-data) to detect the memory capacity of the user's device.
+
+```js
+// Inside of a functional React component
+const initialMemoryStatus = { deviceMemory: 4 };
+const { deviceMemory } = useMemoryStatus(initialMemoryStatus);
+```
+
 ### Adaptive Code-loading & Code-splitting
 
 #### Code-loading

hardware-concurrency/hardware-concurrency.test.js

@@ -22,10 +22,33 @@ afterEach(function() {
 });
 
 describe('useHardwareConcurrency', () => {
+  const navigator = window.navigator;
+
+  afterEach(() => {
+    if (!window.navigator) window.navigator = navigator;
+  });
+
+  test(`should return "true" for unsupported case`, () => {
+    Object.defineProperty(window, 'navigator', {
+      value: undefined,
+      configurable: true,
+      writable: true
+    });
+
+    const { useHardwareConcurrency } = require('./');
+    const { result } = renderHook(() => useHardwareConcurrency());
+
+    expect(result.current.unsupported).toBe(true);
+  });
+
   test(`should return window.navigator.hardwareConcurrency`, () => {
     const { useHardwareConcurrency } = require('./');
     const { result } = renderHook(() => useHardwareConcurrency());
-    expect(result.current.numberOfLogicalProcessors).toBe(window.navigator.hardwareConcurrency);
+
+    expect(result.current.numberOfLogicalProcessors).toBe(
+      window.navigator.hardwareConcurrency
+    );
+    expect(result.current.unsupported).toBe(false);
   });
 
   test('should return 4 for device of hardwareConcurrency = 4', () => {
@@ -38,6 +61,7 @@ describe('useHardwareConcurrency', () => {
     const { result } = renderHook(() => useHardwareConcurrency());
 
     expect(result.current.numberOfLogicalProcessors).toEqual(4);
+    expect(result.current.unsupported).toBe(false);
   });
 
   test('should return 2 for device of hardwareConcurrency = 2', () => {
@@ -50,5 +74,6 @@ describe('useHardwareConcurrency', () => {
     const { result } = renderHook(() => useHardwareConcurrency());
 
     expect(result.current.numberOfLogicalProcessors).toEqual(2);
+    expect(result.current.unsupported).toBe(false);
   });
 });

hardware-concurrency/index.js

@@ -16,7 +16,10 @@
 
 let initialHardwareConcurrency;
 if (typeof navigator !== 'undefined' && 'hardwareConcurrency' in navigator) {
-  initialHardwareConcurrency = { numberOfLogicalProcessors: navigator.hardwareConcurrency };
+  initialHardwareConcurrency = {
+    unsupported: false,
+    numberOfLogicalProcessors: navigator.hardwareConcurrency
+  };
 } else {
   initialHardwareConcurrency = { unsupported: true };
 }

memory/index.js

@@ -20,21 +20,28 @@ if (typeof navigator !== 'undefined' && 'deviceMemory' in navigator) {
 } else {
   unsupported = true;
 }
-let initialMemoryStatus;
+let memoryStatus;
 if (!unsupported) {
   const performanceMemory = 'memory' in performance ? performance.memory : null;
-  initialMemoryStatus = {
+  memoryStatus = {
+    unsupported,
     deviceMemory: navigator.deviceMemory,
-    totalJSHeapSize: performanceMemory ? performanceMemory.totalJSHeapSize : null,
+    totalJSHeapSize: performanceMemory
+      ? performanceMemory.totalJSHeapSize
+      : null,
     usedJSHeapSize: performanceMemory ? performanceMemory.usedJSHeapSize : null,
-    jsHeapSizeLimit: performanceMemory ? performanceMemory.jsHeapSizeLimit : null
+    jsHeapSizeLimit: performanceMemory
+      ? performanceMemory.jsHeapSizeLimit
+      : null
   };
 } else {
-  initialMemoryStatus = { unsupported };
+  memoryStatus = { unsupported };
 }
 
-const useMemoryStatus = () => {
-  return { ...initialMemoryStatus };
+const useMemoryStatus = initialMemoryStatus => {
+  return unsupported && initialMemoryStatus
+    ? { ...memoryStatus, ...initialMemoryStatus }
+    : { ...memoryStatus };
 };
 
 export { useMemoryStatus };

memory/memory.test.js

@@ -22,6 +22,7 @@ afterEach(function() {
 });
 
 const getMemoryStatus = currentResult => ({
+  unsupported: false,
   deviceMemory: currentResult.deviceMemory,
   totalJSHeapSize: currentResult.totalJSHeapSize,
   usedJSHeapSize: currentResult.usedJSHeapSize,
@@ -36,6 +37,21 @@ describe('useMemoryStatus', () => {
     expect(result.current.unsupported).toBe(true);
   });
 
+  test('should return initialMemoryStatus for unsupported case', () => {
+    const mockInitialMemoryStatus = {
+      deviceMemory: 4
+    };
+    const { deviceMemory } = mockInitialMemoryStatus;
+
+    const { useMemoryStatus } = require('./');
+    const { result } = renderHook(() =>
+      useMemoryStatus(mockInitialMemoryStatus)
+    );
+
+    expect(result.current.unsupported).toBe(true);
+    expect(result.current.deviceMemory).toEqual(deviceMemory);
+  });
+
   test('should return mockMemory status', () => {
     const mockMemoryStatus = {
       deviceMemory: 4,
@@ -55,6 +71,54 @@ describe('useMemoryStatus', () => {
     const { useMemoryStatus } = require('./');
     const { result } = renderHook(() => useMemoryStatus());
 
-    expect(getMemoryStatus(result.current)).toEqual(mockMemoryStatus);
+    expect(getMemoryStatus(result.current)).toEqual({
+      ...mockMemoryStatus,
+      unsupported: false
+    });
+  });
+
+  test('should return mockMemory status without performance memory data', () => {
+    const mockMemoryStatus = {
+      deviceMemory: 4
+    };
+
+    global.navigator.deviceMemory = mockMemoryStatus.deviceMemory;
+    delete global.window.performance.memory;
+
+    const { useMemoryStatus } = require('./');
+    const { result } = renderHook(() => useMemoryStatus());
+
+    expect(result.current.deviceMemory).toEqual(mockMemoryStatus.deviceMemory);
+    expect(result.current.unsupported).toEqual(false);
+  });
+
+  test('should not return initialMemoryStatus for supported case', () => {
+    const mockMemoryStatus = {
+      deviceMemory: 4,
+      totalJSHeapSize: 60,
+      usedJSHeapSize: 40,
+      jsHeapSizeLimit: 50
+    };
+    const mockInitialMemoryStatus = {
+      deviceMemory: 4
+    };
+
+    global.navigator.deviceMemory = mockMemoryStatus.deviceMemory;
+
+    global.window.performance.memory = {
+      totalJSHeapSize: mockMemoryStatus.totalJSHeapSize,
+      usedJSHeapSize: mockMemoryStatus.usedJSHeapSize,
+      jsHeapSizeLimit: mockMemoryStatus.jsHeapSizeLimit
+    };
+
+    const { useMemoryStatus } = require('./');
+    const { result } = renderHook(() =>
+      useMemoryStatus(mockInitialMemoryStatus)
+    );
+
+    expect(getMemoryStatus(result.current)).toEqual({
+      ...mockMemoryStatus,
+      unsupported: false
+    });
   });
 });

network/index.js

@@ -18,26 +18,29 @@ import { useState, useEffect } from 'react';
 
 let unsupported;
 
-const useNetworkStatus = () => {
+const useNetworkStatus = initialEffectiveConnectionType => {
   if ('connection' in navigator && 'effectiveType' in navigator.connection) {
     unsupported = false;
   } else {
     unsupported = true;
   }
 
-  const initialNetworkStatus = !unsupported ? {
-    effectiveConnectionType: navigator.connection.effectiveType
-  } : {
-      unsupported
-    };
+  const initialNetworkStatus = {
+    unsupported,
+    effectiveConnectionType: unsupported
+      ? initialEffectiveConnectionType
+      : navigator.connection.effectiveType
+  };
 
   const [networkStatus, setNetworkStatus] = useState(initialNetworkStatus);
 
   useEffect(() => {
     if (!unsupported) {
       const navigatorConnection = navigator.connection;
       const updateECTStatus = () => {
-        setNetworkStatus({ effectiveConnectionType: navigatorConnection.effectiveType });
+        setNetworkStatus({
+          effectiveConnectionType: navigatorConnection.effectiveType
+        });
       };
       navigatorConnection.addEventListener('change', updateECTStatus);
       return () => {

network/network.test.js

@@ -19,34 +19,91 @@ import { renderHook, act } from '@testing-library/react-hooks';
 import { useNetworkStatus } from './';
 
 describe('useNetworkStatus', () => {
+  const map = {};
+
+  const ectStatusListeners = {
+    addEventListener: jest.fn().mockImplementation((event, callback) => {
+      map[event] = callback;
+    }),
+    removeEventListener: jest.fn()
+  };
+
+  afterEach(() => {
+    Object.values(ectStatusListeners).forEach(listener => listener.mockClear());
+  });
+
+  /**
+   * Tests that addEventListener or removeEventListener was called during the
+   * lifecycle of the useEffect hook within useNetworkStatus
+   */
+  const testEctStatusEventListenerMethod = method => {
+    expect(method).toBeCalledTimes(1);
+    expect(method.mock.calls[0][0]).toEqual('change');
+    expect(method.mock.calls[0][1].constructor).toEqual(Function);
+  };
+
+  test(`should return "true" for unsupported case`, () => {
+    const { result } = renderHook(() => useNetworkStatus());
+
+    expect(result.current.unsupported).toBe(true);
+  });
+
+  test('should return initialEffectiveConnectionType for unsupported case', () => {
+    const initialEffectiveConnectionType = '4g';
+
+    const { result } = renderHook(() =>
+      useNetworkStatus(initialEffectiveConnectionType)
+    );
+
+    expect(result.current.unsupported).toBe(true);
+    expect(result.current.effectiveConnectionType).toBe(
+      initialEffectiveConnectionType
+    );
+  });
+
   test('should return 4g of effectiveConnectionType', () => {
     global.navigator.connection = {
-      effectiveType: '4g',
-      addEventListener: jest.fn(),
-      removeEventListener: jest.fn()
+      ...ectStatusListeners,
+      effectiveType: '4g'
     };
 
     const { result } = renderHook(() => useNetworkStatus());
-    
+
+    testEctStatusEventListenerMethod(ectStatusListeners.addEventListener);
+    expect(result.current.unsupported).toBe(false);
+    expect(result.current.effectiveConnectionType).toEqual('4g');
+  });
+
+  test('should not return initialEffectiveConnectionType for supported case', () => {
+    const initialEffectiveConnectionType = '2g';
+    global.navigator.connection = {
+      ...ectStatusListeners,
+      effectiveType: '4g'
+    };
+
+    const { result } = renderHook(() =>
+      useNetworkStatus(initialEffectiveConnectionType)
+    );
+
+    testEctStatusEventListenerMethod(ectStatusListeners.addEventListener);
+    expect(result.current.unsupported).toBe(false);
     expect(result.current.effectiveConnectionType).toEqual('4g');
   });
 
   test('should update the effectiveConnectionType state', () => {
     const { result } = renderHook(() => useNetworkStatus());
 
-    act(() => result.current.setNetworkStatus({effectiveConnectionType: '2g'}));
-  
+    act(() =>
+      result.current.setNetworkStatus({ effectiveConnectionType: '2g' })
+    );
+
     expect(result.current.effectiveConnectionType).toEqual('2g');
   });
 
   test('should update the effectiveConnectionType state when navigator.connection change event', () => {
-    const map = {};
     global.navigator.connection = {
-      effectiveType: '2g',
-      addEventListener: jest.fn().mockImplementation((event, callback) => {
-        map[event] = callback;
-      }),
-      removeEventListener: jest.fn()
+      ...ectStatusListeners,
+      effectiveType: '2g'
     };
 
     const { result } = renderHook(() => useNetworkStatus());
@@ -55,4 +112,17 @@ describe('useNetworkStatus', () => {
 
     expect(result.current.effectiveConnectionType).toEqual('4g');
   });
+
+  test('should remove the listener for the navigator.connection change event on unmount', () => {
+    global.navigator.connection = {
+      ...ectStatusListeners,
+      effectiveType: '2g'
+    };
+
+    const { unmount } = renderHook(() => useNetworkStatus());
+
+    testEctStatusEventListenerMethod(ectStatusListeners.addEventListener);
+    unmount();
+    testEctStatusEventListenerMethod(ectStatusListeners.removeEventListener);
+  });
 });