@dhis2/app-service-offline 3.17.0 → 3.17.2

package/src/lib/__tests__/use-cacheable-section.test.tsx

@@ -0,0 +1,280 @@
+import { renderHook, act, waitFor } from '@testing-library/react'
+import React, { FC, PropsWithChildren } from 'react'
+import {
+    errorRecordingMock,
+    failedMessageRecordingMock,
+    mockOfflineInterface,
+} from '../../utils/test-mocks'
+import { useCacheableSection } from '../cacheable-section'
+import { OfflineProvider } from '../offline-provider'
+
+// Suppress 'act' warning for these tests
+const originalError = console.error
+beforeEach(() => {
+    jest.spyOn(console, 'error').mockImplementation((...args) => {
+        const pattern =
+            /Warning: An update to .* inside a test was not wrapped in act/
+        if (typeof args[0] === 'string' && pattern.test(args[0])) {
+            return
+        }
+        return originalError.call(console, ...args)
+    })
+})
+
+afterEach(() => {
+    jest.clearAllMocks()
+    // This syntax appeases typescript:
+    ;(console.error as jest.Mock).mockRestore()
+})
+
+it('renders in the default state initially', () => {
+    const wrapper: FC<PropsWithChildren> = ({ children }) => (
+        <OfflineProvider offlineInterface={mockOfflineInterface}>
+            {children}
+        </OfflineProvider>
+    )
+
+    const { result } = renderHook(() => useCacheableSection('one'), {
+        wrapper,
+    })
+
+    expect(result.current.recordingState).toBe('default')
+    expect(result.current.isCached).toBe(false)
+    expect(result.current.lastUpdated).toBeUndefined()
+})
+
+it('has stable references', () => {
+    const wrapper: FC<PropsWithChildren> = ({ children }) => (
+        <OfflineProvider offlineInterface={mockOfflineInterface}>
+            {children}
+        </OfflineProvider>
+    )
+    const { result, rerender } = renderHook(() => useCacheableSection('one'), {
+        wrapper,
+    })
+
+    const origRecordingState = result.current.recordingState
+    const origStartRecording = result.current.startRecording
+    const origLastUpdated = result.current.lastUpdated
+    const origIsCached = result.current.isCached
+    const origRemove = result.current.remove
+
+    rerender()
+
+    expect(result.current.recordingState).toBe(origRecordingState)
+    expect(result.current.startRecording).toBe(origStartRecording)
+    expect(result.current.lastUpdated).toBe(origLastUpdated)
+    expect(result.current.isCached).toBe(origIsCached)
+    expect(result.current.remove).toBe(origRemove)
+})
+
+it('handles a successful recording', async (done) => {
+    const [sectionId, timeoutDelay] = ['one', 1234]
+    const recordingSuccessOfflineInterface = {
+        ...mockOfflineInterface,
+        getCachedSections: jest
+            .fn()
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce([
+                { sectionId: sectionId, lastUpdated: new Date() },
+            ]),
+    }
+    const wrapper: FC<PropsWithChildren> = ({ children }) => (
+        <OfflineProvider offlineInterface={recordingSuccessOfflineInterface}>
+            {children}
+        </OfflineProvider>
+    )
+    const { result } = renderHook(() => useCacheableSection(sectionId), {
+        wrapper,
+    })
+
+    const assertRecordingStarted = () => {
+        expect(result.current.recordingState).toBe('recording')
+    }
+    const assertRecordingCompleted = async () => {
+        expect(result.current.recordingState).toBe('default')
+
+        // Test that 'isCached' gets updated
+        expect(
+            recordingSuccessOfflineInterface.getCachedSections
+        ).toBeCalledTimes(2)
+        // Recording states are updated synchronously, but getting isCached
+        // state is asynchronous -- need to wait for that here.
+        // An assertion is not used as the waitFor condition because it may skew
+        // the total number assertions in this test if it needs to retry. Number
+        // of assertions is checked at the bottom of this test to make sure both
+        // of these callbacks are called.
+        await waitFor(() => result.current.isCached === true)
+        expect(result.current.isCached).toBe(true)
+        expect(result.current.lastUpdated).toBeInstanceOf(Date)
+
+        // If this cb is not called, test should time out and fail
+        done()
+    }
+
+    await act(async () => {
+        await result.current.startRecording({
+            onStarted: assertRecordingStarted,
+            onCompleted: assertRecordingCompleted,
+            recordingTimeoutDelay: timeoutDelay,
+        })
+    })
+
+    // At this stage, recording should be 'pending'
+    expect(result.current.recordingState).toBe('pending')
+
+    // Check correct options sent to offline interface
+    const options = mockOfflineInterface.startRecording.mock.calls[0][0]
+    expect(options.sectionId).toBe(sectionId)
+    expect(options.recordingTimeoutDelay).toBe(timeoutDelay)
+    expect(typeof options.onStarted).toBe('function')
+    expect(typeof options.onCompleted).toBe('function')
+    expect(typeof options.onError).toBe('function')
+
+    // Make sure all async assertions are called
+    expect.assertions(11)
+})
+
+it('handles a recording that encounters an error', async (done) => {
+    // Suppress the expected error from console (in addition to 'act' warning)
+    jest.spyOn(console, 'error').mockImplementation((...args) => {
+        const actPattern =
+            /Warning: An update to .* inside a test was not wrapped in act/
+        const errPattern = /Error during recording/
+        const matchesPattern =
+            actPattern.test(args[0]) || errPattern.test(args[0])
+        if (typeof args[0] === 'string' && matchesPattern) {
+            return
+        }
+        return originalError.call(console, ...args)
+    })
+    const recordingErrorOfflineInterface = {
+        ...mockOfflineInterface,
+        startRecording: errorRecordingMock,
+    }
+    const wrapper: FC<PropsWithChildren> = ({ children }) => (
+        <OfflineProvider offlineInterface={recordingErrorOfflineInterface}>
+            {children}
+        </OfflineProvider>
+    )
+    const { result } = renderHook(() => useCacheableSection('one'), {
+        wrapper,
+    })
+
+    const assertRecordingStarted = () => {
+        expect(result.current.recordingState).toBe('recording')
+    }
+    const assertRecordingError = (error: Error) => {
+        expect(result.current.recordingState).toBe('error')
+        expect(error.message).toMatch(/test err/) // see errorRecordingMock
+        expect(console.error).toHaveBeenCalledWith(
+            'Error during recording:',
+            error
+        )
+
+        // Expect only one call, from initialization:
+        expect(mockOfflineInterface.getCachedSections).toBeCalledTimes(1)
+
+        // If this cb is not called, test should time out and fail
+        done()
+    }
+
+    await act(async () => {
+        await result.current.startRecording({
+            onStarted: assertRecordingStarted,
+            onError: assertRecordingError,
+        })
+    })
+
+    // At this stage, recording should be 'pending'
+    expect(result.current.recordingState).toBe('pending')
+
+    // Make sure all async assertions are called
+    expect.assertions(6)
+})
+
+it('handles an error starting the recording', async () => {
+    const messageErrorOfflineInterface = {
+        ...mockOfflineInterface,
+        startRecording: failedMessageRecordingMock,
+    }
+    const wrapper: FC<PropsWithChildren> = ({ children }) => (
+        <OfflineProvider offlineInterface={messageErrorOfflineInterface}>
+            {children}
+        </OfflineProvider>
+    )
+    const { result } = renderHook(() => useCacheableSection('err'), {
+        wrapper,
+    })
+
+    await expect(result.current.startRecording()).rejects.toThrow(
+        'Failed message' // from failedMessageRecordingMock
+    )
+})
+
+it('handles remove and updates sections', async () => {
+    const sectionId = 'one'
+    const sectionOpsOfflineInterface = {
+        ...mockOfflineInterface,
+        getCachedSections: jest
+            .fn()
+            .mockResolvedValueOnce([
+                { sectionId: sectionId, lastUpdated: new Date() },
+            ])
+            .mockResolvedValueOnce([]),
+    }
+    const wrapper: FC<PropsWithChildren> = ({ children }) => (
+        <OfflineProvider offlineInterface={sectionOpsOfflineInterface}>
+            {children}
+        </OfflineProvider>
+    )
+    const { result } = renderHook(() => useCacheableSection(sectionId), {
+        wrapper,
+    })
+
+    // Wait for state to sync with indexedDB
+    await waitFor(() => expect(result.current.isCached).toBe(true))
+
+    let success
+    await act(async () => {
+        success = await result.current.remove()
+    })
+
+    expect(success).toBe(true)
+    // Test that 'isCached' gets updated
+    expect(sectionOpsOfflineInterface.getCachedSections).toBeCalledTimes(2)
+    await waitFor(() => expect(result.current.isCached).toBe(false))
+    expect(result.current.isCached).toBe(false)
+    expect(result.current.lastUpdated).toBeUndefined()
+})
+
+it('handles a change in ID', async () => {
+    const idChangeOfflineInterface = {
+        ...mockOfflineInterface,
+        getCachedSections: jest
+            .fn()
+            .mockResolvedValue([
+                { sectionId: 'id-one', lastUpdated: new Date() },
+            ]),
+    }
+    const wrapper: FC<PropsWithChildren> = ({ children }) => (
+        <OfflineProvider offlineInterface={idChangeOfflineInterface}>
+            {children}
+        </OfflineProvider>
+    )
+    const { result, rerender } = renderHook(
+        (id: any) => useCacheableSection(id),
+        { wrapper, initialProps: 'id-one' }
+    )
+
+    // Wait for state to sync with indexedDB
+    await waitFor(() => expect(result.current.isCached).toBe(true))
+
+    rerender('id-two')
+
+    // Test that 'isCached' gets updated
+    // expect(idChangeOfflineInterface.getCachedSections).toBeCalledTimes(2)
+    await waitFor(() => expect(result.current.isCached).toBe(false))
+    expect(result.current.isCached).toBe(false)
+    expect(result.current.lastUpdated).toBeUndefined()
+})

package/src/lib/__tests__/use-online-status-message.test.tsx

@@ -0,0 +1,27 @@
+import { renderHook, act } from '@testing-library/react'
+import React, { FC, ReactNode } from 'react'
+import { mockOfflineInterface } from '../../utils/test-mocks'
+import { OfflineProvider } from '../offline-provider'
+import { useOnlineStatusMessage } from '../online-status-message'
+
+describe('useOnlineStatusMessage', () => {
+    it('should allow the online status to be updated ', () => {
+        const wrapper: FC<{ children?: ReactNode }> = ({ children }) => (
+            <OfflineProvider offlineInterface={mockOfflineInterface}>
+                {children}
+            </OfflineProvider>
+        )
+
+        const { result } = renderHook(() => useOnlineStatusMessage(), {
+            wrapper,
+        })
+
+        expect(result.current.onlineStatusMessage).toBeUndefined()
+
+        act(() => {
+            result.current.setOnlineStatusMessage('8 offline events')
+        })
+
+        expect(result.current.onlineStatusMessage).toEqual('8 offline events')
+    })
+})

package/src/lib/cacheable-section-state.tsx

@@ -0,0 +1,269 @@
+import PropTypes from 'prop-types'
+import React, { useEffect, useCallback, useMemo } from 'react'
+import {
+    GlobalStateStore,
+    GlobalStateStoreMutationCreator,
+    IndexedDBCachedSection,
+    RecordingState,
+} from '../types'
+import {
+    createStore,
+    useGlobalState,
+    useGlobalStateMutation,
+    GlobalStateProvider,
+} from './global-state-service'
+import { useOfflineInterface } from './offline-interface'
+
+// Functions in here use the global state service to manage cacheable section
+// state in a performant way
+
+interface CachedSectionsById {
+    [index: string]: { lastUpdated: Date }
+}
+
+/**
+ * Helper that transforms an array of cached section objects from the IndexedDB
+ * into an object of values keyed by section ID
+ *
+ * @param {Array} list - An array of section objects
+ * @returns {Object} An object of sections, keyed by ID
+ */
+function getSectionsById(
+    sectionsArray: IndexedDBCachedSection[]
+): CachedSectionsById {
+    return sectionsArray.reduce(
+        (result, { sectionId, lastUpdated }) => ({
+            ...result,
+            [sectionId]: { lastUpdated },
+        }),
+        {}
+    )
+}
+
+/**
+ * Create a store for Cacheable Section state.
+ * Expected to be used in app adapter
+ */
+export function createCacheableSectionStore(): GlobalStateStore {
+    const initialState = { recordingStates: {}, cachedSections: {} }
+    return createStore(initialState)
+}
+
+/**
+ * Helper hook that returns a value that will persist between renders but makes
+ * sure to only set its initial state once.
+ * See https://gist.github.com/amcgee/42bb2fa6d5f79e607f00e6dccc733482
+ */
+function useConst<Type>(factory: () => Type): Type {
+    const ref = React.useRef<Type | null>(null)
+    if (ref.current === null) {
+        ref.current = factory()
+    }
+    return ref.current
+}
+
+/**
+ * Provides context for a global state context which will track cached
+ * sections' status and cacheable sections' recording states, which will
+ * determine how that component will render. The provider will be a part of
+ * the OfflineProvider.
+ */
+export function CacheableSectionProvider({
+    children,
+}: {
+    children: React.ReactNode
+}): JSX.Element {
+    const offlineInterface = useOfflineInterface()
+    const store = useConst(createCacheableSectionStore)
+
+    // On load, get sections and add to store
+    useEffect(() => {
+        if (offlineInterface) {
+            offlineInterface.getCachedSections().then((sections) => {
+                store.mutate((state) => ({
+                    ...state,
+                    cachedSections: getSectionsById(sections),
+                }))
+            })
+        }
+    }, [store, offlineInterface])
+
+    return <GlobalStateProvider store={store}>{children}</GlobalStateProvider>
+}
+CacheableSectionProvider.propTypes = {
+    children: PropTypes.node,
+}
+
+interface RecordingStateControls {
+    recordingState: RecordingState
+    setRecordingState: (newState: RecordingState) => void
+    removeRecordingState: () => void
+}
+
+/**
+ * Uses an optimized global state to manage 'recording state' values without
+ * unnecessarily rerendering all consuming components
+ *
+ * @param {String} id - ID of the cacheable section to track
+ * @returns {Object} { recordingState: String, setRecordingState: Function, removeRecordingState: Function}
+ */
+export function useRecordingState(id: string): RecordingStateControls {
+    const recordingStateSelector = useCallback(
+        (state: any) => state.recordingStates[id],
+        [id]
+    )
+    const [recordingState] = useGlobalState(recordingStateSelector)
+
+    const setRecordingStateMutationCreator = useCallback<
+        GlobalStateStoreMutationCreator<RecordingState>
+    >(
+        (newState) => (state: any) => ({
+            ...state,
+            recordingStates: { ...state.recordingStates, [id]: newState },
+        }),
+        [id]
+    )
+    const setRecordingState = useGlobalStateMutation(
+        setRecordingStateMutationCreator
+    )
+
+    const removeRecordingStateMutationCreator = useCallback(
+        () => (state: any) => {
+            const recordingStates = { ...state.recordingStates }
+            delete recordingStates[id]
+            return { ...state, recordingStates }
+        },
+        [id]
+    )
+    const removeRecordingState = useGlobalStateMutation(
+        removeRecordingStateMutationCreator
+    )
+
+    return useMemo(
+        () => ({
+            recordingState,
+            setRecordingState,
+            removeRecordingState,
+        }),
+        [recordingState, setRecordingState, removeRecordingState]
+    )
+}
+
+/**
+ * Returns a function that syncs cached sections in the global state
+ * with IndexedDB, so that IndexedDB is the single source of truth
+ *
+ * @returns {Function} syncCachedSections
+ */
+function useSyncCachedSections() {
+    const offlineInterface = useOfflineInterface()
+
+    const setCachedSectionsMutationCreator = useCallback<
+        GlobalStateStoreMutationCreator<CachedSectionsById>
+    >(
+        (cachedSections) => (state: any) => ({
+            ...state,
+            cachedSections,
+        }),
+        []
+    )
+    const setCachedSections = useGlobalStateMutation(
+        setCachedSectionsMutationCreator
+    )
+
+    return useCallback(async () => {
+        const sections = await offlineInterface.getCachedSections()
+        setCachedSections(getSectionsById(sections))
+    }, [offlineInterface, setCachedSections])
+}
+
+interface CachedSectionsControls {
+    cachedSections: CachedSectionsById
+    removeById: (id: string) => Promise<boolean>
+    syncCachedSections: () => Promise<void>
+}
+
+/**
+ * Uses global state to manage an object of cached sections' statuses
+ *
+ * @returns {Object} { cachedSections: Object, removeSection: Function }
+ */
+export function useCachedSections(): CachedSectionsControls {
+    const [cachedSections] = useGlobalState((state) => state.cachedSections)
+    const syncCachedSections = useSyncCachedSections()
+    const offlineInterface = useOfflineInterface()
+
+    /**
+     * Uses offline interface to remove a section from IndexedDB and Cache
+     * Storage.
+     *
+     * Returns a promise that resolves to `true` if a section is found and
+     * deleted, or `false` if asection with the specified ID does not exist.
+     */
+    const removeById = useCallback(
+        async (id: string) => {
+            const success = await offlineInterface.removeSection(id)
+            if (success) {
+                await syncCachedSections()
+            }
+            return success
+        },
+        [offlineInterface, syncCachedSections]
+    )
+
+    return useMemo(
+        () => ({
+            cachedSections,
+            removeById,
+            syncCachedSections,
+        }),
+        [cachedSections, removeById, syncCachedSections]
+    )
+}
+
+interface CachedSectionControls {
+    lastUpdated: Date
+    isCached: boolean
+    remove: () => Promise<boolean>
+    syncCachedSections: () => Promise<void>
+}
+
+/**
+ * Uses global state to manage the cached status of just one section, which
+ * prevents unnecessary rerenders of consuming components
+ *
+ * @param {String} id
+ * @returns {Object} { lastUpdated: Date, remove: Function }
+ */
+export function useCachedSection(id: string): CachedSectionControls {
+    const [status] = useGlobalState((state) => state.cachedSections[id])
+    const syncCachedSections = useSyncCachedSections()
+    const offlineInterface = useOfflineInterface()
+
+    const lastUpdated = status && status.lastUpdated
+
+    /**
+     * Uses offline interface to remove a section from IndexedDB and Cache
+     * Storage.
+     *
+     * Returns `true` if a section is found and deleted, or `false` if a
+     * section with the specified ID does not exist.
+     */
+    const remove = useCallback(async () => {
+        const success = await offlineInterface.removeSection(id)
+        if (success) {
+            await syncCachedSections()
+        }
+        return success
+    }, [offlineInterface, id, syncCachedSections])
+
+    return useMemo(
+        () => ({
+            lastUpdated,
+            isCached: !!lastUpdated,
+            remove,
+            syncCachedSections,
+        }),
+        [lastUpdated, remove, syncCachedSections]
+    )
+}