@dhis2/app-service-data 3.17.0 → 3.17.2

package/src/react/hooks/useDataQuery.ts

@@ -0,0 +1,170 @@
+import type {
+    Query,
+    QueryOptions,
+    QueryResult,
+    QueryVariables,
+    FetchError,
+} from '@dhis2/data-engine'
+import { useQuery } from '@tanstack/react-query'
+import { useState, useRef, useCallback, useDebugValue } from 'react'
+import type { QueryRenderInput, QueryRefetchFunction } from '../../types'
+import { mergeAndCompareVariables } from './mergeAndCompareVariables'
+import { useDataEngine } from './useDataEngine'
+import { useStaticInput } from './useStaticInput'
+
+type QueryState = {
+    enabled: boolean
+    variables?: QueryVariables
+    variablesHash?: string
+    refetchCallback?: (data: any) => void
+}
+
+export const useDataQuery = <TQueryResult = QueryResult>(
+    query: Query,
+    {
+        onComplete: userOnSuccess,
+        onError: userOnError,
+        variables: initialVariables = {},
+        lazy: initialLazy = false,
+    }: QueryOptions<TQueryResult> = {}
+): QueryRenderInput<TQueryResult> => {
+    const [staticQuery] = useStaticInput<Query>(query, {
+        warn: true,
+        name: 'query',
+    })
+    const [variablesUpdateCount, setVariablesUpdateCount] = useState(0)
+
+    const queryState = useRef<QueryState>({
+        variables: initialVariables,
+        variablesHash: undefined,
+        enabled: !initialLazy,
+        refetchCallback: undefined,
+    })
+
+    /**
+     * Display current query state and refetch count in React DevTools
+     */
+
+    useDebugValue(
+        {
+            variablesUpdateCount,
+            enabled: queryState.current.enabled,
+            variables: queryState.current.variables,
+        },
+        (debugValue) => JSON.stringify(debugValue)
+    )
+
+    /**
+     * User callbacks and refetch handling
+     */
+
+    const onSuccess = (data: any) => {
+        queryState.current.refetchCallback?.(data)
+        queryState.current.refetchCallback = undefined
+
+        if (userOnSuccess) {
+            userOnSuccess(data)
+        }
+    }
+
+    const onError = (error: FetchError) => {
+        // If we'd want to reject on errors we'd call the cb with the error here
+        queryState.current.refetchCallback = undefined
+
+        if (userOnError) {
+            userOnError(error)
+        }
+    }
+
+    /**
+     * Setting up react-query
+     */
+
+    const engine = useDataEngine()
+    const queryKey = [staticQuery, queryState.current.variables]
+    const queryFn = () =>
+        engine.query(staticQuery, { variables: queryState.current.variables })
+
+    const {
+        status,
+        fetchStatus,
+        error,
+        data,
+        refetch: queryRefetch,
+    } = useQuery({
+        queryKey,
+        queryFn,
+        enabled: queryState.current.enabled,
+        onSuccess,
+        onError,
+    })
+
+    /**
+     * Refetch allows a user to update the variables or just
+     * trigger a refetch of the query with the current variables.
+     *
+     * We're using useCallback to make the identity of the function
+     * as stable as possible, so that it won't trigger excessive
+     * rerenders when used for side-effects.
+     */
+
+    const refetch: QueryRefetchFunction = useCallback(
+        (newVariables) => {
+            const { identical, mergedVariables, mergedVariablesHash } =
+                mergeAndCompareVariables(
+                    queryState.current.variables,
+                    newVariables,
+                    queryState.current.variablesHash
+                )
+
+            /**
+             * If there are no updates that will trigger an automatic refetch
+             * we'll need to call react-query's refetch directly
+             */
+            if (queryState.current.enabled && identical) {
+                return queryRefetch({ throwOnError: false }).then(
+                    ({ data }) => data
+                )
+            }
+
+            queryState.current.variables = mergedVariables
+            queryState.current.variablesHash = mergedVariablesHash
+            queryState.current.enabled = true
+
+            // This promise does not currently reject on errors
+            const refetchPromise = new Promise<TQueryResult>((resolve) => {
+                queryState.current.refetchCallback = (data) => {
+                    resolve(data)
+                }
+            })
+
+            // Trigger a react-query refetch by incrementing variablesUpdateCount state
+            setVariablesUpdateCount((prevCount) => prevCount + 1)
+
+            return refetchPromise
+        },
+        [queryRefetch]
+    )
+
+    /**
+     * react-query returns null or an error, but we return undefined
+     * or an error, so this ensures consistency with the other types.
+     */
+    const ourError = error || undefined
+
+    return {
+        engine,
+        // A query has not been called if it is lazy (fetchStatus = 'idle') and no initial data is available (status = 'loading').
+        // https://tanstack.com/query/v4/docs/framework/react/guides/queries
+        called: !(status === 'loading' && fetchStatus === 'idle'),
+        // 'loading' should only be true when actively fetching (fetchStatus = 'fetching') while there is no data yet (status = 'loading').
+        // If there is already data for the query, then 'loading' will not become 'true' when refetching, so the previous data can still be
+        // displayed while new data is fetched in the background
+        loading: fetchStatus === 'fetching' && status === 'loading',
+        // 'fetching' reflects the fetching behavior behind the scenes
+        fetching: fetchStatus === 'fetching',
+        error: ourError,
+        data,
+        refetch,
+    }
+}

package/src/react/hooks/useQueryExecutor.test.tsx

@@ -0,0 +1,195 @@
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { useQueryExecutor } from './useQueryExecutor'
+
+const testError = new Error('TEST ERROR')
+let theSignal: AbortSignal | undefined
+const execute = jest.fn(async ({ signal }) => {
+    theSignal = signal
+    return 42
+})
+const failingExecute = jest.fn(async () => {
+    throw testError
+})
+
+describe('useQueryExecutor', () => {
+    afterEach(() => {
+        jest.clearAllMocks()
+        theSignal = undefined
+    })
+    it('When not immediate, should start with called false and loading false', () => {
+        const { result } = renderHook(() =>
+            useQueryExecutor({
+                execute,
+                immediate: false,
+                singular: true,
+                variables: {},
+            })
+        )
+
+        expect(result.current).toMatchObject({
+            called: false,
+            loading: false,
+        })
+    })
+
+    it('When immediate, should start with called true and loading true', async () => {
+        const { result } = renderHook(() =>
+            useQueryExecutor({
+                execute,
+                immediate: true,
+                singular: true,
+                variables: {},
+            })
+        )
+
+        expect(result.current).toMatchObject({
+            called: true,
+            loading: true,
+        })
+
+        await waitFor(() => {
+            expect(result.current).toMatchObject({
+                called: true,
+                loading: false,
+                data: 42,
+            })
+        })
+    })
+
+    it('Should start when refetch called (if not immediate)', async () => {
+        const { result } = renderHook(() =>
+            useQueryExecutor({
+                execute,
+                immediate: false,
+                singular: true,
+                variables: {},
+            })
+        )
+
+        expect(result.current).toMatchObject({
+            called: false,
+            loading: false,
+        })
+
+        act(() => {
+            result.current.refetch()
+        })
+
+        expect(result.current).toMatchObject({
+            called: true,
+            loading: true,
+        })
+
+        await waitFor(() => {
+            expect(result.current).toMatchObject({
+                called: true,
+                loading: false,
+                data: 42,
+            })
+        })
+    })
+
+    it('Should report an error when execute fails', async () => {
+        const { result } = renderHook(() =>
+            useQueryExecutor({
+                execute: failingExecute,
+                immediate: false,
+                singular: true,
+                variables: {},
+            })
+        )
+
+        expect(result.current).toMatchObject({
+            called: false,
+            loading: false,
+        })
+
+        act(() => {
+            result.current.refetch()
+        })
+
+        expect(result.current).toMatchObject({
+            called: true,
+            loading: true,
+        })
+
+        await waitFor(() => {
+            expect(result.current).toMatchObject({
+                called: true,
+                loading: false,
+                error: testError,
+            })
+        })
+    })
+
+    it("Shouldn't abort+refetch when inputs change on subsequent renders", async () => {
+        const { result, rerender } = renderHook(
+            ({ onComplete }) =>
+                useQueryExecutor({
+                    execute,
+                    immediate: true,
+                    singular: true,
+                    variables: {},
+                    onComplete,
+                }),
+            {
+                initialProps: { onComplete: () => null },
+            }
+        )
+
+        expect(result.current).toMatchObject({
+            called: true,
+            loading: true,
+        })
+
+        rerender({ onComplete: () => null })
+
+        await waitFor(() => {
+            expect(result.current).toMatchObject({
+                called: true,
+                loading: false,
+                data: 42,
+            })
+
+            expect(theSignal && theSignal.aborted).toBe(false)
+            expect(execute).toHaveBeenCalledTimes(1)
+        })
+    })
+
+    it('Should respect abort signal', async () => {
+        const { result } = renderHook(() =>
+            useQueryExecutor({
+                execute,
+                immediate: false,
+                singular: true,
+                variables: {},
+            })
+        )
+
+        expect(result.current).toMatchObject({
+            called: false,
+            loading: false,
+        })
+
+        act(() => {
+            result.current.refetch()
+        })
+
+        expect(result.current).toMatchObject({
+            called: true,
+            loading: true,
+        })
+
+        act(() => {
+            result.current.abort()
+        })
+
+        expect(theSignal && theSignal.aborted).toBe(true)
+
+        expect(result.current).toMatchObject({
+            called: true,
+            loading: false,
+            error: { type: 'aborted', message: 'Aborted' },
+        })
+    })
+})

package/src/react/hooks/useQueryExecutor.ts

@@ -0,0 +1,99 @@
+import { FetchError } from '@dhis2/data-engine'
+import type { QueryExecuteOptions } from '@dhis2/data-engine'
+import { useState, useCallback, useRef, useEffect } from 'react'
+import { ExecuteHookInput, ExecuteHookResult } from '../../types'
+import { useStaticInput } from './useStaticInput'
+
+interface StateType<T> {
+    called: boolean
+    loading: boolean
+    error?: FetchError
+    data?: T
+}
+
+export const useQueryExecutor = <ReturnType>({
+    execute,
+    variables: initialVariables,
+    singular,
+    immediate,
+    onComplete,
+    onError,
+}: ExecuteHookInput<ReturnType>): ExecuteHookResult<ReturnType> => {
+    const [theExecute] = useStaticInput(execute)
+    const [state, setState] = useState<StateType<ReturnType>>({
+        called: !!immediate,
+        loading: !!immediate,
+    })
+
+    const variables = useRef(initialVariables)
+
+    const abortControllersRef = useRef<AbortController[]>([])
+    const abort = useCallback(() => {
+        abortControllersRef.current.forEach((controller) => controller.abort())
+        abortControllersRef.current = []
+    }, [])
+
+    const manualAbort = useCallback(() => {
+        abort()
+        setState((state) => ({
+            called: state.called,
+            loading: false,
+            error: new FetchError({ type: 'aborted', message: 'Aborted' }),
+        }))
+    }, [abort])
+
+    const refetch = useCallback(
+        (newVariables = {}) => {
+            setState((state) =>
+                !state.called || !state.loading
+                    ? { called: true, loading: true }
+                    : state
+            )
+
+            if (singular) {
+                abort() // Cleanup any in-progress fetches
+            }
+            const controller = new AbortController()
+            abortControllersRef.current.push(controller)
+
+            variables.current = {
+                ...variables.current,
+                ...newVariables,
+            }
+
+            const options: QueryExecuteOptions = {
+                variables: variables.current,
+                signal: controller.signal,
+                onComplete,
+                onError,
+            }
+
+            return theExecute(options)
+                .then((data: ReturnType) => {
+                    if (!controller.signal.aborted) {
+                        setState({ called: true, loading: false, data })
+                        return data
+                    }
+                    return new Promise<ReturnType>(() => undefined) // Wait forever
+                })
+                .catch((error: FetchError) => {
+                    if (!controller.signal.aborted) {
+                        setState({ called: true, loading: false, error })
+                    }
+                    return new Promise<ReturnType>(() => undefined) // Don't throw errors in refetch promises, wait forever
+                })
+        },
+        [abort, onComplete, onError, singular, theExecute]
+    )
+
+    // Don't include immediate or refetch as deps, otherwise unintentional refetches
+    // may be triggered by changes to input, i.e. recreating the onComplete callback
+    useEffect(() => {
+        if (immediate) {
+            refetch()
+        }
+        return abort
+    }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+    return { refetch, abort: manualAbort, ...state }
+}

package/src/react/hooks/useStaticInput.test.ts

@@ -0,0 +1,101 @@
+import { renderHook, act } from '@testing-library/react'
+import { useStaticInput } from './useStaticInput'
+
+describe('useStaticInput', () => {
+    const originalWarn = console.warn
+    const mockWarn = jest.fn()
+    beforeEach(() => {
+        jest.clearAllMocks()
+        console.warn = mockWarn
+    })
+    afterEach(() => (console.warn = originalWarn))
+
+    it('Should pass without warnings on first render', () => {
+        const { result } = renderHook(() => useStaticInput(42))
+        expect(result.current[0]).toBe(42)
+        expect(mockWarn).not.toHaveBeenCalled()
+    })
+
+    it('Should refuse update on updated render', () => {
+        const { result, rerender } = renderHook(
+            ({ value }) => useStaticInput(value),
+            { initialProps: { value: 42 } }
+        )
+        expect(result.current[0]).toBe(42)
+        rerender({ value: 54 })
+        expect(mockWarn).not.toHaveBeenCalled()
+        expect(result.current[0]).toBe(42)
+    })
+
+    it('Should show a warning on updated render (with warn prop)', () => {
+        const { result, rerender } = renderHook(
+            ({ value }) => useStaticInput(value, { warn: true }),
+            { initialProps: { value: 42 } }
+        )
+        expect(result.current[0]).toBe(42)
+        rerender({ value: 54 })
+        expect(mockWarn).toHaveBeenCalled()
+        expect(mockWarn.mock.calls.pop()).toMatchInlineSnapshot(`
+            Array [
+              "The input should be static, don't create it within the render loop!",
+            ]
+        `)
+        expect(result.current[0]).toBe(42)
+    })
+
+    it('Should show custom name in warning if supplied', () => {
+        const { result, rerender } = renderHook(
+            ({ value }) =>
+                useStaticInput(value, { warn: true, name: 'TESTING THING' }),
+            { initialProps: { value: 42 } }
+        )
+        expect(result.current[0]).toBe(42)
+        rerender({ value: 54 })
+        expect(mockWarn).toHaveBeenCalled()
+        expect(mockWarn.mock.calls.pop()[0]).toMatch(/TESTING THING/g)
+        expect(result.current[0]).toBe(42)
+    })
+
+    it('Should update when explicitly set to update', async () => {
+        const { result, rerender } = renderHook(
+            ({ value }) => useStaticInput(value, { warn: true }),
+            {
+                initialProps: { value: 42 },
+            }
+        )
+        const [value, setValue] = result.current
+        expect(value).toBe(42)
+
+        act(() => {
+            setValue(54)
+        })
+
+        expect(result.current[0]).toBe(54)
+        expect(mockWarn).not.toHaveBeenCalled()
+
+        rerender({ value: 54 })
+        expect(result.current[0]).toBe(54)
+        expect(mockWarn).toHaveBeenCalled()
+
+        rerender({ value: 75 })
+        expect(result.current[0]).toBe(54)
+        expect(mockWarn).toHaveBeenCalledTimes(2)
+    })
+
+    it('Should support functional values', () => {
+        const fn = jest.fn()
+        const fn2 = jest.fn()
+        const { result, rerender } = renderHook(
+            ({ value }) => useStaticInput(value, { warn: true }),
+            {
+                initialProps: { value: fn },
+            }
+        )
+        expect(fn).not.toHaveBeenCalled()
+        expect(result.current[0]).toBe(fn)
+        result.current[0]()
+        expect(fn).toHaveBeenCalled()
+        rerender({ value: fn2 })
+        expect(result.current[0]).toBe(fn)
+    })
+})

package/src/react/hooks/useStaticInput.ts

@@ -0,0 +1,27 @@
+import React, { useState, useEffect, useRef, useDebugValue } from 'react'
+
+interface StaticInputOptions {
+    warn?: boolean
+    name?: string
+}
+export const useStaticInput = <T>(
+    staticValue: T,
+    { warn = false, name = 'input' }: StaticInputOptions = {}
+): [T, React.Dispatch<React.SetStateAction<T>>] => {
+    const originalValue = useRef(staticValue)
+    const [value, setValue] = useState<T>(() => originalValue.current)
+
+    useDebugValue(
+        value,
+        (debugValue) => `${name}: ${JSON.stringify(debugValue)}`
+    )
+
+    useEffect(() => {
+        if (warn && originalValue.current !== staticValue) {
+            console.warn(
+                `The ${name} should be static, don't create it within the render loop!`
+            )
+        }
+    }, [warn, staticValue, originalValue, name])
+    return [value, setValue]
+}

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export * from './components'
+export * from './hooks'

package/src/setupRTL.ts

@@ -0,0 +1,5 @@
+import '@testing-library/jest-dom'
+
+process.on('unhandledRejection', (err) => {
+    throw err
+})

package/src/types.ts

@@ -0,0 +1,72 @@
+import type {
+    DataEngine,
+    QueryExecuteOptions,
+    FetchError,
+    JsonValue,
+    QueryVariables,
+    QueryResult,
+} from '@dhis2/data-engine'
+
+export type { Mutation, Query } from '@dhis2/data-engine'
+
+export interface ContextType {
+    engine: DataEngine
+}
+
+export interface ContextInput {
+    baseUrl: string
+    apiVersion: number
+}
+
+export type ExecuteOptions = QueryExecuteOptions
+export type RefetchOptions = QueryVariables
+export type RefetchFunction<ReturnType> = (
+    options?: RefetchOptions
+) => Promise<ReturnType>
+export type QueryRefetchFunction = RefetchFunction<QueryResult>
+export type MutationFunction = RefetchFunction<JsonValue>
+
+export type ExecuteFunction<T> = (options: QueryExecuteOptions) => Promise<T>
+export interface ExecuteHookInput<ReturnType> {
+    execute: ExecuteFunction<ReturnType>
+    variables: QueryVariables
+    singular: boolean
+    immediate: boolean
+    transformData?: (data: JsonValue[]) => JsonValue
+    onComplete?: (data: any) => void
+    onError?: (error: FetchError) => void
+}
+
+export interface ExecuteHookResult<ReturnType> {
+    refetch: RefetchFunction<ReturnType>
+    abort: () => void
+    called: boolean
+    loading: boolean
+    error?: FetchError
+    data?: ReturnType
+}
+
+export interface QueryState<TQueryResult> {
+    called: boolean
+    loading: boolean
+    fetching: boolean
+    error?: FetchError
+    data?: TQueryResult
+}
+
+export interface QueryRenderInput<
+    TQueryResult = QueryResult,
+> extends QueryState<TQueryResult> {
+    engine: DataEngine
+    refetch: QueryRefetchFunction
+}
+
+export interface MutationState {
+    engine: DataEngine
+    called: boolean
+    loading: boolean
+    error?: FetchError
+    data?: JsonValue
+}
+
+export type MutationRenderInput = [MutationFunction, MutationState]

package/tsconfig.json

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