@dhis2/app-service-offline 3.17.0 → 3.17.2

package/src/lib/network-status.ts

@@ -0,0 +1,80 @@
+import debounce from 'lodash/debounce'
+import { useState, useEffect, useCallback, useMemo } from 'react'
+
+type milliseconds = number
+interface NetworkStatusOptions {
+    debounceDelay?: milliseconds
+}
+
+export interface NetworkStatus {
+    online: boolean
+    offline: boolean
+    lastOnline: Date | null
+}
+
+const lastOnlineKey = 'dhis2.lastOnline'
+
+// TODO: Add option to periodically ping server to check online status.
+// TODO: Add logic to return a variable indicating unstable connection.
+
+/**
+ * Returns the browser's online status. Updates in response to 'online' and
+ * 'offline' events. By default, debounces updates to once every second to
+ * avoid UI flicker, but that delay can be configured with the
+ * `options.debounceDelay` param.
+ *
+ * On state change, updates the `dhis2.lastOnline` property in local storage
+ * for consuming apps to format and display. Returns `lastOnline` as `null` if
+ * online or as a Date if offline.
+ *
+ * @param {Object} [options]
+ * @param {Number} [options.debounceDelay] - Timeout delay to debounce updates, in ms
+ * @returns {Object} `{ online: boolean, offline: boolean, lastOnline: Date | null }`
+ */
+export function useNetworkStatus(
+    options: NetworkStatusOptions = {}
+): NetworkStatus {
+    // initialize state to `navigator.onLine` value
+    const [online, setOnline] = useState(navigator.onLine)
+
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const updateState = useCallback(
+        debounce(({ type }: Event) => {
+            if (type === 'online') {
+                setOnline(true)
+            } else if (type === 'offline') {
+                if (online || !localStorage.getItem(lastOnlineKey)) {
+                    localStorage.setItem(
+                        lastOnlineKey,
+                        new Date(Date.now()).toUTCString()
+                    )
+                }
+                setOnline(false)
+            }
+        }, options.debounceDelay ?? 1000),
+        [options.debounceDelay]
+    )
+
+    // on 'online' or 'offline' events, set state
+    useEffect(() => {
+        window.addEventListener('online', updateState)
+        window.addEventListener('offline', updateState)
+        return () => {
+            updateState.flush()
+            window.removeEventListener('online', updateState)
+            window.removeEventListener('offline', updateState)
+        }
+    }, [updateState])
+
+    // Only fetch if `online === false` as local storage is synchronous and disk-based
+    const lastOnline = useMemo(
+        () => !online && localStorage.getItem(lastOnlineKey),
+        [online]
+    )
+
+    return {
+        online,
+        offline: !online,
+        lastOnline: lastOnline ? new Date(lastOnline) : null,
+    }
+}

package/src/lib/offline-interface.tsx

@@ -0,0 +1,57 @@
+import PropTypes from 'prop-types'
+import React, { createContext, useContext } from 'react'
+import { OfflineInterface } from '../types'
+
+// This is to prevent 'offlineInterface could be null' type-checking errors
+const noopOfflineInterface: OfflineInterface = {
+    pwaEnabled: false,
+    latestIsConnected: false,
+    subscribeToDhis2ConnectionStatus: () => () => undefined,
+    startRecording: async () => undefined,
+    getCachedSections: async () => [],
+    removeSection: async () => false,
+}
+
+const OfflineInterfaceContext =
+    createContext<OfflineInterface>(noopOfflineInterface)
+
+interface OfflineInterfaceProviderInput {
+    offlineInterface: OfflineInterface
+    children: React.ReactNode
+}
+
+/**
+ * Receives an OfflineInterface instance as a prop (presumably from the app
+ * adapter) and provides it as context for other offline tools.
+ *
+ * On mount, it initializes the offline interface, which (among other things)
+ * checks for service worker updates and, if updates are ready, prompts the
+ * user with an alert to skip waiting and reload the page to use new content.
+ */
+export function OfflineInterfaceProvider({
+    offlineInterface,
+    children,
+}: OfflineInterfaceProviderInput): JSX.Element {
+    return (
+        <OfflineInterfaceContext.Provider value={offlineInterface}>
+            {children}
+        </OfflineInterfaceContext.Provider>
+    )
+}
+
+OfflineInterfaceProvider.propTypes = {
+    children: PropTypes.node,
+    offlineInterface: PropTypes.shape({ init: PropTypes.func }),
+}
+
+export function useOfflineInterface(): OfflineInterface {
+    const offlineInterface = useContext(OfflineInterfaceContext)
+
+    if (offlineInterface === undefined) {
+        throw new Error(
+            'Offline interface context not found. If this app is using the app platform, make sure `pwa: { enabled: true }` is in d2.config.js. If this is not a platform app, make sure your app is wrapped with an app-runtime <Provider> or an <OfflineProvider> from app-service-offline.'
+        )
+    }
+
+    return offlineInterface
+}

package/src/lib/offline-provider.tsx

@@ -0,0 +1,43 @@
+import PropTypes from 'prop-types'
+import React from 'react'
+import { OfflineInterface } from '../types'
+import { CacheableSectionProvider } from './cacheable-section-state'
+import { Dhis2ConnectionStatusProvider } from './dhis2-connection-status'
+import { OfflineInterfaceProvider } from './offline-interface'
+import { OnlineStatusMessageProvider } from './online-status-message'
+
+interface OfflineProviderInput {
+    offlineInterface?: OfflineInterface
+    children?: React.ReactNode
+}
+
+/** A context provider for all the relevant offline contexts */
+export function OfflineProvider({
+    offlineInterface,
+    children,
+}: OfflineProviderInput): JSX.Element {
+    // If an offline interface is not provided, or if one is provided and PWA
+    // is not enabled, skip adding context providers
+    if (!offlineInterface || !offlineInterface.pwaEnabled) {
+        return <>{children}</>
+    }
+
+    return (
+        <OfflineInterfaceProvider offlineInterface={offlineInterface}>
+            <Dhis2ConnectionStatusProvider>
+                <CacheableSectionProvider>
+                    <OnlineStatusMessageProvider>
+                        {children}
+                    </OnlineStatusMessageProvider>
+                </CacheableSectionProvider>
+            </Dhis2ConnectionStatusProvider>
+        </OfflineInterfaceProvider>
+    )
+}
+
+OfflineProvider.propTypes = {
+    children: PropTypes.node,
+    offlineInterface: PropTypes.shape({
+        pwaEnabled: PropTypes.bool,
+    }),
+}

package/src/lib/online-status-message.tsx

@@ -0,0 +1,47 @@
+import React, { ReactElement, ReactNode, useContext, useState } from 'react'
+
+type SetOnlineStatusMessage = (message: ReactNode) => void
+
+// 'get' and 'set' contexts are separated so 'setter' consumers that don't
+// actually need the value don't have to rerender when the value changes:
+const OnlineStatusMessageValueContext =
+    React.createContext<ReactNode>(undefined)
+const SetOnlineStatusMessageContext =
+    React.createContext<SetOnlineStatusMessage>(() => undefined)
+
+export const OnlineStatusMessageProvider = ({
+    children,
+}: {
+    children: ReactNode
+}): ReactElement => {
+    const [onlineStatusMessage, setOnlineStatusMessage] = useState<ReactNode>() // note: not undefined
+
+    return (
+        <OnlineStatusMessageValueContext.Provider value={onlineStatusMessage}>
+            <SetOnlineStatusMessageContext.Provider
+                value={setOnlineStatusMessage}
+            >
+                {children}
+            </SetOnlineStatusMessageContext.Provider>
+        </OnlineStatusMessageValueContext.Provider>
+    )
+}
+
+export const useOnlineStatusMessageValue = () => {
+    return useContext(OnlineStatusMessageValueContext)
+}
+
+export const useSetOnlineStatusMessage = () => {
+    return useContext(SetOnlineStatusMessageContext)
+}
+
+// combination of both getter and setter (also provides backward compatability)
+export const useOnlineStatusMessage = () => {
+    const onlineStatusMessage = useOnlineStatusMessageValue()
+    const setOnlineStatusMessage = useSetOnlineStatusMessage()
+
+    return {
+        onlineStatusMessage,
+        setOnlineStatusMessage,
+    }
+}

package/src/setupRTL.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom'

package/src/types.ts

@@ -0,0 +1,66 @@
+// Cacheable Section types
+
+export type RecordingState = 'default' | 'pending' | 'error' | 'recording'
+
+// Global state types
+
+// This is the mutation that gets executed by store.mutate. Should return
+// new state
+export interface GlobalStateStoreMutation {
+    (state: any): any
+}
+
+// Uses generic <Type> because global state mutation will also receive
+// the same parameters
+export interface GlobalStateStoreMutationCreator<Type> {
+    (...args: Type[]): GlobalStateStoreMutation
+}
+
+// This is the function returned by useGlobalStateMutation;
+// it triggers a GlobalStateStoreMutation
+export interface GlobalStateMutation<Type> {
+    (...args: Type[]): void
+}
+
+export interface GlobalStateStoreMutateMethod {
+    (mutation: GlobalStateStoreMutation): void
+}
+
+export interface GlobalStateStore {
+    getState: () => any
+    subscribe: (callback: (state: any) => void) => void
+    unsubscribe: (callback: (state: any) => void) => void
+    mutate: GlobalStateStoreMutateMethod
+}
+
+// Offline Interface types
+
+interface StartRecording {
+    (params: {
+        sectionId: string
+        recordingTimeoutDelay: number
+        onStarted: () => void
+        onCompleted: () => void
+        onError: (err: Error) => void
+    }): Promise<undefined>
+}
+
+export interface IndexedDBCachedSection {
+    sectionId: string
+    lastUpdated: Date
+    // this may change in the future:
+    requests: number
+}
+
+export interface OfflineInterface {
+    readonly pwaEnabled: boolean
+    readonly latestIsConnected: boolean | null
+    subscribeToDhis2ConnectionStatus: ({
+        onUpdate,
+    }: {
+        onUpdate: ({ isConnected }: { isConnected: boolean }) => void
+    }) => () => void
+    startRecording: StartRecording
+    getCachedSections: () => Promise<IndexedDBCachedSection[]>
+    removeSection: (id: string) => Promise<boolean>
+}

package/src/utils/__tests__/render-counter.test.tsx

@@ -0,0 +1,45 @@
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import React from 'react'
+import { RenderCounter, resetRenderCounts } from '../render-counter'
+
+const renderCounts = {}
+
+export const Rerenderer = (): JSX.Element => {
+    const [, setState] = React.useState(true)
+    const toggleState = () => setState((prevState) => !prevState)
+
+    return (
+        <>
+            <button onClick={toggleState} role="button" />
+            <RenderCounter id={'rc1'} countsObj={renderCounts} />
+        </>
+    )
+}
+
+afterEach(() => {
+    resetRenderCounts(renderCounts)
+})
+
+it('increments the counter when rerendered', () => {
+    render(<Rerenderer />)
+
+    const { getByTestId, getByRole } = screen
+    expect(getByTestId('rc1')).toHaveTextContent('1')
+
+    act(() => {
+        fireEvent.click(getByRole('button'))
+    })
+
+    expect(getByTestId('rc1')).toHaveTextContent('2')
+
+    act(() => {
+        fireEvent.click(getByRole('button'))
+    })
+
+    expect(getByTestId('rc1')).toHaveTextContent('3')
+})
+
+it('resets the render counter successfully', () => {
+    render(<Rerenderer />)
+    expect(screen.getByTestId('rc1')).toHaveTextContent('1')
+})

package/src/utils/render-counter.tsx

@@ -0,0 +1,22 @@
+/* eslint-disable react-hooks/immutability */
+import React from 'react'
+
+interface RenderCounts {
+    [index: string]: number
+}
+
+export const RenderCounter = ({
+    id,
+    countsObj,
+}: {
+    id: string
+    countsObj: RenderCounts
+}): JSX.Element => {
+    if (!(id in countsObj)) {
+        countsObj[id] = 0
+    }
+    return <div data-testid={id}>{++countsObj[id]}</div>
+}
+
+export const resetRenderCounts = (renderCounts: RenderCounts): void =>
+    Object.keys(renderCounts).forEach((key) => (renderCounts[key] = 0))

package/src/utils/test-mocks.ts

@@ -0,0 +1,47 @@
+export const successfulRecordingMock = jest
+    .fn()
+    .mockImplementation(async ({ onStarted, onCompleted } = {}) => {
+        // in 100ms, call 'onStarted' callback (allows 'pending' state)
+        if (onStarted) {
+            setTimeout(onStarted, 100)
+        }
+
+        // in 200ms, call 'onCompleted' callback
+        if (onCompleted) {
+            setTimeout(onCompleted, 200)
+        }
+
+        // resolve
+        return Promise.resolve()
+    })
+
+export const errorRecordingMock = jest
+    .fn()
+    .mockImplementation(({ onStarted, onError } = {}) => {
+        // in 100ms, call 'onStarted' callback (allows 'pending' state)
+        if (onStarted) {
+            setTimeout(onStarted, 100)
+        }
+
+        // in 200ms, call 'onError'
+        setTimeout(() => onError(new Error('test err')), 200)
+
+        // resolve to signal successful initiation
+        return Promise.resolve()
+    })
+
+export const failedMessageRecordingMock = jest
+    .fn()
+    .mockRejectedValue(new Error('Failed message'))
+
+export const mockOfflineInterface = {
+    pwaEnabled: true,
+    latestIsConnected: true,
+    startRecording: successfulRecordingMock,
+    getCachedSections: jest.fn().mockResolvedValue([]),
+    removeSection: jest.fn().mockResolvedValue(true),
+    // returns an unsubscribe function
+    subscribeToDhis2ConnectionStatus: jest
+        .fn()
+        .mockReturnValue(() => undefined),
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "../../tsconfig.json",
+    "include": ["src"],
+    "exclude": [
+        "src/setupRTL.ts",
+        "src/__tests__",
+        "**/*.test.ts",
+        "**/*.test.tsx"
+    ]
+}