#101 Implement network information utilities

Add network information utils

Author: brandongregoryscott

.editorconfig

@@ -8,5 +8,8 @@ charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 
+[*.ts]
+indent_size = 4
+
 [*.md]
 trim_trailing_whitespace = false

src/enumerations/connection-type.ts

@@ -0,0 +1,17 @@
+/**
+ * ConnectionType - Network Information API
+ * - W3C Draft Community Group Report 11 May 2020
+ * - https://wicg.github.io/netinfo/#connectiontype-enum
+ */
+enum ConnectionType {
+    Bluetooth = "bluetooth",
+    Cellular = "cellular",
+    Ethernet = "ethernet",
+    None = "none",
+    Other = "other",
+    Unknown = "unknown",
+    Wifi = "wifi",
+    Wimax = "wimax",
+}
+
+export { ConnectionType };

src/enumerations/effective-connection-type.ts

@@ -0,0 +1,13 @@
+/**
+ * EffectiveConnectionType - Network Information API
+ * - Draft Community Group Report 11 May 2020
+ * - https://wicg.github.io/netinfo/#effectiveconnectiontype-enum
+ */
+enum EffectiveConnectionType {
+    Cellular2g = "2g",
+    Cellular3g = "3g",
+    Cellular4g = "4g",
+    Slow2g = "slow-2g",
+}
+
+export { EffectiveConnectionType };

src/enumerations/navigator-connection-variant.ts

@@ -0,0 +1,5 @@
+export enum NavigatorConnectionVariant {
+    Standard = "connection",
+    Mozilla = "mozConnection",
+    Webkit = "webkitConnection",
+}

src/index.ts

@@ -22,7 +22,9 @@ export { BaseSpanishSpain } from "./cultures/base-spanish-spain";
 // -----------------------------------------------------------------------------------------
 
 export { AnchorTargetTypes } from "./enumerations/anchor-target-types";
+export { ConnectionType } from "./enumerations/connection-type";
 export { ContentType } from "./enumerations/content-type";
+export { EffectiveConnectionType } from "./enumerations/effective-connection-type";
 export { ErrorType } from "./enumerations/error-type";
 export { HttpHeader } from "./enumerations/http-header";
 export { HttpVerb } from "./enumerations/http-verb";
@@ -40,6 +42,7 @@ export { CultureParams } from "./interfaces/culture-params";
 export { Entity } from "./interfaces/entity";
 export { KeyValuePair } from "./interfaces/key-value-pair";
 export { LocalizationInitOptions } from "./interfaces/localization-init-options";
+export { NetworkConnection } from "./interfaces/network-connection";
 export { PagedQuery } from "./interfaces/paged-query";
 export { PagedResult } from "./interfaces/paged-result";
 export { Result } from "./interfaces/result";
@@ -76,6 +79,7 @@ export { Do } from "./utilities/do-try";
 export { DoSync } from "./utilities/do-try";
 export { EnvironmentUtils } from "./utilities/environment-utils";
 export { LocalizationUtils } from "./utilities/localization-utils";
+export { NetworkInformationUtils } from "./utilities/network-information-utils";
 export { PolyfillUtils } from "./utilities/polyfill-utils";
 export { PromiseFactory } from "./utilities/promise-factory";
 export { RecordUtils } from "./utilities/record-utils";

src/interfaces/network-connection.ts

@@ -0,0 +1,22 @@
+import { NetworkInformation } from "./network-information";
+
+// -----------------------------------------------------------------------------------------
+// #region Interfaces
+// -----------------------------------------------------------------------------------------
+
+interface NetworkConnection extends NetworkInformation {
+    /**
+     * Returns a true or false indicating whether the browser is working online.
+     */
+    isOnline: boolean;
+}
+
+// #endregion Interfaces
+
+// -----------------------------------------------------------------------------------------
+// #region Export
+// -----------------------------------------------------------------------------------------
+
+export { NetworkConnection };
+
+// #endregion Export

src/interfaces/network-information.ts

@@ -0,0 +1,55 @@
+import { ConnectionType } from "../enumerations/connection-type";
+import { EffectiveConnectionType } from "../enumerations/effective-connection-type";
+
+// -----------------------------------------------------------------------------------------
+// #region Interfaces
+// -----------------------------------------------------------------------------------------
+
+/**
+ * NetworkInformation - Network Information API
+ * - Draft Community Group Report 11 May 2020
+ * - https://wicg.github.io/netinfo/#networkinformation-interface
+ */
+interface NetworkInformation extends Partial<EventTarget> {
+    /**
+     * Returns the effective bandwidth estimate in megabits per second, rounded to the nearest multiple of 25 kilobits per seconds.
+     */
+    downlink?: number;
+
+    /**
+     * Returns the maximum downlink speed, in megabits per second (Mbps), for the underlying connection technology.
+     */
+    downlinkMax?: number;
+
+    /**
+     * Returns the effective type of the connection meaning one of 'slow-2g', '2g', '3g', or '4g'.
+     * This value is determined using a combination of recently observed round-trip time and downlink values.
+     */
+    effectiveType?: EffectiveConnectionType;
+
+    /**
+     * Returns the estimated effective round-trip time of the current connection, rounded to the
+     * nearest multiple of 25 milliseconds.
+     */
+    rtt?: number;
+
+    /**
+     * Returns true if the user has set a reduced data usage option on the user agent.
+     */
+    saveData?: boolean;
+
+    /**
+     * Returns the type of connection a device is using to communicate with the network
+     */
+    type?: ConnectionType;
+}
+
+// #endregion Interfaces
+
+// -----------------------------------------------------------------------------------------
+// #region Export
+// -----------------------------------------------------------------------------------------
+
+export { NetworkInformation };
+
+// #endregion Export

src/types/navigator.ts

@@ -0,0 +1,9 @@
+import { NavigatorConnectionVariant } from "../enumerations/navigator-connection-variant";
+import { NetworkInformation } from "../interfaces/network-information";
+
+export declare interface Navigator {
+    [NavigatorConnectionVariant.Standard]?: NetworkInformation;
+    [NavigatorConnectionVariant.Mozilla]?: NetworkInformation;
+    [NavigatorConnectionVariant.Webkit]?: NetworkInformation;
+    onLine: boolean;
+}

src/types/window.ts

@@ -0,0 +1,5 @@
+import { Navigator } from "../types/navigator";
+
+export declare interface Window {
+    navigator: Navigator;
+}

src/utilities/network-information-utils.test.ts

@@ -0,0 +1,119 @@
+import { NavigatorConnectionVariant } from "../enumerations/navigator-connection-variant";
+import buildNetworkInformationUtils, {
+    NetworkInformationUtils,
+} from "./network-information-utils";
+
+const setupSut = (options?: {
+    connectionProperty?: string;
+    onLine?: boolean;
+}): typeof NetworkInformationUtils => {
+    const { connectionProperty, onLine = false } = options ?? {};
+
+    const buildMockNavigator = (): Navigator => {
+        const isOnline = onLine ?? navigator.onLine;
+
+        if (connectionProperty != null) {
+            return {
+                ...navigator,
+                onLine: isOnline,
+                [connectionProperty]: {},
+            };
+        }
+
+        return { ...navigator, onLine: isOnline };
+    };
+
+    const navigator = buildMockNavigator();
+
+    return buildNetworkInformationUtils(navigator);
+};
+
+describe("NetworkInformationUtils", () => {
+    // -----------------------------------------------------------------------------------------
+    // #region getNavigatorConnection
+    // -----------------------------------------------------------------------------------------
+
+    describe("getNavigatorConnection()", () => {
+        test.each`
+            connectionProperty
+            ${NavigatorConnectionVariant.Standard}
+            ${NavigatorConnectionVariant.Mozilla}
+            ${NavigatorConnectionVariant.Webkit}
+        `(
+            "when window.navigator has $connectionProperty, it returns connection",
+            ({ connectionProperty }) => {
+                // Arrange
+                const sut = setupSut({ connectionProperty });
+
+                // Act
+                const navigatorConnection = sut.getNavigatorConnection();
+
+                // Assert
+                expect(navigatorConnection).not.toBeUndefined();
+            }
+        );
+
+        test("when window.navigator does not have a known connection property, it returns undefined", () => {
+            // Arrange
+            const sut = setupSut();
+
+            // Act
+            const connection = sut.getNavigatorConnection();
+
+            // Assert
+            expect(connection).toBeUndefined();
+        });
+    });
+
+    // #endregion getNavigatorConnection
+
+    // -----------------------------------------------------------------------------------------
+    // #region getNetworkConnection
+    // -----------------------------------------------------------------------------------------
+
+    describe("getNetworkConnection()", () => {
+        test("when navigator has no connection, it returns a value", () => {
+            // Arrange
+            const sut = setupSut();
+
+            // Act
+            const networkConnection = sut.getNetworkConnection();
+
+            // Assert
+            expect(networkConnection).toBeDefined();
+        });
+
+        test("when navigator has a connection, it returns a value", () => {
+            // Arrange
+            const sut = setupSut({
+                connectionProperty: NavigatorConnectionVariant.Standard,
+            });
+
+            // Act
+            const networkConnection = sut.getNetworkConnection();
+
+            // Assert
+            expect(networkConnection).toBeDefined();
+        });
+
+        test.each`
+            onLine
+            ${false}
+            ${true}
+        `(
+            "when window.navigator onLine is $onLine, isOnline is $onLine",
+            ({ onLine }) => {
+                // Arrange
+                const sut = setupSut({ onLine });
+
+                // Act
+                const networkConnection = sut.getNetworkConnection();
+
+                // Assert
+                expect(networkConnection.isOnline).toEqual(onLine);
+            }
+        );
+    });
+
+    // #endregion getNetworkConnection
+});