@dhis2/app-service-data 3.17.0 → 3.17.2

package/.gitignore

@@ -0,0 +1,5 @@
+# DHIS2 Platform
+node_modules
+.d2
+src/locales
+build

package/d2.config.js

@@ -0,0 +1,9 @@
+const config = {
+    type: 'lib',
+
+    entryPoints: {
+        lib: './src/index.ts',
+    },
+}
+
+module.exports = config

package/jest.config.js

@@ -0,0 +1,14 @@
+module.exports = {
+    collectCoverageFrom: [
+        'src/**/*.(js|jsx|ts|tsx)',
+        '!src/index.ts',
+        '!src/**/types/*',
+        '!src/**/types.ts',
+        '!src/engine/index.ts',
+        '!src/links/index.ts',
+        '!src/react/index.ts',
+    ],
+
+    // Setup react-testing-library
+    setupFilesAfterEnv: ['<rootDir>/src/setupRTL.ts'],
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2/app-service-data",
-    "version": "3.17.0",
+    "version": "3.17.2",
     "main": "./build/cjs/index.js",
     "module": "./build/es/index.js",
     "types": "./build/types/index.d.ts",
@@ -20,7 +20,7 @@
         "access": "public"
     },
     "files": [
-        "build/**"
+        "**"
     ],
     "scripts": {
         "build:types": "tsc --emitDeclarationOnly --outDir ./build/types",
@@ -33,12 +33,12 @@
         "coverage": "yarn test --coverage"
     },
     "dependencies": {
+        "@dhis2/data-engine": "3.17.2",
         "@tanstack/react-query": "^4.36.1",
         "prop-types": "^15.7.2"
     },
     "peerDependencies": {
-        "@dhis2/app-service-config": "3.17.0",
-        "@dhis2/data-engine": "3.17.0",
+        "@dhis2/app-service-config": "3.17.2",
         "react": "^16.8.6 || ^18",
         "react-dom": "^16.8.6 || ^18"
     }

package/src/__tests__/integration.test.tsx

@@ -0,0 +1,80 @@
+import { render, waitFor } from '@testing-library/react'
+import * as React from 'react'
+import { CustomDataProvider, DataQuery } from '../react'
+
+describe('<DataQuery />', () => {
+    it('should render without failing', async () => {
+        const data = {
+            answer: 42,
+        }
+        const wrapper = ({ children }: { children?: React.ReactNode }) => (
+            <CustomDataProvider data={data}>{children}</CustomDataProvider>
+        )
+        const renderFunction = jest.fn(() => null)
+
+        render(
+            <DataQuery query={{ answer: { resource: 'answer' } }}>
+                {renderFunction}
+            </DataQuery>,
+            { wrapper }
+        )
+
+        expect(renderFunction).toHaveBeenCalledTimes(1)
+        expect(renderFunction).toHaveBeenLastCalledWith(
+            expect.objectContaining({
+                called: true,
+                loading: true,
+            })
+        )
+
+        await waitFor(() => {
+            expect(renderFunction).toHaveBeenCalledTimes(2)
+            expect(renderFunction).toHaveBeenLastCalledWith(
+                expect.objectContaining({
+                    called: true,
+                    loading: false,
+                    data,
+                })
+            )
+        })
+    })
+
+    it('should render an error', async () => {
+        const expectedError = new Error('Something went wrong')
+        const data = {
+            test: () => {
+                throw expectedError
+            },
+        }
+        const wrapper = ({ children }: { children?: React.ReactNode }) => (
+            <CustomDataProvider data={data}>{children}</CustomDataProvider>
+        )
+        const renderFunction = jest.fn(() => null)
+
+        render(
+            <DataQuery query={{ test: { resource: 'test' } }}>
+                {renderFunction}
+            </DataQuery>,
+            { wrapper }
+        )
+
+        expect(renderFunction).toHaveBeenCalledTimes(1)
+        expect(renderFunction).toHaveBeenLastCalledWith(
+            expect.objectContaining({
+                called: true,
+                loading: true,
+            })
+        )
+
+        await waitFor(() => {
+            expect(renderFunction).toHaveBeenCalledTimes(2)
+            expect(renderFunction).toHaveBeenLastCalledWith(
+                expect.objectContaining({
+                    called: true,
+                    loading: false,
+                    error: expectedError,
+                })
+            )
+        })
+    })
+})

package/src/__tests__/mutations.test.tsx

@@ -0,0 +1,71 @@
+import { render, waitFor, act } from '@testing-library/react'
+import * as React from 'react'
+import { CustomDataProvider, DataMutation } from '../react'
+
+describe('<DataMutation />', () => {
+    it('should render without failing', async () => {
+        const endpointSpy = jest.fn(() => Promise.resolve(42))
+        const mutation = {
+            resource: 'answer',
+            type: 'create' as const,
+            data: {
+                question: '?',
+            },
+        }
+        const data = {
+            answer: endpointSpy,
+        }
+        const wrapper = ({ children }: { children?: React.ReactNode }) => (
+            <CustomDataProvider data={data}>{children}</CustomDataProvider>
+        )
+        const renderSpy: jest.Mock = jest.fn(() => null)
+        render(<DataMutation mutation={mutation}>{renderSpy}</DataMutation>, {
+            wrapper,
+        })
+
+        expect(endpointSpy).toHaveBeenCalledTimes(0)
+        expect(renderSpy).toHaveBeenCalledTimes(1)
+        expect(renderSpy).toHaveBeenLastCalledWith([
+            expect.any(Function),
+            expect.objectContaining({
+                called: false,
+                loading: false,
+                engine: expect.any(Object),
+            }),
+        ])
+
+        await act(async () => {
+            const firstRenderSpyCall = renderSpy.mock.calls[0]
+            const firstRenderSpyArgument = firstRenderSpyCall[0]
+            const [mutate] = firstRenderSpyArgument
+            await mutate()
+        })
+
+        waitFor(() => {
+            expect(endpointSpy).toHaveBeenCalledTimes(1)
+            expect(renderSpy).toHaveBeenCalledTimes(2)
+            expect(renderSpy).toHaveBeenLastCalledWith([
+                expect.any(Function),
+                expect.objectContaining({
+                    called: true,
+                    loading: true,
+                    engine: expect.any(Object),
+                }),
+            ])
+        })
+
+        waitFor(() => {
+            expect(endpointSpy).toHaveBeenCalledTimes(1)
+            expect(renderSpy).toHaveBeenCalledTimes(3)
+            expect(renderSpy).toHaveBeenLastCalledWith([
+                expect.any(Function),
+                expect.objectContaining({
+                    called: true,
+                    loading: false,
+                    data: { answer: 42 },
+                    engine: expect.any(Object),
+                }),
+            ])
+        })
+    })
+})

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './react'
+
+export { FetchError } from '@dhis2/data-engine'
+
+export type * from './types'

package/src/react/components/CustomDataProvider.tsx

@@ -0,0 +1,33 @@
+import { DataEngine, CustomDataLink } from '@dhis2/data-engine'
+import type { CustomData, CustomLinkOptions } from '@dhis2/data-engine'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import React from 'react'
+import { DataContext } from '../context/DataContext'
+import { queryClientOptions as queryClientDefaults } from './DataProvider'
+
+interface CustomProviderInput {
+    children: React.ReactNode
+    data: CustomData
+    options?: CustomLinkOptions
+    queryClientOptions?: any
+}
+
+export const CustomDataProvider = ({
+    children,
+    data,
+    options,
+    queryClientOptions = queryClientDefaults,
+}: CustomProviderInput): JSX.Element => {
+    const link = new CustomDataLink(data, options)
+    const engine = new DataEngine(link)
+    const queryClient = new QueryClient(queryClientOptions)
+    const context = { engine }
+
+    return (
+        <QueryClientProvider client={queryClient}>
+            <DataContext.Provider value={context}>
+                {children}
+            </DataContext.Provider>
+        </QueryClientProvider>
+    )
+}

package/src/react/components/DataMutation.tsx

@@ -0,0 +1,24 @@
+import type { Mutation, MutationOptions } from '@dhis2/data-engine'
+import { MutationRenderInput } from '../../types'
+import { useDataMutation } from '../hooks/useDataMutation'
+
+interface MutationInput extends MutationOptions {
+    mutation: Mutation
+    children: (input: MutationRenderInput) => any
+}
+
+export const DataMutation = ({
+    mutation,
+    onComplete,
+    onError,
+    variables,
+    children,
+}: MutationInput) => {
+    const mutationState = useDataMutation(mutation, {
+        onComplete,
+        onError,
+        variables,
+    })
+
+    return children(mutationState)
+}

package/src/react/components/DataProvider.test.tsx

@@ -0,0 +1,22 @@
+import { DataEngine, RestAPILink } from '@dhis2/data-engine'
+import { render } from '@testing-library/react'
+import React from 'react'
+import { DataContext } from '../context/DataContext'
+import { DataProvider } from './DataProvider'
+
+describe('DataProvider', () => {
+    it('Should pass a new engine and RestAPILink to consumers', () => {
+        const renderFunction = jest.fn()
+        render(
+            <DataProvider baseUrl="test" apiVersion={42}>
+                <DataContext.Consumer>{renderFunction}</DataContext.Consumer>
+            </DataProvider>
+        )
+
+        expect(renderFunction).toHaveBeenCalled()
+        const context = renderFunction.mock.calls.pop()[0]
+        expect(context).not.toBeUndefined()
+        expect(context.engine).toBeInstanceOf(DataEngine)
+        expect(context.engine.link).toBeInstanceOf(RestAPILink)
+    })
+})

package/src/react/components/DataProvider.tsx

@@ -0,0 +1,58 @@
+/* eslint-disable react/no-unused-prop-types */
+import { useConfig } from '@dhis2/app-service-config'
+import { DataEngine, RestAPILink } from '@dhis2/data-engine'
+import {
+    QueryClient,
+    QueryClientProvider,
+    type QueryClientConfig,
+} from '@tanstack/react-query'
+import React from 'react'
+import { DataContext } from '../context/DataContext'
+
+export interface ProviderInput {
+    baseUrl?: string
+    apiVersion?: number
+    children: React.ReactNode
+}
+
+export const queryClientOptions: QueryClientConfig = {
+    defaultOptions: {
+        queries: {
+            // Disable automatic error retries
+            retry: false,
+            // Retry on mount if query has errored
+            retryOnMount: true,
+            // Refetch on mount if data is stale
+            refetchOnMount: true,
+            // Don't refetch when the window regains focus
+            refetchOnWindowFocus: false,
+            // Don't refetch after connection issues
+            refetchOnReconnect: false,
+            // RQv4 uses 'online' as the default, which pauses queries without network connection.
+            // 'always' reestablishes behavior from v3, and lets requests fire when offline
+            // https://tanstack.com/query/latest/docs/framework/react/guides/network-mode
+            networkMode: 'always',
+        },
+    },
+}
+
+const queryClient = new QueryClient(queryClientOptions)
+
+export const DataProvider = (props: ProviderInput): JSX.Element => {
+    const config = {
+        ...useConfig(),
+        ...props,
+    }
+
+    const link = new RestAPILink(config)
+    const engine = new DataEngine(link)
+    const context = { engine }
+
+    return (
+        <QueryClientProvider client={queryClient}>
+            <DataContext.Provider value={context}>
+                {props.children}
+            </DataContext.Provider>
+        </QueryClientProvider>
+    )
+}

package/src/react/components/DataQuery.tsx

@@ -0,0 +1,26 @@
+import type { Query, QueryOptions } from '@dhis2/data-engine'
+import { QueryRenderInput } from '../../types'
+import { useDataQuery } from '../hooks/useDataQuery'
+
+interface QueryInput extends QueryOptions {
+    query: Query
+    children: (input: QueryRenderInput) => any
+}
+
+export const DataQuery = ({
+    query,
+    onComplete,
+    onError,
+    variables,
+    lazy,
+    children,
+}: QueryInput) => {
+    const queryState = useDataQuery(query, {
+        onComplete,
+        onError,
+        variables,
+        lazy,
+    })
+
+    return children(queryState)
+}

package/src/react/components/index.ts

@@ -0,0 +1,4 @@
+export { CustomDataProvider } from './CustomDataProvider'
+export { DataMutation } from './DataMutation'
+export { DataProvider } from './DataProvider'
+export { DataQuery } from './DataQuery'

package/src/react/context/DataContext.tsx

@@ -0,0 +1,5 @@
+import React from 'react'
+import { ContextType } from '../../types'
+import { defaultDataContext } from './defaultDataContext'
+
+export const DataContext = React.createContext<ContextType>(defaultDataContext)

package/src/react/context/defaultDataContext.test.ts

@@ -0,0 +1,46 @@
+import { defaultDataContext } from './defaultDataContext'
+
+describe('defaultContext', () => {
+    const originalError = console.error
+    const mockError = jest.fn()
+    beforeEach(() => {
+        jest.clearAllMocks()
+        console.error = mockError
+    })
+    afterEach(() => (console.error = originalError))
+
+    it('Should throw if query is called', () => {
+        const context = defaultDataContext
+        expect(
+            context.engine.query({
+                test: {
+                    resource: 'test',
+                },
+            })
+        ).rejects.toBeTruthy()
+
+        expect(mockError).toHaveBeenCalledTimes(1)
+        expect(mockError.mock.calls.pop()).toMatchInlineSnapshot(`
+            Array [
+              "DHIS2 data context must be initialized, please ensure that you include a <DataProvider> in your application",
+            ]
+        `)
+    })
+
+    it('Should throw and log if mutate is called', () => {
+        const context = defaultDataContext
+        expect(
+            context.engine.mutate({
+                type: 'create',
+                resource: 'test',
+                data: {},
+            })
+        ).rejects.toBeTruthy()
+        expect(mockError).toHaveBeenCalled()
+        expect(mockError.mock.calls.pop()).toMatchInlineSnapshot(`
+            Array [
+              "DHIS2 data context must be initialized, please ensure that you include a <DataProvider> in your application",
+            ]
+        `)
+    })
+})

package/src/react/context/defaultDataContext.ts

@@ -0,0 +1,9 @@
+import { DataEngine, ErrorLink } from '@dhis2/data-engine'
+
+const errorMessage =
+    'DHIS2 data context must be initialized, please ensure that you include a <DataProvider> in your application'
+
+const link = new ErrorLink(errorMessage)
+const engine = new DataEngine(link)
+
+export const defaultDataContext = { engine }

package/src/react/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useDataEngine } from './useDataEngine'
+export { useDataMutation } from './useDataMutation'
+export { useDataQuery } from './useDataQuery'

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

@@ -0,0 +1,65 @@
+import { mergeAndCompareVariables } from './mergeAndCompareVariables'
+import { stableVariablesHash } from './stableVariablesHash'
+jest.mock('./stableVariablesHash', () => ({
+    stableVariablesHash: (object: unknown) => JSON.stringify(object),
+}))
+
+const testVariables = {
+    question: 'What do you get when you multiply six by nine?',
+    answer: 42,
+}
+const testHash = stableVariablesHash(testVariables)
+
+describe('mergeAndCompareVariables', () => {
+    it('Should return previous variables and hash when no new variables are provided', () => {
+        expect(
+            mergeAndCompareVariables(testVariables, undefined, undefined)
+        ).toMatchObject({
+            identical: true,
+            mergedVariables: testVariables,
+            mergedVariablesHash: undefined,
+        })
+    })
+
+    it('Should return identical: true when merged variables are identical to old variables (without prev hash)', () => {
+        const newVariables = { answer: testVariables.answer }
+
+        expect(
+            mergeAndCompareVariables(testVariables, newVariables, undefined)
+        ).toMatchObject({
+            identical: true,
+            mergedVariables: testVariables,
+            mergedVariablesHash: testHash,
+        })
+    })
+
+    it('Should return identical: false with incorrect previous hash', () => {
+        const incorrectPreviousHash = 'IAmAHash'
+        const newVariables = { answer: 42 }
+
+        expect(
+            mergeAndCompareVariables(
+                testVariables,
+                newVariables,
+                incorrectPreviousHash
+            )
+        ).toMatchObject({
+            identical: false,
+            mergedVariables: testVariables,
+            mergedVariablesHash: testHash,
+        })
+    })
+
+    it('Should return identical: false when merged variables are different than old variables', () => {
+        const newVariables = { answer: 43 }
+        const expectedMergedVariables = { ...testVariables, ...newVariables }
+
+        expect(
+            mergeAndCompareVariables(testVariables, newVariables, testHash)
+        ).toMatchObject({
+            identical: false,
+            mergedVariables: expectedMergedVariables,
+            mergedVariablesHash: stableVariablesHash(expectedMergedVariables),
+        })
+    })
+})

package/src/react/hooks/mergeAndCompareVariables.ts

@@ -0,0 +1,32 @@
+import type { QueryVariables } from '@dhis2/data-engine'
+import { stableVariablesHash } from './stableVariablesHash'
+
+export const mergeAndCompareVariables = (
+    previousVariables?: QueryVariables,
+    newVariables?: QueryVariables,
+    previousHash?: string
+) => {
+    if (!newVariables) {
+        return {
+            identical: true,
+            mergedVariablesHash: previousHash,
+            mergedVariables: previousVariables,
+        }
+    }
+
+    // Use cached hash if it exists
+    const currentHash = previousHash || stableVariablesHash(previousVariables)
+
+    const mergedVariables = {
+        ...previousVariables,
+        ...newVariables,
+    }
+    const mergedVariablesHash = stableVariablesHash(mergedVariables)
+    const identical = currentHash === mergedVariablesHash
+
+    return {
+        identical,
+        mergedVariablesHash,
+        mergedVariables,
+    }
+}

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

@@ -0,0 +1,53 @@
+import { stableVariablesHash } from './stableVariablesHash'
+
+describe('stableVariablesHash', () => {
+    it('sorts objects before hashing', () => {
+        const one = {
+            a: {
+                one: 1,
+                two: 2,
+                three: 3,
+            },
+            b: [1, 2, 3],
+            c: 'c',
+        }
+        const two = {
+            c: 'c',
+            b: [1, 2, 3],
+            a: {
+                three: 3,
+                two: 2,
+                one: 1,
+            },
+        }
+
+        expect(stableVariablesHash(one)).toEqual(stableVariablesHash(two))
+    })
+
+    it('can handle primitives', () => {
+        const one = undefined
+        const two = 'string'
+        const three = 3
+        const four = null
+        const five = true
+
+        expect(stableVariablesHash(one)).toMatchInlineSnapshot(`undefined`)
+        expect(stableVariablesHash(two)).toMatchInlineSnapshot(`"\\"string\\""`)
+        expect(stableVariablesHash(three)).toMatchInlineSnapshot(`"3"`)
+        expect(stableVariablesHash(four)).toMatchInlineSnapshot(`"null"`)
+        expect(stableVariablesHash(five)).toMatchInlineSnapshot(`"true"`)
+    })
+
+    it('throws a clear error when the variables contain a circular reference', () => {
+        const unserializable: any = {
+            value: 'value',
+        }
+        unserializable.circular = unserializable
+
+        expect(() =>
+            stableVariablesHash(unserializable)
+        ).toThrowErrorMatchingInlineSnapshot(
+            `"Could not serialize variables. Make sure that the variables do not contain circular references and can be processed by JSON.stringify."`
+        )
+    })
+})

package/src/react/hooks/stableVariablesHash.ts

@@ -0,0 +1,56 @@
+function hasObjectPrototype(o: any): boolean {
+    return Object.prototype.toString.call(o) === '[object Object]'
+}
+
+export function isPlainObject(o: any): o is object {
+    if (!hasObjectPrototype(o)) {
+        return false
+    }
+
+    // If has modified constructor
+    const ctor = o.constructor
+    if (typeof ctor === 'undefined') {
+        return true
+    }
+
+    // If has modified prototype
+    const prot = ctor.prototype
+    if (!hasObjectPrototype(prot)) {
+        return false
+    }
+
+    // If constructor does not have an Object-specific method
+    if (!Object.prototype.hasOwnProperty.call(prot, 'isPrototypeOf')) {
+        return false
+    }
+
+    // Most likely a plain Object
+    return true
+}
+
+/**
+ * Hashes the value into a stable hash.
+ */
+
+export function stableVariablesHash(value: any): string {
+    let hash
+
+    try {
+        hash = JSON.stringify(value, (_, val) =>
+            isPlainObject(val)
+                ? Object.keys(val)
+                      .sort()
+                      .reduce((result: Record<string, unknown>, key) => {
+                          result[key] = (val as Record<string, unknown>)[key]
+                          return result
+                      }, {})
+                : val
+        )
+    } catch (e) {
+        throw new Error(
+            'Could not serialize variables. Make sure that the variables do not contain circular references and can be processed by JSON.stringify.'
+        )
+    }
+
+    return hash
+}