@dhis2/app-service-data 3.17.1 → 3.18.0-beta.2

package/README.md

@@ -9,3 +9,107 @@ This library is intended for use with the [DHIS2 Application Platform](https://g
 This package is internal to `@dhis2/app-runtime` and generally should not be installed independently.
 
 See [the docs](https://developers.dhis2.org/docs/app-runtime/getting-started) for more.
+
+## TypeScript — typed query responses
+
+`useDataQuery` infers the response type automatically from the query object. The default map covers all DHIS2 v43 metadata endpoints. Three patterns are supported:
+
+### 1. Default — v43 types, fully inferred
+
+Pass the query `as const` so TypeScript can see the literal resource name and field list. No type annotation needed.
+
+```ts
+import { useDataQuery } from '@dhis2/app-runtime'
+
+const { data } = useDataQuery({
+    dataElements: {
+        resource: 'dataElements',
+        params: { fields: ['id', 'name', 'valueType'] as const },
+    },
+} as const)
+
+// data?.dataElements.pager.page                   → number
+// data?.dataElements.dataElements[0].id           → string | undefined
+// data?.dataElements.dataElements[0].valueType    → ValueType  (enum, not just string)
+```
+
+`as const` on the fields array is what allows TypeScript to narrow the element type. Without it the response type is broader but still valid. Without `as const` on the outer object, resource names are not captured as literals and field narrowing is skipped entirely.
+
+### 2. Targeting a specific DHIS2 API version
+
+If the target instance runs an older DHIS2 version, build the result type from that version's paths. `paths` comes from the version-specific entry point; `DeriveResourceTypeMap` and `InferQueryResult` are version-agnostic and always come from `@dhis2/api-types/utils`:
+
+```ts
+import { useDataQuery } from '@dhis2/app-runtime'
+import type { paths } from '@dhis2/api-types/v42'
+import type {
+    DeriveResourceTypeMap,
+    InferQueryResult,
+} from '@dhis2/api-types/utils'
+
+const query = {
+    dataElements: {
+        resource: 'dataElements',
+        params: { fields: ['id', 'name', 'valueType'] as const },
+    },
+} as const
+
+type Result = InferQueryResult<typeof query, DeriveResourceTypeMap<paths>>
+
+const { data } = useDataQuery<typeof query, Result>(query)
+// data?.dataElements.dataElements[0].valueType → v42's ValueType
+```
+
+`@dhis2/api-types/v40`, `/v41`, `/v42`, and `/v43` are all available.
+
+### 3. Overriding the inferred type
+
+Pass an explicit result type as the second generic to opt out of inference entirely — useful for custom endpoints or when the inferred type needs to be shaped differently:
+
+```ts
+import { useDataQuery } from '@dhis2/app-runtime'
+
+type MyResult = {
+    dataElements: {
+        pager: {
+            page: number
+            pageCount: number
+            total: number
+            pageSize: number
+        }
+        dataElements: Array<{ id: string; name: string; valueType: string }>
+    }
+}
+
+const { data } = useDataQuery<typeof query, MyResult>(query)
+// data?.dataElements.dataElements[0] → { id: string; name: string; valueType: string }
+```
+
+### Tracker resources
+
+Tracker endpoints (`tracker/enrollments`, `tracker/trackedEntities`, etc.) resolve to `unknown` with the default map because the spec types their responses opaquely. Extend the map manually to cover them:
+
+```ts
+import { useDataQuery } from '@dhis2/app-runtime'
+import type { paths, TrackerEnrollment } from '@dhis2/api-types'
+import type {
+    DeriveResourceTypeMap,
+    InferQueryResult,
+} from '@dhis2/api-types/utils'
+
+type TrackerMap = DeriveResourceTypeMap<paths> & {
+    'tracker/enrollments': TrackerEnrollment
+}
+
+const query = {
+    enrollments: {
+        resource: 'tracker/enrollments',
+        params: { fields: ['enrollment', 'status'] as const },
+    },
+} as const
+
+type Result = InferQueryResult<typeof query, TrackerMap>
+
+const { data } = useDataQuery<typeof query, Result>(query)
+// data?.enrollments.enrollments[0].status → EnrollmentStatus
+```

package/build/cjs/react/hooks/useDataQuery.js

@@ -9,6 +9,10 @@ var _react = require("react");
 var _mergeAndCompareVariables = require("./mergeAndCompareVariables");
 var _useDataEngine = require("./useDataEngine");
 var _useStaticInput = require("./useStaticInput");
+// Pre-compute the default resource→item map once from the latest API version's paths type.
+// Consumers targeting an older DHIS2 version can pass an explicit TResult built with
+// InferQueryResult<typeof query, DeriveResourceTypeMap<v4xPaths>> as the second generic.
+
 const useDataQuery = (query, {
   onComplete: userOnSuccess,
   onError: userOnError,

package/build/es/react/hooks/useDataQuery.js

@@ -3,6 +3,11 @@ import { useState, useRef, useCallback, useDebugValue } from 'react';
 import { mergeAndCompareVariables } from './mergeAndCompareVariables';
 import { useDataEngine } from './useDataEngine';
 import { useStaticInput } from './useStaticInput';
+
+// Pre-compute the default resource→item map once from the latest API version's paths type.
+// Consumers targeting an older DHIS2 version can pass an explicit TResult built with
+// InferQueryResult<typeof query, DeriveResourceTypeMap<v4xPaths>> as the second generic.
+
 export const useDataQuery = (query, {
   onComplete: userOnSuccess,
   onError: userOnError,

package/build/types/react/hooks/useDataQuery.d.ts

@@ -1,3 +1,7 @@
-import type { Query, QueryOptions, QueryResult } from '@dhis2/data-engine';
+import type { paths } from '@dhis2/api-types';
+import type { DeriveResourceTypeMap, InferQueryResult } from '@dhis2/api-types/utils';
+import type { Query, QueryOptions } from '@dhis2/data-engine';
 import type { QueryRenderInput } from '../../types';
-export declare const useDataQuery: <TQueryResult = QueryResult>(query: Query, { onComplete: userOnSuccess, onError: userOnError, variables: initialVariables, lazy: initialLazy, }?: QueryOptions<TQueryResult>) => QueryRenderInput<TQueryResult>;
+type DefaultMap = DeriveResourceTypeMap<paths>;
+export declare const useDataQuery: <Q extends Query, TResult = InferQueryResult<Q, DefaultMap>>(query: Q, { onComplete: userOnSuccess, onError: userOnError, variables: initialVariables, lazy: initialLazy, }?: QueryOptions<TResult>) => QueryRenderInput<TResult>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2/app-service-data",
-    "version": "3.17.1",
+    "version": "3.18.0-beta.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,13 @@
         "coverage": "yarn test --coverage"
     },
     "dependencies": {
+        "@dhis2/api-types": "43.0.0-beta.a48b417",
         "@tanstack/react-query": "^4.36.1",
         "prop-types": "^15.7.2"
     },
     "peerDependencies": {
-        "@dhis2/app-service-config": "3.17.1",
-        "@dhis2/data-engine": "3.17.1",
+        "@dhis2/app-service-config": "3.18.0-beta.2",
+        "@dhis2/data-engine": "3.18.0-beta.2",
         "react": "^16.8.6 || ^18",
         "react-dom": "^16.8.6 || ^18"
     }

package/.gitignore

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

package/d2.config.js

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

package/jest.config.js

@@ -1,14 +0,0 @@
-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/src/__tests__/integration.test.tsx

@@ -1,80 +0,0 @@
-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

@@ -1,71 +0,0 @@
-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

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

package/src/react/components/CustomDataProvider.tsx

@@ -1,33 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,58 +0,0 @@
-/* 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

@@ -1,26 +0,0 @@
-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

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

package/src/react/context/DataContext.tsx

@@ -1,5 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

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