diff --git a/package.json b/package.json
index c67f64617..ae7ea7c43 100644
--- a/package.json
+++ b/package.json
@@ -60,7 +60,7 @@
"styled-jsx": "^4.0.1"
},
"dependencies": {
- "@dhis2/multi-calendar-dates": "^1.2.2",
+ "@dhis2/multi-calendar-dates": "^1.3.2",
"@dnd-kit/core": "^6.0.7",
"@dnd-kit/sortable": "^7.0.2",
"@dnd-kit/utilities": "^3.2.1",
@@ -81,6 +81,16 @@
"src",
"!src/**/__snapshots__/**",
"!src/**/__demo__/data/**",
+ "!src/__fixtures__/period-types/**",
+ "!src/__fixtures__/org-units/**",
+ "!src/__fixtures__/fakeOrgUnitServer.js",
+ "!src/__fixtures__/dataItemProfileMetadata.js",
+ "!src/__fixtures__/dataItemProfileOrgUnits.js",
+ "!build/*/__fixtures__/period-types/**",
+ "!build/*/__fixtures__/org-units/**",
+ "!build/*/__fixtures__/fakeOrgUnitServer.js",
+ "!build/*/__fixtures__/dataItemProfileMetadata.js",
+ "!build/*/__fixtures__/dataItemProfileOrgUnits.js",
"docs",
"CHANGELOG.md"
],
diff --git a/src/__demo__/DataItemProfile.reference.js b/src/__demo__/DataItemProfile.reference.js
new file mode 100644
index 000000000..e8e4bc17a
--- /dev/null
+++ b/src/__demo__/DataItemProfile.reference.js
@@ -0,0 +1,359 @@
+import PropTypes from 'prop-types'
+import React from 'react'
+
+export const STATUS_DEFINITIONS = [
+ [
+ 'full',
+ 'Compatible with all the item’s data sets and programs that apply to the selection: every value comes back (also repeated, from an earlier period, or where only some org units are assigned).',
+ 'Data element in a monthly data set, with aggregation enabled, requested quarterly',
+ 'Indicator whose components are all in data sets assigned at facility level, requested at district level',
+ ],
+ [
+ 'partial',
+ 'Compatible with only some of the item’s data sets and programs that apply to the selection: the others’ values are left out. For an item in several data sets or programs that differ, a selection whose periods or org units don’t all give a value, or a sum where some items give none (OPERAND_EMPTY). For an expression, computed from such an operand (OPERAND_PARTIAL).',
+ 'Data element in a Monday weekly and a Wednesday weekly data set, requested by Monday week',
+ 'Data element in a data set assigned at facility level and one assigned at district level, requested at a facility',
+ ],
+ [
+ 'none',
+ 'Compatible with none of the item’s data sets and programs that apply to the selection: no value comes back. For an indicator, one side gives no value at all (OPERAND_EMPTY).',
+ 'Data element in a monthly data set, requested weekly',
+ 'Data element in a data set assigned at district level, requested at a facility',
+ ],
+ [
+ 'unknown',
+ 'Can’t tell: see the reasons.',
+ 'Relative weeks when the weekly start setting is missing',
+ 'An org unit or group that isn’t loaded, or missing metadata',
+ ],
+]
+
+export const PERIOD_REASON_DEFINITIONS = [
+ [
+ 'OPERAND_EMPTY',
+ 'An operand gives no value: a sum misses it (it counts as 0), a side where all are missing has none (a ratio without its denominator).',
+ 'partial, none',
+ 'ANC 1 Coverage by week: ANC 1st visit is monthly',
+ ],
+ [
+ 'OPERAND_PARTIAL',
+ 'An expression computed from an operand that leaves values out: it can be off either way.',
+ 'partial',
+ 'An indicator over IDSR Measles by Monday week',
+ ],
+ [
+ 'PERIOD_TOO_SHORT',
+ 'The period is shorter than the period type of the data sets.',
+ 'partial, none',
+ 'ANC 1st visit (monthly) by week',
+ ],
+ [
+ 'PERIOD_TYPE_MISMATCH',
+ 'Another period type of the same length.',
+ 'partial, none',
+ 'IDSR Measles’ Wednesday weeks by Monday week',
+ ],
+ [
+ 'REPORTING_RATE_TOO_SHORT',
+ 'A reporting rate asked for a shorter period: a meaningless value.',
+ 'partial, none',
+ 'Child Health reporting rate by week',
+ ],
+ [
+ 'NO_EARLIER_PERIOD_VALUE',
+ 'FIRST or LAST data with no data period that counts for the period.',
+ 'partial, none',
+ 'Monthly LAST data on 1 January',
+ ],
+ [
+ 'REPEATED_VALUE',
+ 'The value of a longer data period, repeated (period aggregation AVERAGE).',
+ 'full, partial',
+ 'Total Population (yearly) by month',
+ ],
+ [
+ 'EARLIER_PERIOD_VALUE',
+ 'The value of an earlier data period (period aggregation FIRST or LAST).',
+ 'full, partial',
+ 'Monthly LAST data on 15 July: June’s value',
+ ],
+ [
+ 'PROFILE_UNKNOWN',
+ 'Missing metadata: see the profile’s reasons.',
+ 'unknown',
+ 'A data element in no data set',
+ ],
+ [
+ 'UNKNOWN_PERIOD',
+ 'The period id can’t be read.',
+ 'unknown',
+ 'A mistyped period id, like 2025X1',
+ ],
+ [
+ 'SETTING_MISSING',
+ 'A relative period’s type depends on a setting that wasn’t given, and its types disagree.',
+ 'unknown',
+ 'LAST_4_WEEKS on weekly data, weekly start unknown',
+ ],
+ [
+ 'UNSUPPORTED_VERSION',
+ 'The server version can’t answer it.',
+ 'unknown',
+ '2025NovQ1 on 2.40; a program indicator without period boundaries before 2.43',
+ ],
+]
+
+export const ORG_UNIT_REASON_DEFINITIONS = [
+ [
+ 'NOT_ASSIGNED',
+ 'Neither the org unit nor its ancestors are assigned.',
+ 'none',
+ 'An event program’s indicator at a facility the program isn’t assigned to',
+ ],
+ [
+ 'ASSIGNED_AT_HIGHER_LEVEL',
+ 'Assigned only at higher levels than the one asked: analytics never splits values down. Partial when another data set fills the org unit.',
+ 'none, partial',
+ 'A data set assigned at district level, requested by facility',
+ ],
+ [
+ 'STOPPED_BY_AGGREGATION_LEVEL',
+ 'The data element’s aggregation levels stop values from lower levels reaching the level asked. Partial when another data set fills the org unit.',
+ 'none, partial',
+ 'Facility data with aggregation level 2, requested by district',
+ ],
+ [
+ 'NO_ORG_UNITS_AT_LEVEL',
+ 'No org unit at the level asked under the parent org units, or no group member under them: analytics returns nothing there.',
+ 'none',
+ 'LEVEL-2 under a facility',
+ ],
+ [
+ 'EMPTY_GROUP',
+ 'An org unit group without members: analytics refuses it (E7143). Leave it out of the request.',
+ 'none',
+ 'A group whose members were all removed',
+ ],
+ [
+ 'PARTLY_ASSIGNED',
+ 'Assigned to only some org units at the deepest level: the others aren’t assigned, so nothing is left out.',
+ 'full',
+ 'ANC 1st visit in Sierra Leone: 1,159 of 1,166 facilities',
+ ],
+ [
+ 'ANY_ORG_UNIT',
+ 'A program indicator placed by registration or an org unit attribute: its values can be at any org unit, wherever its program is assigned.',
+ 'full',
+ 'A program indicator by registration org unit',
+ ],
+ [
+ 'UNKNOWN_ORG_UNIT',
+ 'The org unit, level or group isn’t loaded or can’t be read.',
+ 'unknown',
+ 'A mistyped id',
+ ],
+]
+
+const ReferenceTable = ({ title, columns, rows }) => (
+
+ {title}
+
+
+
+ {columns.map((column) => (
+ {column}
+ ))}
+
+
+
+ {rows.map(([code, ...cells]) => (
+
+
+ {code}
+
+ {cells.map((cell, i) => (
+ {cell}
+ ))}
+
+ ))}
+
+
+
+
+)
+
+ReferenceTable.propTypes = {
+ columns: PropTypes.arrayOf(PropTypes.string),
+ rows: PropTypes.arrayOf(PropTypes.arrayOf(PropTypes.string)),
+ title: PropTypes.string,
+}
+
+// The API a story shows, apart from the demo itself
+const NO_REFERENCES = []
+
+export const ApiPanel = ({
+ basedOn,
+ runs,
+ input,
+ signature,
+ summary,
+ returns,
+ uses,
+ references = NO_REFERENCES,
+}) => (
+
+ API
+ {signature}
+ {summary}
+
+ Based on
+ {basedOn}
+ Input
+
+ {input}
+
+ Runs
+ {runs}
+ Returns
+
+ {returns}
+
+ Uses
+
+ {uses}
+
+
+ {references.map((reference) => (
+
+)
+
+ApiPanel.propTypes = {
+ basedOn: PropTypes.string,
+ input: PropTypes.string,
+ references: PropTypes.arrayOf(
+ PropTypes.shape({
+ columns: PropTypes.arrayOf(PropTypes.string),
+ rows: PropTypes.arrayOf(PropTypes.arrayOf(PropTypes.string)),
+ title: PropTypes.string,
+ })
+ ),
+ returns: PropTypes.string,
+ runs: PropTypes.string,
+ signature: PropTypes.string,
+ summary: PropTypes.string,
+ uses: PropTypes.string,
+}
+
+export const DemoHeading = () => (
+
+ Demo
+
+
+)
+
+// The steps of a scenario, apart from the demo itself
+export const ScenarioPanel = ({ title, steps }) => (
+
+ Scenario
+ {title}
+
+ {steps.map(([text, code]) => (
+
+ {text} {code && {code}}
+
+ ))}
+
+
+
+)
+
+ScenarioPanel.propTypes = {
+ steps: PropTypes.arrayOf(PropTypes.arrayOf(PropTypes.string)),
+ title: PropTypes.string,
+}
diff --git a/src/__demo__/DataItemProfile.shared.js b/src/__demo__/DataItemProfile.shared.js
new file mode 100644
index 000000000..1e7cbab4b
--- /dev/null
+++ b/src/__demo__/DataItemProfile.shared.js
@@ -0,0 +1,164 @@
+import { DataProvider } from '@dhis2/app-runtime'
+import { ConfigProvider } from '@dhis2/app-service-config'
+import { CircularLoader, NoticeBox, Tag } from '@dhis2/ui'
+import PropTypes from 'prop-types'
+import React from 'react'
+
+/* Log in to the server in the same browser first. It must allow requests
+ * from Storybook (localhost:5000): this dev server does, the play instances
+ * don't. */
+export const BASE_URL = 'https://dev.im.dhis2.org/analytics-dev/'
+
+export const Wrapper = (story) => (
+
+
+ {story()}
+
+
+)
+
+// Sierra Leone demo items, one per case
+export const ITEMS = [
+ {
+ id: 'fbfJHSPpUQD',
+ dimensionItemType: 'DATA_ELEMENT',
+ name: 'ANC 1st visit (monthly, sum)',
+ },
+ {
+ id: 'fbfJHSPpUQD.pq2XI5kz2BY',
+ dimensionItemType: 'DATA_ELEMENT_OPERAND',
+ name: 'ANC 1st visit at facilities (category: Fixed)',
+ },
+ {
+ id: 'WUg3MYWQ7pt',
+ dimensionItemType: 'DATA_ELEMENT',
+ name: 'Total Population (yearly, averaged)',
+ },
+ {
+ id: 'YazgqXbizv1',
+ dimensionItemType: 'DATA_ELEMENT',
+ name: 'IDSR Measles (Monday and Wednesday weeks)',
+ },
+ {
+ id: 'Uvn6LCg7dVU',
+ dimensionItemType: 'INDICATOR',
+ name: 'ANC 1 Coverage (indicator over the population)',
+ },
+ {
+ id: 'BfMAe6Itzgt.REPORTING_RATE',
+ dimensionItemType: 'REPORTING_RATE',
+ name: 'Child Health reporting rate (monthly)',
+ },
+ {
+ id: 'GSae40Fyppf',
+ dimensionItemType: 'PROGRAM_INDICATOR',
+ name: 'Age at visit (program indicator)',
+ },
+ {
+ id: 'gKv1pdjF3wM',
+ dimensionItemType: 'INDICATOR',
+ name: 'Inpatient cases per 10 000 population (indicator over a program indicator)',
+ },
+ {
+ id: 'eBAyeGv0exc.vV9UWAZohSf',
+ dimensionItemType: 'PROGRAM_DATA_ELEMENT',
+ name: 'Weight in kg (program data element)',
+ },
+]
+
+export const SIERRA_LEONE = 'ImspTQPwCqd'
+// A district, and a facility without Reproductive Health (ANC 1st visit)
+export const BO = 'O6uvpzGd5pu'
+export const JUNCTIONLA_MCHP = 'QCnJDmNjQy0'
+
+export const splitList = (text) =>
+ text
+ .split(/[,\s]+/)
+ .map((value) => value.trim())
+ .filter(Boolean)
+
+const STATUS_TAG = {
+ full: { positive: true },
+ partial: { neutral: true },
+ none: { negative: true },
+ unknown: {},
+}
+
+const NO_REASONS = []
+
+export const Status = ({ status, reasons = NO_REASONS }) => (
+
+ {status}
+ {reasons.length > 0 && (
+ {reasons.join(', ')}
+ )}
+
+
+)
+
+Status.propTypes = {
+ reasons: PropTypes.arrayOf(PropTypes.string),
+ status: PropTypes.string,
+}
+
+export const Loading = () =>
+ {error.message}. Are you logged in to {BASE_URL} in this browser?
+
+)
+
+ErrorNotice.propTypes = { error: PropTypes.object }
+
+export const tableStyle = (
+
+)
diff --git a/src/__demo__/DataItemProfile.stories.js b/src/__demo__/DataItemProfile.stories.js
new file mode 100644
index 000000000..8ac1d72e3
--- /dev/null
+++ b/src/__demo__/DataItemProfile.stories.js
@@ -0,0 +1,414 @@
+import { Button, Checkbox, InputField } from '@dhis2/ui'
+import PropTypes from 'prop-types'
+import React, { useMemo, useState } from 'react'
+import { useDataItemProfiles } from '../components/DataItemProfile/useDataItemProfiles.js'
+import { readOrgUnitSelection } from '../modules/dataItemProfile/orgUnits/orgUnitSelection.js'
+import {
+ ApiPanel,
+ DemoHeading,
+ ORG_UNIT_REASON_DEFINITIONS,
+ PERIOD_REASON_DEFINITIONS,
+ STATUS_DEFINITIONS,
+} from './DataItemProfile.reference.js'
+import {
+ ErrorNotice,
+ BO,
+ ITEMS,
+ JUNCTIONLA_MCHP,
+ Loading,
+ SIERRA_LEONE,
+ splitList,
+ Status,
+ tableStyle,
+ Wrapper,
+} from './DataItemProfile.shared.js'
+
+export default {
+ title: 'DataItemProfile/Hooks',
+ decorators: [Wrapper],
+}
+
+// The status table with one example column: periods or org units
+const statusReference = (exampleColumn, exampleIndex) => ({
+ title: 'Compatibility statuses',
+ columns: ['Status', 'Meaning', exampleColumn],
+ rows: STATUS_DEFINITIONS.map(([status, meaning, ...examples]) => [
+ status,
+ meaning,
+ examples[exampleIndex],
+ ]),
+})
+
+// Event data comes from programs: it is placed in any period by its dates
+const isPlacedByDate = (profile) =>
+ !profile.unknown && profile.sources.every(({ program }) => program)
+
+const listWithSeveral = ({ hasSeveral }, values) =>
+ `${values.join(', ')}${hasSeveral ? ' (several)' : ''}`
+
+const describePeriodTypes = (profile) => {
+ const { assignedPeriodTypes } = profile
+
+ if (assignedPeriodTypes.types.length) {
+ return listWithSeveral(assignedPeriodTypes, assignedPeriodTypes.types)
+ }
+
+ return isPlacedByDate(profile) ? 'Event dates' : 'Unknown'
+}
+
+const describeShortestDirectType = (profile) => {
+ if (profile.assignedPeriodTypes.shortestDirectType) {
+ return profile.assignedPeriodTypes.shortestDirectType
+ }
+
+ return isPlacedByDate(profile) ? 'Any' : 'Unknown'
+}
+
+// The levels its data sets and programs are assigned at, deepest first
+const describeLevels = ({ assignedOrgUnitLevels }) =>
+ assignedOrgUnitLevels?.levels.length
+ ? listWithSeveral(assignedOrgUnitLevels, assignedOrgUnitLevels.levels)
+ : '–'
+
+/* How many org units at the deepest level assigned the data sets are
+ * assigned to, of how many when the coverage counted them */
+const Assignment = ({ assignment }) =>
+ assignment ? (
+
+ {assignment.assigned.toLocaleString('en')}
+ {assignment.total !== undefined &&
+ ` of ${assignment.total.toLocaleString('en')}`}{' '}
+ at level {assignment.level}
+
+
+ ) : null
+
+Assignment.propTypes = { assignment: PropTypes.object }
+
+// The item's name, its status when the profile is unknown, and the profile as JSON
+const ItemCells = ({ name, profile }) => (
+ <>
+
+ {name}
+ {profile.unknown && (
+
+ code)}
+ />
+
+ )}
+
+
+
+ Show
+ {JSON.stringify(profile, null, 2)}
+
+
+
+)
+
+ItemCells.propTypes = {
+ name: PropTypes.string,
+ profile: PropTypes.object,
+}
+
+// What a story judges is judged alone: this says so above its table
+const AloneNote = ({ children }) => (
+
+ {children}
+
+
+)
+
+AloneNote.propTypes = { children: PropTypes.node }
+
+const PERIOD_EXAMPLES = 0
+const ORG_UNIT_EXAMPLES = 1
+
+export const Periods = () => {
+ const [periodsText, setPeriodsText] = useState(
+ '2025W2, 202501, 2025Q1, 2025, LAST_12_MONTHS, LAST_4_WEEKS, Weekly'
+ )
+ const periods = useMemo(() => splitList(periodsText), [periodsText])
+ // No org units: periods need no request beyond the metadata
+ const {
+ loading,
+ error,
+ profiles,
+ relativePeriodTypes,
+ getDataItemCompatibility,
+ } = useDataItemProfiles(ITEMS)
+
+ return (
+
+ {tableStyle}
+
+
+
+ setPeriodsText(value)}
+ inputWidth="600px"
+ />
+
+ {loading &&
}
+ {error &&
}
+ {profiles && (
+ <>
+
+ Each period is judged alone, over all the item’s data
+ sets and programs, whatever the org units: where they
+ are assigned isn’t read here. Relative weeks:{' '}
+ {relativePeriodTypes.weeklyPeriodType ?? 'unknown'}.
+ Relative financial years:{' '}
+ {relativePeriodTypes.financialYearPeriodType ??
+ 'unknown'}
+ .
+
+
+
+
+ Item
+
+ Profile getDataItemProfile
+
+ {periods.length > 0 && (
+
+ Each period{' '}
+ getDataItemCompatibility
+
+ )}
+
+
+ JSON
+ Period types
+ Shortest direct type
+ {periods.map((period) => (
+ {period}
+ ))}
+
+
+
+ {ITEMS.map(({ id, name }) => {
+ const profile = profiles[id]
+ const { periods: results } =
+ getDataItemCompatibility(id, { periods })
+
+ return (
+
+ {describePeriodTypes(profile)}
+
+ {describeShortestDirectType(
+ profile
+ )}
+
+ {results.map((result) => (
+
+
+ ))}
+
+ )
+ })}
+
+
+
+ )}
+
+ {tableStyle}
+
+
+
+
setOrgUnitsDraft(value)}
+ onBlur={({ value }) => applyOrgUnits(value)}
+ inputWidth="600px"
+ />
+
+ {ORG_UNIT_SCENARIOS.map(([label, text]) => (
+ applyOrgUnits(text)}
+ >
+ {label}
+
+ ))}
+
+ setWithAssignmentTotals(checked)}
+ dense
+ />
+
+
+ {loading &&
}
+ {error &&
}
+ {profiles && (
+ <>
+
+ Each org unit, level or group is judged alone, over all
+ the item’s data sets and programs, whatever the periods:
+ their period types aren’t read here.
+
+
+
+
+ Item
+
+ Profile getDataItemProfile
+
+ {orgUnitItems.length > 0 && (
+
+ Each org unit{' '}
+ getDataItemCompatibility
+
+ )}
+
+
+ JSON
+ Org unit levels
+ {orgUnitItems.map((orgUnit) => (
+ {orgUnit}
+ ))}
+
+
+
+ {ITEMS.map(({ id, name }) => {
+ const profile = profiles[id]
+ const { orgUnits: results = [] } =
+ getDataItemCompatibility(id, { orgUnits })
+
+ return (
+
+ {describeLevels(profile)}
+ {results.map((result) => (
+
+
+ ))}
+
+ )
+ })}
+
+
+
+ )}
+
+
+
+ Period type
+ {items.map(({ id, name }) => (
+ {name}
+ ))}
+
+
+
+ {PICKER_PERIOD_TYPES.map((periodType) => (
+
+ {periodType}
+ {items.map(({ id }) => (
+
+
+ ))}
+
+ ))}
+
+
+)
+
+const formatCount = (count) => count.toLocaleString('en')
+
+// The total is there only when the org units were counted too (withAssignmentTotals)
+const describeAssignment = ({ assigned, total, level }, levels) => {
+ const levelName = levels.find((item) => item.level === level)?.name
+ const counts =
+ total === undefined
+ ? formatCount(assigned)
+ : `${formatCount(assigned)} of ${formatCount(total)}`
+
+ return `${counts} org units at level ${levelName ?? level}`
+}
+
+const ORG_UNIT_NONE_ADVICE = {
+ ASSIGNED_AT_HIGHER_LEVEL:
+ 'Not shown: its data sets are assigned at a higher level.',
+ STOPPED_BY_AGGREGATION_LEVEL:
+ 'Not shown: its aggregation levels stop values before this level.',
+ EMPTY_GROUP: 'Leave it out: the group has no members.',
+ NO_ORG_UNITS_AT_LEVEL: 'Not shown: no org unit at this level there.',
+}
+
+const getFullAdvice = (reasons, assignment, levels) => {
+ if (reasons.includes('ANY_ORG_UNIT') || !assignment) {
+ return 'Shown.'
+ }
+
+ const assignedTo = describeAssignment(assignment, levels)
+
+ return reasons.includes('PARTLY_ASSIGNED')
+ ? `Shown: assigned to ${assignedTo}; the others aren’t assigned.`
+ : `Shown: assigned to ${assignedTo}.`
+}
+
+// What DV could say about an item, for one org unit selection item
+const orgUnitAdviceFor = ({ status, reasons, assignment }, levels) => {
+ switch (status) {
+ case 'full':
+ return getFullAdvice(reasons, assignment, levels)
+ case 'partial':
+ return reasons.includes('OPERAND_PARTIAL')
+ ? 'Shown, but computed from incomplete data: it can be off either way.'
+ : 'Partly shown: values of data sets assigned at a higher level are left out.'
+ case 'none': {
+ const reason = reasons.find((code) => ORG_UNIT_NONE_ADVICE[code])
+
+ return reason
+ ? ORG_UNIT_NONE_ADVICE[reason]
+ : 'Not shown: its data sets aren’t assigned here.'
+ }
+ default:
+ return 'Can’t tell.'
+ }
+}
+
+const OrgUnitLevelMarks = ({ items, levels, getDataItemCompatibility }) => (
+
+
+
+ Level
+ {items.map(({ id, name }) => (
+ {name}
+ ))}
+
+
+
+ {levels.map(({ level, name }) => (
+
+ {name}
+ {items.map(({ id }) => (
+
+
+ ))}
+
+ ))}
+
+
+)
+
+OrgUnitLevelMarks.propTypes = {
+ getDataItemCompatibility: PropTypes.func,
+ items: PropTypes.array,
+ levels: PropTypes.array,
+}
+
+PeriodTypeMarks.propTypes = {
+ getDataItemCompatibility: PropTypes.func,
+ items: PropTypes.array,
+}
+
+// One column per dimension
+const Columns = ({ period, orgUnit }) => (
+
+
+
+ Org unit
+ {orgUnit ?? Coming soon.
}
+
+
+
+ Past data may have been entered with a different configuration.
+
+)
+
+export const TypicalUse = () => {
+ const [selectedIds, setSelectedIds] = useState([
+ 'fbfJHSPpUQD',
+ 'Uvn6LCg7dVU',
+ 'YazgqXbizv1',
+ ])
+ const [periodsText, setPeriodsText] = useState('2025W2')
+ const [orgUnitsText, setOrgUnitsText] = useState(SIERRA_LEONE)
+ const items = useMemo(
+ () => ITEMS.filter(({ id }) => selectedIds.includes(id)),
+ [selectedIds]
+ )
+ const periods = useMemo(() => splitList(periodsText), [periodsText])
+ const orgUnits = useMemo(() => splitList(orgUnitsText), [orgUnitsText])
+ // The country, for the levels in the picker, and the org units selected
+ const loadedOrgUnits = useMemo(
+ () => [...new Set([SIERRA_LEONE, ...orgUnits])],
+ [orgUnits]
+ )
+ const {
+ loading,
+ error,
+ profiles,
+ orgUnitCoverage,
+ getDataItemCompatibility,
+ } = useDataItemProfiles(items, { orgUnits: loadedOrgUnits })
+ // While a newly picked item loads, the others keep their profiles
+ const loadedItems = items.filter(({ id }) => profiles?.[id])
+
+ const toggle = (id) =>
+ setSelectedIds((ids) =>
+ ids.includes(id)
+ ? ids.filter((other) => other !== id)
+ : [...ids, id]
+ )
+ return (
+
+ {tableStyle}
+
+
+
Data items
+ {ITEMS.map(({ id, name }) => (
+
toggle(id)}
+ />
+ ))}
+ {loading && Pickers
+ Selected, before Update
+
+
+
+ setPeriodsText(value)
+ }
+ />
+
+
+
+ {loadedItems.map(({ id, name }) => (
+
+ {name}
+
+ {getDataItemCompatibility(
+ id,
+ { periods }
+ )?.periods.map((result) => (
+
+
+ {result.id}
+ {' '}
+
+ ))}
+
+
+ ))}
+
+
+
+ }
+ orgUnit={
+ <>
+
+
+ setOrgUnitsText(value)
+ }
+ />
+
+
+
+ {loadedItems.map(({ id, name }) => (
+
+ {name}
+
+ {orgUnitCoverage
+ ? getDataItemCompatibility(
+ id,
+ { orgUnits }
+ )?.orgUnits?.map(
+ (result) => (
+
+
+ {
+ result.id
+ }
+ {' '}
+
+ )
+ )
+ : null}
+
+
+ ))}
+
+
+
+ }
+ />
+
+ )}
+ {children}
+ )
+ Wrapper.propTypes = { children: PropTypes.node }
+
+ return Wrapper
+}
+
+const MONTHLY = { id: 'monthly', dimensionItemType: 'DATA_ELEMENT' }
+const WEEKLY = { id: 'weekly', dimensionItemType: 'DATA_ELEMENT' }
+const COVERAGE = { id: 'coverage', dimensionItemType: 'INDICATOR' }
+
+describe('useDataItemProfiles', () => {
+ const renderProfiles = (items, data = createData(), options) =>
+ renderHook((props) => useDataItemProfiles(props, options), {
+ initialProps: items,
+ wrapper: createWrapper(data),
+ })
+
+ it('loads the profile of each item', async () => {
+ const { result } = renderProfiles([MONTHLY, COVERAGE])
+
+ expect(result.current.loading).toBe(true)
+
+ await waitFor(() => expect(result.current.loading).toBe(false))
+
+ expect(result.current.error).toBeUndefined()
+ expect(result.current.profiles.monthly).toMatchObject({
+ unknown: false,
+ assignedPeriodTypes: { shortestDirectType: 'Monthly' },
+ })
+ expect(result.current.profiles.coverage).toMatchObject({
+ assignedPeriodTypes: {
+ types: ['Monthly', 'Yearly'],
+ shortestDirectType: 'Yearly',
+ hasSeveral: true,
+ },
+ })
+ })
+
+ it('checks periods, with the settings for relative periods', async () => {
+ const { result } = renderProfiles([WEEKLY])
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+
+ expect(result.current.relativePeriodTypes).toEqual({
+ weeklyPeriodType: 'Weekly',
+ financialYearPeriodType: 'FinancialOct',
+ })
+ expect(
+ result.current.getDataItemCompatibility('weekly', {
+ periods: ['LAST_4_WEEKS', '202501'],
+ })
+ ).toMatchObject({
+ status: 'full',
+ periods: [
+ { status: 'full', alignsWithData: null },
+ { status: 'full', alignsWithData: false },
+ ],
+ })
+ expect(
+ result.current.getDataItemCompatibility('weekly', {
+ periods: ['20250115'],
+ }).status
+ ).toBe('none')
+ expect(
+ result.current.getDataItemCompatibility('other', {
+ periods: ['202501'],
+ })
+ ).toBe(undefined)
+ })
+
+ it('judges org units from where data sets are assigned', async () => {
+ const assigned = [{ id: 'assigned', dimensionItemType: 'DATA_ELEMENT' }]
+ const resultAt = async (options) => {
+ const { result } = renderProfiles(assigned, createData(), {
+ orgUnits: ['nationUnit1'],
+ ...options,
+ })
+
+ await waitFor(() =>
+ expect(result.current.orgUnitCoverage).toBeDefined()
+ )
+ expect(result.current.loading).toBe(false)
+
+ return result.current.getDataItemCompatibility('assigned', {
+ orgUnits: ['nationUnit1'],
+ }).orgUnits[0]
+ }
+
+ expect(await resultAt()).toEqual({
+ id: 'nationUnit1',
+ status: 'full',
+ reasons: [],
+ assignment: { assigned: 2, level: 1 },
+ })
+ expect(await resultAt({ withAssignmentTotals: true })).toEqual({
+ id: 'nationUnit1',
+ status: 'full',
+ reasons: ['PARTLY_ASSIGNED'],
+ assignment: { assigned: 2, total: 3, level: 1 },
+ })
+ })
+
+ it('gives profiles their assigned org unit levels once org units are loaded', async () => {
+ const assigned = [{ id: 'assigned', dimensionItemType: 'DATA_ELEMENT' }]
+ const withoutOrgUnits = renderProfiles(assigned)
+
+ await waitFor(() =>
+ expect(withoutOrgUnits.result.current.profiles).toBeDefined()
+ )
+
+ expect(
+ withoutOrgUnits.result.current.profiles.assigned
+ .assignedOrgUnitLevels
+ ).toBeUndefined()
+
+ const withOrgUnits = renderProfiles(assigned, createData(), {
+ orgUnits: ['nationUnit1'],
+ })
+
+ await waitFor(() =>
+ expect(withOrgUnits.result.current.orgUnitCoverage).toBeDefined()
+ )
+
+ expect(
+ withOrgUnits.result.current.profiles.assigned.assignedOrgUnitLevels
+ ).toEqual({
+ levels: [1],
+ deepestLevel: 1,
+ hasSeveral: false,
+ })
+ })
+
+ it('gives the error of a failed org unit request', async () => {
+ const { result } = renderProfiles(
+ [{ id: 'assigned', dimensionItemType: 'DATA_ELEMENT' }],
+ createData({
+ organisationUnits: { organisationUnits: [] },
+ organisationUnitLevels: () =>
+ Promise.reject(new Error('no levels')),
+ }),
+ { orgUnits: ['nationUnit1'] }
+ )
+
+ await waitFor(() => expect(result.current.error).toBeDefined())
+
+ expect(result.current.error.message).toBe('no levels')
+ expect(result.current.orgUnitCoverage).toBeUndefined()
+ })
+
+ it('is unknown for relative weeks on a version without the setting', async () => {
+ const data = createData({
+ 'systemSettings/analyticsWeeklyStart': () =>
+ Promise.reject(
+ Object.assign(new Error('Setting does not exist'), {
+ details: { httpStatusCode: 404 },
+ })
+ ),
+ })
+ const { result } = renderProfiles([WEEKLY], data)
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+
+ expect(result.current.relativePeriodTypes.weeklyPeriodType).toBe(
+ undefined
+ )
+ expect(
+ result.current.getDataItemCompatibility('weekly', {
+ periods: ['LAST_4_WEEKS'],
+ }).status
+ ).toBe('unknown')
+ })
+
+ it('is unknown for an item the server does not have', async () => {
+ const { result } = renderProfiles([
+ { id: 'gone', dimensionItemType: 'DATA_ELEMENT' },
+ ])
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+
+ expect(result.current.profiles.gone).toMatchObject({
+ unknown: true,
+ reasons: [{ code: 'MISSING_METADATA', id: 'gone' }],
+ })
+ expect(
+ result.current.getDataItemCompatibility('gone', {
+ periods: ['202501'],
+ }).status
+ ).toBe('unknown')
+ })
+
+ it('gives the error of a failed request', async () => {
+ const { result } = renderProfiles(
+ [MONTHLY],
+ createData({
+ dataElements: () => Promise.reject(new Error('offline')),
+ })
+ )
+
+ await waitFor(() => expect(result.current.loading).toBe(false))
+
+ expect(result.current.error.message).toBe('offline')
+ expect(result.current.profiles).toBeUndefined()
+ })
+
+ it('sends nothing without items, but the settings', async () => {
+ const data = createData()
+ const { result } = renderProfiles([], data)
+
+ expect(result.current).toMatchObject({
+ loading: false,
+ profiles: undefined,
+ })
+
+ await waitFor(() =>
+ expect(result.current.relativePeriodTypes.weeklyPeriodType).toBe(
+ 'Weekly'
+ )
+ )
+
+ expect(data.dataElements).not.toHaveBeenCalled()
+ })
+
+ it('sends nothing again for the same items in a new array', async () => {
+ const data = createData()
+ const { result, rerender } = renderProfiles([MONTHLY], data)
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+ rerender([{ ...MONTHLY }])
+
+ expect(result.current.loading).toBe(false)
+ expect(data.dataElements).toHaveBeenCalledTimes(1)
+ })
+
+ it('loads again when the items change, and drops a stale answer', async () => {
+ const { result, rerender } = renderProfiles([MONTHLY])
+
+ rerender([WEEKLY])
+
+ await waitFor(() =>
+ expect(result.current.profiles?.weekly).toBeDefined()
+ )
+
+ expect(result.current.profiles.monthly).toBeUndefined()
+ })
+
+ it('keeps the loaded profiles while new items load, and fetches only those', async () => {
+ const data = createData()
+ const { result, rerender } = renderProfiles([MONTHLY], data)
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+
+ const monthlyProfile = result.current.profiles.monthly
+
+ rerender([MONTHLY, WEEKLY])
+
+ expect(result.current.loading).toBe(true)
+ expect(result.current.profiles).toEqual({ monthly: monthlyProfile })
+
+ await waitFor(() =>
+ expect(result.current.profiles?.weekly).toMatchObject({
+ unknown: false,
+ })
+ )
+
+ const filters = data.dataElements.mock.calls.map(
+ ([, { params }]) => params.filter
+ )
+
+ expect(filters[1]).toContain('weekly')
+ expect(filters[1]).not.toContain('monthly')
+ })
+
+ it('fetches the settings once', async () => {
+ const settings = jest.fn(() => ({ analyticsWeeklyStart: 'WEEKLY' }))
+ const { result, rerender } = renderProfiles(
+ [MONTHLY],
+ createData({ 'systemSettings/analyticsWeeklyStart': settings })
+ )
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+ rerender([WEEKLY])
+ await waitFor(() =>
+ expect(result.current.profiles?.weekly).toBeDefined()
+ )
+
+ expect(settings).toHaveBeenCalledTimes(1)
+ })
+
+ it('gives the error of a failed setting request', async () => {
+ const { result } = renderProfiles(
+ [MONTHLY],
+ createData({
+ 'systemSettings/analyticsWeeklyStart': () =>
+ Promise.reject(new Error('Unauthorized')),
+ })
+ )
+
+ await waitFor(() => expect(result.current.error).toBeDefined())
+
+ expect(result.current.error.message).toBe('Unauthorized')
+ })
+
+ it('gives the same result for the same selection', async () => {
+ const { result } = renderProfiles([MONTHLY])
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+
+ const check = () =>
+ result.current.getDataItemCompatibility('monthly', {
+ periods: ['202501'],
+ })
+
+ expect(check()).toBe(check())
+ })
+
+ it('gives no coverage of earlier org units while new ones load', async () => {
+ const { result, rerender } = renderHook(
+ ({ orgUnits }) =>
+ useDataItemProfiles(
+ [{ id: 'assigned', dimensionItemType: 'DATA_ELEMENT' }],
+ { orgUnits }
+ ),
+ {
+ initialProps: { orgUnits: ['nationUnit1'] },
+ wrapper: createWrapper(createData()),
+ }
+ )
+
+ await waitFor(() =>
+ expect(result.current.orgUnitCoverage).toBeDefined()
+ )
+
+ rerender({ orgUnits: ['LEVEL-1'] })
+
+ expect(result.current.orgUnitCoverage).toBeUndefined()
+
+ await waitFor(() =>
+ expect(result.current.orgUnitCoverage).toBeDefined()
+ )
+
+ expect(
+ result.current.orgUnitCoverage.orgUnits.nationUnit1
+ ).toBeDefined()
+ })
+
+ it('ignores a failure that came after the items changed', async () => {
+ let rejectFirst
+ const data = createData({
+ dataElements: jest
+ .fn()
+ .mockImplementationOnce(
+ () =>
+ new Promise((_, reject) => {
+ rejectFirst = reject
+ })
+ )
+ .mockImplementation(byIdFilter('dataElements')),
+ })
+ const { result, rerender } = renderProfiles([MONTHLY], data)
+
+ await waitFor(() => expect(rejectFirst).toBeDefined())
+ rerender([WEEKLY])
+ await waitFor(() =>
+ expect(result.current.profiles?.weekly).toBeDefined()
+ )
+ await act(async () => rejectFirst(new Error('late')))
+
+ expect(result.current.error).toBeUndefined()
+ })
+
+ it('passes the server version: 2.40 has no QuarterlyNov', async () => {
+ mockConfig = { systemInfo: {}, serverVersion: { major: 2, minor: 40 } }
+ const { result } = renderProfiles([MONTHLY])
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+
+ expect(
+ result.current.getDataItemCompatibility('monthly', {
+ periods: ['2025NovQ1'],
+ }).status
+ ).toBe('unknown')
+ expect(
+ result.current.getDataItemCompatibility('monthly', {
+ periods: ['2025Q1'],
+ }).status
+ ).toBe('full')
+ })
+
+ it('uses the system calendar', async () => {
+ mockConfig = { systemInfo: { calendar: 'nepali' } }
+ const { result } = renderProfiles([MONTHLY])
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+
+ expect(
+ result.current.getDataItemCompatibility('monthly', {
+ periods: ['2081Q1'],
+ }).periods[0].alignsWithData
+ ).toBe(true)
+ })
+
+ it('uses the calendar it is given', async () => {
+ const { result } = renderProfiles([MONTHLY], createData(), {
+ calendar: 'nepali',
+ })
+
+ await waitFor(() => expect(result.current.profiles).toBeDefined())
+
+ expect(
+ result.current.getDataItemCompatibility('monthly', {
+ periods: ['2081Q1'],
+ }).periods[0].alignsWithData
+ ).toBe(true)
+ })
+})
diff --git a/src/components/DataItemProfile/__tests__/utils.spec.js b/src/components/DataItemProfile/__tests__/utils.spec.js
new file mode 100644
index 000000000..53e73dbd0
--- /dev/null
+++ b/src/components/DataItemProfile/__tests__/utils.spec.js
@@ -0,0 +1,85 @@
+import {
+ fetchRelativePeriodTypeOptions,
+ getItemsKey,
+ parseItemsKey,
+} from '../utils.js'
+
+const settingsEngine = (settings) => ({
+ query: jest.fn(async ({ setting }) => {
+ const key = setting.resource.split('/')[1]
+
+ if (!(key in settings)) {
+ throw Object.assign(new Error('Setting does not exist'), {
+ details: { httpStatusCode: 404 },
+ })
+ }
+
+ return { setting: { [key]: settings[key] } }
+ }),
+})
+
+describe('fetchRelativePeriodTypeOptions', () => {
+ it('reads the period types of relative weeks and financial years from the settings', async () => {
+ expect(
+ await fetchRelativePeriodTypeOptions(
+ settingsEngine({
+ analyticsWeeklyStart: 'WEEKLY_WEDNESDAY',
+ analyticsFinancialYearStart: 'FINANCIAL_YEAR_APRIL',
+ })
+ )
+ ).toEqual({
+ weeklyPeriodType: 'WeeklyWednesday',
+ financialYearPeriodType: 'FinancialApril',
+ })
+ })
+
+ it('leaves out a setting the server doesn’t have', async () => {
+ expect(
+ await fetchRelativePeriodTypeOptions(
+ settingsEngine({ analyticsWeeklyStart: 'WEEKLY' })
+ )
+ ).toEqual({
+ weeklyPeriodType: 'Weekly',
+ financialYearPeriodType: undefined,
+ })
+ })
+
+ it('fails on any other error', async () => {
+ const engine = {
+ query: jest.fn().mockRejectedValue(new Error('Unauthorized')),
+ }
+
+ await expect(fetchRelativePeriodTypeOptions(engine)).rejects.toThrow(
+ 'Unauthorized'
+ )
+ })
+})
+
+describe('items keys', () => {
+ it('compare items by value, and read them back', () => {
+ const items = [{ id: 'elementAAAA', dimensionItemType: 'DATA_ELEMENT' }]
+ const key = getItemsKey(items)
+
+ expect(getItemsKey([...items])).toBe(key)
+ expect(parseItemsKey(key)).toEqual(items)
+ })
+
+ it('ignore the order of items', () => {
+ const elementA = {
+ id: 'elementAAAA',
+ dimensionItemType: 'DATA_ELEMENT',
+ }
+ const elementB = {
+ id: 'elementBBBB',
+ dimensionItemType: 'DATA_ELEMENT',
+ }
+
+ expect(getItemsKey([elementB, elementA])).toBe(
+ getItemsKey([elementA, elementB])
+ )
+ })
+
+ it('accept no items', () => {
+ expect(getItemsKey()).toBe('[]')
+ })
+})
diff --git a/src/components/DataItemProfile/useDataItemProfiles.js b/src/components/DataItemProfile/useDataItemProfiles.js
new file mode 100644
index 000000000..06113a0e3
--- /dev/null
+++ b/src/components/DataItemProfile/useDataItemProfiles.js
@@ -0,0 +1,293 @@
+import { useConfig } from '@dhis2/app-runtime'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { getDataItemProfileSourceKeys } from '../../api/dataItemProfile/assignedOrgUnitCounts.js'
+import { fetchDataItemProfileMetadata } from '../../api/dataItemProfile/fetchDataItemProfileMetadata.js'
+import { fetchOrgUnitCoverage } from '../../api/dataItemProfile/fetchOrgUnitCoverage.js'
+import { getDataItemProfile } from '../../modules/dataItemProfile/getDataItemProfile.js'
+import { getDataItemProfileCompatibility } from '../../modules/dataItemProfile/getDataItemProfileCompatibility.js'
+import { addAssignedOrgUnitLevels } from '../../modules/dataItemProfile/profile/assignedOrgUnitLevels.js'
+import {
+ fetchRelativePeriodTypeOptions,
+ getItemsKey,
+ parseItemsKey,
+ useCalendar,
+ useEngineRef,
+} from './utils.js'
+
+/**
+ * The profiles of data items, and whether a selection suits them.
+ *
+ * `items` are { id, dimensionItemType }, as in a visualization's dx items.
+ * `profiles` are keyed by item id. Once `orgUnits` are given and their
+ * coverage is loaded, each also has its assigned org unit levels.
+ *
+ * `getDataItemCompatibility(itemId, { periods, orgUnits })` runs
+ * getDataItemProfileCompatibility on the item's profile, with the server's
+ * settings for relative weeks and financial years, its calendar and its
+ * version, and `relativePeriodDate` for relative periods (today by default);
+ * it gives undefined for an item not loaded. Its results are kept until the
+ * profiles or options change.
+ *
+ * Periods need no request, so they are only passed to
+ * getDataItemCompatibility. Org units do: `orgUnits` (DV's org unit items)
+ * loads where the items' data sets and programs are assigned under them
+ * (fetchOrgUnitCoverage, `orgUnitCoverage`), so getDataItemCompatibility can
+ * judge any selection whose org units it loaded, such as a level under one of
+ * them. `withAssignmentTotals` also counts the org units under them, for "x
+ * of y" and PARTLY_ASSIGNED (fetchOrgUnitCoverage).
+ *
+ * Changes fetch only what is missing: metadata of new items, counts of new
+ * org units. While new items load, the loaded ones keep their profiles.
+ */
+export const useDataItemProfiles = (
+ items,
+ {
+ calendar,
+ orgUnits,
+ relativePeriodDate,
+ withAssignmentTotals = false,
+ } = {}
+) => {
+ const engineRef = useEngineRef()
+ const itemsKey = getItemsKey(items)
+ const resolvedCalendar = useCalendar(calendar)
+ const { serverVersion } = useConfig()
+ const [settingsState, setSettingsState] = useState({
+ loading: true,
+ error: undefined,
+ options: {},
+ })
+ const [state, setState] = useState({
+ loading: false,
+ error: undefined,
+ metadata: undefined,
+ metadataItemsKey: undefined,
+ })
+ const [coverageState, setCoverageState] = useState({
+ loading: false,
+ error: undefined,
+ coverage: undefined,
+ coverageKey: undefined,
+ })
+ const metadataRef = useRef()
+ const coverageRef = useRef()
+ const orgUnitsKey = JSON.stringify(orgUnits ?? [])
+
+ metadataRef.current = state.metadata
+ coverageRef.current = coverageState.coverage
+
+ // The settings don't change with the items: fetched once
+ useEffect(() => {
+ const controller = new AbortController()
+
+ fetchRelativePeriodTypeOptions(engineRef.current, {
+ signal: controller.signal,
+ })
+ .then((options) => setSettingsState({ loading: false, options }))
+ .catch((error) => {
+ if (!controller.signal.aborted) {
+ setSettingsState({ loading: false, error, options: {} })
+ }
+ })
+
+ return () => controller.abort()
+ }, [engineRef])
+
+ useEffect(() => {
+ const requestedItems = parseItemsKey(itemsKey)
+ const controller = new AbortController()
+
+ if (!requestedItems.length) {
+ setState({ loading: false, metadata: metadataRef.current })
+ return undefined
+ }
+
+ setState((previous) => ({
+ ...previous,
+ loading: true,
+ error: undefined,
+ }))
+
+ fetchDataItemProfileMetadata(engineRef.current, requestedItems, {
+ known: metadataRef.current,
+ signal: controller.signal,
+ })
+ .then((metadata) => {
+ if (!controller.signal.aborted) {
+ setState({
+ loading: false,
+ metadata,
+ metadataItemsKey: itemsKey,
+ })
+ }
+ })
+ .catch((error) => {
+ if (!controller.signal.aborted) {
+ setState((previous) => ({
+ ...previous,
+ loading: false,
+ error,
+ metadataItemsKey: undefined,
+ }))
+ }
+ })
+
+ return () => controller.abort()
+ }, [engineRef, itemsKey])
+
+ /* Profiles from the metadata of the items it was fetched for: while new
+ * items load, the others keep theirs */
+ const metadataProfiles = useMemo(() => {
+ const loadedIds = new Set(
+ state.metadataItemsKey
+ ? parseItemsKey(state.metadataItemsKey).map(({ id }) => id)
+ : []
+ )
+ const loadedItems = parseItemsKey(itemsKey).filter(({ id }) =>
+ loadedIds.has(id)
+ )
+
+ return loadedItems.length
+ ? Object.fromEntries(
+ loadedItems.map((item) => [
+ item.id,
+ getDataItemProfile(item, state.metadata),
+ ])
+ )
+ : undefined
+ }, [itemsKey, state.metadata, state.metadataItemsKey])
+
+ const sourceKeysKey = JSON.stringify(
+ metadataProfiles
+ ? getDataItemProfileSourceKeys(Object.values(metadataProfiles))
+ : null
+ )
+ const coverageKey = `${sourceKeysKey}|${orgUnitsKey}|${withAssignmentTotals}`
+
+ useEffect(() => {
+ const sourceKeys = JSON.parse(sourceKeysKey)
+ const requestedOrgUnits = JSON.parse(orgUnitsKey)
+ const controller = new AbortController()
+
+ if (!sourceKeys || !requestedOrgUnits.length) {
+ setCoverageState({ loading: false, coverage: coverageRef.current })
+ return undefined
+ }
+
+ setCoverageState((previous) => ({
+ ...previous,
+ loading: true,
+ error: undefined,
+ }))
+
+ fetchOrgUnitCoverage(engineRef.current, {
+ sourceKeys,
+ orgUnits: requestedOrgUnits,
+ withAssignmentTotals,
+ previous: coverageRef.current,
+ signal: controller.signal,
+ })
+ .then((coverage) => {
+ if (!controller.signal.aborted) {
+ setCoverageState({
+ loading: false,
+ coverage,
+ coverageKey: `${sourceKeysKey}|${orgUnitsKey}|${withAssignmentTotals}`,
+ })
+ }
+ })
+ .catch((error) => {
+ if (!controller.signal.aborted) {
+ setCoverageState((previous) => ({
+ ...previous,
+ loading: false,
+ error,
+ coverageKey: undefined,
+ }))
+ }
+ })
+
+ return () => controller.abort()
+ }, [engineRef, sourceKeysKey, orgUnitsKey, withAssignmentTotals])
+
+ // Only the coverage of these sources and org units, never an earlier one
+ const coverage =
+ coverageState.coverageKey === coverageKey
+ ? coverageState.coverage
+ : undefined
+
+ /* None before the settings, which relative periods need. The coverage
+ * gives the assigned org unit levels. */
+ const profiles = useMemo(() => {
+ if (settingsState.loading || !metadataProfiles) {
+ return undefined
+ }
+
+ return Object.fromEntries(
+ Object.entries(metadataProfiles).map(([id, profile]) => [
+ id,
+ !coverage
+ ? profile
+ : addAssignedOrgUnitLevels(
+ profile,
+ coverage.assignedOrgUnitCounts
+ ),
+ ])
+ )
+ }, [settingsState.loading, metadataProfiles, coverage])
+
+ const options = useMemo(
+ () => ({
+ ...settingsState.options,
+ calendar: resolvedCalendar,
+ relativePeriodDate,
+ serverVersion,
+ orgUnitCoverage: coverage,
+ }),
+ [
+ settingsState.options,
+ resolvedCalendar,
+ relativePeriodDate,
+ serverVersion,
+ coverage,
+ ]
+ )
+
+ // A list of items asks for the same results on every render
+ const getDataItemCompatibility = useMemo(() => {
+ const results = new Map()
+
+ return (itemId, selection) => {
+ if (!profiles?.[itemId]) {
+ return undefined
+ }
+
+ const key = JSON.stringify([itemId, selection])
+
+ if (!results.has(key)) {
+ results.set(
+ key,
+ getDataItemProfileCompatibility(
+ profiles[itemId],
+ selection,
+ options
+ )
+ )
+ }
+
+ return results.get(key)
+ }
+ }, [profiles, options])
+
+ return {
+ loading:
+ state.loading ||
+ coverageState.loading ||
+ (settingsState.loading && itemsKey !== '[]'),
+ profiles,
+ error: settingsState.error ?? state.error ?? coverageState.error,
+ orgUnitCoverage: coverage,
+ relativePeriodTypes: settingsState.options,
+ getDataItemCompatibility,
+ }
+}
diff --git a/src/components/DataItemProfile/utils.js b/src/components/DataItemProfile/utils.js
new file mode 100644
index 000000000..5a0adf7fd
--- /dev/null
+++ b/src/components/DataItemProfile/utils.js
@@ -0,0 +1,66 @@
+import { useConfig, useDataEngine } from '@dhis2/app-runtime'
+import { useRef } from 'react'
+import { getRelativePeriodTypeOptions } from '../../modules/dataItemProfile/periods/periodTypes.js'
+
+const SETTING_KEYS = ['analyticsWeeklyStart', 'analyticsFinancialYearStart']
+
+// The server answers 404 (E1005) for a setting its version doesn't have
+const isMissingSetting = (error) => error?.details?.httpStatusCode === 404
+
+// A setting a version doesn't have is left out, never guessed
+const fetchSetting = (engine, key, signal) =>
+ engine
+ .query({ setting: { resource: `systemSettings/${key}` } }, { signal })
+ .then(({ setting }) => setting?.[key])
+ .catch((error) => {
+ if (isMissingSetting(error)) {
+ return undefined
+ }
+
+ throw error
+ })
+
+export const fetchRelativePeriodTypeOptions = async (
+ engine,
+ { signal } = {}
+) => {
+ const values = await Promise.all(
+ SETTING_KEYS.map((key) => fetchSetting(engine, key, signal))
+ )
+
+ return getRelativePeriodTypeOptions(
+ Object.fromEntries(SETTING_KEYS.map((key, i) => [key, values[i]]))
+ )
+}
+
+export const useCalendar = (calendar) => {
+ const { systemInfo } = useConfig()
+
+ return calendar ?? systemInfo?.calendar ?? 'gregory'
+}
+
+/* Items ({ id, dimensionItemType }) are compared by value, in any order, so
+ * a new array with the same items sends no request */
+export const getItemsKey = (items = []) =>
+ JSON.stringify(
+ items
+ .map(({ id, dimensionItemType }) => [id, dimensionItemType])
+ .sort(([a], [b]) => a.localeCompare(b))
+ )
+
+export const parseItemsKey = (itemsKey) =>
+ JSON.parse(itemsKey).map(([id, dimensionItemType]) => ({
+ id,
+ dimensionItemType,
+ }))
+
+/* The latest engine, without making requests depend on its identity: a test
+ * provider can give a new one on each render */
+export const useEngineRef = () => {
+ const engine = useDataEngine()
+ const engineRef = useRef(engine)
+
+ engineRef.current = engine
+
+ return engineRef
+}
diff --git a/src/components/PeriodDimension/useDataOutputPeriodTypes.js b/src/components/PeriodDimension/useDataOutputPeriodTypes.js
index f76031fdb..719e09fd9 100644
--- a/src/components/PeriodDimension/useDataOutputPeriodTypes.js
+++ b/src/components/PeriodDimension/useDataOutputPeriodTypes.js
@@ -1,5 +1,9 @@
import { useConfig, useDataQuery } from '@dhis2/app-runtime'
import { useEffect, useMemo } from 'react'
+import {
+ FINANCIAL_YEAR_START_TO_PERIOD_TYPE,
+ WEEKLY_START_TO_PERIOD_TYPE,
+} from './utils/enabledPeriodTypes.js'
const v43Query = {
enabledPeriodTypes: {
@@ -18,27 +22,6 @@ const v43Query = {
},
}
-// v43-only: analyticsFinancialYearStart is removed in v44
-const FY_SETTING_TO_SERVER_PT = {
- FINANCIAL_YEAR_FEBRUARY: 'FinancialFeb',
- FINANCIAL_YEAR_APRIL: 'FinancialApril',
- FINANCIAL_YEAR_JULY: 'FinancialJuly',
- FINANCIAL_YEAR_AUGUST: 'FinancialAug',
- FINANCIAL_YEAR_SEPTEMBER: 'FinancialSep',
- FINANCIAL_YEAR_OCTOBER: 'FinancialOct',
- FINANCIAL_YEAR_NOVEMBER: 'FinancialNov',
-}
-
-// v43-only: analyticsWeeklyStart is removed in v44
-const WEEKLY_START_TO_SERVER_PT = {
- WEEKLY: 'Weekly',
- WEEKLY_WEDNESDAY: 'WeeklyWednesday',
- WEEKLY_THURSDAY: 'WeeklyThursday',
- WEEKLY_FRIDAY: 'WeeklyFriday',
- WEEKLY_SATURDAY: 'WeeklySaturday',
- WEEKLY_SUNDAY: 'WeeklySunday',
-}
-
const useDataOutputPeriodTypes = () => {
const { serverVersion } = useConfig()
const supportsEnabledPeriodTypes = serverVersion.minor >= 43
@@ -82,7 +65,7 @@ const useDataOutputPeriodTypes = () => {
const fyStartValue =
v43Data.financialYearStart.analyticsFinancialYearStart
- const mappedFyPt = FY_SETTING_TO_SERVER_PT[fyStartValue]
+ const mappedFyPt = FINANCIAL_YEAR_START_TO_PERIOD_TYPE[fyStartValue]
const matchingPt = enabledTypes.find((pt) => pt.name === mappedFyPt)
if (matchingPt) {
financialYearStart = fyStartValue
@@ -97,7 +80,7 @@ const useDataOutputPeriodTypes = () => {
if (v43Data.weeklyStart?.analyticsWeeklyStart) {
const weeklyStartValue = v43Data.weeklyStart.analyticsWeeklyStart
- const mappedWeeklyPt = WEEKLY_START_TO_SERVER_PT[weeklyStartValue]
+ const mappedWeeklyPt = WEEKLY_START_TO_PERIOD_TYPE[weeklyStartValue]
const matchingWeeklyPt = enabledTypes.find(
(pt) => pt.name === mappedWeeklyPt
)
diff --git a/src/components/PeriodDimension/utils/enabledPeriodTypes.js b/src/components/PeriodDimension/utils/enabledPeriodTypes.js
index 7cadc0833..383be1d04 100644
--- a/src/components/PeriodDimension/utils/enabledPeriodTypes.js
+++ b/src/components/PeriodDimension/utils/enabledPeriodTypes.js
@@ -25,6 +25,28 @@ export const SERVER_PT_TO_MULTI_CALENDAR_PT = {
FinancialNov: 'FYNOV',
}
+// VERSION-TOGGLE: remove when 44 is the lowest supported version (v44 removes the analyticsWeeklyStart and analyticsFinancialYearStart settings)
+// The period type of relative weeks, by the analyticsWeeklyStart setting
+export const WEEKLY_START_TO_PERIOD_TYPE = {
+ WEEKLY: 'Weekly',
+ WEEKLY_WEDNESDAY: 'WeeklyWednesday',
+ WEEKLY_THURSDAY: 'WeeklyThursday',
+ WEEKLY_FRIDAY: 'WeeklyFriday',
+ WEEKLY_SATURDAY: 'WeeklySaturday',
+ WEEKLY_SUNDAY: 'WeeklySunday',
+}
+
+// The period type of relative financial years, by the analyticsFinancialYearStart setting
+export const FINANCIAL_YEAR_START_TO_PERIOD_TYPE = {
+ FINANCIAL_YEAR_FEBRUARY: 'FinancialFeb',
+ FINANCIAL_YEAR_APRIL: 'FinancialApril',
+ FINANCIAL_YEAR_JULY: 'FinancialJuly',
+ FINANCIAL_YEAR_AUGUST: 'FinancialAug',
+ FINANCIAL_YEAR_SEPTEMBER: 'FinancialSep',
+ FINANCIAL_YEAR_OCTOBER: 'FinancialOct',
+ FINANCIAL_YEAR_NOVEMBER: 'FinancialNov',
+}
+
// Mapping from relative period categories to their corresponding fixed period types
export const RP_CATEGORY_TO_FP_DEPENDENCIES = {
DAILY: ['Daily'],
diff --git a/src/index.js b/src/index.js
index 976210f68..90f90ea2b 100644
--- a/src/index.js
+++ b/src/index.js
@@ -7,6 +7,8 @@ export { default as PeriodDimension } from './components/PeriodDimension/PeriodD
export { default as FixedPeriodSelect } from './components/PeriodDimension/FixedPeriodSelect.js'
export { useDataOutputPeriodTypes } from './components/PeriodDimension/useDataOutputPeriodTypes.js'
+export { useDataItemProfiles } from './components/DataItemProfile/useDataItemProfiles.js'
+
export { default as OrgUnitDimension } from './components/OrgUnitDimension/OrgUnitDimension.js'
export {
@@ -330,6 +332,57 @@ export {
export { renderValue as formatValue } from './modules/renderValue.js'
+// Modules: dataItemProfile
+
+export { getDataItemProfile } from './modules/dataItemProfile/getDataItemProfile.js'
+export { getPeriodAggregationType } from './modules/dataItemProfile/profile/collectSources.js'
+export { addAssignedOrgUnitLevels } from './modules/dataItemProfile/profile/assignedOrgUnitLevels.js'
+export { getDataItemProfileCompatibility } from './modules/dataItemProfile/getDataItemProfileCompatibility.js'
+export { getDataItemProfilePeriodCompatibility } from './modules/dataItemProfile/compatibility/getDataItemProfilePeriodCompatibility.js'
+export { getDataItemProfileOrgUnitCompatibility } from './modules/dataItemProfile/compatibility/getDataItemProfileOrgUnitCompatibility.js'
+export { getPeriodAtOrgUnitResults } from './modules/dataItemProfile/compatibility/periodAtOrgUnitResults.js'
+export {
+ COMPATIBILITY_FULL,
+ COMPATIBILITY_PARTIAL,
+ COMPATIBILITY_NONE,
+ COMPATIBILITY_UNKNOWN,
+ REASON_OPERAND_EMPTY,
+ REASON_OPERAND_PARTIAL,
+ REASON_PERIOD_TOO_SHORT,
+ REASON_PERIOD_TYPE_MISMATCH,
+ REASON_REPORTING_RATE_TOO_SHORT,
+ REASON_NO_EARLIER_PERIOD_VALUE,
+ REASON_REPEATED_VALUE,
+ REASON_EARLIER_PERIOD_VALUE,
+ REASON_NOT_ASSIGNED,
+ REASON_ASSIGNED_AT_HIGHER_LEVEL,
+ REASON_STOPPED_BY_AGGREGATION_LEVEL,
+ REASON_NO_ORG_UNITS_AT_LEVEL,
+ REASON_EMPTY_GROUP,
+ REASON_PARTLY_ASSIGNED,
+ REASON_ANY_ORG_UNIT,
+ REASON_PROFILE_UNKNOWN,
+ REASON_UNKNOWN_PERIOD,
+ REASON_SETTING_MISSING,
+ REASON_UNSUPPORTED_VERSION,
+ REASON_UNKNOWN_ORG_UNIT,
+ PROFILE_REASON_MISSING_METADATA,
+ PROFILE_REASON_MISSING_PROGRAM,
+ PROFILE_REASON_UNKNOWN_OPERAND,
+ PROFILE_REASON_UNKNOWN_PERIOD_TYPE,
+ PROFILE_REASON_UNSUPPORTED_ITEM_TYPE,
+ PROFILE_REASON_NO_DATA_SET,
+ PROFILE_REASON_NOT_AGGREGATABLE,
+ SKIP_IF_ANY_VALUE_MISSING,
+ SKIP_IF_ALL_VALUES_MISSING,
+} from './modules/dataItemProfile/constants.js'
+export { fetchDataItemProfileMetadata } from './api/dataItemProfile/fetchDataItemProfileMetadata.js'
+export {
+ fetchAssignedOrgUnitCounts,
+ getDataItemProfileSourceKeys,
+} from './api/dataItemProfile/assignedOrgUnitCounts.js'
+export { fetchOrgUnitCoverage } from './api/dataItemProfile/fetchOrgUnitCoverage.js'
+
// Modules: response
export { transformResponse as transformEventAggregateResponse } from './modules/response/event/response.js'
diff --git a/src/modules/dataItemProfile/__tests__/expressionOperands.spec.js b/src/modules/dataItemProfile/__tests__/expressionOperands.spec.js
new file mode 100644
index 000000000..b1bdc68a3
--- /dev/null
+++ b/src/modules/dataItemProfile/__tests__/expressionOperands.spec.js
@@ -0,0 +1,82 @@
+import {
+ getCategoryOptionComboId,
+ parseExpressionOperands,
+} from '../expressionOperands.js'
+
+const summarize = (expression) =>
+ parseExpressionOperands(expression).map(
+ ({ type, id, operand, aggregationType }) => ({
+ type,
+ ...(id !== undefined && { id }),
+ ...(operand && { operand }),
+ ...(aggregationType && { aggregationType }),
+ })
+ )
+
+describe('parseExpressionOperands', () => {
+ it.each([
+ ['#{deA}', [{ type: 'DATA_ELEMENT', id: 'deA' }]],
+ [
+ '#{deA.cocA}',
+ [{ type: 'DATA_ELEMENT', id: 'deA', operand: 'deA.cocA' }],
+ ],
+ [
+ '#{deA.cocA.aocA}',
+ [{ type: 'DATA_ELEMENT', id: 'deA', operand: 'deA.cocA.aocA' }],
+ ],
+ ['#{deA.*}', [{ type: 'DATA_ELEMENT', id: 'deA' }]],
+ ['R{dsA.REPORTING_RATE}', [{ type: 'REPORTING_RATE', id: 'dsA' }]],
+ ['N{indA}', [{ type: 'INDICATOR', id: 'indA' }]],
+ ['I{piA}', [{ type: 'PROGRAM_INDICATOR', id: 'piA' }]],
+ ['D{prA.deA}', [{ type: 'PROGRAM_DATA_ELEMENT', id: 'prA.deA' }]],
+ ['A{prA.atA}', [{ type: 'PROGRAM_ATTRIBUTE', id: 'prA.atA' }]],
+ ['C{cA}', [{ type: 'CONSTANT', id: 'cA' }]],
+ ['OUG{ougA}', [{ type: 'ORG_UNIT_GROUP', id: 'ougA' }]],
+ ['[days]', [{ type: 'DAYS' }]],
+ ['S{subA}', [{ type: 'UNKNOWN', id: 'subA' }]],
+ ])('reads %s', (expression, expected) => {
+ expect(summarize(expression)).toEqual(expected)
+ })
+
+ it('reads every operand of an expression, in order', () => {
+ expect(
+ summarize(
+ '(#{deA.cocA} + #{deB}) * C{cA} / [days] - R{dsA.ACTUAL_REPORTS}'
+ )
+ ).toEqual([
+ { type: 'DATA_ELEMENT', id: 'deA', operand: 'deA.cocA' },
+ { type: 'DATA_ELEMENT', id: 'deB' },
+ { type: 'CONSTANT', id: 'cA' },
+ { type: 'DAYS' },
+ { type: 'REPORTING_RATE', id: 'dsA' },
+ ])
+ })
+
+ it('reads the functions chained after an operand', () => {
+ const [operand] = parseExpressionOperands(
+ '#{deA}.periodOffset(-1).aggregationType( LAST )'
+ )
+
+ expect(operand.functions).toEqual([
+ { name: 'periodOffset', arg: '-1' },
+ { name: 'aggregationType', arg: 'LAST' },
+ ])
+ expect(operand.aggregationType).toBe('LAST')
+ })
+
+ it('reads nothing from an empty expression', () => {
+ expect(parseExpressionOperands()).toEqual([])
+ expect(parseExpressionOperands(null)).toEqual([])
+ expect(parseExpressionOperands('1 + 2')).toEqual([])
+ })
+})
+
+describe('getCategoryOptionComboId', () => {
+ it('reads the option combo of a disaggregation', () => {
+ expect(getCategoryOptionComboId('de.coc')).toBe('coc')
+ expect(getCategoryOptionComboId('de.coc.aoc')).toBe('coc')
+ expect(getCategoryOptionComboId('de.*.aoc')).toBeUndefined()
+ expect(getCategoryOptionComboId('de')).toBeUndefined()
+ expect(getCategoryOptionComboId(undefined)).toBeUndefined()
+ })
+})
diff --git a/src/modules/dataItemProfile/__tests__/getDataItemProfile.spec.js b/src/modules/dataItemProfile/__tests__/getDataItemProfile.spec.js
new file mode 100644
index 000000000..75fe2eafc
--- /dev/null
+++ b/src/modules/dataItemProfile/__tests__/getDataItemProfile.spec.js
@@ -0,0 +1,629 @@
+import { inDataSets } from '../../../__fixtures__/dataItemProfileMetadata.js'
+import { getDataItemProfile } from '../getDataItemProfile.js'
+import { getPeriodAggregationType } from '../profile/collectSources.js'
+
+const dataElement = (periodTypes, aggregationType = 'SUM') => ({
+ aggregationType,
+ valueType: 'INTEGER',
+ domainType: 'AGGREGATE',
+ dataSets: inDataSets(periodTypes),
+})
+
+const metadata = {
+ dataElements: {
+ monthly: dataElement(['Monthly']),
+ weekly: dataElement(['Weekly']),
+ mondayAndWednesday: dataElement(['Weekly', 'WeeklyWednesday']),
+ weeklyAndMonthly: dataElement(['Monthly', 'Weekly']),
+ population: dataElement(['Yearly'], 'AVERAGE'),
+ stock: dataElement(['Monthly'], 'AVERAGE_SUM_ORG_UNIT'),
+ noAggregation: dataElement(['Monthly'], 'NONE'),
+ noDataSet: dataElement([]),
+ oddType: dataElement(['Hourly']),
+ },
+ dataSets: {
+ weeklyForm: { periodType: 'Weekly' },
+ oddForm: { periodType: 'Hourly' },
+ },
+ indicators: {
+ coverage: {
+ numerator: '#{monthly.cocA}',
+ denominator: '#{population}',
+ },
+ weeklyShare: { numerator: '#{weekly}', denominator: '#{monthly}' },
+ nested: { numerator: 'N{coverage}', denominator: '1' },
+ loopA: { numerator: 'N{loopB}', denominator: '1' },
+ loopB: { numerator: 'N{loopA} + #{weekly}', denominator: '1' },
+ withMissing: { numerator: '#{missing}', denominator: '1' },
+ withUnknown: { numerator: 'S{sub}', denominator: '1' },
+ eventsOnly: { numerator: 'I{pi} + D{pr.de}', denominator: 'C{c}' },
+ reportingRate: {
+ numerator: 'R{weeklyForm.REPORTING_RATE}',
+ denominator: '1',
+ },
+ lastOverride: {
+ numerator: '#{population}.aggregationType(LAST)',
+ denominator: '1',
+ },
+ withMissingNested: { numerator: 'N{gone}', denominator: '1' },
+ withMissingDataSet: {
+ numerator: 'R{goneForm.REPORTING_RATE}',
+ denominator: '1',
+ },
+ },
+ programIndicators: {
+ pi: { program: 'pr' },
+ piByOwner: { program: 'pr', orgUnitField: 'OWNER_AT_START' },
+ piByRegist: { program: 'pr', orgUnitField: 'REGISTRATION' },
+ },
+ programs: { pr: { programType: 'WITHOUT_REGISTRATION' } },
+ expressionDimensionItems: {
+ weeklyPlusMonthly: { expression: '#{weekly} + #{monthly}' },
+ },
+}
+
+const profile = (id, dimensionItemType, data = metadata) =>
+ getDataItemProfile({ id, dimensionItemType }, data)
+
+describe('getDataItemProfile', () => {
+ describe('data elements', () => {
+ it('takes the data set type', () => {
+ expect(profile('monthly', 'DATA_ELEMENT')).toEqual({
+ unknown: false,
+ reasons: [],
+ sources: [
+ {
+ dataSet: { id: 'MonthlyForm', periodType: 'Monthly' },
+ elements: [
+ {
+ id: 'monthly',
+ aggregationType: 'SUM',
+ periodAggregationType: 'SUM',
+ },
+ ],
+ reportingRate: false,
+ },
+ ],
+ assignedPeriodTypes: {
+ types: ['Monthly'],
+ shortestDirectType: 'Monthly',
+ hasSeveral: false,
+ },
+ })
+ })
+
+ it('has one source per data set', () => {
+ expect(profile('weeklyAndMonthly', 'DATA_ELEMENT').sources).toEqual(
+ [
+ {
+ dataSet: { id: 'MonthlyForm', periodType: 'Monthly' },
+ elements: [
+ {
+ id: 'weeklyAndMonthly',
+ aggregationType: 'SUM',
+ periodAggregationType: 'SUM',
+ },
+ ],
+ reportingRate: false,
+ },
+ {
+ dataSet: { id: 'WeeklyForm', periodType: 'Weekly' },
+ elements: [
+ {
+ id: 'weeklyAndMonthly',
+ aggregationType: 'SUM',
+ periodAggregationType: 'SUM',
+ },
+ ],
+ reportingRate: false,
+ },
+ ]
+ )
+ })
+
+ it('reads an operand by its data element, and keeps it', () => {
+ const operand = profile('monthly.cocA', 'DATA_ELEMENT_OPERAND')
+
+ expect(operand.assignedPeriodTypes.shortestDirectType).toBe(
+ 'Monthly'
+ )
+ expect(operand.sources[0].elements).toEqual([
+ expect.objectContaining({
+ id: 'monthly',
+ operand: 'monthly.cocA',
+ }),
+ ])
+ })
+
+ it('lists several types, and the shortest direct type is the longest', () => {
+ expect(profile('weeklyAndMonthly', 'DATA_ELEMENT')).toMatchObject({
+ assignedPeriodTypes: {
+ types: ['Weekly', 'Monthly'],
+ shortestDirectType: 'Monthly',
+ hasSeveral: true,
+ },
+ })
+ })
+
+ it('goes up a type when two types have the same length', () => {
+ /* Analytics fills BiWeekly from Wednesday weeks though they don't
+ * nest: the test tool's fixtures show values on all 8 versions,
+ * for every aggregation type but NONE */
+ expect(profile('mondayAndWednesday', 'DATA_ELEMENT')).toMatchObject(
+ {
+ assignedPeriodTypes: {
+ types: ['Weekly', 'WeeklyWednesday'],
+ shortestDirectType: 'BiWeekly',
+ hasSeveral: true,
+ },
+ }
+ )
+ })
+
+ it.each([
+ ['population', 'AVERAGE', 'Yearly'],
+ ['stock', 'AVERAGE', 'Monthly'],
+ ])(
+ 'counts averaged data in the shortest direct type: %s',
+ (id, periodAggregationType, shortestDirectType) => {
+ expect(profile(id, 'DATA_ELEMENT')).toMatchObject({
+ unknown: false,
+ sources: [{ elements: [{ periodAggregationType }] }],
+ assignedPeriodTypes: { shortestDirectType },
+ })
+ }
+ )
+
+ it('is unknown when not aggregatable', () => {
+ expect(profile('noAggregation', 'DATA_ELEMENT')).toMatchObject({
+ unknown: true,
+ reasons: [{ code: 'NOT_AGGREGATABLE', id: 'noAggregation' }],
+ })
+ })
+
+ it('is unknown in no data set', () => {
+ expect(profile('noDataSet', 'DATA_ELEMENT')).toMatchObject({
+ unknown: true,
+ reasons: [{ code: 'NO_DATA_SET', id: 'noDataSet' }],
+ sources: [
+ {
+ dataSet: null,
+ elements: [{ id: 'noDataSet' }],
+ },
+ ],
+ assignedPeriodTypes: { types: [], shortestDirectType: null },
+ })
+ })
+
+ it('is unknown with a period type it does not know', () => {
+ expect(profile('oddType', 'DATA_ELEMENT')).toMatchObject({
+ unknown: true,
+ reasons: [
+ {
+ code: 'UNKNOWN_PERIOD_TYPE',
+ id: 'oddType',
+ periodType: 'Hourly',
+ },
+ ],
+ assignedPeriodTypes: { types: [] },
+ })
+ })
+
+ it('is unknown without metadata', () => {
+ expect(profile('missing', 'DATA_ELEMENT', {})).toMatchObject({
+ unknown: true,
+ reasons: [{ code: 'MISSING_METADATA', id: 'missing' }],
+ })
+ })
+ })
+
+ describe('disaggregations', () => {
+ // As on the demo database: one element, three data sets, three category combos
+ const deathsMetadata = {
+ dataElements: {
+ deaths: {
+ aggregationType: 'SUM',
+ dataSets: [
+ {
+ id: 'mortality',
+ periodType: 'Monthly',
+ categoryComboId: 'defaultComb',
+ },
+ {
+ id: 'byAgeGroup',
+ periodType: 'Quarterly',
+ categoryComboId: 'ageGroupsCo',
+ },
+ {
+ id: 'byGender',
+ periodType: 'Yearly',
+ categoryComboId: 'genderCombo',
+ },
+ ],
+ },
+ },
+ categoryOptionCombos: {
+ under1Year1: { categoryComboId: 'ageGroupsCo' },
+ otherCombo1: { categoryComboId: 'notInAnySet' },
+ },
+ }
+ const dataSetsOf = (id, data = deathsMetadata) =>
+ profile(id, 'DATA_ELEMENT_OPERAND', data).sources.map(
+ ({ dataSet }) => dataSet?.id
+ )
+
+ it('count only the data sets whose category combo holds the option combo', () => {
+ expect(dataSetsOf('deaths.under1Year1')).toEqual(['byAgeGroup'])
+ expect(
+ profile(
+ 'deaths.under1Year1',
+ 'DATA_ELEMENT_OPERAND',
+ deathsMetadata
+ ).assignedPeriodTypes.types
+ ).toEqual(['Quarterly'])
+ })
+
+ it('count every data set for the whole element, a wildcard, or an option combo not known', () => {
+ expect(dataSetsOf('deaths')).toEqual([
+ 'mortality',
+ 'byAgeGroup',
+ 'byGender',
+ ])
+ expect(dataSetsOf('deaths.unknownComb')).toHaveLength(3)
+ })
+
+ it('are unknown when no data set collects the option combo', () => {
+ expect(
+ profile(
+ 'deaths.otherCombo1',
+ 'DATA_ELEMENT_OPERAND',
+ deathsMetadata
+ )
+ ).toMatchObject({
+ unknown: true,
+ reasons: [{ code: 'NO_DATA_SET', id: 'deaths' }],
+ })
+ })
+
+ it('count the same way in expressions', () => {
+ expect(
+ profile('deathsRatio', 'INDICATOR', {
+ ...deathsMetadata,
+ indicators: {
+ deathsRatio: {
+ numerator: '#{deaths.under1Year1}',
+ denominator: '1',
+ },
+ },
+ }).sources.map(({ dataSet }) => dataSet.id)
+ ).toEqual(['byAgeGroup'])
+ })
+ })
+
+ describe('reporting rates', () => {
+ it('take the data set type', () => {
+ expect(
+ profile('weeklyForm.REPORTING_RATE', 'REPORTING_RATE')
+ ).toMatchObject({
+ sources: [
+ {
+ dataSet: { id: 'weeklyForm', periodType: 'Weekly' },
+ elements: [],
+ reportingRate: true,
+ },
+ ],
+ assignedPeriodTypes: {
+ types: ['Weekly'],
+ shortestDirectType: 'Weekly',
+ },
+ })
+ })
+
+ it('are unknown without the data set', () => {
+ expect(
+ profile('goneForm.ACTUAL_REPORTS', 'REPORTING_RATE')
+ ).toMatchObject({ unknown: true })
+ })
+
+ it('are unknown with a period type it does not know', () => {
+ expect(
+ profile('oddForm.REPORTING_RATE', 'REPORTING_RATE')
+ ).toMatchObject({
+ unknown: true,
+ assignedPeriodTypes: { types: [] },
+ })
+ })
+ })
+
+ describe('indicators', () => {
+ it('read numerator and denominator', () => {
+ // The yearly population is measured directly by year only
+ expect(profile('coverage', 'INDICATOR')).toMatchObject({
+ assignedPeriodTypes: {
+ types: ['Monthly', 'Yearly'],
+ shortestDirectType: 'Yearly',
+ hasSeveral: true,
+ },
+ })
+ })
+
+ it('group their data elements by data set, with their disaggregations', () => {
+ const { sources } = getDataItemProfile(
+ { id: 'sum', dimensionItemType: 'INDICATOR' },
+ {
+ ...metadata,
+ indicators: {
+ sum: {
+ numerator: '#{monthly} + #{stock} + #{monthly.coc}',
+ denominator: 'R{MonthlyForm.REPORTING_RATE}',
+ },
+ },
+ dataSets: { MonthlyForm: { periodType: 'Monthly' } },
+ }
+ )
+
+ expect(sources).toEqual([
+ {
+ dataSet: { id: 'MonthlyForm', periodType: 'Monthly' },
+ elements: [
+ {
+ id: 'monthly',
+ aggregationType: 'SUM',
+ periodAggregationType: 'SUM',
+ },
+ {
+ id: 'stock',
+ aggregationType: 'AVERAGE_SUM_ORG_UNIT',
+ periodAggregationType: 'AVERAGE',
+ },
+ {
+ id: 'monthly',
+ operand: 'monthly.coc',
+ aggregationType: 'SUM',
+ periodAggregationType: 'SUM',
+ },
+ ],
+ reportingRate: true,
+ },
+ ])
+ })
+
+ it('mix the types of their data elements', () => {
+ expect(profile('weeklyShare', 'INDICATOR')).toMatchObject({
+ assignedPeriodTypes: {
+ shortestDirectType: 'Monthly',
+ hasSeveral: true,
+ },
+ })
+ })
+
+ it('read nested indicators', () => {
+ expect(
+ profile('nested', 'INDICATOR').assignedPeriodTypes
+ .shortestDirectType
+ ).toBe('Yearly')
+ })
+
+ it('say how their operands combine: both sides, any item of a side', () => {
+ const side = (...keys) => ({
+ missingValueStrategy: 'SKIP_IF_ALL_VALUES_MISSING',
+ parts: keys.map((key) => ({ operand: key })),
+ })
+
+ expect(profile('nested', 'INDICATOR').expression).toEqual({
+ missingValueStrategy: 'SKIP_IF_ANY_VALUE_MISSING',
+ parts: [
+ {
+ missingValueStrategy: 'SKIP_IF_ALL_VALUES_MISSING',
+ parts: [
+ {
+ missingValueStrategy:
+ 'SKIP_IF_ANY_VALUE_MISSING',
+ parts: [
+ side('element:monthly:SUM'),
+ side('element:population:AVERAGE'),
+ ],
+ },
+ ],
+ },
+ side(),
+ ],
+ })
+ expect(profile('eventsOnly', 'INDICATOR').expression.parts).toEqual(
+ [side('program:pr::', 'program:pr::'), side()]
+ )
+ })
+
+ it('read indicators that refer to each other once', () => {
+ expect(profile('loopA', 'INDICATOR')).toMatchObject({
+ unknown: false,
+ assignedPeriodTypes: { shortestDirectType: 'Weekly' },
+ })
+ })
+
+ it('take an aggregation type set in the expression', () => {
+ expect(profile('lastOverride', 'INDICATOR')).toMatchObject({
+ sources: [
+ {
+ elements: [
+ {
+ aggregationType: 'LAST',
+ periodAggregationType: 'LAST',
+ },
+ ],
+ },
+ ],
+ assignedPeriodTypes: { shortestDirectType: 'Yearly' },
+ })
+ })
+
+ it('take a reporting rate operand', () => {
+ expect(
+ profile('reportingRate', 'INDICATOR').assignedPeriodTypes
+ .shortestDirectType
+ ).toBe('Weekly')
+ })
+
+ it('are not limited by event data, constants or days', () => {
+ expect(profile('eventsOnly', 'INDICATOR')).toMatchObject({
+ unknown: false,
+ assignedPeriodTypes: { types: [], shortestDirectType: null },
+ })
+ })
+
+ it('read the programs of their event data', () => {
+ expect(profile('eventsOnly', 'INDICATOR').sources).toEqual([
+ {
+ dataSet: null,
+ program: { id: 'pr' },
+ elements: [],
+ reportingRate: false,
+ },
+ ])
+ })
+
+ it.each([
+ ['withMissing', 'MISSING_METADATA'],
+ ['withMissingNested', 'MISSING_METADATA'],
+ ['withMissingDataSet', 'MISSING_METADATA'],
+ ['withUnknown', 'UNKNOWN_OPERAND'],
+ ['gone', 'MISSING_METADATA'],
+ ])('%s is unknown: %s', (id, code) => {
+ expect(profile(id, 'INDICATOR')).toMatchObject({
+ unknown: true,
+ reasons: [expect.objectContaining({ code })],
+ })
+ })
+ })
+
+ describe('expression dimension items', () => {
+ it('read their expression', () => {
+ expect(
+ profile('weeklyPlusMonthly', 'EXPRESSION_DIMENSION_ITEM')
+ ).toMatchObject({
+ assignedPeriodTypes: {
+ shortestDirectType: 'Monthly',
+ hasSeveral: true,
+ },
+ })
+ })
+
+ it('skip only when all their values are missing, whatever strategy they are saved with', () => {
+ const strategyOf = (missingValueStrategy) =>
+ profile('sum', 'EXPRESSION_DIMENSION_ITEM', {
+ ...metadata,
+ expressionDimensionItems: {
+ sum: {
+ expression: '#{weekly} + #{monthly}',
+ missingValueStrategy,
+ },
+ },
+ }).expression.missingValueStrategy
+
+ expect(strategyOf(undefined)).toBe('SKIP_IF_ALL_VALUES_MISSING')
+ expect(strategyOf('SKIP_IF_ANY_VALUE_MISSING')).toBe(
+ 'SKIP_IF_ALL_VALUES_MISSING'
+ )
+ })
+
+ it('are unknown without metadata', () => {
+ expect(profile('gone', 'EXPRESSION_DIMENSION_ITEM').unknown).toBe(
+ true
+ )
+ })
+ })
+
+ describe('event and tracker items', () => {
+ it.each([
+ ['pi', 'PROGRAM_INDICATOR'],
+ ['pr.de', 'PROGRAM_DATA_ELEMENT'],
+ ['pr.de.option', 'PROGRAM_DATA_ELEMENT_OPTION'],
+ ['pr.at', 'PROGRAM_ATTRIBUTE'],
+ ['pr.de', 'EVENT_DATA_ITEM'],
+ ])(
+ '%s (%s) has its program as source, and no period type',
+ (id, type) => {
+ expect(profile(id, type)).toMatchObject({
+ unknown: false,
+ sources: [{ program: { id: 'pr' } }],
+ assignedPeriodTypes: {
+ types: [],
+ shortestDirectType: null,
+ },
+ })
+ }
+ )
+
+ it('keeps a program indicator placed by registration or an attribute apart from its program', () => {
+ expect(profile('piByRegist', 'PROGRAM_INDICATOR').sources).toEqual([
+ {
+ dataSet: null,
+ program: { id: 'pr' },
+ orgUnitField: 'REGISTRATION',
+ elements: [],
+ reportingRate: false,
+ },
+ ])
+ expect(profile('piByOwner', 'PROGRAM_INDICATOR').sources).toEqual([
+ {
+ dataSet: null,
+ program: { id: 'pr' },
+ elements: [],
+ reportingRate: false,
+ },
+ ])
+ })
+
+ it('is unknown without a program in its id', () => {
+ expect(profile('de', 'EVENT_DATA_ITEM')).toMatchObject({
+ unknown: true,
+ reasons: [{ code: 'MISSING_PROGRAM', id: 'de' }],
+ sources: [],
+ })
+ })
+
+ it('is unknown without the metadata of its program indicator or program', () => {
+ expect(profile('gone', 'PROGRAM_INDICATOR')).toMatchObject({
+ unknown: true,
+ reasons: [{ code: 'MISSING_METADATA', id: 'gone' }],
+ })
+ expect(profile('nope.de', 'PROGRAM_DATA_ELEMENT')).toMatchObject({
+ unknown: true,
+ reasons: [{ code: 'MISSING_METADATA', id: 'nope' }],
+ })
+ })
+ })
+
+ it('is unknown for an item type it does not read', () => {
+ expect(profile('any', 'ORGANISATION_UNIT')).toMatchObject({
+ unknown: true,
+ reasons: [
+ {
+ code: 'UNSUPPORTED_ITEM_TYPE',
+ id: 'any',
+ dimensionItemType: 'ORGANISATION_UNIT',
+ },
+ ],
+ })
+ expect(getDataItemProfile({ id: 'any' }).unknown).toBe(true)
+ })
+})
+
+describe('getPeriodAggregationType', () => {
+ it.each([
+ ['SUM', 'SUM'],
+ ['AVERAGE', 'AVERAGE'],
+ ['AVERAGE_SUM_ORG_UNIT', 'AVERAGE'],
+ ['LAST', 'LAST'],
+ ['LAST_AVERAGE_ORG_UNIT', 'LAST'],
+ ['LAST_LAST_ORG_UNIT', 'LAST'],
+ ['LAST_IN_PERIOD_AVERAGE_ORG_UNIT', 'LAST_IN_PERIOD'],
+ ['FIRST_AVERAGE_ORG_UNIT', 'FIRST'],
+ ['FIRST_FIRST_ORG_UNIT', 'FIRST'],
+ ['MAX_SUM_ORG_UNIT', 'MAX'],
+ ['MIN_SUM_ORG_UNIT', 'MIN'],
+ [undefined, undefined],
+ ])('%s aggregates over time as %s', (aggregationType, expected) => {
+ expect(getPeriodAggregationType(aggregationType)).toBe(expected)
+ })
+})
diff --git a/src/modules/dataItemProfile/__tests__/getDataItemProfileCompatibility.spec.js b/src/modules/dataItemProfile/__tests__/getDataItemProfileCompatibility.spec.js
new file mode 100644
index 000000000..feb09f6d3
--- /dev/null
+++ b/src/modules/dataItemProfile/__tests__/getDataItemProfileCompatibility.spec.js
@@ -0,0 +1,740 @@
+import { inDataSets } from '../../../__fixtures__/dataItemProfileMetadata.js'
+import {
+ ORG_UNIT_COVERAGE,
+ orgUnitProfileOf,
+} from '../../../__fixtures__/dataItemProfileOrgUnits.js'
+import { getDataItemProfile } from '../getDataItemProfile.js'
+import { getDataItemProfileCompatibility } from '../getDataItemProfileCompatibility.js'
+
+const dataElement = (periodTypes, aggregationType = 'SUM') => ({
+ aggregationType,
+ dataSets: inDataSets(periodTypes),
+})
+
+const metadata = {
+ dataElements: {
+ monthly: dataElement(['Monthly']),
+ weekly: dataElement(['Weekly']),
+ wednesday: dataElement(['WeeklyWednesday']),
+ yearly: dataElement(['Yearly']),
+ financialOct: dataElement(['FinancialOct']),
+ population: dataElement(['Yearly'], 'AVERAGE'),
+ stock: dataElement(['Monthly'], 'LAST'),
+ firstMonthly: dataElement(['Monthly'], 'FIRST'),
+ firstDaily: dataElement(['Daily'], 'FIRST'),
+ lastFinancialApril: dataElement(['FinancialApril'], 'LAST'),
+ lastYearly: dataElement(['Yearly'], 'LAST'),
+ lastTwoYearly: dataElement(['TwoYearly'], 'LAST'),
+ twoYearly: dataElement(['TwoYearly']),
+ mondayWednesday: dataElement(['Weekly', 'WeeklyWednesday']),
+ },
+ indicators: {
+ coverage: { numerator: '#{monthly}', denominator: '#{population}' },
+ share: { numerator: '#{weekly}', denominator: '#{monthly}' },
+ stockPerHead: { numerator: '#{stock}', denominator: '#{population}' },
+ weeklyShareOfMonthly: {
+ numerator: '#{mondayWednesday}',
+ denominator: '#{weekly}',
+ },
+ timesTwelve: { numerator: '#{monthly} * 12', denominator: '1' },
+ // A missing item of a side counts as 0
+ monthlyPlusYearly: {
+ numerator: '#{monthly} + #{yearly}',
+ denominator: '1',
+ },
+ weeklyPlusWeekly: {
+ numerator: '#{weekly} + #{wednesday}',
+ denominator: '1',
+ },
+ sumOverRatio: {
+ numerator: 'N{monthlyPlusYearly}',
+ denominator: '#{yearly}',
+ },
+ },
+ expressionDimensionItems: {
+ sumByDefault: { expression: '#{monthly} + #{yearly}' },
+ sumNeedingAll: {
+ expression: '#{monthly} + #{yearly}',
+ missingValueStrategy: 'SKIP_IF_ANY_VALUE_MISSING',
+ },
+ sumNeverSkipped: {
+ expression: '#{monthly} + #{yearly}',
+ missingValueStrategy: 'NEVER_SKIP',
+ },
+ },
+}
+
+const indicator = (id) => ({ id, dimensionItemType: 'INDICATOR' })
+
+// A data element id, or an item
+const profileOf = (item) =>
+ getDataItemProfile(
+ typeof item === 'string'
+ ? { id: item, dimensionItemType: 'DATA_ELEMENT' }
+ : item,
+ metadata
+ )
+
+const compatibilityOf = (item, periods, options) =>
+ getDataItemProfileCompatibility(profileOf(item), { periods }, options)
+
+// The overall status and reasons
+const outcomeOf = (...args) => {
+ const { status, reasons } = compatibilityOf(...args)
+
+ return { status, reasons }
+}
+
+const full = (reasons = []) => ({ status: 'full', reasons })
+const partial = (reasons) => ({ status: 'partial', reasons })
+const none = (reasons) => ({ status: 'none', reasons })
+const unknown = (reasons) => ({ status: 'unknown', reasons })
+
+describe('getDataItemProfileCompatibility', () => {
+ it('gives results per period, per source and overall, which add up', () => {
+ expect(compatibilityOf('monthly', ['2025W2', '202501'])).toEqual({
+ status: 'partial',
+ reasons: ['PERIOD_TOO_SHORT'],
+ sources: [
+ {
+ sourceId: 'MonthlyForm',
+ status: 'partial',
+ reasons: ['PERIOD_TOO_SHORT'],
+ },
+ ],
+ periods: [
+ {
+ id: '2025W2',
+ periodTypes: ['Weekly'],
+ status: 'none',
+ reasons: ['PERIOD_TOO_SHORT'],
+ alignsWithData: null,
+ sources: [
+ {
+ sourceId: 'MonthlyForm',
+ status: 'none',
+ reasons: ['PERIOD_TOO_SHORT'],
+ },
+ ],
+ },
+ {
+ id: '202501',
+ periodTypes: ['Monthly'],
+ status: 'full',
+ reasons: [],
+ alignsWithData: true,
+ sources: [
+ {
+ sourceId: 'MonthlyForm',
+ status: 'full',
+ reasons: [],
+ },
+ ],
+ },
+ ],
+ })
+ })
+
+ it('has no status without periods', () => {
+ expect(getDataItemProfileCompatibility(profileOf('monthly'))).toEqual({
+ status: null,
+ reasons: [],
+ sources: [{ sourceId: 'MonthlyForm', status: null, reasons: [] }],
+ periods: [],
+ })
+ })
+
+ it('takes period types', () => {
+ expect(outcomeOf('monthly', ['Quarterly'])).toEqual(full())
+ expect(outcomeOf('monthly', ['Daily'])).toEqual(
+ none(['PERIOD_TOO_SHORT'])
+ )
+ })
+
+ it('gives nothing for another type of the same length', () => {
+ expect(outcomeOf('wednesday', ['2025W2'])).toEqual(
+ none(['PERIOD_TYPE_MISMATCH'])
+ )
+ expect(outcomeOf('yearly', ['2025April'])).toEqual(
+ none(['PERIOD_TYPE_MISMATCH'])
+ )
+ })
+
+ describe('values not measured for the period', () => {
+ it('are averaged for averaged data in shorter periods', () => {
+ expect(outcomeOf('population', ['202501'])).toEqual(
+ full(['REPEATED_VALUE'])
+ )
+ expect(outcomeOf('population', ['2025'])).toEqual(full())
+ })
+
+ describe('FIRST and LAST', () => {
+ it('LAST takes the latest data period of the years touched', () => {
+ // June's value, for a day in July
+ expect(outcomeOf('stock', ['20250715'])).toEqual(
+ full(['EARLIER_PERIOD_VALUE'])
+ )
+ // December 2024 is outside the years 1 January 2025 touches
+ expect(outcomeOf('stock', ['20250101'])).toEqual(
+ none(['NO_EARLIER_PERIOD_VALUE'])
+ )
+ expect(outcomeOf('stock', ['2025WedW1'])).toEqual(
+ none(['NO_EARLIER_PERIOD_VALUE'])
+ )
+ })
+
+ it('LAST is measured for the period when its data adds up into it', () => {
+ expect(outcomeOf('stock', ['2025Q3'])).toEqual(full())
+ expect(outcomeOf('stock', ['2025'])).toEqual(full())
+ })
+
+ it('FIRST takes the earliest data period of the years touched', () => {
+ // January's value, for July and for the third quarter
+ expect(outcomeOf('firstMonthly', ['202507'])).toEqual(
+ full(['EARLIER_PERIOD_VALUE'])
+ )
+ expect(outcomeOf('firstMonthly', ['2025Q3'])).toEqual(
+ full(['EARLIER_PERIOD_VALUE'])
+ )
+ expect(outcomeOf('firstMonthly', ['2025'])).toEqual(full())
+ expect(outcomeOf('firstMonthly', ['20250101'])).toEqual(
+ none(['NO_EARLIER_PERIOD_VALUE'])
+ )
+ // 1 January's value, not the day's own
+ expect(outcomeOf('firstDaily', ['20250715'])).toEqual(
+ full(['EARLIER_PERIOD_VALUE'])
+ )
+ expect(outcomeOf('firstDaily', ['20250101'])).toEqual(full())
+ expect(outcomeOf('firstDaily', ['2025WedW1'])).toEqual(full())
+ })
+
+ it('read every period of the selection as one request', () => {
+ // With 2024 in the request, December 2024 counts on 1 January
+ const withYear = compatibilityOf('stock', ['20250101', '2024'])
+
+ expect(withYear.periods[0]).toMatchObject(
+ full(['EARLIER_PERIOD_VALUE'])
+ )
+ })
+
+ it('read the year in a data period id', () => {
+ // 2024April (April 2024 to March 2025) is a 2024 period
+ expect(outcomeOf('lastFinancialApril', ['20250715'])).toEqual(
+ none(['NO_EARLIER_PERIOD_VALUE'])
+ )
+ // …but it counts when the request touches 2024
+ expect(
+ compatibilityOf('lastFinancialApril', ['20250715', '2024'])
+ .periods[0]
+ ).toMatchObject(full(['EARLIER_PERIOD_VALUE']))
+ })
+
+ it('judges a period type by type alone, as it has no dates', () => {
+ expect(outcomeOf('stock', ['Weekly'])).toEqual(
+ full(['EARLIER_PERIOD_VALUE'])
+ )
+ expect(outcomeOf('stock', ['Quarterly'])).toEqual(full())
+ })
+
+ describe('with relative periods, resolved on relativePeriodDate', () => {
+ const ON_15_JUNE_2025 = { relativePeriodDate: '2025-06-15' }
+
+ it('judges each fixed period they cover', () => {
+ // June 2024 to May 2025: each month has its own value
+ expect(
+ outcomeOf('stock', ['LAST_12_MONTHS'], ON_15_JUNE_2025)
+ ).toEqual(full())
+ // FIRST gives January 2024's value to every month
+ expect(
+ outcomeOf(
+ 'firstMonthly',
+ ['LAST_12_MONTHS'],
+ ON_15_JUNE_2025
+ )
+ ).toEqual(full(['EARLIER_PERIOD_VALUE']))
+ })
+
+ it('count the years they touch for the fixed periods beside them', () => {
+ expect(
+ compatibilityOf('stock', ['20250101']).periods[0]
+ ).toMatchObject(none(['NO_EARLIER_PERIOD_VALUE']))
+ // LAST_12_MONTHS adds 2024: December 2024 counts
+ expect(
+ compatibilityOf(
+ 'stock',
+ ['20250101', 'LAST_12_MONTHS'],
+ ON_15_JUNE_2025
+ ).periods[0]
+ ).toMatchObject(full(['EARLIER_PERIOD_VALUE']))
+ })
+
+ it('is partial when only some of their fixed periods have a value', () => {
+ /* The months of 2025 touch only 2025: the 2025 value ends in
+ * December, and 2024's year isn't in the request */
+ expect(
+ outcomeOf(
+ 'lastYearly',
+ ['MONTHS_THIS_YEAR'],
+ ON_15_JUNE_2025
+ )
+ ).toEqual({
+ status: 'partial',
+ reasons: [
+ 'NO_EARLIER_PERIOD_VALUE',
+ 'EARLIER_PERIOD_VALUE',
+ ],
+ })
+ })
+ })
+
+ it('may take an earlier value when the data type has no dates', () => {
+ expect(outcomeOf('lastTwoYearly', ['2025'])).toEqual(
+ full(['EARLIER_PERIOD_VALUE'])
+ )
+ })
+ })
+
+ it('show in each source', () => {
+ expect(compatibilityOf('stock', ['20250715']).sources).toEqual([
+ {
+ sourceId: 'MonthlyForm',
+ status: 'full',
+ reasons: ['EARLIER_PERIOD_VALUE'],
+ },
+ ])
+ })
+ })
+
+ describe('expressions', () => {
+ it('are complete with an averaged denominator, which they report', () => {
+ expect(outcomeOf(indicator('coverage'), ['202501'])).toEqual(
+ full(['REPEATED_VALUE'])
+ )
+ expect(outcomeOf(indicator('coverage'), ['2025'])).toEqual(full())
+ })
+
+ it('are empty when one operand gives nothing, and say so', () => {
+ expect(outcomeOf(indicator('coverage'), ['2025W2'])).toEqual(
+ none(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT', 'REPEATED_VALUE'])
+ )
+ expect(outcomeOf(indicator('share'), ['2025W2'])).toEqual(
+ none(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT'])
+ )
+ })
+
+ it('are partial from a partial operand, and say so', () => {
+ expect(
+ outcomeOf(indicator('weeklyShareOfMonthly'), ['2025W2'])
+ ).toEqual({
+ status: 'partial',
+ reasons: ['OPERAND_PARTIAL', 'PERIOD_TYPE_MISMATCH'],
+ })
+ })
+
+ it('are partial when some items of a side give nothing, which count as 0', () => {
+ expect(
+ outcomeOf(indicator('monthlyPlusYearly'), ['202501'])
+ ).toEqual(partial(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ expect(outcomeOf(indicator('monthlyPlusYearly'), ['2025'])).toEqual(
+ full()
+ )
+ })
+
+ it('are empty when all items of a side give nothing', () => {
+ expect(
+ outcomeOf(indicator('weeklyPlusWeekly'), ['20250115'])
+ ).toEqual(none(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ })
+
+ it('need both sides of a nested indicator', () => {
+ expect(outcomeOf(indicator('sumOverRatio'), ['202501'])).toEqual(
+ none(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT'])
+ )
+ })
+
+ it('add up the operands of an expression dimension item, whatever its strategy', () => {
+ const expressionItem = (id) => ({
+ id,
+ dimensionItemType: 'EXPRESSION_DIMENSION_ITEM',
+ })
+
+ expect(
+ outcomeOf(expressionItem('sumByDefault'), ['202501'])
+ ).toEqual(partial(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ expect(
+ outcomeOf(expressionItem('sumNeverSkipped'), ['202501'])
+ ).toEqual(partial(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ // Analytics ignores SKIP_IF_ANY_VALUE_MISSING: a value comes back
+ expect(
+ outcomeOf(expressionItem('sumNeedingAll'), ['202501'])
+ ).toEqual(partial(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ })
+
+ it('say nothing more with one operand', () => {
+ expect(outcomeOf(indicator('timesTwelve'), ['2025W2'])).toEqual(
+ none(['PERIOD_TOO_SHORT'])
+ )
+ })
+
+ it('report every kind of indirect value', () => {
+ expect(outcomeOf(indicator('stockPerHead'), ['20250715'])).toEqual(
+ full(['REPEATED_VALUE', 'EARLIER_PERIOD_VALUE'])
+ )
+ })
+ })
+
+ describe('an element in several data sets', () => {
+ const malaria = (aggregationType) =>
+ getDataItemProfile(
+ { id: 'malaria', dimensionItemType: 'DATA_ELEMENT' },
+ {
+ dataElements: {
+ malaria: {
+ aggregationType,
+ dataSets: [
+ { id: 'surveillance', periodType: 'Weekly' },
+ { id: 'report', periodType: 'Monthly' },
+ ],
+ },
+ },
+ }
+ )
+
+ it('is partial when some data sets give nothing', () => {
+ expect(
+ getDataItemProfileCompatibility(malaria('SUM'), {
+ periods: ['2025W2', '202501'],
+ })
+ ).toMatchObject({
+ status: 'partial',
+ reasons: ['PERIOD_TOO_SHORT'],
+ sources: [
+ { sourceId: 'surveillance', status: 'full' },
+ { sourceId: 'report', status: 'partial' },
+ ],
+ periods: [
+ {
+ status: 'partial',
+ reasons: ['PERIOD_TOO_SHORT'],
+ sources: [
+ {
+ sourceId: 'surveillance',
+ status: 'full',
+ reasons: [],
+ },
+ {
+ sourceId: 'report',
+ status: 'none',
+ reasons: ['PERIOD_TOO_SHORT'],
+ },
+ ],
+ },
+ full(),
+ ],
+ })
+ })
+
+ it('is complete when the others give averaged values', () => {
+ expect(
+ getDataItemProfileCompatibility(malaria('AVERAGE'), {
+ periods: ['2025W2'],
+ })
+ ).toMatchObject(full(['REPEATED_VALUE']))
+ })
+
+ it('is empty when every data set gives nothing', () => {
+ expect(
+ getDataItemProfileCompatibility(malaria('SUM'), {
+ periods: ['20250115'],
+ })
+ ).toMatchObject(none(['PERIOD_TOO_SHORT']))
+ })
+ })
+
+ it('reads a reporting rate in a shorter period as empty', () => {
+ const profile = getDataItemProfile(
+ { id: 'form.REPORTING_RATE', dimensionItemType: 'REPORTING_RATE' },
+ { dataSets: { form: { periodType: 'Monthly' } } }
+ )
+
+ expect(
+ getDataItemProfileCompatibility(profile, { periods: ['2025W2'] })
+ ).toMatchObject({
+ ...none(['REPORTING_RATE_TOO_SHORT']),
+ sources: [
+ { sourceId: 'form', ...none(['REPORTING_RATE_TOO_SHORT']) },
+ ],
+ })
+ expect(
+ getDataItemProfileCompatibility(profile, { periods: ['2025Q1'] })
+ ).toMatchObject(full())
+ })
+
+ describe('a program indicator without period boundaries', () => {
+ const profile = getDataItemProfile(
+ { id: 'pi', dimensionItemType: 'PROGRAM_INDICATOR' },
+ {
+ programIndicators: {
+ pi: { program: 'pr', hasPeriodBoundaries: false },
+ },
+ programs: { pr: {} },
+ }
+ )
+ const judge = (serverVersion) =>
+ getDataItemProfileCompatibility(
+ profile,
+ { periods: ['2025Q1'] },
+ { serverVersion }
+ )
+
+ it('is unknown before 2.43, which can’t query it', () => {
+ expect(judge({ major: 2, minor: 42 })).toMatchObject({
+ status: 'unknown',
+ reasons: ['UNSUPPORTED_VERSION'],
+ })
+ })
+
+ it('is full from 2.43, or without a server version', () => {
+ expect(judge({ major: 2, minor: 43 })).toMatchObject(full())
+ expect(judge()).toMatchObject(full())
+ })
+ })
+
+ it('is full for event data, placed by its own dates', () => {
+ const profile = getDataItemProfile(
+ { id: 'pi', dimensionItemType: 'PROGRAM_INDICATOR' },
+ {
+ programIndicators: { pi: { program: 'pr' } },
+ programs: { pr: {} },
+ }
+ )
+
+ expect(
+ getDataItemProfileCompatibility(profile, { periods: ['20250115'] })
+ ).toMatchObject({
+ ...full(),
+ sources: [{ sourceId: 'pr', status: 'full', reasons: [] }],
+ })
+ })
+
+ describe('unknown', () => {
+ it('when the profile is, for the item and each source', () => {
+ const profile = getDataItemProfile(
+ { id: 'odd', dimensionItemType: 'DATA_ELEMENT' },
+ {
+ dataElements: {
+ odd: {
+ aggregationType: 'SUM',
+ dataSets: [{ id: 'hourly', periodType: 'Hourly' }],
+ },
+ },
+ }
+ )
+
+ expect(
+ getDataItemProfileCompatibility(profile, {
+ periods: ['202501'],
+ })
+ ).toMatchObject({
+ ...unknown(['PROFILE_UNKNOWN']),
+ sources: [
+ { sourceId: 'hourly', ...unknown(['PROFILE_UNKNOWN']) },
+ ],
+ })
+ expect(outcomeOf('missing', ['202501'])).toEqual(
+ unknown(['PROFILE_UNKNOWN'])
+ )
+ })
+
+ it('for a period it cannot read', () => {
+ expect(compatibilityOf('monthly', ['NEXT_CENTURY'])).toMatchObject({
+ ...unknown(['UNKNOWN_PERIOD']),
+ periods: [{ periodTypes: [], alignsWithData: null }],
+ })
+ })
+
+ it('for QuarterlyNov before 2.41', () => {
+ const on = (minor) => ({ serverVersion: { major: 2, minor } })
+
+ expect(outcomeOf('monthly', ['2025NovQ1'], on(40))).toEqual(
+ unknown(['UNSUPPORTED_VERSION'])
+ )
+ expect(outcomeOf('monthly', ['2025NovQ1'], on(41))).toEqual(full())
+ expect(outcomeOf('monthly', ['2025NovQ1'])).toEqual(full())
+ expect(outcomeOf('monthly', ['2025Q1'], on(40))).toEqual(full())
+ })
+ })
+
+ it('adds up periods: none when all are, partial when some give values', () => {
+ expect(outcomeOf('monthly', ['2025W2', '2025W3'])).toEqual(
+ none(['PERIOD_TOO_SHORT'])
+ )
+ expect(outcomeOf('monthly', ['202501', '2025W2'])).toEqual(
+ partial(['PERIOD_TOO_SHORT'])
+ )
+ expect(outcomeOf('monthly', ['202501', 'NEXT_CENTURY'])).toEqual(
+ unknown(['UNKNOWN_PERIOD'])
+ )
+ // Nothing from one, and the other can't be told
+ expect(outcomeOf('monthly', ['NEXT_CENTURY', '2025W2'])).toEqual(
+ unknown(['PERIOD_TOO_SHORT', 'UNKNOWN_PERIOD'])
+ )
+ })
+
+ describe('relative periods', () => {
+ it('read their type', () => {
+ expect(outcomeOf('monthly', ['LAST_12_MONTHS'])).toEqual(full())
+ expect(outcomeOf('monthly', ['LAST_7_DAYS'])).toEqual(
+ none(['PERIOD_TOO_SHORT'])
+ )
+ })
+
+ it('hold when every type they could be agrees', () => {
+ expect(outcomeOf('monthly', ['LAST_4_WEEKS'])).toEqual(
+ none(['PERIOD_TOO_SHORT'])
+ )
+ expect(outcomeOf('monthly', ['THIS_FINANCIAL_YEAR'])).toEqual(
+ full()
+ )
+ // Yearly data gives nothing in any financial year
+ expect(outcomeOf('yearly', ['THIS_FINANCIAL_YEAR'])).toEqual(
+ none(['PERIOD_TYPE_MISMATCH'])
+ )
+ })
+
+ it('are unknown when their type depends on a setting not given', () => {
+ expect(outcomeOf('weekly', ['LAST_4_WEEKS'])).toEqual(
+ unknown(['SETTING_MISSING'])
+ )
+ expect(outcomeOf('financialOct', ['THIS_FINANCIAL_YEAR'])).toEqual(
+ unknown(['SETTING_MISSING'])
+ )
+ })
+
+ it('take the settings as options', () => {
+ expect(
+ outcomeOf('weekly', ['LAST_4_WEEKS'], {
+ weeklyPeriodType: 'Weekly',
+ })
+ ).toEqual(full())
+ expect(
+ outcomeOf('weekly', ['LAST_4_WEEKS'], {
+ weeklyPeriodType: 'WeeklySunday',
+ })
+ ).toEqual(none(['PERIOD_TYPE_MISMATCH']))
+ expect(
+ outcomeOf('financialOct', ['THIS_FINANCIAL_YEAR'], {
+ financialYearPeriodType: 'FinancialOct',
+ })
+ ).toEqual(full())
+ })
+
+ it('do not tell whether they align with the data', () => {
+ expect(
+ compatibilityOf('monthly', ['LAST_12_MONTHS']).periods[0]
+ .alignsWithData
+ ).toBeNull()
+ })
+ })
+
+ describe('alignsWithData', () => {
+ const alignsOf = (id, period, options) =>
+ compatibilityOf(id, [period], options).periods[0].alignsWithData
+
+ it('is true when the period is whole data periods', () => {
+ expect(alignsOf('monthly', '2025Q1')).toBe(true)
+ expect(alignsOf('population', '2025')).toBe(true)
+ })
+
+ it('is false when data periods cross its edges', () => {
+ expect(alignsOf('weekly', '202501')).toBe(false)
+ expect(alignsOf('weekly', '2025')).toBe(false)
+ })
+
+ it('is null when it cannot be told', () => {
+ expect(alignsOf('monthly', 'Yearly')).toBeNull()
+ expect(alignsOf('monthly', '2025W2')).toBeNull()
+ expect(alignsOf('twoYearly', 'TwoYearly')).toBeNull()
+ })
+
+ it('works in other calendars', () => {
+ expect(alignsOf('monthly', '2081Q1', { calendar: 'nepali' })).toBe(
+ true
+ )
+ expect(alignsOf('weekly', '208101', { calendar: 'nepali' })).toBe(
+ false
+ )
+ })
+
+ it('is null when a data type has no dates', () => {
+ const profile = getDataItemProfile(
+ { id: 'mixed', dimensionItemType: 'DATA_ELEMENT' },
+ {
+ dataElements: {
+ mixed: dataElement(['Monthly', 'TwoYearly']),
+ },
+ }
+ )
+
+ expect(
+ getDataItemProfileCompatibility(profile, { periods: ['2025'] })
+ .periods[0]
+ ).toMatchObject({ status: 'partial', alignsWithData: true })
+ })
+ })
+})
+
+describe('getDataItemProfileCompatibility, with org units', () => {
+ it('judges periods and org units apart, and adds them up overall', () => {
+ const result = getDataItemProfileCompatibility(
+ orgUnitProfileOf('facility'),
+ { periods: ['2025Q1'], orgUnits: ['nationUnit1', 'facilityDDD'] },
+ { orgUnitCoverage: ORG_UNIT_COVERAGE }
+ )
+
+ expect(result).toMatchObject({
+ status: 'partial',
+ reasons: ['ASSIGNED_AT_HIGHER_LEVEL', 'PARTLY_ASSIGNED'],
+ periods: [{ id: '2025Q1', status: 'full' }],
+ orgUnits: [
+ { id: 'nationUnit1', status: 'full' },
+ { id: 'facilityDDD', status: 'none' },
+ ],
+ })
+ })
+
+ it('judges each period at each org unit overall, with only the data sets assigned there', () => {
+ const result = getDataItemProfileCompatibility(
+ orgUnitProfileOf('twoForms'),
+ { periods: ['2025W2'], orgUnits: ['facilityAAA'] },
+ { orgUnitCoverage: ORG_UNIT_COVERAGE }
+ )
+
+ // Apart: the weekly data set fills weeks; the monthly one is assigned at facilityAAA
+ expect(result.periods[0].status).toBe('partial')
+ expect(result.orgUnits[0].status).toBe('full')
+ // Together: at facilityAAA, only the monthly one counts, and it can't fill a week
+ expect(result).toMatchObject({
+ status: 'none',
+ reasons: ['PERIOD_TOO_SHORT'],
+ })
+ })
+
+ it('leaves org units out when none are asked', () => {
+ expect(
+ getDataItemProfileCompatibility(orgUnitProfileOf('facility'), {
+ periods: ['2025Q1'],
+ })
+ ).not.toHaveProperty('orgUnits')
+ })
+
+ it('judges org units alone', () => {
+ expect(
+ getDataItemProfileCompatibility(
+ orgUnitProfileOf('facility'),
+ { orgUnits: ['districtAAA'] },
+ { orgUnitCoverage: ORG_UNIT_COVERAGE }
+ )
+ ).toMatchObject({ status: 'full', periods: [] })
+ })
+})
diff --git a/src/modules/dataItemProfile/__tests__/orgUnitFixtures.spec.js b/src/modules/dataItemProfile/__tests__/orgUnitFixtures.spec.js
new file mode 100644
index 000000000..1bb588ae7
--- /dev/null
+++ b/src/modules/dataItemProfile/__tests__/orgUnitFixtures.spec.js
@@ -0,0 +1,324 @@
+import fs from 'fs'
+import path from 'path'
+import { createFakeOrgUnitServer } from '../../../__fixtures__/fakeOrgUnitServer.js'
+import { getDataItemProfileSourceKeys } from '../../../api/dataItemProfile/assignedOrgUnitCounts.js'
+import { fetchOrgUnitCoverage } from '../../../api/dataItemProfile/fetchOrgUnitCoverage.js'
+import { normalizeDataItemProfileMetadata } from '../../../api/dataItemProfile/metadataQueries.js'
+import { getDataItemProfileOrgUnitCompatibility } from '../compatibility/getDataItemProfileOrgUnitCompatibility.js'
+import { getDataItemProfile } from '../getDataItemProfile.js'
+
+/* The fixtures come from the test tool in dhis2/maps-tools
+ * (test-data-item-profile, org unit groups): analytics' answers on 2.40 to
+ * 2.44 for data sets and programs assigned at different levels, on the
+ * tool's own org units. Each case is rebuilt here: its hierarchy and
+ * assignments become a fake server, and the library judges the selection
+ * from metadata as it would on a real one. */
+const FIXTURES_DIR = path.join(__dirname, '../../../__fixtures__/org-units')
+
+const readFixture = (name) =>
+ JSON.parse(fs.readFileSync(path.join(FIXTURES_DIR, `${name}.json`)))
+
+const CASE_GROUPS = [
+ 'entered-above',
+ 'partly-assigned',
+ 'mixed-levels',
+ 'aggregation-levels',
+ 'org-unit-groups',
+ 'user-org-units',
+ 'programs',
+]
+
+/* Where the tool's prediction differs from the library's on purpose (the
+ * analytics answers agree with both) */
+const PREDICTION_DIFFERENCES = {
+ // One operand: the library gives the element's reason, OPERAND_PARTIAL is for expressions of several
+ 'ou-mixed-indicator__F1': {
+ status: 'partial',
+ reasons: ['ASSIGNED_AT_HIGHER_LEVEL'],
+ },
+}
+
+/* Cases at the region, where the tool leaves out PARTLY_ASSIGNED (only some
+ * of its districts or facilities are assigned): the library notes it */
+const TOOL_LEAVES_OUT_PARTLY_ASSIGNED = new Set([
+ 'ou-above__level-3-region',
+ 'ou-above__region',
+ 'ou-agg-d1-3__region',
+ 'ou-prog-event__region',
+])
+
+// The tool's names for the library's reasons
+const REASON_BY_TOOL_NAME = {
+ BELOW_COLLECTION: 'ASSIGNED_AT_HIGHER_LEVEL',
+ AGGREGATION_LEVEL: 'STOPPED_BY_AGGREGATION_LEVEL',
+ ORG_UNIT_FIELD: 'ANY_ORG_UNIT',
+}
+
+// Ids the library reads as org unit uids (11 characters)
+const toUid = (prefix, key) => `${prefix}${key}xxxxxxxxxxx`.slice(0, 11)
+const orgUnitUid = (key) => toUid('orgUnit', key)
+const groupUid = (key) => toUid('groupOf', key)
+const sourceUid = (name) =>
+ toUid('src', name.replace(/[^a-zA-Z0-9]/g, '').slice(-8))
+
+// The tool's root region sits under a level 1 org unit, as on the server
+const ROOT = 'root'
+
+const getPath = (key, orgUnits) =>
+ key === ROOT
+ ? `/${orgUnitUid(ROOT)}`
+ : `${getPath(orgUnits[key].parent ?? ROOT, orgUnits)}/${orgUnitUid(
+ key
+ )}`
+
+const getSources = ({ collectionSources = [], operands = [] }) => [
+ ...collectionSources,
+ ...operands.flatMap(getSources),
+]
+
+const createServer = (hierarchy, item) => {
+ const sources = getSources(item)
+ const assignedTo = (key, field) =>
+ sources
+ .filter((source) => source[field] && source.orgUnits.includes(key))
+ .map((source) => sourceUid(source[field]))
+ const orgUnits = Object.entries({
+ [ROOT]: { level: 1 },
+ ...hierarchy.orgUnits,
+ }).map(([key, { level }]) => ({
+ id: orgUnitUid(key),
+ level,
+ path: getPath(key, hierarchy.orgUnits),
+ dataSets: assignedTo(key, 'dataSet'),
+ programs: assignedTo(key, 'program'),
+ }))
+ const groups = Object.fromEntries(
+ Object.entries(hierarchy.groups).map(([key, members]) => [
+ groupUid(key),
+ members.map(orgUnitUid),
+ ])
+ )
+ const userOrgUnits = [orgUnitUid('region')]
+
+ return createFakeOrgUnitServer({
+ orgUnits,
+ groups,
+ user: {
+ organisationUnits: userOrgUnits,
+ dataViewOrganisationUnits: userOrgUnits,
+ },
+ })
+}
+
+const toDataElement = ({ aggregationType = 'SUM', collectionSources }) => ({
+ aggregationType,
+ ...(collectionSources.find(({ aggregationLevels }) => aggregationLevels)
+ ?.aggregationLevels && {
+ aggregationLevels: collectionSources.find(
+ ({ aggregationLevels }) => aggregationLevels
+ ).aggregationLevels,
+ }),
+ dataSetElements: collectionSources.map(({ dataSet, periodType }) => ({
+ dataSet: { id: sourceUid(dataSet), periodType },
+ })),
+})
+
+// An org unit data element's id, for a program indicator placed by one
+const ORG_UNIT_DATA_ELEMENT = 'orgUnitDeAA'
+
+// The metadata the library would fetch for the case's item
+const getMetadata = (itemId, item) => {
+ const [source] = item.collectionSources ?? []
+
+ switch (item.dimensionItemType) {
+ case 'INDICATOR':
+ return normalizeDataItemProfileMetadata({
+ indicators: [
+ {
+ id: itemId,
+ numerator: item.numerator,
+ denominator: item.denominator,
+ },
+ ],
+ dataElements: item.operands.map((operand) => ({
+ id: operand.id,
+ ...toDataElement(operand),
+ })),
+ })
+ case 'PROGRAM_INDICATOR':
+ return normalizeDataItemProfileMetadata({
+ programIndicators: [
+ {
+ id: itemId,
+ program: { id: sourceUid(source.program) },
+ orgUnitField:
+ source.orgUnitField === 'DATA_ELEMENT'
+ ? ORG_UNIT_DATA_ELEMENT
+ : source.orgUnitField,
+ },
+ ],
+ programs: [{ id: sourceUid(source.program) }],
+ })
+ default:
+ return normalizeDataItemProfileMetadata({
+ dataElements: [{ id: itemId, ...toDataElement(item) }],
+ })
+ }
+}
+
+const toSelectionItem = (key, hierarchy) => {
+ if (hierarchy.orgUnits[key]) {
+ return orgUnitUid(key)
+ }
+
+ return key.startsWith('OU_GROUP-')
+ ? `OU_GROUP-${groupUid(key.slice('OU_GROUP-'.length))}`
+ : key
+}
+
+const judgeCase = async (hierarchy, { item, query }) => {
+ const itemId = 'itemUnderTe'
+ const profile = getDataItemProfile(
+ { id: itemId, dimensionItemType: item.dimensionItemType },
+ getMetadata(itemId, item)
+ )
+ const orgUnits = query.orgUnits.map((key) =>
+ toSelectionItem(key, hierarchy)
+ )
+ const coverage = await fetchOrgUnitCoverage(
+ createServer(hierarchy, item).createEngine(),
+ // With the totals, to check PARTLY_ASSIGNED too
+ {
+ sourceKeys: getDataItemProfileSourceKeys([profile]),
+ orgUnits,
+ withAssignmentTotals: true,
+ }
+ )
+
+ return getDataItemProfileOrgUnitCompatibility(
+ profile,
+ { orgUnits },
+ { orgUnitCoverage: coverage }
+ )[0]
+}
+
+const getExpected = ({ id, expected, observed }) => {
+ if (PREDICTION_DIFFERENCES[id]) {
+ return PREDICTION_DIFFERENCES[id]
+ }
+
+ const isRefused = Object.values(observed).every(({ error }) =>
+ error?.startsWith('E7143')
+ )
+
+ if (isRefused) {
+ return { status: 'none', reasons: ['EMPTY_GROUP'] }
+ }
+
+ const reasons = expected.reasons.map(
+ (reason) => REASON_BY_TOOL_NAME[reason] ?? reason
+ )
+
+ return {
+ status: expected.compatibility,
+ reasons: TOOL_LEAVES_OUT_PARTLY_ASSIGNED.has(id)
+ ? [...reasons, 'PARTLY_ASSIGNED']
+ : reasons,
+ }
+}
+
+/* What analytics must have returned on every version for the library's
+ * status: none, nothing (or the refusal of an empty group); partial, some
+ * values (the ones that reach the org unit); full, never an error. A full
+ * result says nothing is left out, not that there is data: a program with no
+ * event in an org unit gives nothing there. */
+const ANSWERS_BY_STATUS = {
+ none: ['EMPTY'],
+ partial: ['VALUE'],
+ full: ['VALUE', 'EMPTY'],
+}
+
+const agreesWithAnalytics = ({ status, reasons }, observed) =>
+ Object.values(observed).every((answer) =>
+ reasons.includes('EMPTY_GROUP')
+ ? answer.status === 'ERROR'
+ : ANSWERS_BY_STATUS[status].includes(answer.status)
+ )
+
+describe('org unit fixtures', () => {
+ describe.each(CASE_GROUPS)('%s', (group) => {
+ const { hierarchy, cases } = readFixture(group)
+
+ it.each(cases.map((fixtureCase) => [fixtureCase.id, fixtureCase]))(
+ '%s: the library judges as the tool expects, and as analytics answered',
+ async (_, fixtureCase) => {
+ const result = await judgeCase(hierarchy, fixtureCase)
+
+ expect({
+ status: result.status,
+ reasons: result.reasons,
+ }).toEqual(getExpected(fixtureCase))
+ expect(agreesWithAnalytics(result, fixtureCase.observed)).toBe(
+ true
+ )
+ }
+ )
+ })
+
+ // The org unit requests are recorded with the period ones, in metadata-shapes.json
+ describe('the metadata requests, as each version answered them', () => {
+ const { versions } = JSON.parse(
+ fs.readFileSync(
+ path.join(FIXTURES_DIR, '../period-types/metadata-shapes.json')
+ )
+ )
+
+ describe.each(Object.entries(versions))('%s', (_, { requests }) => {
+ const responseOf = (name) =>
+ requests.find((request) => request.name === name).response
+
+ it('give data elements their aggregation levels', () => {
+ const { dataElements } = normalizeDataItemProfileMetadata({
+ dataElements: responseOf('dataElements-aggregationLevels'),
+ })
+
+ expect(
+ Object.values(dataElements).map(
+ ({ aggregationLevels }) => aggregationLevels
+ )
+ ).toContainEqual([2, 3])
+ })
+
+ it('give program indicators their program and orgUnitField', () => {
+ const response = responseOf('programIndicators')
+ const { programIndicators } = normalizeDataItemProfileMetadata({
+ programIndicators: response,
+ })
+ const read = Object.entries(programIndicators).map(
+ ([id, { program, orgUnitField }]) => ({
+ id,
+ program,
+ orgUnitField,
+ })
+ )
+
+ expect(read).toEqual(
+ response.programIndicators.map(
+ ({ id, program, orgUnitField }) => ({
+ id,
+ program: program.id,
+ orgUnitField,
+ })
+ )
+ )
+ expect(read.some(({ orgUnitField }) => orgUnitField)).toBe(true)
+ })
+
+ it('give the user data view org units', () => {
+ expect(
+ responseOf('me-ptt-user').dataViewOrganisationUnits
+ ).toHaveLength(1)
+ })
+ })
+ })
+})
diff --git a/src/modules/dataItemProfile/__tests__/periodFixtures.spec.js b/src/modules/dataItemProfile/__tests__/periodFixtures.spec.js
new file mode 100644
index 000000000..571d2fdff
--- /dev/null
+++ b/src/modules/dataItemProfile/__tests__/periodFixtures.spec.js
@@ -0,0 +1,592 @@
+import fs from 'fs'
+import path from 'path'
+import { inDataSets } from '../../../__fixtures__/dataItemProfileMetadata.js'
+import { getDataItemProfile } from '../getDataItemProfile.js'
+import { getDataItemProfileCompatibility } from '../getDataItemProfileCompatibility.js'
+import { getYear } from '../periods/calendarDates.js'
+import {
+ getFirstOrLastValuePeriod,
+ getYearsTouched,
+} from '../periods/firstLastValues.js'
+import {
+ getFixedPeriodOfTypeByDate,
+ getPeriodDates,
+} from '../periods/periodRanges.js'
+import { getPeriodTypeOfPeriodId } from '../periods/periodTypes.js'
+import { getPeriodAggregationType } from '../profile/collectSources.js'
+
+/* The fixtures come from the test tool in dhis2/maps-tools
+ * (test-data-item-profile). PERIOD_TYPES_FIXTURES_DIR points the test at the
+ * tool's full export; a folder in it holds one group split in parts. */
+const FIXTURES_DIR =
+ process.env.PERIOD_TYPES_FIXTURES_DIR ??
+ path.join(__dirname, '../../../__fixtures__/period-types')
+
+const readFixtures = (dir) =>
+ fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+ const entryPath = path.join(dir, entry.name)
+
+ if (entry.isDirectory()) {
+ return readFixtures(entryPath)
+ }
+
+ return entry.name.endsWith('.json') &&
+ entry.name !== 'metadata-shapes.json'
+ ? [JSON.parse(fs.readFileSync(entryPath, 'utf8'))]
+ : []
+ })
+
+const LIBRARY_STATUS = {
+ VALUE: 'full',
+ REPEATED: 'full',
+ EMPTY: 'none',
+ PARTIAL: 'partial',
+ // Analytics refuses the query: aggregation type NONE, or QuarterlyNov on 2.40
+ ERROR: 'unknown',
+}
+
+const FIRST_OR_LAST_AGGREGATION =
+ /^(FIRST|LAST)(_AVERAGE_ORG_UNIT|_FIRST_ORG_UNIT|_LAST_ORG_UNIT)?$/
+
+const getItemParts = (item) => [item, ...(item.operands ?? [])]
+
+const takesFirstOrLast = (item) =>
+ getItemParts(item).some(({ aggregationType }) =>
+ FIRST_OR_LAST_AGGREGATION.test(aggregationType)
+ )
+
+const hasReportingRate = (item) =>
+ getItemParts(item).some(
+ ({ dimensionItemType }) => dimensionItemType === 'REPORTING_RATE'
+ )
+
+/* What the library should answer, as a status and the reason it must give,
+ * if any. The tool calls any value at a shorter period REPEATED; the library
+ * tells apart:
+ * - averaged values, repeated from the data period that holds the period:
+ * full, REPEATED_VALUE;
+ * - the value FIRST and LAST take from an earlier data period: full,
+ * EARLIER_PERIOD_VALUE; when there is none, none, NO_EARLIER_PERIOD_VALUE;
+ * - the meaningless value a reporting rate gives (0, or the expected reports
+ * count for another type of the same length): none,
+ * REPORTING_RATE_TOO_SHORT.
+ * FIRST also takes earlier values in periods its data adds up into
+ * (January's value for July), which the tool calls VALUE: any reason is
+ * accepted there. */
+const toExpected = ({ item }, { status }) => {
+ if (status === 'REPEATED') {
+ if (hasReportingRate(item)) {
+ return { status: 'none', reason: 'REPORTING_RATE_TOO_SHORT' }
+ }
+
+ return takesFirstOrLast(item)
+ ? { status: 'full', reason: 'EARLIER_PERIOD_VALUE' }
+ : { status: 'full', reason: 'REPEATED_VALUE' }
+ }
+
+ if (status === 'EMPTY' && takesFirstOrLast(item)) {
+ return { status: 'none', reason: 'NO_EARLIER_PERIOD_VALUE' }
+ }
+
+ return { status: LIBRARY_STATUS[status] }
+}
+
+const agrees = (expected, library) =>
+ expected.status === library.status &&
+ (!expected.reason || library.reasons.includes(expected.reason))
+
+const describeExpected = ({ status, reason }) =>
+ reason ? `${status} with ${reason}` : status
+
+const describeLibrary = ({ status, reasons }) =>
+ reasons.length ? `${status} [${reasons.join(', ')}]` : status
+
+/* Cases the metadata can't see: the library's answer differs from what
+ * analytics returns, on purpose, so they are not compared. The empty-result
+ * check after Update is the way to find them. */
+// The test data covers the periods of 2024 and 2025
+const TEST_DATA_START = '2024-01-01'
+
+// The periods asked in one request: the case's, and in the carry-windows group the other one of the pair
+const getRequestPeriods = ({ query }) =>
+ [query.period, query.withPeriod].filter(Boolean)
+
+const isFirstOrLast = ({ aggregationType }) =>
+ ['FIRST', 'LAST'].includes(getPeriodAggregationType(aggregationType))
+
+/* The data period whose value the library says FIRST or LAST data takes for
+ * the case's period, by the dates of the request's periods; null when none,
+ * undefined when it doesn't apply. `fromYear` leaves out the years before it,
+ * as when they hold no data. */
+const predictFirstOrLastValuePeriod = (
+ fixtureCase,
+ { periodAggregationType, fromYear = -Infinity } = {}
+) => {
+ const { item, query } = fixtureCase
+ const requestDates = getRequestPeriods(fixtureCase).map((period) =>
+ getPeriodDates(period)
+ )
+
+ if (
+ !isFirstOrLast(item) ||
+ (item.collectionPeriodTypes ?? []).length !== 1 ||
+ requestDates.includes(null)
+ ) {
+ return undefined
+ }
+
+ const years = [...new Set(requestDates.flatMap(getYearsTouched))].filter(
+ (year) => year >= fromYear
+ )
+
+ return years.length
+ ? getFirstOrLastValuePeriod({
+ periodAggregationType:
+ periodAggregationType ??
+ getPeriodAggregationType(item.aggregationType),
+ periodType: item.collectionPeriodTypes[0],
+ dates: getPeriodDates(query.period),
+ years,
+ })
+ : null
+}
+
+/* What analytics can answer when FIRST or LAST should take a period before
+ * the test data: nothing, or (where it names the data period) the first one
+ * with data among the years the request touches. That is the period holding
+ * the start of the test data (it overlaps 2024, so it holds data), or the
+ * first that counts in a year after it. Any other answer is compared, so a
+ * wrong prediction fails. */
+const answersWithoutEarlierData = (fixtureCase) => {
+ const firstDataPeriods = [
+ getFixedPeriodOfTypeByDate(
+ fixtureCase.item.collectionPeriodTypes[0],
+ TEST_DATA_START
+ ),
+ predictFirstOrLastValuePeriod(fixtureCase, {
+ periodAggregationType: 'FIRST',
+ fromYear: getYear(TEST_DATA_START),
+ }),
+ ].map((period) => period?.startDate)
+
+ return getOutcomes(fixtureCase).every(([, { value, source }]) =>
+ source
+ ? firstDataPeriods.includes(getPeriodDates(source)?.startDate)
+ : value === null || value === undefined
+ )
+}
+
+const METADATA_BLIND_SPOTS = [
+ {
+ pattern: /^mixed-history__.*__r-2024/,
+ reason: 'the metadata only shows the data sets of today',
+ },
+ {
+ pattern: /^mixed-orphan__/,
+ reason: 'without a data set, the metadata gives no period type',
+ },
+ {
+ pattern: /^ind-period-offset__/,
+ /* The test data starts with the periods that overlap 2024: the period
+ * before one that starts by then has none */
+ applies: ({ query }) =>
+ getPeriodDates(query.period)?.startDate <= TEST_DATA_START,
+ reason: 'periodOffset(-1) reads a period before the test data',
+ },
+ {
+ pattern: /^(agg|carry-dense|carry-pair)-/,
+ applies: (fixtureCase) => {
+ const source = predictFirstOrLastValuePeriod(fixtureCase)
+
+ return (
+ Boolean(source) &&
+ source.endDate < TEST_DATA_START &&
+ answersWithoutEarlierData(fixtureCase)
+ )
+ },
+ reason: 'FIRST or LAST takes a period before the test data',
+ },
+ {
+ pattern: /^carry-sparse-/,
+ reason: 'the library does not know which periods hold data',
+ // Not in every subset: its patterns can all be dense ones
+ optional: true,
+ },
+ {
+ pattern: /^carry-/,
+ applies: ({ query }) =>
+ getPeriodDates(query.period)?.endDate < TEST_DATA_START,
+ reason: 'the period ends before the test data',
+ },
+]
+
+const isBlindSpot = (fixtureCase) =>
+ METADATA_BLIND_SPOTS.some(
+ ({ pattern, applies = () => true }) =>
+ pattern.test(fixtureCase.id) && applies(fixtureCase)
+ )
+
+// collectionSources is optional in the fixtures: one data set per period type otherwise
+// With the category combo each data set gives the element, when the case names it
+const getDataSets = ({ collectionSources, collectionPeriodTypes }) =>
+ collectionSources
+ ? collectionSources.map(({ dataSet, periodType, categoryCombo }) => ({
+ id: dataSet,
+ periodType,
+ ...(categoryCombo && { categoryComboId: categoryCombo.id }),
+ }))
+ : inDataSets(collectionPeriodTypes)
+
+/* A disaggregation (group 16): the operand asked, and the category combo of
+ * its option combo, which the case names by key */
+const getDisaggregation = (item) => {
+ const optionCombo = item.categoryOptionCombo
+
+ if (!optionCombo) {
+ return { id: 'de', categoryOptionCombos: {} }
+ }
+
+ const combos = [item.categoryCombo, ...item.collectionSources].map(
+ (source) => source.categoryCombo ?? source
+ )
+ const categoryComboId = combos.find(
+ ({ key }) => key === optionCombo.categoryCombo
+ )?.id
+
+ return {
+ id: `de.${optionCombo.id}`,
+ categoryOptionCombos: { [optionCombo.id]: { categoryComboId } },
+ }
+}
+
+// Indicator operands need the id their expression uses
+const addOperands = (metadata, operands = []) => {
+ operands.forEach((operand) => {
+ if (!operand.id) {
+ throw new Error('an operand has no id')
+ }
+
+ if (operand.dimensionItemType === 'REPORTING_RATE') {
+ metadata.dataSets[operand.id] = {
+ periodType: operand.collectionPeriodTypes[0],
+ }
+ } else if (operand.dimensionItemType === 'INDICATOR') {
+ metadata.indicators[operand.id] = {
+ numerator: operand.numerator,
+ denominator: operand.denominator,
+ }
+ addOperands(metadata, operand.operands)
+ } else {
+ metadata.dataElements[operand.id] = {
+ aggregationType: operand.aggregationType,
+ dataSets: getDataSets(operand),
+ }
+ }
+ })
+}
+
+const toMetadata = ({ item }) => {
+ const metadata = {
+ dataElements: {},
+ dataSets: {},
+ indicators: {},
+ expressionDimensionItems: {},
+ }
+
+ switch (item.dimensionItemType) {
+ case 'REPORTING_RATE':
+ metadata.dataSets.ds = { periodType: item.collectionPeriodTypes[0] }
+ return { id: `ds.${item.metric ?? 'REPORTING_RATE'}`, metadata }
+ case 'INDICATOR':
+ metadata.indicators.item = {
+ numerator: item.numerator,
+ denominator: item.denominator,
+ }
+ addOperands(metadata, item.operands)
+ return { id: 'item', metadata }
+ case 'EXPRESSION_DIMENSION_ITEM':
+ metadata.expressionDimensionItems.item = {
+ expression: item.expression,
+ }
+ addOperands(metadata, item.operands)
+ return { id: 'item', metadata }
+ default: {
+ const { id, categoryOptionCombos } = getDisaggregation(item)
+
+ metadata.dataElements.de = {
+ aggregationType: item.aggregationType,
+ valueType: item.valueType,
+ dataSets: getDataSets(item),
+ }
+ metadata.categoryOptionCombos = categoryOptionCombos
+ return { id, metadata }
+ }
+ }
+}
+
+// What analytics returned on each version, or what is expected before a run
+const getOutcomes = (fixtureCase) => {
+ const observed = Object.entries(fixtureCase.observed ?? {})
+
+ return observed.length ? observed : [['expected', fixtureCase.expected]]
+}
+
+// '2.40.12' or '2.43.3-SNAPSHOT' to { major, minor }
+const toServerVersion = (version) => {
+ const [major, minor] = version.split('.').map(Number)
+
+ return Number.isInteger(minor) ? { major, minor } : undefined
+}
+
+// Ids the library reads as org unit uids (11 characters)
+const toOrgUnitUid = (key) => `place${key}xxxxxxxxxxx`.slice(0, 11)
+
+/* A case asked at an org unit, with its data sets assigned to some org units
+ * (by place: monthly at A, weekly at B): a coverage of those org units at
+ * level 2, under the one asked when it isn't one of them (the region) */
+const getPlaceCoverage = ({ item, query }) => {
+ const sources = item.collectionSources ?? []
+
+ if (!query.orgUnit || !sources.some(({ orgUnits }) => orgUnits)) {
+ return null
+ }
+
+ const keys = [...new Set(sources.flatMap(({ orgUnits = [] }) => orgUnits))]
+ const parentKey = keys.includes(query.orgUnit) ? 'Root' : query.orgUnit
+ const parent = {
+ id: toOrgUnitUid(parentKey),
+ level: 1,
+ path: `/${toOrgUnitUid(parentKey)}`,
+ }
+ const assignedAmong = (dataSetKeys, orgUnits) =>
+ dataSetKeys.filter((key) => orgUnits.includes(key)).length
+ const countsOf = (unitKeys) => ({
+ totals: { 2: unitKeys.length },
+ sources: Object.fromEntries(
+ sources.map(({ dataSet, orgUnits = [] }) => [
+ dataSet,
+ { byLevel: { 2: assignedAmong(unitKeys, orgUnits) } },
+ ])
+ ),
+ })
+
+ return {
+ levels: [{ level: 1 }, { level: 2 }],
+ orgUnits: {
+ [parent.id]: parent,
+ ...Object.fromEntries(
+ keys.map((key) => [
+ toOrgUnitUid(key),
+ {
+ id: toOrgUnitUid(key),
+ level: 2,
+ path: `${parent.path}/${toOrgUnitUid(key)}`,
+ },
+ ])
+ ),
+ },
+ counts: {
+ [parent.id]: countsOf(keys),
+ ...Object.fromEntries(
+ keys.map((key) => [toOrgUnitUid(key), countsOf([key])])
+ ),
+ },
+ }
+}
+
+const computeLibraryAnswer = (fixtureCase, serverVersion) => {
+ const { id, metadata } = toMetadata(fixtureCase)
+ const profile = getDataItemProfile(
+ { id, dimensionItemType: fixtureCase.item.dimensionItemType },
+ metadata
+ )
+ const { period, periodType } = fixtureCase.query
+ /* `period` is a period of the query type, or the range the query type is
+ * asked over (the weeks of 2025Q2) */
+ const asked =
+ getPeriodTypeOfPeriodId(period) === periodType ? period : periodType
+
+ const { withPeriod } = fixtureCase.query
+ const placeCoverage = getPlaceCoverage(fixtureCase)
+
+ // Asked at an org unit: the period judged there, with only the data sets assigned to it
+ if (placeCoverage) {
+ const { status, reasons } = getDataItemProfileCompatibility(
+ profile,
+ {
+ periods: [asked],
+ orgUnits: [toOrgUnitUid(fixtureCase.query.orgUnit)],
+ },
+ { serverVersion, orgUnitCoverage: placeCoverage }
+ )
+
+ return { status, reasons }
+ }
+
+ const { periods } = getDataItemProfileCompatibility(
+ profile,
+ { periods: withPeriod ? [asked, withPeriod] : [asked] },
+ { serverVersion }
+ )
+ const { status, reasons } = periods[0]
+
+ return { status, reasons }
+}
+
+/* The versions only differ for QuarterlyNov, which 2.40 can't answer: one
+ * answer for 2.40, one for the others */
+const libraryAnswers = new Map()
+
+const getLibraryAnswer = (fixtureCase, version) => {
+ const serverVersion = toServerVersion(version)
+ const key = `${fixtureCase.id}:${serverVersion?.minor < 41}`
+
+ if (!libraryAnswers.has(key)) {
+ libraryAnswers.set(
+ key,
+ computeLibraryAnswer(fixtureCase, serverVersion)
+ )
+ }
+
+ return libraryAnswers.get(key)
+}
+
+/* A case the metadata check can't read: a request without a period type
+ * (the detection requests, for the after-Update check), or operands without
+ * ids */
+const canRead = (fixtureCase) => {
+ try {
+ return (
+ Boolean(fixtureCase.item?.dimensionItemType) &&
+ Boolean(fixtureCase.query?.periodType) &&
+ toMetadata(fixtureCase)
+ )
+ } catch {
+ return false
+ }
+}
+
+const describeCase = ({ item, query }) =>
+ [
+ item.dimensionItemType,
+ item.aggregationType ?? item.metric,
+ (item.collectionPeriodTypes ?? []).join('+'),
+ `q ${query.periodType}`,
+ ].join(' ')
+
+/* One line per pattern, not per case: the full export has hundreds of
+ * thousands of outcomes */
+const summarize = (mismatches) =>
+ Object.values(
+ mismatches.reduce((patterns, mismatch) => {
+ const key = `${describeCase(mismatch.fixtureCase)}: analytics ${
+ mismatch.status
+ } (${describeExpected(
+ mismatch.expected
+ )}), library ${describeLibrary(mismatch.library)}`
+ const pattern = patterns[key] ?? { key, count: 0, example: '' }
+
+ pattern.count++
+ pattern.example ||= `${mismatch.fixtureCase.id} (${mismatch.version})`
+ patterns[key] = pattern
+
+ return patterns
+ }, {})
+ ).map(({ key, count, example }) => `${count}× ${key}, e.g. ${example}`)
+
+const fixtures = readFixtures(FIXTURES_DIR)
+const allCases = fixtures.flatMap(({ cases }) => cases)
+const casesOf = (group) =>
+ fixtures
+ .filter((fixture) => fixture.group === group)
+ .flatMap((fixture) => fixture.cases)
+const allGroups = [...new Set(fixtures.map(({ group }) => group))]
+// The detection requests are for the after-Update check: nothing to compare here
+const NOT_COMPARED_GROUPS = ['detection-requests']
+const groups = allGroups.filter((group) => !NOT_COMPARED_GROUPS.includes(group))
+
+describe('period type fixtures', () => {
+ it('are there', () => {
+ expect(allCases.length).toBeGreaterThan(0)
+ })
+
+ it('use only statuses the library maps', () => {
+ const statuses = allCases.flatMap((fixtureCase) =>
+ getOutcomes(fixtureCase).map(([, { status }]) => status)
+ )
+
+ expect(
+ [...new Set(statuses)].filter(
+ (status) => !(status in LIBRARY_STATUS)
+ )
+ ).toEqual([])
+ })
+
+ it('list only blind spots that exist', () => {
+ expect(
+ METADATA_BLIND_SPOTS.filter(
+ ({ pattern, applies = () => true, optional }) =>
+ !optional &&
+ !allCases.some(
+ (fixtureCase) =>
+ pattern.test(fixtureCase.id) && applies(fixtureCase)
+ )
+ ).map(({ reason }) => reason)
+ ).toEqual([])
+ })
+
+ /* The carry-windows group names the data period each FIRST or LAST value
+ * comes from. Where every period holds data (the dense layout), the
+ * library must pick the same one. */
+ it('pick the data period analytics names for FIRST and LAST', () => {
+ const cases = allCases.filter(
+ (fixtureCase) =>
+ fixtureCase.id.startsWith('carry-') &&
+ !isBlindSpot(fixtureCase) &&
+ predictFirstOrLastValuePeriod(fixtureCase) !== undefined
+ )
+ const startOf = (period) =>
+ period ? getPeriodDates(period)?.startDate ?? period : null
+ const mismatches = cases.flatMap((fixtureCase) => {
+ const predicted =
+ predictFirstOrLastValuePeriod(fixtureCase)?.startDate ?? null
+
+ return getOutcomes(fixtureCase)
+ .filter(([, { source }]) => startOf(source) !== predicted)
+ .map(
+ ([version, { source }]) =>
+ `${fixtureCase.id} (${version}): analytics ${source}, library ${predicted}`
+ )
+ })
+
+ expect(cases.length).toBeGreaterThan(0)
+ expect(mismatches.slice(0, 20)).toEqual([])
+ })
+
+ it('leave out only the groups the metadata check can’t read', () => {
+ expect(
+ allGroups.filter((group) => !casesOf(group).some(canRead))
+ ).toEqual(NOT_COMPARED_GROUPS)
+ })
+
+ it.each(groups)('%s: the library agrees with analytics', (group) => {
+ const cases = casesOf(group).filter(
+ (fixtureCase) => canRead(fixtureCase) && !isBlindSpot(fixtureCase)
+ )
+
+ expect(cases.length).toBeGreaterThan(0)
+ const mismatches = cases.flatMap((fixtureCase) =>
+ getOutcomes(fixtureCase)
+ .map(([version, outcome]) => ({
+ fixtureCase,
+ version,
+ status: outcome.status,
+ expected: toExpected(fixtureCase, outcome),
+ library: getLibraryAnswer(fixtureCase, version),
+ }))
+ .filter(({ expected, library }) => !agrees(expected, library))
+ )
+
+ expect(summarize(mismatches)).toEqual([])
+ })
+})
diff --git a/src/modules/dataItemProfile/__tests__/sources.spec.js b/src/modules/dataItemProfile/__tests__/sources.spec.js
new file mode 100644
index 000000000..66bfba2ea
--- /dev/null
+++ b/src/modules/dataItemProfile/__tests__/sources.spec.js
@@ -0,0 +1,131 @@
+import {
+ canBeAtAnyOrgUnit,
+ getAssignmentField,
+ getItemOperands,
+ getSourceId,
+ isProgramSource,
+ usesProgramOrgUnits,
+} from '../sources.js'
+
+const dataSetSource = (id, elements = [], reportingRate = false) => ({
+ dataSet: { id, periodType: 'Monthly' },
+ elements,
+ reportingRate,
+})
+const programSource = (id, extra = {}) => ({
+ dataSet: null,
+ program: { id },
+ elements: [],
+ reportingRate: false,
+ ...extra,
+})
+const unassignedSource = (elements) => ({
+ dataSet: null,
+ elements,
+ reportingRate: false,
+})
+const element = (id, aggregationType = 'SUM') => ({ id, aggregationType })
+
+describe('sources', () => {
+ it('tells a program from a data set or an element in no data set', () => {
+ expect(isProgramSource(programSource('programAAA'))).toBe(true)
+ expect(isProgramSource(dataSetSource('dataSetAAA'))).toBe(false)
+ expect(isProgramSource(unassignedSource([]))).toBe(false)
+ })
+
+ it('gives the id of the data set or program, or null', () => {
+ expect(getSourceId(dataSetSource('dataSetAAA'))).toBe('dataSetAAA')
+ expect(getSourceId(programSource('programAAA'))).toBe('programAAA')
+ expect(getSourceId(unassignedSource([]))).toBeNull()
+ })
+
+ it('gives the org unit field that lists where a source is assigned', () => {
+ expect(getAssignmentField(dataSetSource('dataSetAAA'))).toBe('dataSets')
+ expect(getAssignmentField(programSource('programAAA'))).toBe('programs')
+ })
+
+ it.each([
+ undefined,
+ 'EVENT',
+ 'ENROLLMENT',
+ 'OWNER_AT_START',
+ 'OWNER_AT_END',
+ ])(
+ 'places values where the program is assigned with orgUnitField %s',
+ (orgUnitField) => {
+ expect(usesProgramOrgUnits(orgUnitField)).toBe(true)
+ expect(
+ canBeAtAnyOrgUnit(programSource('p', { orgUnitField }))
+ ).toBe(false)
+ }
+ )
+
+ it.each(['REGISTRATION', 'orgUnitDeAA'])(
+ 'places values at any org unit with orgUnitField %s',
+ (orgUnitField) => {
+ expect(usesProgramOrgUnits(orgUnitField)).toBe(false)
+ expect(
+ canBeAtAnyOrgUnit(programSource('p', { orgUnitField }))
+ ).toBe(true)
+ }
+ )
+
+ describe('getItemOperands', () => {
+ it('groups an element over the sources it is in', () => {
+ const monthly = dataSetSource('monthlyForm', [element('elementA')])
+ const weekly = dataSetSource('weeklyForm', [element('elementA')])
+
+ expect(getItemOperands({ sources: [monthly, weekly] })).toEqual([
+ {
+ key: 'element:elementA:SUM',
+ element: element('elementA'),
+ sources: [monthly, weekly],
+ },
+ ])
+ })
+
+ it('keeps an element with another aggregation type apart', () => {
+ const source = dataSetSource('monthlyForm', [
+ element('elementA'),
+ element('elementA', 'LAST'),
+ ])
+
+ expect(getItemOperands({ sources: [source] })).toHaveLength(2)
+ })
+
+ it('adds each reporting rate and each program as an operand', () => {
+ const rate = dataSetSource('monthlyForm', [], true)
+ const program = programSource('programAAA')
+
+ expect(getItemOperands({ sources: [rate, program] })).toEqual([
+ {
+ key: 'reportingRate:monthlyForm',
+ reportingRate: true,
+ sources: [rate],
+ },
+ {
+ key: 'program:programAAA::',
+ program: true,
+ sources: [program],
+ },
+ ])
+ })
+
+ it('keys a program apart by where and how its indicators place values', () => {
+ expect(
+ getItemOperands({
+ sources: [
+ programSource('programAAA', {
+ orgUnitField: 'REGISTRATION',
+ missingPeriodBoundaries: true,
+ }),
+ ],
+ })[0].key
+ ).toBe('program:programAAA:REGISTRATION:missingPeriodBoundaries')
+ })
+
+ it('has no operand without sources', () => {
+ expect(getItemOperands({ sources: [] })).toEqual([])
+ })
+ })
+})
diff --git a/src/modules/dataItemProfile/compatibility/__tests__/combineResults.spec.js b/src/modules/dataItemProfile/compatibility/__tests__/combineResults.spec.js
new file mode 100644
index 000000000..86c8a838d
--- /dev/null
+++ b/src/modules/dataItemProfile/compatibility/__tests__/combineResults.spec.js
@@ -0,0 +1,201 @@
+import {
+ combineAddedUpResults,
+ combineExpressionResults,
+ combineOperandResults,
+ combineResults,
+ createResult,
+ getMostSevere,
+ getUnknownResult,
+ unionOfReasons,
+} from '../combineResults.js'
+
+const full = (reasons) => createResult('full', reasons)
+const partial = (reasons) => createResult('partial', reasons)
+const none = (reasons) => createResult('none', reasons)
+
+describe('combineResults', () => {
+ it('creates a result with no reason by default', () => {
+ expect(createResult('full')).toEqual({ status: 'full', reasons: [] })
+ expect(getUnknownResult('UNKNOWN_PERIOD')).toEqual({
+ status: 'unknown',
+ reasons: ['UNKNOWN_PERIOD'],
+ })
+ })
+
+ it('lists every reason once, in the reason order', () => {
+ expect(
+ unionOfReasons([
+ full(['REPEATED_VALUE']),
+ none(['PERIOD_TOO_SHORT', 'REPEATED_VALUE']),
+ ])
+ ).toEqual(['PERIOD_TOO_SHORT', 'REPEATED_VALUE'])
+ })
+
+ it('picks the most severe result: none, partial, unknown, full', () => {
+ const unknown = getUnknownResult('UNKNOWN_PERIOD')
+
+ expect(getMostSevere([full(), unknown, partial()])).toEqual(partial())
+ expect(getMostSevere([full(), unknown])).toBe(unknown)
+ expect(getMostSevere([])).toBeUndefined()
+ })
+
+ it('combines into the most severe status with every reason', () => {
+ expect(
+ combineResults([
+ full(['REPEATED_VALUE']),
+ none(['PERIOD_TOO_SHORT']),
+ ])
+ ).toEqual(none(['PERIOD_TOO_SHORT', 'REPEATED_VALUE']))
+ expect(combineResults([])).toEqual(full())
+ })
+
+ describe('combineAddedUpResults', () => {
+ it('is none when all are, partial when some are none or partial', () => {
+ expect(
+ combineAddedUpResults([
+ none(['PERIOD_TOO_SHORT']),
+ none(['NO_EARLIER_PERIOD_VALUE']),
+ ])
+ ).toEqual(none(['PERIOD_TOO_SHORT', 'NO_EARLIER_PERIOD_VALUE']))
+ expect(
+ combineAddedUpResults([full(), none(['PERIOD_TOO_SHORT'])])
+ ).toEqual(partial(['PERIOD_TOO_SHORT']))
+ expect(
+ combineAddedUpResults([full(), partial(['OPERAND_PARTIAL'])])
+ ).toEqual(partial(['OPERAND_PARTIAL']))
+ })
+
+ it('is unknown when the results without none are all unknown', () => {
+ expect(
+ combineAddedUpResults([
+ none(['PERIOD_TOO_SHORT']),
+ getUnknownResult('UNKNOWN_PERIOD'),
+ ])
+ ).toEqual(
+ createResult('unknown', ['PERIOD_TOO_SHORT', 'UNKNOWN_PERIOD'])
+ )
+ expect(
+ combineAddedUpResults([
+ full(),
+ none(['PERIOD_TOO_SHORT']),
+ getUnknownResult('UNKNOWN_PERIOD'),
+ ])
+ ).toEqual(partial(['PERIOD_TOO_SHORT', 'UNKNOWN_PERIOD']))
+ })
+
+ it('is otherwise the most severe of the rest, and full for none', () => {
+ expect(
+ combineAddedUpResults([
+ full(),
+ getUnknownResult('UNSUPPORTED_VERSION'),
+ ])
+ ).toEqual(getUnknownResult('UNSUPPORTED_VERSION'))
+ expect(combineAddedUpResults([])).toEqual(full())
+ })
+ })
+
+ describe('combineOperandResults', () => {
+ it('says first when an operand of an expression gives none or leaves values out', () => {
+ expect(
+ combineOperandResults([full(), none(['PERIOD_TOO_SHORT'])])
+ ).toEqual(none(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ expect(
+ combineOperandResults([
+ full(),
+ partial(['PERIOD_TYPE_MISMATCH']),
+ ])
+ ).toEqual(partial(['OPERAND_PARTIAL', 'PERIOD_TYPE_MISMATCH']))
+ })
+
+ it('adds operands up when a missing value counts as 0', () => {
+ expect(
+ combineOperandResults(
+ [full(), none(['PERIOD_TOO_SHORT'])],
+ 'SKIP_IF_ALL_VALUES_MISSING'
+ )
+ ).toEqual(partial(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ expect(
+ combineOperandResults(
+ [none(['PERIOD_TOO_SHORT']), partial(['REPEATED_VALUE'])],
+ 'SKIP_IF_ALL_VALUES_MISSING'
+ )
+ ).toEqual(
+ partial([
+ 'OPERAND_EMPTY',
+ 'OPERAND_PARTIAL',
+ 'PERIOD_TOO_SHORT',
+ 'REPEATED_VALUE',
+ ])
+ )
+ expect(
+ combineOperandResults(
+ [none(['PERIOD_TOO_SHORT']), none(['PERIOD_TOO_SHORT'])],
+ 'SKIP_IF_ALL_VALUES_MISSING'
+ )
+ ).toEqual(none(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ })
+
+ it('says nothing more for a single operand, or a full result', () => {
+ expect(combineOperandResults([none(['PERIOD_TOO_SHORT'])])).toEqual(
+ none(['PERIOD_TOO_SHORT'])
+ )
+ expect(combineOperandResults([full(), full()])).toEqual(full())
+ })
+ })
+
+ describe('combineExpressionResults', () => {
+ const results = {
+ a: full(),
+ b: none(['PERIOD_TOO_SHORT']),
+ }
+ const resultOf = (key) => results[key]
+
+ it('needs every operand without an expression', () => {
+ expect(
+ combineExpressionResults(undefined, ['a', 'b'], resultOf)
+ ).toEqual(none(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ })
+
+ it('combines nested parts by their strategies', () => {
+ const sum = {
+ missingValueStrategy: 'SKIP_IF_ALL_VALUES_MISSING',
+ parts: [{ operand: 'a' }, { operand: 'b' }],
+ }
+
+ expect(combineExpressionResults(sum, [], resultOf)).toEqual(
+ partial(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT'])
+ )
+ expect(
+ combineExpressionResults(
+ {
+ missingValueStrategy: 'SKIP_IF_ANY_VALUE_MISSING',
+ parts: [sum, { operand: 'b' }],
+ },
+ [],
+ resultOf
+ )
+ ).toEqual(none(['OPERAND_EMPTY', 'PERIOD_TOO_SHORT']))
+ })
+
+ it('leaves out parts with no operand, and is full without any', () => {
+ const constants = {
+ missingValueStrategy: 'SKIP_IF_ALL_VALUES_MISSING',
+ parts: [],
+ }
+
+ expect(
+ combineExpressionResults(
+ {
+ missingValueStrategy: 'SKIP_IF_ANY_VALUE_MISSING',
+ parts: [{ operand: 'b' }, constants],
+ },
+ [],
+ resultOf
+ )
+ ).toEqual(none(['PERIOD_TOO_SHORT']))
+ expect(combineExpressionResults(undefined, [], resultOf)).toEqual(
+ full()
+ )
+ })
+ })
+})
diff --git a/src/modules/dataItemProfile/compatibility/__tests__/getDataItemProfileOrgUnitCompatibility.spec.js b/src/modules/dataItemProfile/compatibility/__tests__/getDataItemProfileOrgUnitCompatibility.spec.js
new file mode 100644
index 000000000..c69be6864
--- /dev/null
+++ b/src/modules/dataItemProfile/compatibility/__tests__/getDataItemProfileOrgUnitCompatibility.spec.js
@@ -0,0 +1,464 @@
+import {
+ ORG_UNIT_COVERAGE as COVERAGE,
+ orgUnitProfileOf as profileOf,
+} from '../../../../__fixtures__/dataItemProfileOrgUnits.js'
+import { getDataItemProfileOrgUnitCompatibility } from '../getDataItemProfileOrgUnitCompatibility.js'
+
+const judge = (id, orgUnits, { type, coverage = COVERAGE } = {}) =>
+ getDataItemProfileOrgUnitCompatibility(
+ profileOf(id, type),
+ { orgUnits },
+ { orgUnitCoverage: coverage }
+ )
+
+describe('getDataItemProfileOrgUnitCompatibility', () => {
+ it('is full where every org unit at the deepest level assigned is', () => {
+ expect(judge('facility', ['districtAAA'])).toEqual([
+ {
+ id: 'districtAAA',
+ status: 'full',
+ reasons: [],
+ assignment: { assigned: 2, total: 2, level: 3 },
+ },
+ ])
+ })
+
+ it('is full where only some are, since the others aren’t assigned', () => {
+ expect(judge('facility', ['nationUnit1'])).toEqual([
+ {
+ id: 'nationUnit1',
+ status: 'full',
+ reasons: ['PARTLY_ASSIGNED'],
+ assignment: { assigned: 3, total: 4, level: 3 },
+ },
+ ])
+ })
+
+ it('gives no total, nor PARTLY_ASSIGNED, when the org units weren’t counted', () => {
+ const withoutTotals = {
+ ...COVERAGE,
+ counts: Object.fromEntries(
+ Object.entries(COVERAGE.counts).map(([key, counts]) => [
+ key,
+ { ...counts, totals: {} },
+ ])
+ ),
+ }
+
+ expect(
+ judge('facility', ['nationUnit1'], { coverage: withoutTotals })
+ ).toEqual([
+ {
+ id: 'nationUnit1',
+ status: 'full',
+ reasons: [],
+ assignment: { assigned: 3, level: 3 },
+ },
+ ])
+ expect(
+ judge('facility', ['LEVEL-2'], { coverage: withoutTotals })[0]
+ .assignment
+ ).toEqual({ assigned: 3, level: 3 })
+ })
+
+ it('is none, assigned higher, where only an ancestor of the org unit is assigned', () => {
+ expect(judge('facility', ['facilityDDD'])).toMatchObject([
+ {
+ status: 'none',
+ reasons: ['ASSIGNED_AT_HIGHER_LEVEL'],
+ assignment: null,
+ },
+ ])
+ })
+
+ it('is none, not assigned, where neither the org unit nor its ancestors are', () => {
+ expect(
+ judge('pi', ['facilityDDD'], { type: 'PROGRAM_INDICATOR' })
+ ).toMatchObject([
+ { status: 'none', reasons: ['NOT_ASSIGNED'], assignment: null },
+ ])
+ })
+
+ it('is none below the levels it is assigned at', () => {
+ expect(judge('district', ['facilityAAA'])).toMatchObject([
+ { status: 'none', reasons: ['ASSIGNED_AT_HIGHER_LEVEL'] },
+ ])
+ expect(judge('district', ['nationUnit1', 'LEVEL-3'])).toMatchObject([
+ {
+ id: 'LEVEL-3',
+ status: 'none',
+ reasons: ['ASSIGNED_AT_HIGHER_LEVEL'],
+ },
+ ])
+ })
+
+ it('counts an element where any of its data sets is assigned', () => {
+ // The monthly form is assigned to the nation above facilityDDD: its values are left out there
+ expect(judge('twoForms', ['facilityDDD'])).toMatchObject([
+ { status: 'partial', reasons: ['ASSIGNED_AT_HIGHER_LEVEL'] },
+ ])
+ expect(judge('twoForms', ['nationUnit1'])).toMatchObject([
+ {
+ status: 'full',
+ reasons: ['PARTLY_ASSIGNED'],
+ assignment: { assigned: 3, total: 4 },
+ },
+ ])
+ })
+
+ it('is not partly assigned when one data set is assigned to every org unit', () => {
+ const coverage = {
+ ...COVERAGE,
+ counts: {
+ ...COVERAGE.counts,
+ districtBBB: {
+ totals: { 2: 1, 3: 2 },
+ sources: {
+ MonthlyForm: { byLevel: { 3: 2 } },
+ WeeklyForm: { byLevel: { 3: 1 } },
+ },
+ },
+ },
+ }
+
+ expect(judge('twoForms', ['districtBBB'], { coverage })).toEqual([
+ {
+ id: 'districtBBB',
+ status: 'full',
+ reasons: [],
+ assignment: { assigned: 2, total: 2, level: 3 },
+ },
+ ])
+ })
+
+ it('is partial when another data set is assigned at a higher level: its values are left out', () => {
+ expect(judge('twoLevels', ['facilityAAA'])).toEqual([
+ {
+ id: 'facilityAAA',
+ status: 'partial',
+ reasons: ['ASSIGNED_AT_HIGHER_LEVEL'],
+ assignment: { assigned: 1, total: 1, level: 3 },
+ },
+ ])
+ })
+
+ it('needs every operand of an expression', () => {
+ expect(
+ judge('ratio', ['facilityAAA'], { type: 'INDICATOR' })
+ ).toMatchObject([
+ {
+ status: 'none',
+ reasons: ['OPERAND_EMPTY', 'ASSIGNED_AT_HIGHER_LEVEL'],
+ },
+ ])
+ expect(
+ judge('MonthlyForm.REPORTING_RATE', ['districtAAA'], {
+ type: 'REPORTING_RATE',
+ })
+ ).toMatchObject([{ status: 'full' }])
+ expect(
+ judge('completeness', ['facilityDDD'], { type: 'INDICATOR' })
+ ).toMatchObject([
+ {
+ status: 'none',
+ reasons: ['OPERAND_EMPTY', 'ASSIGNED_AT_HIGHER_LEVEL'],
+ },
+ ])
+ })
+
+ it('is partial for a sum where one item has no value, which counts as 0', () => {
+ expect(
+ judge('facilityPlusDistrict', ['facilityAAA'], {
+ type: 'INDICATOR',
+ })
+ ).toMatchObject([
+ {
+ status: 'partial',
+ reasons: ['OPERAND_EMPTY', 'ASSIGNED_AT_HIGHER_LEVEL'],
+ },
+ ])
+ })
+
+ it('says an expression is computed from a partial operand', () => {
+ expect(
+ judge('partOfTotal', ['facilityAAA'], { type: 'INDICATOR' })
+ ).toMatchObject([
+ {
+ status: 'partial',
+ reasons: ['OPERAND_PARTIAL', 'ASSIGNED_AT_HIGHER_LEVEL'],
+ },
+ ])
+ })
+
+ it('stops values below an aggregation level from reaching it', () => {
+ expect(judge('cappedAtDistrict', ['districtAAA'])).toEqual([
+ {
+ id: 'districtAAA',
+ status: 'none',
+ reasons: ['STOPPED_BY_AGGREGATION_LEVEL'],
+ assignment: null,
+ },
+ ])
+ expect(judge('cappedAtDistrict', ['facilityAAA'])).toMatchObject([
+ { status: 'full', reasons: [] },
+ ])
+ })
+
+ it('counts values from the aggregation level or above it', () => {
+ expect(judge('cappedAtDistrict', ['nationUnit1'])).toMatchObject([
+ {
+ status: 'full',
+ assignment: { assigned: 1, total: 1, level: 1 },
+ },
+ ])
+ })
+
+ it('is partial when the values of one data set are stopped', () => {
+ expect(judge('cappedWithDistrictForm', ['districtAAA'])).toMatchObject([
+ { status: 'partial', reasons: ['STOPPED_BY_AGGREGATION_LEVEL'] },
+ ])
+ })
+
+ it('judges a level under parent org units, adding up their counts', () => {
+ expect(
+ judge('facility', ['districtAAA', 'districtBBB', 'LEVEL-3'])
+ ).toEqual([
+ {
+ id: 'LEVEL-3',
+ status: 'full',
+ reasons: ['PARTLY_ASSIGNED'],
+ assignment: { assigned: 3, total: 4, level: 3 },
+ },
+ ])
+ })
+
+ it('judges a level under the roots, and the user org units', () => {
+ expect(judge('district', ['LEVEL-2'])).toMatchObject([
+ { status: 'full', assignment: { assigned: 2, total: 2 } },
+ ])
+ expect(judge('facility', ['USER_ORGUNIT_CHILDREN'])).toMatchObject([
+ { status: 'full', assignment: { assigned: 1, total: 2 } },
+ ])
+ })
+
+ it('is none, with no org units there, for a level above every parent or below the hierarchy', () => {
+ expect(judge('facility', ['facilityAAA', 'LEVEL-2'])).toEqual([
+ {
+ id: 'LEVEL-2',
+ status: 'none',
+ reasons: ['NO_ORG_UNITS_AT_LEVEL'],
+ assignment: null,
+ },
+ ])
+ expect(judge('facility', ['nationUnit1', 'LEVEL-9'])).toMatchObject([
+ { status: 'none', reasons: ['NO_ORG_UNITS_AT_LEVEL'] },
+ ])
+ })
+
+ it('adds up a level under several parents: one with nothing assigned only lowers the counts', () => {
+ expect(
+ judge('pi', ['districtAAA', 'districtBBB', 'LEVEL-3'], {
+ type: 'PROGRAM_INDICATOR',
+ })
+ ).toEqual([
+ {
+ id: 'LEVEL-3',
+ status: 'full',
+ reasons: ['PARTLY_ASSIGNED'],
+ assignment: { assigned: 2, total: 4, level: 3 },
+ },
+ ])
+ })
+
+ it('is partial for a level under several parents where values are left out', () => {
+ expect(
+ judge('twoLevels', ['districtAAA', 'districtBBB', 'LEVEL-3'])
+ ).toMatchObject([
+ {
+ status: 'partial',
+ reasons: ['ASSIGNED_AT_HIGHER_LEVEL', 'PARTLY_ASSIGNED'],
+ assignment: { assigned: 3, total: 4, level: 3 },
+ },
+ ])
+ })
+
+ it('is partial for a level under several parents where an operand has no value under one', () => {
+ // districtBBB: facilities collect the numerator, nothing the denominator
+ const coverage = {
+ ...COVERAGE,
+ counts: {
+ ...COVERAGE.counts,
+ districtBBB: {
+ totals: { 2: 1, 3: 2 },
+ sources: {
+ MonthlyForm: { byLevel: { 3: 1 } },
+ QuarterlyForm: { byLevel: {} },
+ },
+ },
+ },
+ }
+
+ expect(
+ judge('ratio', ['LEVEL-2', 'districtAAA', 'districtBBB'], {
+ type: 'INDICATOR',
+ coverage,
+ })
+ ).toMatchObject([
+ {
+ status: 'partial',
+ reasons: ['OPERAND_EMPTY', 'PARTLY_ASSIGNED'],
+ },
+ ])
+ })
+
+ it('takes the user org units as parents of a level', () => {
+ expect(judge('facility', ['USER_ORGUNIT', 'LEVEL-3'])).toEqual([
+ {
+ id: 'LEVEL-3',
+ status: 'full',
+ reasons: ['PARTLY_ASSIGNED'],
+ assignment: { assigned: 1, total: 2, level: 3 },
+ },
+ ])
+ })
+
+ it('judges event data where its program is assigned', () => {
+ expect(
+ judge('pi', ['nationUnit1'], { type: 'PROGRAM_INDICATOR' })
+ ).toEqual([
+ {
+ id: 'nationUnit1',
+ status: 'full',
+ reasons: ['PARTLY_ASSIGNED'],
+ assignment: { assigned: 2, total: 4, level: 3 },
+ },
+ ])
+ expect(
+ judge('pi', ['facilityDDD'], { type: 'PROGRAM_INDICATOR' })
+ ).toMatchObject([{ status: 'none', reasons: ['NOT_ASSIGNED'] }])
+ expect(
+ judge('eventProgra.someElement', ['facilityDDD'], {
+ type: 'PROGRAM_DATA_ELEMENT',
+ })
+ ).toMatchObject([{ status: 'none', reasons: ['NOT_ASSIGNED'] }])
+ })
+
+ it('needs the program of an indicator too', () => {
+ expect(
+ judge('casesPerFacility', ['facilityDDD'], { type: 'INDICATOR' })
+ ).toMatchObject([
+ {
+ status: 'none',
+ reasons: [
+ 'OPERAND_EMPTY',
+ 'NOT_ASSIGNED',
+ 'ASSIGNED_AT_HIGHER_LEVEL',
+ ],
+ },
+ ])
+ })
+
+ it('judges a group where its members are', () => {
+ expect(judge('facility', ['OU_GROUP-clinicGroup'])).toEqual([
+ {
+ id: 'OU_GROUP-clinicGroup',
+ status: 'full',
+ reasons: ['PARTLY_ASSIGNED'],
+ assignment: { assigned: 1, total: 2, level: 3 },
+ },
+ ])
+ expect(judge('district', ['OU_GROUP-clinicGroup'])).toMatchObject([
+ { status: 'none', reasons: ['ASSIGNED_AT_HIGHER_LEVEL'] },
+ ])
+ })
+
+ it('adds up a group over the levels its members are at', () => {
+ expect(judge('facility', ['OU_GROUP-mixedGroupA'])).toMatchObject([
+ {
+ status: 'full',
+ reasons: ['PARTLY_ASSIGNED'],
+ assignment: { assigned: 2, total: 3, level: 3 },
+ },
+ ])
+ })
+
+ it('leaves out the levels with no member under the parent org units', () => {
+ expect(
+ judge('facility', ['districtAAA', 'OU_GROUP-mixedGroupA'])
+ ).toEqual([
+ {
+ id: 'OU_GROUP-mixedGroupA',
+ status: 'full',
+ reasons: [],
+ assignment: { assigned: 1, total: 1, level: 3 },
+ },
+ ])
+ })
+
+ it('is none for a group with no members, which analytics refuses', () => {
+ expect(judge('facility', ['OU_GROUP-emptyGroupA'])).toEqual([
+ {
+ id: 'OU_GROUP-emptyGroupA',
+ status: 'none',
+ reasons: ['EMPTY_GROUP'],
+ assignment: null,
+ },
+ ])
+ })
+
+ it('is full for an item with no source, nothing limits where it has values', () => {
+ expect(
+ judge('constantsOnly', ['facilityDDD'], { type: 'INDICATOR' })
+ ).toEqual([
+ {
+ id: 'facilityDDD',
+ status: 'full',
+ reasons: [],
+ assignment: null,
+ },
+ ])
+ })
+
+ it('fits any org unit for a program indicator placed by registration or an attribute', () => {
+ expect(
+ judge('piByRegistr', ['facilityDDD'], { type: 'PROGRAM_INDICATOR' })
+ ).toEqual([
+ {
+ id: 'facilityDDD',
+ status: 'full',
+ reasons: ['ANY_ORG_UNIT'],
+ assignment: null,
+ },
+ ])
+ expect(
+ judge('piByAttribu', ['facilityDDD'], { type: 'PROGRAM_INDICATOR' })
+ ).toMatchObject([{ status: 'full', reasons: ['ANY_ORG_UNIT'] }])
+ })
+
+ it('keeps the program assignment for a program indicator placed by owner', () => {
+ expect(
+ judge('piByOwner', ['facilityDDD'], { type: 'PROGRAM_INDICATOR' })
+ ).toMatchObject([{ status: 'none', reasons: ['NOT_ASSIGNED'] }])
+ })
+
+ it('cannot tell for groups or org units not loaded, or missing metadata', () => {
+ expect(judge('facility', ['OU_GROUP-notLoadedGr'])).toMatchObject([
+ { status: 'unknown', reasons: ['UNKNOWN_ORG_UNIT'] },
+ ])
+ expect(judge('facility', ['notLoadedUn'])).toMatchObject([
+ { status: 'unknown', reasons: ['UNKNOWN_ORG_UNIT'] },
+ ])
+ expect(
+ judge('facility', ['nationUnit1'], { coverage: null })
+ ).toMatchObject([{ status: 'unknown', reasons: ['UNKNOWN_ORG_UNIT'] }])
+ expect(
+ judge('someElement', ['nationUnit1'], { type: 'EVENT_DATA_ITEM' })
+ ).toMatchObject([{ status: 'unknown', reasons: ['PROFILE_UNKNOWN'] }])
+ expect(
+ judge('notThere', ['nationUnit1'], { type: 'PROGRAM_INDICATOR' })
+ ).toMatchObject([{ status: 'unknown', reasons: ['PROFILE_UNKNOWN'] }])
+ expect(judge('orphan', ['nationUnit1'])).toMatchObject([
+ { status: 'unknown', reasons: ['PROFILE_UNKNOWN'] },
+ ])
+ })
+})
diff --git a/src/modules/dataItemProfile/compatibility/__tests__/periodAtOrgUnitResults.spec.js b/src/modules/dataItemProfile/compatibility/__tests__/periodAtOrgUnitResults.spec.js
new file mode 100644
index 000000000..973c2e463
--- /dev/null
+++ b/src/modules/dataItemProfile/compatibility/__tests__/periodAtOrgUnitResults.spec.js
@@ -0,0 +1,88 @@
+import {
+ ORG_UNIT_COVERAGE as COVERAGE,
+ orgUnitProfileOf as profileOf,
+} from '../../../../__fixtures__/dataItemProfileOrgUnits.js'
+import { getPeriodAtOrgUnitResults } from '../periodAtOrgUnitResults.js'
+
+const judge = (id, selection, { type, coverage = COVERAGE } = {}) =>
+ getPeriodAtOrgUnitResults(profileOf(id, type), selection, {
+ orgUnitCoverage: coverage,
+ }).map(({ periodId, orgUnitId, status, reasons }) => [
+ periodId,
+ orgUnitId,
+ status,
+ reasons,
+ ])
+
+/* twoForms: a monthly data set at 3 of the 4 facilities (and the nation), a
+ * weekly one at facilityDDD only */
+describe('getPeriodAtOrgUnitResults', () => {
+ it('counts only the data sets assigned at the org unit', () => {
+ expect(
+ judge('twoForms', {
+ periods: ['2025W2'],
+ orgUnits: ['facilityAAA', 'facilityDDD'],
+ })
+ ).toEqual([
+ // Only the monthly data set is assigned at facilityAAA: nothing by week
+ ['2025W2', 'facilityAAA', 'none', ['PERIOD_TOO_SHORT']],
+ // The weekly one fills it at facilityDDD; the nation's monthly values are left out
+ ['2025W2', 'facilityDDD', 'partial', ['ASSIGNED_AT_HIGHER_LEVEL']],
+ ])
+ })
+
+ it('judges each period at each org unit', () => {
+ expect(
+ judge('twoForms', {
+ periods: ['202501', '2025W2'],
+ orgUnits: ['facilityAAA'],
+ }).map(([periodId, , status]) => [periodId, status])
+ ).toEqual([
+ ['202501', 'full'],
+ ['2025W2', 'none'],
+ ])
+ })
+
+ it('adds up a level under parents where the data sets are assigned', () => {
+ expect(
+ judge('facility', {
+ periods: ['2025Q1'],
+ orgUnits: ['LEVEL-3', 'districtAAA', 'districtBBB'],
+ })
+ ).toEqual([['2025Q1', 'LEVEL-3', 'full', ['PARTLY_ASSIGNED']]])
+ })
+
+ it('is none where nothing is assigned, whatever the period', () => {
+ expect(
+ judge(
+ 'pi',
+ { periods: ['2025Q1'], orgUnits: ['facilityDDD'] },
+ {
+ type: 'PROGRAM_INDICATOR',
+ }
+ )
+ ).toEqual([['2025Q1', 'facilityDDD', 'none', ['NOT_ASSIGNED']]])
+ })
+
+ it('gives the org unit result where it needs no period, and cannot tell without coverage or profile', () => {
+ expect(
+ judge('facility', {
+ periods: ['2025Q1'],
+ orgUnits: ['OU_GROUP-emptyGroupA'],
+ })
+ ).toEqual([['2025Q1', 'OU_GROUP-emptyGroupA', 'none', ['EMPTY_GROUP']]])
+ expect(
+ judge(
+ 'facility',
+ { periods: ['2025Q1'], orgUnits: ['facilityAAA'] },
+ { coverage: null }
+ )
+ ).toEqual([['2025Q1', 'facilityAAA', 'unknown', ['UNKNOWN_ORG_UNIT']]])
+ expect(
+ judge('missing', {
+ periods: ['2025Q1'],
+ orgUnits: ['facilityAAA'],
+ })
+ ).toEqual([['2025Q1', 'facilityAAA', 'unknown', ['PROFILE_UNKNOWN']]])
+ })
+})
diff --git a/src/modules/dataItemProfile/compatibility/combineResults.js b/src/modules/dataItemProfile/compatibility/combineResults.js
new file mode 100644
index 000000000..ad00fb600
--- /dev/null
+++ b/src/modules/dataItemProfile/compatibility/combineResults.js
@@ -0,0 +1,140 @@
+import {
+ COMPATIBILITY_FULL,
+ COMPATIBILITY_NONE,
+ COMPATIBILITY_PARTIAL,
+ COMPATIBILITY_SEVERITY,
+ COMPATIBILITY_UNKNOWN,
+ REASON_OPERAND_EMPTY,
+ REASON_OPERAND_PARTIAL,
+ REASON_ORDER,
+ SKIP_IF_ANY_VALUE_MISSING,
+} from '../constants.js'
+
+export const createResult = (status, reasons = []) => ({ status, reasons })
+
+export const getUnknownResult = (reason) =>
+ createResult(COMPATIBILITY_UNKNOWN, [reason])
+
+// Every reason of the results, once each, in REASON_ORDER
+export const unionOfReasons = (results) =>
+ REASON_ORDER.filter((reason) =>
+ results.some(({ reasons }) => reasons.includes(reason))
+ )
+
+// The result with the most severe status, or undefined for none
+export const getMostSevere = (results) =>
+ COMPATIBILITY_SEVERITY.map((status) =>
+ results.find((result) => result.status === status)
+ ).find(Boolean)
+
+// The most severe status, with every reason; full for no results
+export const combineResults = (results) =>
+ createResult(
+ getMostSevere(results)?.status ?? COMPATIBILITY_FULL,
+ unionOfReasons(results)
+ )
+
+const hasStatus =
+ (...statuses) =>
+ ({ status }) =>
+ statuses.includes(status)
+
+/**
+ * Results whose values add up, such as a relative period over its fixed
+ * periods, or a selection over its periods and org units: none when all are,
+ * partial when some give values and others none or only some, otherwise the
+ * most severe of the rest. When those without none are all unknown, so is
+ * the result.
+ */
+export const combineAddedUpResults = (results) => {
+ const reasons = unionOfReasons(results)
+ const isNone = hasStatus(COMPATIBILITY_NONE)
+
+ if (results.length && results.every(isNone)) {
+ return createResult(COMPATIBILITY_NONE, reasons)
+ }
+
+ const givesValues = results.some(
+ hasStatus(COMPATIBILITY_FULL, COMPATIBILITY_PARTIAL)
+ )
+
+ if (results.some(hasStatus(COMPATIBILITY_PARTIAL))) {
+ return createResult(COMPATIBILITY_PARTIAL, reasons)
+ }
+
+ if (results.some(isNone)) {
+ return createResult(
+ givesValues ? COMPATIBILITY_PARTIAL : COMPATIBILITY_UNKNOWN,
+ reasons
+ )
+ }
+
+ return createResult(
+ getMostSevere(results)?.status ?? COMPATIBILITY_FULL,
+ reasons
+ )
+}
+
+const OPERAND_REASON_BY_STATUS = {
+ [COMPATIBILITY_NONE]: REASON_OPERAND_EMPTY,
+ [COMPATIBILITY_PARTIAL]: REASON_OPERAND_PARTIAL,
+}
+
+/**
+ * An expression's result, from its operands', by its missing value
+ * strategy. SKIP_IF_ANY_VALUE_MISSING (the default): the most severe
+ * decides. SKIP_IF_ALL_VALUES_MISSING: a missing value counts as 0, so the
+ * operands add up (combineAddedUpResults). With more than one
+ * operand, OPERAND_EMPTY and OPERAND_PARTIAL say first that one gives none
+ * or only some values.
+ */
+export const combineOperandResults = (
+ results,
+ missingValueStrategy = SKIP_IF_ANY_VALUE_MISSING
+) => {
+ const needsAll = missingValueStrategy === SKIP_IF_ANY_VALUE_MISSING
+ const combined = needsAll
+ ? combineResults(results)
+ : combineAddedUpResults(results)
+
+ if (results.length < 2) {
+ return combined
+ }
+
+ const operandReasons = needsAll
+ ? [OPERAND_REASON_BY_STATUS[combined.status]]
+ : results.map(({ status }) => OPERAND_REASON_BY_STATUS[status])
+
+ return createResult(
+ combined.status,
+ unionOfReasons([{ reasons: operandReasons.filter(Boolean) }, combined])
+ )
+}
+
+/**
+ * An item's result from its operands' results (`resultOf(key)`), combined
+ * as its expression says (profile.expression); without one, all are needed.
+ * A part with no operand (constants only) never misses: it is left out.
+ */
+export const combineExpressionResults = (expression, operandKeys, resultOf) => {
+ const combine = ({ operand, missingValueStrategy, parts }) => {
+ if (operand) {
+ return resultOf(operand)
+ }
+
+ const results = parts.map(combine).filter(Boolean)
+
+ return results.length
+ ? combineOperandResults(results, missingValueStrategy)
+ : null
+ }
+
+ return (
+ combine(
+ expression ?? {
+ missingValueStrategy: SKIP_IF_ANY_VALUE_MISSING,
+ parts: operandKeys.map((key) => ({ operand: key })),
+ }
+ ) ?? createResult(COMPATIBILITY_FULL)
+ )
+}
diff --git a/src/modules/dataItemProfile/compatibility/getDataItemProfileOrgUnitCompatibility.js b/src/modules/dataItemProfile/compatibility/getDataItemProfileOrgUnitCompatibility.js
new file mode 100644
index 000000000..da9e9f2a0
--- /dev/null
+++ b/src/modules/dataItemProfile/compatibility/getDataItemProfileOrgUnitCompatibility.js
@@ -0,0 +1,269 @@
+import {
+ COMPATIBILITY_NONE,
+ COMPATIBILITY_PARTIAL,
+ LEFT_OUT_REASONS,
+ ORG_UNIT_ITEM_TYPE_GROUP,
+ REASON_EMPTY_GROUP,
+ REASON_NO_ORG_UNITS_AT_LEVEL,
+ REASON_NOT_ASSIGNED,
+ REASON_OPERAND_EMPTY,
+ REASON_OPERAND_PARTIAL,
+ REASON_PARTLY_ASSIGNED,
+ REASON_PROFILE_UNKNOWN,
+ REASON_UNKNOWN_ORG_UNIT,
+} from '../constants.js'
+import {
+ getRequestedLevels,
+ readOrgUnitSelection,
+} from '../orgUnits/orgUnitSelection.js'
+import { getItemOperands } from '../sources.js'
+import {
+ combineExpressionResults,
+ createResult,
+ getMostSevere,
+ getUnknownResult,
+ unionOfReasons,
+} from './combineResults.js'
+import {
+ getOperandResult,
+ isPartlyAssigned,
+ withAssignment,
+} from './orgUnitSourceResults.js'
+
+/* The org units of all requested levels add up: only those that are
+ * assigned count, and the assignment adds up over all of them (an org unit
+ * with nothing assigned adds its org units to the total). The total is
+ * known only when every part's total was counted. */
+const addUpAssignments = (judged) => {
+ const assignments = judged
+ .map(({ result }) => result.assignment)
+ .filter(Boolean)
+
+ if (!assignments.length) {
+ return null
+ }
+
+ const level = Math.max(...assignments.map((assignment) => assignment.level))
+ const assigned = assignments.reduce((sum, item) => sum + item.assigned, 0)
+ const totals = judged.map(
+ ({ result, counts }) =>
+ result.assignment?.total ?? counts.totals?.[level]
+ )
+
+ return {
+ assigned,
+ ...(totals.every((total) => total !== undefined) && {
+ total: totals.reduce((sum, total) => sum + total, 0),
+ }),
+ level,
+ }
+}
+
+/* Where an operand has no value, the values of the others are dropped: they
+ * are left out, unlike values of an org unit nothing is assigned to */
+const DROPPED_BY_OPERAND_REASONS = new Set([
+ REASON_OPERAND_EMPTY,
+ REASON_OPERAND_PARTIAL,
+])
+
+const leavesValuesOut = ({ status, reasons }) =>
+ status === COMPATIBILITY_PARTIAL ||
+ reasons.some(
+ (reason) =>
+ LEFT_OUT_REASONS.has(reason) ||
+ DROPPED_BY_OPERAND_REASONS.has(reason)
+ )
+
+/* A level under several parents, or a group with members at several levels:
+ * the values of all add up. Where nothing is assigned, nothing is left out,
+ * only fewer org units are assigned (PARTLY_ASSIGNED); where values can't
+ * reach the level asked, or an operand has none, they are left out
+ * (partial). */
+const combineRequestedLevels = (judged) => {
+ const results = judged.map(({ result }) => result)
+ const reasons = unionOfReasons(results)
+
+ if (results.every(({ status }) => status === COMPATIBILITY_NONE)) {
+ return withAssignment(createResult(COMPATIBILITY_NONE, reasons))
+ }
+
+ const assignment = addUpAssignments(judged)
+ const status = results.some(leavesValuesOut)
+ ? COMPATIBILITY_PARTIAL
+ : getMostSevere(
+ results.filter(({ status }) => status !== COMPATIBILITY_NONE)
+ ).status
+ const isPartly = Boolean(assignment) && isPartlyAssigned(assignment)
+
+ return withAssignment(
+ createResult(
+ status,
+ unionOfReasons([
+ {
+ reasons: reasons.filter(
+ (reason) =>
+ reason !== REASON_NOT_ASSIGNED &&
+ reason !== REASON_PARTLY_ASSIGNED
+ ),
+ },
+ { reasons: isPartly ? [REASON_PARTLY_ASSIGNED] : [] },
+ ])
+ ),
+ assignment
+ )
+}
+
+/* The item at one requested level: each operand over its sources, combined
+ * as its expression says; the assignment of the most severe operand */
+const getResultAtLevel = ({ expression, operands }, counts) => {
+ const results = new Map(
+ operands.map((operand) => [
+ operand.key,
+ getOperandResult(operand, counts),
+ ])
+ )
+
+ return withAssignment(
+ combineExpressionResults(expression, [...results.keys()], (key) =>
+ results.get(key)
+ ),
+ getMostSevere([...results.values()])?.assignment
+ )
+}
+
+const isEmptyGroup = (selectionItem, coverage) =>
+ selectionItem.type === ORG_UNIT_ITEM_TYPE_GROUP &&
+ coverage.groups?.[selectionItem.groupId] &&
+ !Object.values(coverage.groups[selectionItem.groupId]).some(
+ (members) => members > 0
+ )
+
+/**
+ * The counts a selection item is judged by, one per level analytics
+ * aggregates to under each parent (`{ levels: [counts] }`, each with the
+ * `level` asked), or its result when it needs none (`{ result }`: an empty
+ * group, an org unit not loaded, no org unit there).
+ */
+export const getSelectionItemLevels = (
+ selectionItem,
+ { parentItems, coverage }
+) => {
+ if (isEmptyGroup(selectionItem, coverage)) {
+ return {
+ result: withAssignment(
+ createResult(COMPATIBILITY_NONE, [REASON_EMPTY_GROUP])
+ ),
+ }
+ }
+
+ const requestedLevels = getRequestedLevels(
+ selectionItem,
+ parentItems,
+ coverage
+ )
+
+ if (!requestedLevels) {
+ return {
+ result: withAssignment(getUnknownResult(REASON_UNKNOWN_ORG_UNIT)),
+ }
+ }
+
+ const levels = requestedLevels
+ // Parents a group has no member under add nothing
+ .filter(
+ ({ groupId, countsKey, level }) =>
+ !groupId || coverage.counts[countsKey]?.totals?.[level] > 0
+ )
+ .map(({ countsKey, level }) => ({
+ ...coverage.counts[countsKey],
+ level,
+ }))
+
+ return levels.length
+ ? { levels }
+ : {
+ result: withAssignment(
+ createResult(COMPATIBILITY_NONE, [
+ REASON_NO_ORG_UNITS_AT_LEVEL,
+ ])
+ ),
+ }
+}
+
+const getSelectionItemCompatibility = (
+ selectionItem,
+ { item, parentItems, coverage }
+) => {
+ const { result, levels } = getSelectionItemLevels(selectionItem, {
+ parentItems,
+ coverage,
+ })
+
+ if (result) {
+ return result
+ }
+
+ const judged = levels.map((counts) => ({
+ counts,
+ result: getResultAtLevel(item, counts),
+ }))
+
+ return judged.length === 1
+ ? judged[0].result
+ : combineRequestedLevels(judged)
+}
+
+/**
+ * Whether the org units of a selection (DV's org unit items) suit a data
+ * item, from where its data sets and programs are assigned (`coverage`, from
+ * fetchOrgUnitCoverage): one result per selection item, `{ id, status,
+ * reasons, assignment }`, with the same statuses as for periods.
+ *
+ * Assigned only at higher levels: none, ASSIGNED_AT_HIGHER_LEVEL. Not
+ * assigned there: none, NOT_ASSIGNED. Stopped by the element's aggregation
+ * levels: none, STOPPED_BY_AGGREGATION_LEVEL. Assigned to only some org units
+ * at the deepest level: full, since nothing is left out, with
+ * PARTLY_ASSIGNED and the counts (`assignment`). An element in several data
+ * sets is full where one is assigned, and partial when another's values can't
+ * reach the org unit. A group is judged at each level its members are at; a
+ * group without members is refused by analytics (EMPTY_GROUP). An item with
+ * no source (an expression of constants) has nothing limiting where it has
+ * values: full.
+ */
+export const getDataItemProfileOrgUnitCompatibility = (
+ profile,
+ { orgUnits = [] } = {},
+ { orgUnitCoverage: coverage } = {}
+) => {
+ const { selectionItems, parentItems } = readOrgUnitSelection(orgUnits)
+ const judge = (getResult) =>
+ selectionItems.map((selectionItem) => ({
+ id: selectionItem.id,
+ ...getResult(selectionItem),
+ }))
+
+ if (profile.unknown) {
+ return judge(() =>
+ withAssignment(getUnknownResult(REASON_PROFILE_UNKNOWN))
+ )
+ }
+
+ if (!coverage) {
+ return judge(() =>
+ withAssignment(getUnknownResult(REASON_UNKNOWN_ORG_UNIT))
+ )
+ }
+
+ const item = {
+ expression: profile.expression,
+ operands: getItemOperands(profile),
+ }
+
+ return judge((selectionItem) =>
+ getSelectionItemCompatibility(selectionItem, {
+ item,
+ parentItems,
+ coverage,
+ })
+ )
+}
diff --git a/src/modules/dataItemProfile/compatibility/getDataItemProfilePeriodCompatibility.js b/src/modules/dataItemProfile/compatibility/getDataItemProfilePeriodCompatibility.js
new file mode 100644
index 000000000..c374eca5f
--- /dev/null
+++ b/src/modules/dataItemProfile/compatibility/getDataItemProfilePeriodCompatibility.js
@@ -0,0 +1,241 @@
+import {
+ REASON_PROFILE_UNKNOWN,
+ REASON_SETTING_MISSING,
+ REASON_UNKNOWN_PERIOD,
+ REASON_UNSUPPORTED_VERSION,
+} from '../constants.js'
+import { getYearsTouched } from '../periods/firstLastValues.js'
+import {
+ getPeriodDates,
+ isAlignedWithPeriodType,
+} from '../periods/periodRanges.js'
+import {
+ canAggregateInto,
+ getCandidatePeriodTypes,
+ getPeriodTypeOfPeriodId,
+ isPeriodType,
+ isPeriodTypeSupported,
+} from '../periods/periodTypes.js'
+import { getRelativePeriodFixedPeriods } from '../periods/relativePeriodRanges.js'
+import { getSourcePeriodType } from '../profile/assignedPeriodTypes.js'
+import { getItemOperands, getSourceId } from '../sources.js'
+import {
+ combineAddedUpResults,
+ combineExpressionResults,
+ getUnknownResult,
+} from './combineResults.js'
+import { getOperandResult, getSourceResult } from './periodSourceResults.js'
+
+// The operands' results, combined as the item's expression says
+const getItemResult = ({ expression, operands }, query) => {
+ const results = new Map(
+ operands.map((operand) => [
+ operand.key,
+ getOperandResult(operand, query),
+ ])
+ )
+
+ return combineExpressionResults(expression, [...results.keys()], (key) =>
+ results.get(key)
+ )
+}
+
+const isSameResult = (a, b) =>
+ a.status === b.status && a.reasons.join() === b.reasons.join()
+
+/* A relative period can be of several types: a result holds only when they
+ * all agree. A type the server version can't answer gives unknown. */
+const agreeOn = (queries, getResult) => {
+ const results = queries.map((query) =>
+ query.supported
+ ? getResult(query)
+ : getUnknownResult(REASON_UNSUPPORTED_VERSION)
+ )
+
+ return results.every((candidate) => isSameResult(candidate, results[0]))
+ ? results[0]
+ : getUnknownResult(REASON_SETTING_MISSING)
+}
+
+// Whether the period starts and ends on the edges of the data's own periods
+const getAlignsWithData = (profile, { periodType, dates, calendar }) => {
+ const dataPeriodTypes = profile.sources
+ .map(getSourcePeriodType)
+ .filter((dataPeriodType) =>
+ canAggregateInto(dataPeriodType, periodType)
+ )
+
+ if (!dates || !dataPeriodTypes.length) {
+ return null
+ }
+
+ const aligned = new Set(
+ dataPeriodTypes.map((dataPeriodType) =>
+ isAlignedWithPeriodType(dates, dataPeriodType, calendar)
+ )
+ )
+
+ if (aligned.has(false)) {
+ return false
+ }
+
+ return aligned.has(null) ? null : true
+}
+
+/* The date ranges a period covers for one of its types: a fixed period's,
+ * the fixed periods of a relative one, none for a period type */
+const getPeriodRanges = (period, periodType, options) => {
+ if (getPeriodTypeOfPeriodId(period)) {
+ const dates = getPeriodDates(period, options.calendar)
+
+ return dates ? [dates] : null
+ }
+
+ return isPeriodType(period)
+ ? null
+ : getRelativePeriodFixedPeriods(period, periodType, options)
+}
+
+/* The calendar years the selection's periods touch, as one request would, or
+ * null when a fixed or relative period can't be dated. Period types aren't
+ * periods of a request: they don't count. */
+export const getSelectionYears = (periods, options) => {
+ const ranges = periods
+ .filter((period) => !isPeriodType(period))
+ .flatMap((period) =>
+ getCandidatePeriodTypes(period, options).map((periodType) =>
+ getPeriodRanges(period, periodType, options)
+ )
+ )
+
+ if (!ranges.length || ranges.includes(null)) {
+ return null
+ }
+
+ return [...new Set(ranges.flat().flatMap(getYearsTouched))].sort(
+ (a, b) => a - b
+ )
+}
+
+/* A result for each range of the query, added up: a relative period is
+ * judged over its fixed periods. Without ranges, by type alone. */
+const judgeRanges = (query, getResult) =>
+ query.ranges
+ ? combineAddedUpResults(
+ query.ranges.map((dates) => getResult({ ...query, dates }))
+ )
+ : getResult({ ...query, dates: null })
+
+const getUnknownPeriodResult = (profile, { period, periodTypes, reason }) => ({
+ id: period,
+ periodTypes,
+ ...getUnknownResult(reason),
+ alignsWithData: null,
+ sources: profile.sources.map((source) => ({
+ sourceId: getSourceId(source),
+ ...getUnknownResult(reason),
+ })),
+})
+
+/**
+ * The queries a period is judged by, one per type it can be (`options`
+ * holding the `selectionYears`), or the reason it can't be: `{ periodTypes,
+ * queries }` or `{ periodTypes, unknownReason }`. judgePeriodQueries judges
+ * them.
+ */
+export const getPeriodQueries = (profile, period, options) => {
+ const periodTypes = getCandidatePeriodTypes(period, options)
+
+ if (profile.unknown || !periodTypes.length) {
+ return {
+ periodTypes,
+ unknownReason: profile.unknown
+ ? REASON_PROFILE_UNKNOWN
+ : REASON_UNKNOWN_PERIOD,
+ }
+ }
+
+ return {
+ periodTypes,
+ queries: periodTypes.map((periodType) => ({
+ periodType,
+ ranges: getPeriodRanges(period, periodType, options),
+ years: options.selectionYears,
+ calendar: options.calendar,
+ serverVersion: options.serverVersion,
+ supported: isPeriodTypeSupported(periodType, options.serverVersion),
+ })),
+ }
+}
+
+// A result from `getResult(query)` for each type and range, as one result for the period
+export const judgePeriodQueries = (queries, getResult) =>
+ agreeOn(queries, (query) => judgeRanges(query, getResult))
+
+const getPeriodResult = (profile, period, options) => {
+ const { periodTypes, queries, unknownReason } = getPeriodQueries(
+ profile,
+ period,
+ options
+ )
+
+ if (unknownReason) {
+ return getUnknownPeriodResult(profile, {
+ period,
+ periodTypes,
+ reason: unknownReason,
+ })
+ }
+
+ const item = {
+ expression: profile.expression,
+ operands: getItemOperands(profile),
+ }
+ const isFixed = Boolean(getPeriodTypeOfPeriodId(period))
+
+ return {
+ id: period,
+ periodTypes,
+ ...judgePeriodQueries(queries, (query) => getItemResult(item, query)),
+ alignsWithData: isFixed
+ ? getAlignsWithData(profile, {
+ ...queries[0],
+ dates: queries[0].ranges?.[0],
+ })
+ : null,
+ sources: profile.sources.map((source) => ({
+ sourceId: getSourceId(source),
+ ...judgePeriodQueries(queries, (query) =>
+ getSourceResult(source, query)
+ ),
+ })),
+ }
+}
+
+/**
+ * Whether the periods of a selection suit a data item, from its profile: for
+ * each period, `{ id, periodTypes, status, reasons, alignsWithData, sources }`,
+ * with a result per source (aligned with `profile.sources`).
+ *
+ * `periods` are fixed ids, relative ids or period types. A relative period is
+ * judged over the fixed periods it covers on `options.relativePeriodDate`
+ * (an ISO date, today by default). `options` also sets the type of relative
+ * weeks and financial years (`weeklyPeriodType`, `financialYearPeriodType`),
+ * the `calendar` for dates, and the `serverVersion` ({ major, minor }), since
+ * some versions can't answer some period types. The periods are taken as one
+ * request: for FIRST and LAST data, the years they touch decide which data
+ * periods count (other items of the request, like a `.periodOffset()`
+ * operand, can add years and aren't seen). A period type is judged by type
+ * alone.
+ */
+export const getDataItemProfilePeriodCompatibility = (
+ profile,
+ { periods = [] } = {},
+ options = {}
+) => {
+ const selectionYears = getSelectionYears(periods, options)
+
+ return periods.map((period) =>
+ getPeriodResult(profile, period, { ...options, selectionYears })
+ )
+}
diff --git a/src/modules/dataItemProfile/compatibility/orgUnitSourceResults.js b/src/modules/dataItemProfile/compatibility/orgUnitSourceResults.js
new file mode 100644
index 000000000..8bd7e73aa
--- /dev/null
+++ b/src/modules/dataItemProfile/compatibility/orgUnitSourceResults.js
@@ -0,0 +1,188 @@
+import {
+ COMPATIBILITY_FULL,
+ COMPATIBILITY_NONE,
+ COMPATIBILITY_PARTIAL,
+ LEFT_OUT_REASONS,
+ REASON_ANY_ORG_UNIT,
+ REASON_ASSIGNED_AT_HIGHER_LEVEL,
+ REASON_NOT_ASSIGNED,
+ REASON_PARTLY_ASSIGNED,
+ REASON_STOPPED_BY_AGGREGATION_LEVEL,
+} from '../constants.js'
+import { getLevelsWithOrgUnits } from '../profile/assignedOrgUnitLevels.js'
+import { canBeAtAnyOrgUnit, getSourceId } from '../sources.js'
+import { createResult, unionOfReasons } from './combineResults.js'
+
+/* Org unit results carry `assignment`: how many org units at the deepest
+ * level assigned are assigned ({ assigned, level }, and `total` when the
+ * coverage counted the org units there), or null */
+export const withAssignment = (result, assignment = null) => ({
+ ...result,
+ assignment,
+})
+
+// Known only when the coverage counted the org units at that level
+export const isPartlyAssigned = ({ assigned, total }) =>
+ total !== undefined && assigned < total
+
+const getAssignedShare = ({ assigned, total }) => (total ? assigned / total : 1)
+
+/* Analytics nulls the levels up to each aggregation level for values from
+ * org units below it (dhis2-core AggregationLevelsHelper): a value from
+ * `assignedLevel` can't reach `requestedLevel` when an aggregation level lies
+ * between them (requestedLevel ≤ L < assignedLevel; checked by the test tool
+ * on 2.40 to 2.44) */
+const isBlockedByAggregationLevel = (
+ assignedLevel,
+ requestedLevel,
+ aggregationLevels
+) =>
+ aggregationLevels.some(
+ (aggregationLevel) =>
+ requestedLevel <= aggregationLevel &&
+ aggregationLevel < assignedLevel
+ )
+
+/* Values that don't reach the level asked are assigned higher when the
+ * source is assigned above it, within the org unit (its ancestors, or higher
+ * levels under a parent); otherwise the org unit simply isn't assigned */
+const getNotReachingReason = ({ byLevel, ancestors, level }) =>
+ ancestors > 0 ||
+ getLevelsWithOrgUnits(byLevel).some(
+ (assignedLevel) => assignedLevel < level
+ )
+ ? REASON_ASSIGNED_AT_HIGHER_LEVEL
+ : REASON_NOT_ASSIGNED
+
+/* One data set or program at one requested level, from its assignment
+ * counts. Values add up from lower levels, but are never split down, so a
+ * source assigned only at higher levels can't fill the level asked. The
+ * deepest level assigned says how much of the org unit it covers. */
+const getSourceResult = ({
+ sourceCounts,
+ aggregationLevels = [],
+ totals,
+ level,
+}) => {
+ const { byLevel = {}, ancestors = 0 } = sourceCounts ?? {}
+ const assignedAtOrBelow = getLevelsWithOrgUnits(byLevel).filter(
+ (assignedLevel) => assignedLevel >= level
+ )
+ const reaching = assignedAtOrBelow.filter(
+ (assignedLevel) =>
+ !isBlockedByAggregationLevel(
+ assignedLevel,
+ level,
+ aggregationLevels
+ )
+ )
+
+ if (assignedAtOrBelow.length && !reaching.length) {
+ return withAssignment(
+ createResult(COMPATIBILITY_NONE, [
+ REASON_STOPPED_BY_AGGREGATION_LEVEL,
+ ])
+ )
+ }
+
+ if (!reaching.length) {
+ return withAssignment(
+ createResult(COMPATIBILITY_NONE, [
+ getNotReachingReason({ byLevel, ancestors, level }),
+ ])
+ )
+ }
+
+ const deepestLevel = Math.max(...reaching)
+ const assignment = {
+ assigned: byLevel[deepestLevel],
+ ...(totals[deepestLevel] !== undefined && {
+ total: totals[deepestLevel],
+ }),
+ level: deepestLevel,
+ }
+
+ // Org units it isn't assigned to have no values: nothing is left out
+ return withAssignment(
+ createResult(
+ COMPATIBILITY_FULL,
+ isPartlyAssigned(assignment) ? [REASON_PARTLY_ASSIGNED] : []
+ ),
+ assignment
+ )
+}
+
+const AT_ANY_ORG_UNIT = withAssignment(
+ createResult(COMPATIBILITY_FULL, [REASON_ANY_ORG_UNIT])
+)
+
+const isLeftOut = ({ reasons }) =>
+ reasons.some((reason) => LEFT_OUT_REASONS.has(reason))
+
+/* One operand over its sources. A source not assigned there leaves nothing
+ * out; one whose values can't reach the level asked (assigned higher, or
+ * stopped by aggregation levels) leaves them out, so with another that fills
+ * the org unit, the value is partial. */
+const combineSources = (bySource) => {
+ const filling = bySource.filter(
+ ({ status }) => status === COMPATIBILITY_FULL
+ )
+ const reasons = unionOfReasons(bySource)
+ const leftOut = bySource.some(isLeftOut)
+
+ if (!filling.length) {
+ return withAssignment(
+ createResult(
+ COMPATIBILITY_NONE,
+ leftOut
+ ? reasons.filter((reason) => LEFT_OUT_REASONS.has(reason))
+ : [REASON_NOT_ASSIGNED]
+ )
+ )
+ }
+
+ const bestAssignment = filling
+ .map(({ assignment }) => assignment)
+ .filter(Boolean)
+ .sort((a, b) => getAssignedShare(b) - getAssignedShare(a))[0]
+ // Partly assigned only when no source is assigned to all its org units
+ const isPartly = Boolean(bestAssignment) && isPartlyAssigned(bestAssignment)
+
+ return withAssignment(
+ createResult(
+ leftOut ? COMPATIBILITY_PARTIAL : COMPATIBILITY_FULL,
+ reasons.filter(
+ (reason) =>
+ reason !== REASON_NOT_ASSIGNED &&
+ (reason !== REASON_PARTLY_ASSIGNED || isPartly)
+ )
+ ),
+ bestAssignment
+ )
+}
+
+/**
+ * Each source of one operand ({ element, sources }, getItemOperands) at one
+ * requested level, from the counts kept for it in the coverage, with the
+ * `level` asked; aligned with `sources`.
+ */
+export const getOperandSourceResults = ({ element, sources }, counts) =>
+ sources.map((source) =>
+ canBeAtAnyOrgUnit(source)
+ ? AT_ANY_ORG_UNIT
+ : getSourceResult({
+ sourceCounts: counts.sources?.[getSourceId(source)],
+ aggregationLevels: element?.aggregationLevels,
+ totals: counts.totals ?? {},
+ level: counts.level,
+ })
+ )
+
+// A source not assigned there doesn't apply: it leaves nothing out
+export const isNotAssigned = ({ status, reasons }) =>
+ status === COMPATIBILITY_NONE &&
+ reasons.every((reason) => reason === REASON_NOT_ASSIGNED)
+
+// One operand at one requested level, over its sources
+export const getOperandResult = (operand, counts) =>
+ combineSources(getOperandSourceResults(operand, counts))
diff --git a/src/modules/dataItemProfile/compatibility/periodAtOrgUnitResults.js b/src/modules/dataItemProfile/compatibility/periodAtOrgUnitResults.js
new file mode 100644
index 000000000..c1b349956
--- /dev/null
+++ b/src/modules/dataItemProfile/compatibility/periodAtOrgUnitResults.js
@@ -0,0 +1,143 @@
+import {
+ COMPATIBILITY_FULL,
+ COMPATIBILITY_NONE,
+ REASON_NOT_ASSIGNED,
+ REASON_UNKNOWN_ORG_UNIT,
+} from '../constants.js'
+import { readOrgUnitSelection } from '../orgUnits/orgUnitSelection.js'
+import { getItemOperands } from '../sources.js'
+import {
+ combineAddedUpResults,
+ combineExpressionResults,
+ createResult,
+ getUnknownResult,
+ unionOfReasons,
+} from './combineResults.js'
+import { getSelectionItemLevels } from './getDataItemProfileOrgUnitCompatibility.js'
+import {
+ getPeriodQueries,
+ getSelectionYears,
+ judgePeriodQueries,
+} from './getDataItemProfilePeriodCompatibility.js'
+import {
+ getOperandSourceResults as getOrgUnitSourceResults,
+ isNotAssigned,
+} from './orgUnitSourceResults.js'
+import { getOperandSourceResults as getPeriodSourceResults } from './periodSourceResults.js'
+
+/* A period at an org unit: only the sources assigned there count, each
+ * judged for the period. A monthly data set at district A and a weekly one
+ * at B give nothing by week at A, and every value by week at B, which the
+ * period and the org unit judged apart can't tell. */
+
+const NOT_ASSIGNED = createResult(COMPATIBILITY_NONE, [REASON_NOT_ASSIGNED])
+
+/* One source of an operand: not assigned there, it doesn't apply; its values
+ * can't reach the level asked, they are left out; otherwise, the period
+ * decides */
+const getSourceResult = (orgUnitResult, periodResult) => {
+ if (isNotAssigned(orgUnitResult)) {
+ return null
+ }
+
+ if (orgUnitResult.status !== COMPATIBILITY_FULL) {
+ return createResult(orgUnitResult.status, orgUnitResult.reasons)
+ }
+
+ return createResult(
+ periodResult.status,
+ unionOfReasons([orgUnitResult, periodResult])
+ )
+}
+
+// One operand, for one period query, at one requested level: its sources there add up
+const getOperandResult = (operand, { query, counts }) => {
+ const periodResults = getPeriodSourceResults(operand, query)
+ const results = getOrgUnitSourceResults(operand, counts)
+ .map((orgUnitResult, i) =>
+ getSourceResult(orgUnitResult, periodResults[i])
+ )
+ .filter(Boolean)
+
+ return results.length ? combineAddedUpResults(results) : NOT_ASSIGNED
+}
+
+const getItemResult = ({ expression, operands }, at) => {
+ const results = new Map(
+ operands.map((operand) => [operand.key, getOperandResult(operand, at)])
+ )
+
+ return combineExpressionResults(expression, [...results.keys()], (key) =>
+ results.get(key)
+ )
+}
+
+// Under several parents, or at several member levels, the org units where it applies add up
+const combineLevels = (results) => {
+ const applying = results.filter((result) => !isNotAssigned(result))
+
+ return applying.length ? combineAddedUpResults(applying) : NOT_ASSIGNED
+}
+
+const judgeSelectionItem = (
+ item,
+ { queries, selectionItem, parentItems, coverage }
+) => {
+ if (!coverage) {
+ return getUnknownResult(REASON_UNKNOWN_ORG_UNIT)
+ }
+
+ const { result, levels } = getSelectionItemLevels(selectionItem, {
+ parentItems,
+ coverage,
+ })
+
+ if (result) {
+ return createResult(result.status, result.reasons)
+ }
+
+ return judgePeriodQueries(queries, (query) =>
+ combineLevels(
+ levels.map((counts) => getItemResult(item, { query, counts }))
+ )
+ )
+}
+
+/**
+ * Each period of a selection at each of its org unit selection items,
+ * judged together (`{ periodId, orgUnitId, status, reasons }`), with the
+ * options of getDataItemProfileCompatibility. Where a data set isn't
+ * assigned, its period type doesn't count.
+ */
+export const getPeriodAtOrgUnitResults = (
+ profile,
+ { periods = [], orgUnits = [] } = {},
+ { orgUnitCoverage: coverage, ...options } = {}
+) => {
+ const selectionYears = getSelectionYears(periods, options)
+ const { selectionItems, parentItems } = readOrgUnitSelection(orgUnits)
+ const item = {
+ expression: profile.expression,
+ operands: getItemOperands(profile),
+ }
+
+ return periods.flatMap((period) => {
+ const { queries, unknownReason } = getPeriodQueries(profile, period, {
+ ...options,
+ selectionYears,
+ })
+
+ return selectionItems.map((selectionItem) => ({
+ periodId: period,
+ orgUnitId: selectionItem.id,
+ ...(unknownReason
+ ? getUnknownResult(unknownReason)
+ : judgeSelectionItem(item, {
+ queries,
+ selectionItem,
+ parentItems,
+ coverage,
+ })),
+ }))
+ })
+}
diff --git a/src/modules/dataItemProfile/compatibility/periodSourceResults.js b/src/modules/dataItemProfile/compatibility/periodSourceResults.js
new file mode 100644
index 000000000..1d99a6ff5
--- /dev/null
+++ b/src/modules/dataItemProfile/compatibility/periodSourceResults.js
@@ -0,0 +1,158 @@
+import {
+ COMPATIBILITY_FULL,
+ COMPATIBILITY_NONE,
+ PERIOD_AGGREGATION_AVERAGE,
+ PERIOD_AGGREGATION_FIRST,
+ PERIOD_AGGREGATION_LAST,
+ REASON_EARLIER_PERIOD_VALUE,
+ REASON_NO_EARLIER_PERIOD_VALUE,
+ REASON_PERIOD_TOO_SHORT,
+ REASON_PERIOD_TYPE_MISMATCH,
+ REASON_REPEATED_VALUE,
+ REASON_REPORTING_RATE_TOO_SHORT,
+ REASON_UNSUPPORTED_VERSION,
+} from '../constants.js'
+import { getFirstOrLastValuePeriod } from '../periods/firstLastValues.js'
+import { getFixedPeriodOfTypeByDate } from '../periods/periodRanges.js'
+import { canAggregateInto, getFrequencyOrder } from '../periods/periodTypes.js'
+import { getSourcePeriodType } from '../profile/assignedPeriodTypes.js'
+import { isProgramSource } from '../sources.js'
+import {
+ combineAddedUpResults,
+ combineResults,
+ createResult,
+ getUnknownResult,
+} from './combineResults.js'
+
+/* The period rules for one source and one query ({ periodType, dates, years,
+ * calendar, serverVersion }): a fixed period's dates, the years the request
+ * touches, and a period type of the selection */
+
+const FULL = createResult(COMPATIBILITY_FULL)
+
+const getMissingReason = (dataPeriodType, queryPeriodType) =>
+ getFrequencyOrder(queryPeriodType) < getFrequencyOrder(dataPeriodType)
+ ? REASON_PERIOD_TOO_SHORT
+ : REASON_PERIOD_TYPE_MISMATCH
+
+/* FIRST and LAST data, by analytics' rule (firstLastValues.js): the value of
+ * a data period inside the period, of one before it, or none. It can only be
+ * told for fixed periods in a selection of fixed periods, since every period
+ * of the request decides which data periods count. */
+const getFirstOrLastResult = (element, dataPeriodType, query) => {
+ const canDate =
+ query.dates &&
+ query.years &&
+ getFixedPeriodOfTypeByDate(
+ dataPeriodType,
+ query.dates.endDate,
+ query.calendar
+ )
+
+ if (!canDate) {
+ const takesEarlierValue =
+ element.periodAggregationType === PERIOD_AGGREGATION_FIRST ||
+ !canAggregateInto(dataPeriodType, query.periodType)
+
+ return takesEarlierValue
+ ? createResult(COMPATIBILITY_FULL, [REASON_EARLIER_PERIOD_VALUE])
+ : FULL
+ }
+
+ const valuePeriod = getFirstOrLastValuePeriod({
+ periodAggregationType: element.periodAggregationType,
+ periodType: dataPeriodType,
+ dates: query.dates,
+ years: query.years,
+ calendar: query.calendar,
+ })
+
+ if (!valuePeriod) {
+ return createResult(COMPATIBILITY_NONE, [
+ REASON_NO_EARLIER_PERIOD_VALUE,
+ ])
+ }
+
+ return valuePeriod.startDate >= query.dates.startDate
+ ? FULL
+ : createResult(COMPATIBILITY_FULL, [REASON_EARLIER_PERIOD_VALUE])
+}
+
+/* One element of one data set, for one query. When the data can't add up
+ * into the period, averaged values are repeated into it, and other data
+ * gives none. FIRST and LAST follow their own rule. */
+const getElementResult = (element, dataPeriodType, query) => {
+ if (
+ element.periodAggregationType === PERIOD_AGGREGATION_FIRST ||
+ element.periodAggregationType === PERIOD_AGGREGATION_LAST
+ ) {
+ return getFirstOrLastResult(element, dataPeriodType, query)
+ }
+
+ if (canAggregateInto(dataPeriodType, query.periodType)) {
+ return FULL
+ }
+
+ return element.periodAggregationType === PERIOD_AGGREGATION_AVERAGE
+ ? createResult(COMPATIBILITY_FULL, [REASON_REPEATED_VALUE])
+ : createResult(COMPATIBILITY_NONE, [
+ getMissingReason(dataPeriodType, query.periodType),
+ ])
+}
+
+// A reporting rate asked for a shorter period gives a meaningless value
+const getReportingRateResult = (dataPeriodType, query) =>
+ canAggregateInto(dataPeriodType, query.periodType)
+ ? FULL
+ : createResult(COMPATIBILITY_NONE, [REASON_REPORTING_RATE_TOO_SHORT])
+
+/* Events and enrollments are placed by their own dates: they fit any period.
+ * VERSION-TOGGLE: remove the check when 43 is the lowest supported version.
+ * Before 2.43, analytics can't query a program indicator without period
+ * boundaries (E7145). */
+const getProgramResult = (source, query) => {
+ const missingBoundariesUnsupported =
+ source.missingPeriodBoundaries &&
+ query.serverVersion?.major === 2 &&
+ query.serverVersion.minor < 43
+
+ return missingBoundariesUnsupported
+ ? getUnknownResult(REASON_UNSUPPORTED_VERSION)
+ : FULL
+}
+
+export const getSourceResult = (source, query) => {
+ if (isProgramSource(source)) {
+ return getProgramResult(source, query)
+ }
+
+ const dataPeriodType = getSourcePeriodType(source)
+ const results = source.elements.map((element) =>
+ getElementResult(element, dataPeriodType, query)
+ )
+
+ if (source.reportingRate) {
+ results.push(getReportingRateResult(dataPeriodType, query))
+ }
+
+ return combineResults(results)
+}
+
+// Each source of one operand (getItemOperands) for one query, aligned with its `sources`
+export const getOperandSourceResults = (
+ { element, reportingRate, sources },
+ query
+) =>
+ sources.map((source) => {
+ if (element) {
+ return getElementResult(element, getSourcePeriodType(source), query)
+ }
+
+ return reportingRate
+ ? getReportingRateResult(getSourcePeriodType(source), query)
+ : getProgramResult(source, query)
+ })
+
+// One operand for one query: an element adds up over its data sets
+export const getOperandResult = (operand, query) =>
+ combineAddedUpResults(getOperandSourceResults(operand, query))
diff --git a/src/modules/dataItemProfile/constants.js b/src/modules/dataItemProfile/constants.js
new file mode 100644
index 000000000..48d93b5a6
--- /dev/null
+++ b/src/modules/dataItemProfile/constants.js
@@ -0,0 +1,170 @@
+// Compatibility statuses: compatible with all, some or none of the item's sources that apply to the selection
+export const COMPATIBILITY_FULL = 'full'
+export const COMPATIBILITY_PARTIAL = 'partial'
+export const COMPATIBILITY_NONE = 'none'
+export const COMPATIBILITY_UNKNOWN = 'unknown'
+
+// Most severe first: where all results are needed (an indicator's two sides), the most severe wins
+export const COMPATIBILITY_SEVERITY = [
+ COMPATIBILITY_NONE,
+ COMPATIBILITY_PARTIAL,
+ COMPATIBILITY_UNKNOWN,
+ COMPATIBILITY_FULL,
+]
+
+/* Why a profile is unknown (profile.reasons, each with the id it concerns):
+ * metadata is missing or can't be read, never guessed */
+export const PROFILE_REASON_MISSING_METADATA = 'MISSING_METADATA'
+export const PROFILE_REASON_MISSING_PROGRAM = 'MISSING_PROGRAM'
+export const PROFILE_REASON_UNKNOWN_OPERAND = 'UNKNOWN_OPERAND'
+export const PROFILE_REASON_UNKNOWN_PERIOD_TYPE = 'UNKNOWN_PERIOD_TYPE'
+export const PROFILE_REASON_UNSUPPORTED_ITEM_TYPE = 'UNSUPPORTED_ITEM_TYPE'
+export const PROFILE_REASON_NO_DATA_SET = 'NO_DATA_SET'
+export const PROFILE_REASON_NOT_AGGREGATABLE = 'NOT_AGGREGATABLE'
+
+/* Why a compatibility status, in the order results list them */
+
+// An operand gives no value: a sum misses it, a side where all are missing has none (a ratio without its denominator)
+export const REASON_OPERAND_EMPTY = 'OPERAND_EMPTY'
+// An expression computed from an operand that leaves values out: it can be off either way
+export const REASON_OPERAND_PARTIAL = 'OPERAND_PARTIAL'
+
+// The period is shorter than the period type of the data sets
+export const REASON_PERIOD_TOO_SHORT = 'PERIOD_TOO_SHORT'
+// Another period type of the same length (Wednesday weeks asked by Monday week)
+export const REASON_PERIOD_TYPE_MISMATCH = 'PERIOD_TYPE_MISMATCH'
+// A reporting rate asked for a shorter period: a meaningless value
+export const REASON_REPORTING_RATE_TOO_SHORT = 'REPORTING_RATE_TOO_SHORT'
+// FIRST or LAST data with no data period that counts for the period
+export const REASON_NO_EARLIER_PERIOD_VALUE = 'NO_EARLIER_PERIOD_VALUE'
+// The value of a longer data period, repeated (period aggregation AVERAGE)
+export const REASON_REPEATED_VALUE = 'REPEATED_VALUE'
+// The value of an earlier data period (period aggregation FIRST or LAST)
+export const REASON_EARLIER_PERIOD_VALUE = 'EARLIER_PERIOD_VALUE'
+
+// Neither the org unit nor its ancestors are assigned: nothing is there to show
+export const REASON_NOT_ASSIGNED = 'NOT_ASSIGNED'
+// Assigned only at higher levels than the one asked: analytics never splits values down
+export const REASON_ASSIGNED_AT_HIGHER_LEVEL = 'ASSIGNED_AT_HIGHER_LEVEL'
+// The data element's aggregation levels stop values from reaching the level asked
+export const REASON_STOPPED_BY_AGGREGATION_LEVEL =
+ 'STOPPED_BY_AGGREGATION_LEVEL'
+// No org unit at the level asked under the parent org units, or no group member under them
+export const REASON_NO_ORG_UNITS_AT_LEVEL = 'NO_ORG_UNITS_AT_LEVEL'
+// An org unit group without members: analytics refuses it (E7143), leave it out of the request
+export const REASON_EMPTY_GROUP = 'EMPTY_GROUP'
+// Assigned to only some org units at the deepest level: the others aren't assigned, so nothing is left out
+export const REASON_PARTLY_ASSIGNED = 'PARTLY_ASSIGNED'
+// A program indicator placed by registration or an org unit attribute: values can be at any org unit
+export const REASON_ANY_ORG_UNIT = 'ANY_ORG_UNIT'
+
+// The profile is unknown: see its reasons
+export const REASON_PROFILE_UNKNOWN = 'PROFILE_UNKNOWN'
+// The period id can't be read
+export const REASON_UNKNOWN_PERIOD = 'UNKNOWN_PERIOD'
+// A relative period's type depends on a setting that wasn't given, and its types disagree
+export const REASON_SETTING_MISSING = 'SETTING_MISSING'
+// The server version can't answer it (QuarterlyNov before 2.41, a program indicator without period boundaries before 2.43)
+export const REASON_UNSUPPORTED_VERSION = 'UNSUPPORTED_VERSION'
+// The org unit, level or group isn't loaded or can't be read
+export const REASON_UNKNOWN_ORG_UNIT = 'UNKNOWN_ORG_UNIT'
+
+export const REASON_ORDER = [
+ REASON_OPERAND_EMPTY,
+ REASON_OPERAND_PARTIAL,
+ REASON_PERIOD_TOO_SHORT,
+ REASON_PERIOD_TYPE_MISMATCH,
+ REASON_REPORTING_RATE_TOO_SHORT,
+ REASON_NO_EARLIER_PERIOD_VALUE,
+ REASON_REPEATED_VALUE,
+ REASON_EARLIER_PERIOD_VALUE,
+ REASON_NOT_ASSIGNED,
+ REASON_ASSIGNED_AT_HIGHER_LEVEL,
+ REASON_STOPPED_BY_AGGREGATION_LEVEL,
+ REASON_NO_ORG_UNITS_AT_LEVEL,
+ REASON_EMPTY_GROUP,
+ REASON_PARTLY_ASSIGNED,
+ REASON_ANY_ORG_UNIT,
+ REASON_PROFILE_UNKNOWN,
+ REASON_UNKNOWN_PERIOD,
+ REASON_SETTING_MISSING,
+ REASON_UNSUPPORTED_VERSION,
+ REASON_UNKNOWN_ORG_UNIT,
+]
+
+// Values that exist but can't reach the org unit level asked
+export const LEFT_OUT_REASONS = new Set([
+ REASON_ASSIGNED_AT_HIGHER_LEVEL,
+ REASON_STOPPED_BY_AGGREGATION_LEVEL,
+])
+
+/* How an expression treats missing operand values (dhis2-core
+ * MissingValueStrategy). Indicators evaluate each side with
+ * SKIP_IF_ALL_VALUES_MISSING, then need both sides; expression dimension
+ * items are evaluated with SKIP_IF_ALL_VALUES_MISSING, whatever strategy they
+ * are saved with (checked by the test tool on 2.40 to 2.44). */
+export const SKIP_IF_ANY_VALUE_MISSING = 'SKIP_IF_ANY_VALUE_MISSING'
+export const SKIP_IF_ALL_VALUES_MISSING = 'SKIP_IF_ALL_VALUES_MISSING'
+
+/* Expression operands without a dimension item type: constants, org unit
+ * group counts and [days] have no source; an unknown prefix makes the
+ * profile unknown */
+export const OPERAND_TYPE_CONSTANT = 'CONSTANT'
+export const OPERAND_TYPE_ORG_UNIT_GROUP = 'ORG_UNIT_GROUP'
+export const OPERAND_TYPE_DAYS = 'DAYS'
+export const OPERAND_TYPE_UNKNOWN = 'UNKNOWN'
+
+// How values aggregate over time (dhis2-core periodAggregationType)
+export const PERIOD_AGGREGATION_AVERAGE = 'AVERAGE'
+export const PERIOD_AGGREGATION_FIRST = 'FIRST'
+export const PERIOD_AGGREGATION_LAST = 'LAST'
+
+export const NOT_AGGREGATABLE_AGGREGATION_TYPES = new Set(['NONE'])
+
+/* A program indicator's orgUnitField that places values where its program is
+ * assigned: the event's or enrollment's org unit (unset, EVENT, ENROLLMENT),
+ * or the owner's, which falls back to it. REGISTRATION and an org unit data
+ * element or attribute (its id) can place values at any org unit. */
+export const PROGRAM_ORG_UNIT_FIELDS = new Set([
+ 'EVENT',
+ 'ENROLLMENT',
+ 'OWNER_AT_START',
+ 'OWNER_AT_END',
+])
+
+// Org unit selection items, as DV saves them
+export const ORG_UNIT_ITEM_TYPE_ORG_UNIT = 'ORG_UNIT'
+export const ORG_UNIT_ITEM_TYPE_LEVEL = 'LEVEL'
+export const ORG_UNIT_ITEM_TYPE_GROUP = 'GROUP'
+export const ORG_UNIT_ITEM_TYPE_USER = 'USER'
+export const ORG_UNIT_ITEM_TYPE_UNKNOWN = 'UNKNOWN'
+
+// Server period type names with their frequencyOrder, as /api/periodTypes returns them
+export const PERIOD_TYPE_FREQUENCY_ORDER = {
+ Daily: 1,
+ Weekly: 7,
+ WeeklyWednesday: 7,
+ WeeklyThursday: 7,
+ WeeklyFriday: 7,
+ WeeklySaturday: 7,
+ WeeklySunday: 7,
+ BiWeekly: 14,
+ Monthly: 30,
+ BiMonthly: 61,
+ Quarterly: 91,
+ QuarterlyNov: 91,
+ SixMonthly: 182,
+ SixMonthlyApril: 182,
+ SixMonthlyNov: 182,
+ Yearly: 365,
+ FinancialFeb: 365,
+ FinancialApril: 365,
+ FinancialJuly: 365,
+ FinancialAug: 365,
+ FinancialSep: 365,
+ FinancialOct: 365,
+ FinancialNov: 365,
+ TwoYearly: 730,
+}
+
+export const PERIOD_TYPES = Object.keys(PERIOD_TYPE_FREQUENCY_ORDER)
diff --git a/src/modules/dataItemProfile/expressionOperands.js b/src/modules/dataItemProfile/expressionOperands.js
new file mode 100644
index 000000000..f43333bd4
--- /dev/null
+++ b/src/modules/dataItemProfile/expressionOperands.js
@@ -0,0 +1,111 @@
+import { REPORTING_RATE } from '../dataSets.js'
+import {
+ DIMENSION_TYPE_DATA_ELEMENT,
+ DIMENSION_TYPE_INDICATOR,
+ DIMENSION_TYPE_PROGRAM_ATTRIBUTE,
+ DIMENSION_TYPE_PROGRAM_DATA_ELEMENT,
+ DIMENSION_TYPE_PROGRAM_INDICATOR,
+} from '../dataTypes.js'
+import {
+ OPERAND_TYPE_CONSTANT,
+ OPERAND_TYPE_DAYS,
+ OPERAND_TYPE_ORG_UNIT_GROUP,
+ OPERAND_TYPE_UNKNOWN,
+} from './constants.js'
+
+/* The full indicator and expression syntax (the library's parseExpression in
+ * modules/expressions.js reads only the #{} of calculations) */
+const OPERAND_TYPE_BY_PREFIX = {
+ '#': DIMENSION_TYPE_DATA_ELEMENT,
+ R: REPORTING_RATE,
+ N: DIMENSION_TYPE_INDICATOR,
+ I: DIMENSION_TYPE_PROGRAM_INDICATOR,
+ D: DIMENSION_TYPE_PROGRAM_DATA_ELEMENT,
+ A: DIMENSION_TYPE_PROGRAM_ATTRIBUTE,
+ C: OPERAND_TYPE_CONSTANT,
+ OUG: OPERAND_TYPE_ORG_UNIT_GROUP,
+}
+
+// An operand: `#{de.coc}`, `R{ds.REPORTING_RATE}`, `[days]`… (prefixes are 1 to 3 letters)
+const OPERAND_REGEX = /(#|[A-Z]{1,3})\{([^}]*)\}|\[days\]/g
+// One function chained after it: `.periodOffset(-1)`, `.aggregationType(LAST)`
+const FUNCTION_REGEX = /\.([a-zA-Z]+)\(([^)]*)\)/y
+
+// The functions chained at `position`, and where they end
+const readFunctions = (expression, position) => {
+ const functions = []
+
+ FUNCTION_REGEX.lastIndex = position
+
+ for (
+ let match = FUNCTION_REGEX.exec(expression);
+ match;
+ match = FUNCTION_REGEX.exec(expression)
+ ) {
+ functions.push({ name: match[1], arg: match[2].trim() })
+ position = FUNCTION_REGEX.lastIndex
+ }
+
+ return { functions, end: position }
+}
+
+/* The object to fetch for the operand: the data element of `#{de.coc.aoc}`,
+ * the data set of `R{ds.REPORTING_RATE}`, the whole content otherwise */
+const getOperandObjectId = (type, content) =>
+ type === DIMENSION_TYPE_DATA_ELEMENT || type === REPORTING_RATE
+ ? content.split('.')[0]
+ : content
+
+// One operand found by OPERAND_REGEX: its type, the object behind it, its token and functions
+const toOperand = (expression, match) => {
+ const [operandToken, prefix, content] = match
+ const { functions, end } = readFunctions(
+ expression,
+ match.index + operandToken.length
+ )
+ const token = expression.slice(match.index, end)
+
+ if (prefix === undefined) {
+ return { type: OPERAND_TYPE_DAYS, token, functions }
+ }
+
+ const type = OPERAND_TYPE_BY_PREFIX[prefix] ?? OPERAND_TYPE_UNKNOWN
+ // A disaggregation (de.coc, de.coc.aoc); a wildcard (de.*) is the whole element
+ const isDisaggregation =
+ type === DIMENSION_TYPE_DATA_ELEMENT &&
+ content.includes('.') &&
+ !content.includes('*')
+ const aggregationType = functions.find(
+ ({ name }) => name === 'aggregationType'
+ )?.arg
+
+ return {
+ type,
+ id: getOperandObjectId(type, content),
+ ...(isDisaggregation && { operand: content }),
+ token,
+ functions,
+ ...(aggregationType && { aggregationType }),
+ }
+}
+
+/**
+ * Every operand of an indicator or expression dimension item expression, in
+ * order: its type (a dimension item type, or a constant, org unit group,
+ * [days] or unknown operand), the id of the object behind it, and the
+ * functions chained after it.
+ */
+export const parseExpressionOperands = (expression) =>
+ [...(expression ?? '').matchAll(OPERAND_REGEX)].map((match) =>
+ toOperand(expression, match)
+ )
+
+/**
+ * The category option combo a disaggregation asks for (`de.coc`,
+ * `de.coc.aoc`), or undefined for a whole element or a wildcard (`de.*`).
+ */
+export const getCategoryOptionComboId = (operand) => {
+ const id = operand?.split('.')[1]
+
+ return id && id !== '*' ? id : undefined
+}
diff --git a/src/modules/dataItemProfile/getDataItemProfile.js b/src/modules/dataItemProfile/getDataItemProfile.js
new file mode 100644
index 000000000..96c6eb805
--- /dev/null
+++ b/src/modules/dataItemProfile/getDataItemProfile.js
@@ -0,0 +1,33 @@
+import { getAssignedPeriodTypes } from './profile/assignedPeriodTypes.js'
+import { collectSources } from './profile/collectSources.js'
+
+/**
+ * The profile of a data item ({ id, dimensionItemType }), from its metadata
+ * (fetchDataItemProfileMetadata): where its data comes from.
+ *
+ * - `sources`: one per data set it is assigned to, with the item's elements
+ * in it (a reporting rate is its data set), and one per program.
+ * - `expression`, for an indicator or expression dimension item: how its
+ * operands combine, `{ missingValueStrategy, parts }`, each part an
+ * `{ operand }` (a key of getItemOperands) or an expression. An indicator
+ * needs both sides (SKIP_IF_ANY_VALUE_MISSING); each side has a value
+ * when one of its operands has (SKIP_IF_ALL_VALUES_MISSING).
+ * - `assignedPeriodTypes`: the period types of those data sets
+ * (getAssignedPeriodTypes).
+ * - `assignedOrgUnitLevels` is added by addAssignedOrgUnitLevels, from
+ * counts fetched apart (fetchAssignedOrgUnitCounts, or an org unit
+ * coverage).
+ * - `unknown` and `reasons`: missing metadata makes the item unknown; it is
+ * never guessed.
+ */
+export const getDataItemProfile = (item, metadata = {}) => {
+ const { sources, reasons, expression } = collectSources(item, metadata)
+
+ return {
+ sources,
+ ...(expression && { expression }),
+ unknown: reasons.length > 0,
+ reasons,
+ assignedPeriodTypes: getAssignedPeriodTypes(sources),
+ }
+}
diff --git a/src/modules/dataItemProfile/getDataItemProfileCompatibility.js b/src/modules/dataItemProfile/getDataItemProfileCompatibility.js
new file mode 100644
index 000000000..7b45912d8
--- /dev/null
+++ b/src/modules/dataItemProfile/getDataItemProfileCompatibility.js
@@ -0,0 +1,80 @@
+import { combineAddedUpResults } from './compatibility/combineResults.js'
+import { getDataItemProfileOrgUnitCompatibility } from './compatibility/getDataItemProfileOrgUnitCompatibility.js'
+import { getDataItemProfilePeriodCompatibility } from './compatibility/getDataItemProfilePeriodCompatibility.js'
+import { getPeriodAtOrgUnitResults } from './compatibility/periodAtOrgUnitResults.js'
+import { getSourceId } from './sources.js'
+
+const NO_RESULT = { status: null, reasons: [] }
+
+/**
+ * Whether a selection suits a data item, from its profile (getDataItemProfile):
+ * whether analytics will return all of the item's values for these periods
+ * and org units.
+ *
+ * The status is `full`, `partial`, `none` or `unknown`: compatible with all,
+ * some or none of the item's data sets and programs that apply to the
+ * selection. `reasons` say why, and on a full result whether values are
+ * repeated or taken from an earlier period rather than added up for it.
+ *
+ * - `periods`: getDataItemProfilePeriodCompatibility, one result per period.
+ * - `orgUnits` (DV's org unit items): getDataItemProfileOrgUnitCompatibility,
+ * one result per selection item, from `options.orgUnitCoverage`
+ * (fetchOrgUnitCoverage). Given only when org units are asked.
+ * - `sources`: each source over the periods (aligned with `profile.sources`).
+ * - Overall: with periods and org units, each period at each org unit
+ * (getPeriodAtOrgUnitResults), where only the data sets and programs
+ * assigned there count; with one of them alone, its results. They add up,
+ * as the fixed periods of a relative period do: none when all are none,
+ * partial when some give values and others none, with every reason.
+ *
+ * `periods` and `orgUnits` are each judged alone, for pickers: by week, an
+ * element in a monthly data set at district A and a weekly one at B is
+ * partial (the monthly values are left out), and at A it is full (the
+ * weekly data set isn't assigned there). Only the overall result sees that
+ * by week at A it has nothing.
+ * `options` are passed to the period check (relative period settings,
+ * relativePeriodDate, calendar, server version).
+ */
+export const getDataItemProfileCompatibility = (
+ profile,
+ { periods = [], orgUnits = [] } = {},
+ { orgUnitCoverage, ...options } = {}
+) => {
+ const periodResults = getDataItemProfilePeriodCompatibility(
+ profile,
+ { periods },
+ options
+ )
+ const orgUnitResults = orgUnits.length
+ ? getDataItemProfileOrgUnitCompatibility(
+ profile,
+ { orgUnits },
+ { orgUnitCoverage }
+ )
+ : []
+ const periodAtOrgUnitResults =
+ periods.length && orgUnits.length
+ ? getPeriodAtOrgUnitResults(
+ profile,
+ { periods, orgUnits },
+ { orgUnitCoverage, ...options }
+ )
+ : []
+ const overall = periodAtOrgUnitResults.length
+ ? periodAtOrgUnitResults
+ : [...periodResults, ...orgUnitResults]
+
+ return {
+ ...(overall.length ? combineAddedUpResults(overall) : NO_RESULT),
+ sources: profile.sources.map((source, i) => ({
+ sourceId: getSourceId(source),
+ ...(periodResults.length
+ ? combineAddedUpResults(
+ periodResults.map(({ sources }) => sources[i])
+ )
+ : NO_RESULT),
+ })),
+ periods: periodResults,
+ ...(orgUnits.length && { orgUnits: orgUnitResults }),
+ }
+}
diff --git a/src/modules/dataItemProfile/orgUnits/__tests__/orgUnitSelection.spec.js b/src/modules/dataItemProfile/orgUnits/__tests__/orgUnitSelection.spec.js
new file mode 100644
index 000000000..bd27cba1c
--- /dev/null
+++ b/src/modules/dataItemProfile/orgUnits/__tests__/orgUnitSelection.spec.js
@@ -0,0 +1,226 @@
+import {
+ getRequestedLevels,
+ getOrgUnitsToFetch,
+ parseOrgUnitSelectionItem,
+ readOrgUnitSelection,
+} from '../orgUnitSelection.js'
+
+describe('parseOrgUnitSelectionItem', () => {
+ it.each([
+ ['ImspTQPwCqd', { type: 'ORG_UNIT' }],
+ ['LEVEL-2', { type: 'LEVEL', level: 2 }],
+ ['LEVEL-wjP19dkFeIk', { type: 'LEVEL', level: 'wjP19dkFeIk' }],
+ ['OU_GROUP-RXL3lPSK8oG', { type: 'GROUP', groupId: 'RXL3lPSK8oG' }],
+ ['USER_ORGUNIT', { type: 'USER', depth: 0 }],
+ ['USER_ORGUNIT_CHILDREN', { type: 'USER', depth: 1 }],
+ ['USER_ORGUNIT_GRANDCHILDREN', { type: 'USER', depth: 2 }],
+ ['not an id', { type: 'UNKNOWN' }],
+ ['toString', { type: 'UNKNOWN' }],
+ ])('reads %s', (id, expected) => {
+ expect(parseOrgUnitSelectionItem(id)).toEqual({ id, ...expected })
+ })
+})
+
+describe('readOrgUnitSelection', () => {
+ it('judges org units on their own', () => {
+ expect(readOrgUnitSelection(['unitAAAAAAA', 'unitBBBBBBB'])).toEqual({
+ selectionItems: [
+ { id: 'unitAAAAAAA', type: 'ORG_UNIT' },
+ { id: 'unitBBBBBBB', type: 'ORG_UNIT' },
+ ],
+ parentItems: [],
+ })
+ })
+
+ it('takes the org units and the user org units as parents of a level or a group', () => {
+ expect(
+ readOrgUnitSelection(['unitAAAAAAA', 'LEVEL-3', 'USER_ORGUNIT'])
+ ).toEqual({
+ selectionItems: [{ id: 'LEVEL-3', type: 'LEVEL', level: 3 }],
+ parentItems: [
+ { id: 'unitAAAAAAA', type: 'ORG_UNIT' },
+ { id: 'USER_ORGUNIT', type: 'USER', depth: 0 },
+ ],
+ })
+ })
+
+ it('reads nothing from no selection', () => {
+ expect(readOrgUnitSelection()).toEqual({
+ selectionItems: [],
+ parentItems: [],
+ })
+ })
+})
+
+describe('getOrgUnitsToFetch', () => {
+ it('fetches the org units of a selection', () => {
+ expect(getOrgUnitsToFetch(['unitAAAAAAA', 'LEVEL-2'])).toEqual({
+ orgUnitIds: ['unitAAAAAAA'],
+ needsRoots: false,
+ needsUserOrgUnits: false,
+ groupIds: [],
+ })
+ })
+
+ it('fetches the roots for a level alone, and the user org units', () => {
+ expect(getOrgUnitsToFetch(['LEVEL-2'])).toMatchObject({
+ needsRoots: true,
+ needsUserOrgUnits: false,
+ })
+ expect(
+ getOrgUnitsToFetch(['LEVEL-2', 'USER_ORGUNIT_CHILDREN'])
+ ).toEqual({
+ orgUnitIds: [],
+ needsRoots: false,
+ needsUserOrgUnits: true,
+ groupIds: [],
+ })
+ expect(getOrgUnitsToFetch()).toEqual({
+ orgUnitIds: [],
+ needsRoots: false,
+ needsUserOrgUnits: false,
+ groupIds: [],
+ })
+ })
+
+ it('lists the groups once each, with no roots for them', () => {
+ expect(
+ getOrgUnitsToFetch(['OU_GROUP-groupAAAAAA', 'OU_GROUP-groupAAAAAA'])
+ ).toEqual({
+ orgUnitIds: [],
+ needsRoots: false,
+ needsUserOrgUnits: false,
+ groupIds: ['groupAAAAAA'],
+ })
+ })
+})
+
+describe('getRequestedLevels', () => {
+ const COVERAGE = {
+ levels: [
+ { id: 'levelNation', level: 1 },
+ { id: 'levelDistri', level: 2 },
+ { id: 'levelChiefd', level: 3 },
+ { id: 'levelFacili', level: 4 },
+ ],
+ orgUnits: {
+ nationUnit1: { id: 'nationUnit1', level: 1, path: '/nationUnit1' },
+ districtAAA: {
+ id: 'districtAAA',
+ level: 2,
+ path: '/nationUnit1/districtAAA',
+ },
+ facilityAAA: {
+ id: 'facilityAAA',
+ level: 4,
+ path: '/nationUnit1/districtAAA/chiefdomAAA/facilityAAA',
+ },
+ },
+ rootIds: ['nationUnit1'],
+ userOrgUnitIds: ['districtAAA'],
+ groups: { groupAAAAAA: { 2: 3, 3: 0, 4: 5 } },
+ }
+ const targets = (id, parents = [], coverage = COVERAGE) =>
+ getRequestedLevels(
+ parseOrgUnitSelectionItem(id),
+ parents.map(parseOrgUnitSelectionItem),
+ coverage
+ )
+
+ it('asks an org unit at its own level', () => {
+ expect(targets('districtAAA')).toEqual([
+ { countsKey: 'districtAAA', level: 2 },
+ ])
+ })
+
+ it('asks a level under each parent that holds it', () => {
+ expect(targets('LEVEL-3', ['nationUnit1', 'facilityAAA'])).toEqual([
+ { countsKey: 'nationUnit1', level: 3 },
+ ])
+ })
+
+ it('asks a level once under a parent given twice, or within another', () => {
+ expect(
+ targets('LEVEL-4', ['districtAAA', 'districtAAA', 'facilityAAA'])
+ ).toEqual([{ countsKey: 'districtAAA', level: 4 }])
+ expect(
+ targets('LEVEL-4', ['USER_ORGUNIT', 'USER_ORGUNIT_CHILDREN'])
+ ).toEqual([{ countsKey: 'districtAAA', level: 4 }])
+ })
+
+ it('keeps a parent within another that holds fewer levels', () => {
+ expect(
+ targets('LEVEL-3', ['USER_ORGUNIT_GRANDCHILDREN', 'districtAAA'])
+ ).toEqual([{ countsKey: 'districtAAA', level: 3 }])
+ })
+
+ it('asks a level under the user org units, below the depth of the user item', () => {
+ expect(targets('LEVEL-3', ['USER_ORGUNIT_CHILDREN'])).toEqual([
+ { countsKey: 'districtAAA', level: 3 },
+ ])
+ expect(targets('LEVEL-2', ['USER_ORGUNIT_CHILDREN'])).toEqual([])
+ })
+
+ it('asks nothing for a level deeper than the hierarchy', () => {
+ expect(targets('LEVEL-7', ['nationUnit1'])).toEqual([])
+ })
+
+ it('asks a level under the roots without parents, by number or id', () => {
+ expect(targets('LEVEL-levelDistri')).toEqual([
+ { countsKey: 'nationUnit1', level: 2 },
+ ])
+ })
+
+ it('asks the user org units at their level plus the depth', () => {
+ expect(targets('USER_ORGUNIT_GRANDCHILDREN')).toEqual([
+ { countsKey: 'districtAAA', level: 4 },
+ ])
+ })
+
+ it('asks a group at each level its members are at', () => {
+ expect(targets('OU_GROUP-groupAAAAAA')).toEqual([
+ { countsKey: 'groupAAAAAA:2:', level: 2, groupId: 'groupAAAAAA' },
+ { countsKey: 'groupAAAAAA:4:', level: 4, groupId: 'groupAAAAAA' },
+ ])
+ })
+
+ it('asks a group under each parent at or above its members, inside no other', () => {
+ expect(
+ targets('OU_GROUP-groupAAAAAA', ['districtAAA', 'facilityAAA'])
+ ).toEqual([
+ {
+ countsKey: 'groupAAAAAA:2:districtAAA',
+ level: 2,
+ groupId: 'groupAAAAAA',
+ },
+ {
+ countsKey: 'groupAAAAAA:4:districtAAA',
+ level: 4,
+ groupId: 'groupAAAAAA',
+ },
+ ])
+ expect(targets('OU_GROUP-groupAAAAAA', ['facilityAAA'])).toEqual([
+ {
+ countsKey: 'groupAAAAAA:4:facilityAAA',
+ level: 4,
+ groupId: 'groupAAAAAA',
+ },
+ ])
+ })
+
+ it('cannot tell for a group, an unknown level, or org units not loaded', () => {
+ expect(targets('OU_GROUP-notLoadedGr')).toBeNull()
+ expect(targets('OU_GROUP-groupAAAAAA', ['notLoadedUn'])).toBeNull()
+ expect(targets('LEVEL-unknownLvl')).toBeNull()
+ expect(targets('LEVEL-3', ['notLoadedUn'])).toBeNull()
+ expect(
+ targets('USER_ORGUNIT', [], { ...COVERAGE, userOrgUnitIds: null })
+ ).toBeNull()
+ expect(
+ targets('USER_ORGUNIT', [], {
+ ...COVERAGE,
+ userOrgUnitIds: ['other'],
+ })
+ ).toBeNull()
+ })
+})
diff --git a/src/modules/dataItemProfile/orgUnits/orgUnitSelection.js b/src/modules/dataItemProfile/orgUnits/orgUnitSelection.js
new file mode 100644
index 000000000..8711b0a03
--- /dev/null
+++ b/src/modules/dataItemProfile/orgUnits/orgUnitSelection.js
@@ -0,0 +1,267 @@
+import {
+ ouIdHelper,
+ USER_ORG_UNIT,
+ USER_ORG_UNIT_CHILDREN,
+ USER_ORG_UNIT_GRANDCHILDREN,
+} from '../../ouIdHelper/index.js'
+import {
+ ORG_UNIT_ITEM_TYPE_GROUP,
+ ORG_UNIT_ITEM_TYPE_LEVEL,
+ ORG_UNIT_ITEM_TYPE_ORG_UNIT,
+ ORG_UNIT_ITEM_TYPE_UNKNOWN,
+ ORG_UNIT_ITEM_TYPE_USER,
+} from '../constants.js'
+
+/* An org unit selection is DV's org unit items: org unit ids, LEVEL-n (a
+ * number or a level id), OU_GROUP-id, and the user's org units
+ * (USER_ORGUNIT, its children or grandchildren). A selection item is one of
+ * them, not a data item. */
+
+// How many levels below the user's org units each user item reaches
+const USER_ITEM_DEPTHS = new Map([
+ [USER_ORG_UNIT, 0],
+ [USER_ORG_UNIT_CHILDREN, 1],
+ [USER_ORG_UNIT_GRANDCHILDREN, 2],
+])
+
+const UID = /^[a-zA-Z][a-zA-Z0-9]{10}$/
+
+export const parseOrgUnitSelectionItem = (id) => {
+ if (USER_ITEM_DEPTHS.has(id)) {
+ return {
+ id,
+ type: ORG_UNIT_ITEM_TYPE_USER,
+ depth: USER_ITEM_DEPTHS.get(id),
+ }
+ }
+
+ if (ouIdHelper.hasLevelPrefix(id)) {
+ const level = ouIdHelper.removePrefix(id)
+
+ return {
+ id,
+ type: ORG_UNIT_ITEM_TYPE_LEVEL,
+ level: /^\d+$/.test(level) ? Number(level) : level,
+ }
+ }
+
+ if (ouIdHelper.hasGroupPrefix(id)) {
+ return {
+ id,
+ type: ORG_UNIT_ITEM_TYPE_GROUP,
+ groupId: ouIdHelper.removePrefix(id),
+ }
+ }
+
+ return {
+ id,
+ type: UID.test(id)
+ ? ORG_UNIT_ITEM_TYPE_ORG_UNIT
+ : ORG_UNIT_ITEM_TYPE_UNKNOWN,
+ }
+}
+
+const isOfType = (...types) => {
+ const typeSet = new Set(types)
+
+ return ({ type }) => typeSet.has(type)
+}
+
+const isLevelOrGroup = isOfType(
+ ORG_UNIT_ITEM_TYPE_LEVEL,
+ ORG_UNIT_ITEM_TYPE_GROUP
+)
+
+/**
+ * A selection as analytics reads it: with a level or a group in it, the org
+ * units and the user's org units are parents (districts in Bo, a group's
+ * members in the user's district), not items of their own. Gives the
+ * `selectionItems` to judge and the `parentItems`.
+ */
+export const readOrgUnitSelection = (orgUnits = []) => {
+ const parsed = orgUnits.map(parseOrgUnitSelectionItem)
+ const isParent = isOfType(
+ ORG_UNIT_ITEM_TYPE_ORG_UNIT,
+ ORG_UNIT_ITEM_TYPE_USER
+ )
+
+ return parsed.some(isLevelOrGroup)
+ ? {
+ selectionItems: parsed.filter((item) => !isParent(item)),
+ parentItems: parsed.filter(isParent),
+ }
+ : { selectionItems: parsed, parentItems: [] }
+}
+
+/**
+ * What a selection needs fetched: its org units, the roots (a level with no
+ * parent), the user's org units, and its groups.
+ */
+export const getOrgUnitsToFetch = (orgUnits = []) => {
+ const parsed = orgUnits.map(parseOrgUnitSelectionItem)
+ const ofType = (type) => parsed.filter(isOfType(type))
+
+ return {
+ orgUnitIds: ofType(ORG_UNIT_ITEM_TYPE_ORG_UNIT).map(({ id }) => id),
+ needsRoots:
+ ofType(ORG_UNIT_ITEM_TYPE_LEVEL).length > 0 &&
+ !ofType(ORG_UNIT_ITEM_TYPE_ORG_UNIT).length &&
+ !ofType(ORG_UNIT_ITEM_TYPE_USER).length,
+ needsUserOrgUnits: ofType(ORG_UNIT_ITEM_TYPE_USER).length > 0,
+ groupIds: [
+ ...new Set(
+ ofType(ORG_UNIT_ITEM_TYPE_GROUP).map(({ groupId }) => groupId)
+ ),
+ ],
+ }
+}
+
+/**
+ * The org units a level or a group is kept under, each with the shallowest
+ * level it holds (`minLevel`): an org unit at its own level and below; the
+ * user's org units, below their level plus the item's depth (the children of
+ * the user's org units hold levels from one below theirs). Without parents,
+ * the roots. A parent given twice, or within another that holds its levels,
+ * counts once. Null when one isn't loaded.
+ */
+export const resolveParents = (parentItems, coverage) => {
+ const { orgUnits, rootIds = [], userOrgUnitIds } = coverage
+
+ if (!parentItems.length) {
+ return rootIds.map((id) => ({ orgUnitId: id, minLevel: 1 }))
+ }
+
+ const parents = parentItems.flatMap(({ type, id, depth }) =>
+ type === ORG_UNIT_ITEM_TYPE_USER
+ ? (userOrgUnitIds ?? [undefined]).map((userId) => ({
+ orgUnitId: userId,
+ minLevel: (orgUnits[userId]?.level ?? 0) + depth,
+ }))
+ : [{ orgUnitId: id, minLevel: orgUnits[id]?.level }]
+ )
+
+ if (!parents.every(({ orgUnitId }) => orgUnits[orgUnitId])) {
+ return null
+ }
+
+ // A parent given twice counts once, from the shallowest level either holds
+ const distinct = [
+ ...parents
+ .reduce((byId, parent) => {
+ const known = byId.get(parent.orgUnitId)
+
+ return known && known.minLevel <= parent.minLevel
+ ? byId
+ : byId.set(parent.orgUnitId, parent)
+ }, new Map())
+ .values(),
+ ]
+ // Analytics takes the org units under all parents once each
+ const isWithin = (parent, other) =>
+ other !== parent &&
+ orgUnits[parent.orgUnitId].path.includes(`/${other.orgUnitId}/`) &&
+ other.minLevel <= parent.minLevel
+
+ return distinct.filter(
+ (parent) => !distinct.some((other) => isWithin(parent, other))
+ )
+}
+
+// Where the counts of a group's members at one level, under one parent, are kept
+export const getGroupCountsKey = (groupId, level, parentOrgUnitId) =>
+ `${groupId}:${level}:${parentOrgUnitId ?? ''}`
+
+const getLevelNumber = (level, levels) =>
+ typeof level === 'number'
+ ? level
+ : levels.find(({ id }) => id === level)?.level ?? null
+
+/* A group's members at each level they are at, under each parent that holds
+ * that level (or anywhere, without parents) */
+const getGroupRequestedLevels = (groupId, parents, groups) => {
+ const membersByLevel = groups?.[groupId]
+
+ if (!membersByLevel) {
+ return null
+ }
+
+ return Object.keys(membersByLevel)
+ .map(Number)
+ .filter((level) => membersByLevel[level] > 0)
+ .flatMap((level) =>
+ (parents ?? [{ orgUnitId: null, minLevel: 1 }])
+ .filter(({ minLevel }) => minLevel <= level)
+ .map(({ orgUnitId }) => ({
+ countsKey: getGroupCountsKey(groupId, level, orgUnitId),
+ level,
+ groupId,
+ }))
+ )
+}
+
+/**
+ * The levels analytics aggregates to for a selection item, each with where
+ * its counts are kept in the coverage (fetchOrgUnitCoverage): an org unit at
+ * its own level; LEVEL-n at level n under each parent that holds it (or under
+ * the roots); the user's org units at their level plus the item's depth; a
+ * group at each level its members are at, under each parent. An empty list
+ * when no parent holds the level. Null when it can't be told: an unknown id
+ * or level, or an org unit or group that isn't loaded.
+ */
+export const getRequestedLevels = (selectionItem, parentItems, coverage) => {
+ const { orgUnits, userOrgUnitIds, levels = [] } = coverage
+ const atOwnLevel = (orgUnitId, depth = 0) =>
+ orgUnits[orgUnitId] && {
+ countsKey: orgUnitId,
+ level: orgUnits[orgUnitId].level + depth,
+ }
+
+ switch (selectionItem.type) {
+ case ORG_UNIT_ITEM_TYPE_ORG_UNIT: {
+ const requested = atOwnLevel(selectionItem.id)
+
+ return requested ? [requested] : null
+ }
+ case ORG_UNIT_ITEM_TYPE_LEVEL: {
+ const level = getLevelNumber(selectionItem.level, levels)
+ const parents = resolveParents(parentItems, coverage)
+
+ if (!level || !parents) {
+ return null
+ }
+
+ // A level deeper than the hierarchy holds no org unit
+ if (levels.length && level > levels.at(-1).level) {
+ return []
+ }
+
+ return parents
+ .filter(({ minLevel }) => minLevel <= level)
+ .map(({ orgUnitId }) => ({ countsKey: orgUnitId, level }))
+ }
+ case ORG_UNIT_ITEM_TYPE_USER: {
+ const requested = (userOrgUnitIds ?? []).map((id) =>
+ atOwnLevel(id, selectionItem.depth)
+ )
+
+ return userOrgUnitIds && !requested.includes(undefined)
+ ? requested
+ : null
+ }
+ case ORG_UNIT_ITEM_TYPE_GROUP: {
+ const parents = parentItems.length
+ ? resolveParents(parentItems, coverage)
+ : undefined
+
+ return parents === null
+ ? null
+ : getGroupRequestedLevels(
+ selectionItem.groupId,
+ parents,
+ coverage.groups
+ )
+ }
+ default:
+ return null
+ }
+}
diff --git a/src/modules/dataItemProfile/periods/__tests__/calendarDates.spec.js b/src/modules/dataItemProfile/periods/__tests__/calendarDates.spec.js
new file mode 100644
index 000000000..cc44a7aa8
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/__tests__/calendarDates.spec.js
@@ -0,0 +1,48 @@
+import {
+ formatDate,
+ getYear,
+ isIsoCalendar,
+ pad,
+ shiftDate,
+ fromIsoDate,
+} from '../calendarDates.js'
+
+describe('calendarDates', () => {
+ it('needs no conversion for the ISO calendars only', () => {
+ expect(isIsoCalendar()).toBe(true)
+ expect(isIsoCalendar('iso8601')).toBe(true)
+ expect(isIsoCalendar('gregorian')).toBe(true)
+ expect(isIsoCalendar('nepali')).toBe(false)
+ })
+
+ it('formats and reads dates', () => {
+ expect(pad(7)).toBe('07')
+ expect(pad(825, 4)).toBe('0825')
+ expect(formatDate({ year: 2025, month: 1, day: 6 })).toBe('2025-01-06')
+ expect(getYear('2025-01-06')).toBe(2025)
+ })
+
+ it('shifts a date by days, across months and years', () => {
+ expect(shiftDate('2025-01-01', -1)).toBe('2024-12-31')
+ expect(shiftDate('2024-02-28', 1, 'iso8601')).toBe('2024-02-29')
+ })
+
+ it('shifts a date of another calendar in that calendar', () => {
+ expect(shiftDate('2081-01-03', 1, 'nepali')).toBe('2081-01-04')
+ expect(fromIsoDate('2024-04-16', 'nepali')).toBe('2081-01-04')
+ })
+})
+
+describe('fromIsoDate', () => {
+ it('keeps ISO dates, and converts them to other calendars', () => {
+ expect(fromIsoDate('2025-01-06')).toBe('2025-01-06')
+ expect(fromIsoDate('2024-04-15', 'nepali')).toBe('2081-01-03')
+ })
+})
+
+describe('a conversion that fails', () => {
+ it('gives null, never throws', () => {
+ expect(fromIsoDate('2024-04-15', 'noSuchCalendar')).toBeNull()
+ expect(shiftDate('2081-01-03', 1, 'noSuchCalendar')).toBeNull()
+ })
+})
diff --git a/src/modules/dataItemProfile/periods/__tests__/firstLastValues.spec.js b/src/modules/dataItemProfile/periods/__tests__/firstLastValues.spec.js
new file mode 100644
index 000000000..2b8e2a7ba
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/__tests__/firstLastValues.spec.js
@@ -0,0 +1,214 @@
+import {
+ getFirstOrLastValuePeriod,
+ getYearsTouched,
+} from '../firstLastValues.js'
+import { getPeriodDates } from '../periodRanges.js'
+
+const sourceOf = ({
+ periodAggregationType = 'LAST',
+ periodType,
+ period,
+ years,
+ calendar,
+}) => {
+ const dates = getPeriodDates(period, calendar)
+
+ return getFirstOrLastValuePeriod({
+ periodAggregationType,
+ periodType,
+ dates,
+ years: years ?? getYearsTouched(dates),
+ calendar,
+ })
+}
+
+describe('getYearsTouched', () => {
+ it('lists the calendar years a period falls in', () => {
+ expect(getYearsTouched(getPeriodDates('2025W1'))).toEqual([2024, 2025])
+ expect(getYearsTouched(getPeriodDates('2025WedW1'))).toEqual([2025])
+ expect(getYearsTouched(getPeriodDates('2024April'))).toEqual([
+ 2024, 2025,
+ ])
+ })
+})
+
+describe('getFirstOrLastValuePeriod', () => {
+ describe('LAST', () => {
+ it('takes the latest data period that ended by the end of the period', () => {
+ expect(
+ sourceOf({ periodType: 'Monthly', period: '20250715' })
+ ).toMatchObject({ id: '202506' })
+ expect(
+ sourceOf({ periodType: 'Monthly', period: '2025Q3' })
+ ).toMatchObject({ id: '202509' })
+ })
+
+ it('skips a gap year in the request, for weekly and monthly data', () => {
+ expect(
+ sourceOf({
+ periodType: 'Weekly',
+ period: '20240101',
+ years: [2022, 2024],
+ })
+ ).toMatchObject({ id: '2022W52' })
+ expect(
+ sourceOf({
+ periodType: 'Monthly',
+ period: '20240101',
+ years: [2020, 2024],
+ })
+ ).toMatchObject({ id: '202012' })
+ })
+
+ it('counts only data periods of the years touched, by the year they start in', () => {
+ expect(
+ sourceOf({ periodType: 'Monthly', period: '20250101' })
+ ).toBeNull()
+ // 2025W1 starts in 2024, so December 2024 counts
+ expect(
+ sourceOf({ periodType: 'Monthly', period: '2025W1' })
+ ).toMatchObject({ id: '202412' })
+ // 2025Nov (November 2024 to October 2025) is a 2024 period
+ expect(
+ sourceOf({ periodType: 'FinancialNov', period: '20251101' })
+ ).toBeNull()
+ expect(
+ sourceOf({ periodType: 'FinancialNov', period: '2025W1' })
+ ).toBeNull()
+ expect(
+ sourceOf({
+ periodType: 'FinancialNov',
+ period: '20251101',
+ years: [2024, 2025],
+ })
+ ).toMatchObject({ id: '2025Nov' })
+ })
+
+ it('counts weeks by the year in their id, and bi-weeks by their start', () => {
+ // 2026W1 starts on 29 December 2025: a 2026 period
+ expect(
+ sourceOf({
+ periodType: 'Weekly',
+ period: '20260105',
+ years: [2026],
+ })
+ ).toMatchObject({ id: '2026W1' })
+ // 2026BiW1 starts on the same day: a 2025 period
+ expect(
+ sourceOf({
+ periodType: 'BiWeekly',
+ period: '20260112',
+ years: [2026],
+ })
+ ).toBeNull()
+ expect(
+ sourceOf({
+ periodType: 'BiWeekly',
+ period: '20260112',
+ years: [2025, 2026],
+ })
+ ).toMatchObject({ id: '2026BiW1' })
+ })
+
+ it('skips years the request does not touch', () => {
+ expect(
+ sourceOf({
+ periodType: 'Monthly',
+ period: '20250715',
+ years: [2023, 2025],
+ })
+ ).toMatchObject({ id: '202506' })
+ // 2024 isn't touched: December 2023 is the latest that counts
+ expect(
+ sourceOf({
+ periodType: 'Monthly',
+ period: '20250101',
+ years: [2023, 2025],
+ })
+ ).toMatchObject({ id: '202312' })
+ expect(
+ sourceOf({
+ periodType: 'Monthly',
+ period: '20250101',
+ years: [2026],
+ })
+ ).toBeNull()
+ })
+ })
+
+ describe('FIRST', () => {
+ it('takes the earliest data period of the years touched', () => {
+ expect(
+ sourceOf({
+ periodAggregationType: 'FIRST',
+ periodType: 'Monthly',
+ period: '202507',
+ })
+ ).toMatchObject({ id: '202501' })
+ expect(
+ sourceOf({
+ periodAggregationType: 'FIRST',
+ periodType: 'Daily',
+ period: '20250715',
+ years: [2024, 2025],
+ })
+ ).toMatchObject({ id: '20240101' })
+ })
+
+ it('needs that period to end by the end of the period asked for', () => {
+ expect(
+ sourceOf({
+ periodAggregationType: 'FIRST',
+ periodType: 'Monthly',
+ period: '20250101',
+ })
+ ).toBeNull()
+ })
+
+ it('starts from the first period whose id names the year', () => {
+ // 2024April holds 1 January 2025, but is a 2024 period
+ expect(
+ sourceOf({
+ periodAggregationType: 'FIRST',
+ periodType: 'FinancialApril',
+ period: '2025April',
+ years: [2025, 2026],
+ })
+ ).toMatchObject({ id: '2025April' })
+ })
+ })
+
+ it('is null without years, or for a type without dates', () => {
+ expect(
+ sourceOf({ periodType: 'Monthly', period: '20250715', years: [] })
+ ).toBeNull()
+ expect(
+ sourceOf({ periodType: 'TwoYearly', period: '20250715' })
+ ).toBeNull()
+ expect(
+ sourceOf({
+ periodAggregationType: 'FIRST',
+ periodType: 'TwoYearly',
+ period: '20250715',
+ })
+ ).toBeNull()
+ })
+
+ it('works in other calendars', () => {
+ expect(
+ sourceOf({
+ periodType: 'Monthly',
+ period: '20810415',
+ calendar: 'nepali',
+ })
+ ).toMatchObject({ id: '208103' })
+ expect(
+ sourceOf({
+ periodAggregationType: 'FIRST',
+ periodType: 'Monthly',
+ period: '208104',
+ calendar: 'nepali',
+ })
+ ).toMatchObject({ id: '208101' })
+ })
+})
diff --git a/src/modules/dataItemProfile/periods/__tests__/memoize.spec.js b/src/modules/dataItemProfile/periods/__tests__/memoize.spec.js
new file mode 100644
index 000000000..d8ae8bfdb
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/__tests__/memoize.spec.js
@@ -0,0 +1,34 @@
+import { memoize } from '../memoize.js'
+
+describe('memoize', () => {
+ it('computes once per arguments', () => {
+ const double = jest.fn((a, b) => [a, b])
+ const memoized = memoize(double)
+
+ expect(memoized(1, 2)).toBe(memoized(1, 2))
+ expect(memoized(2, 1)).toEqual([2, 1])
+ expect(double).toHaveBeenCalledTimes(2)
+ })
+
+ it('starts over when full', () => {
+ const identity = jest.fn((a) => ({ a }))
+ const memoized = memoize(identity, { maxSize: 2 })
+
+ memoized(1)
+ memoized(2)
+ memoized(3)
+ memoized(2)
+
+ expect(identity).toHaveBeenCalledTimes(4)
+ })
+
+ it('takes a key of its own', () => {
+ const read = jest.fn(({ id }) => id)
+ const memoized = memoize(read, { getKey: ({ id }) => id })
+
+ memoized({ id: 'a', other: 1 })
+ memoized({ id: 'a', other: 2 })
+
+ expect(read).toHaveBeenCalledTimes(1)
+ })
+})
diff --git a/src/modules/dataItemProfile/periods/__tests__/multiCalendarPatches.spec.js b/src/modules/dataItemProfile/periods/__tests__/multiCalendarPatches.spec.js
new file mode 100644
index 000000000..103336e1f
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/__tests__/multiCalendarPatches.spec.js
@@ -0,0 +1,38 @@
+import {
+ getNovemberPeriodByDate,
+ getNovemberPeriodDates,
+ isNovemberPeriodId,
+ isNovemberPeriodType,
+} from '../multiCalendarPatches.js'
+
+describe('multiCalendarPatches', () => {
+ it('tells November periods and types apart', () => {
+ expect(isNovemberPeriodId('2025NovQ1')).toBe(true)
+ expect(isNovemberPeriodId('2025Nov')).toBe(true)
+ expect(isNovemberPeriodId('2025Q1')).toBe(false)
+ expect(isNovemberPeriodType('SixMonthlyNov')).toBe(true)
+ expect(isNovemberPeriodType('SixMonthly')).toBe(false)
+ expect(isNovemberPeriodType('toString')).toBe(false)
+ })
+
+ it('dates November periods by the year they end in', () => {
+ expect(getNovemberPeriodDates('2025Nov')).toEqual({
+ startDate: '2024-11-01',
+ endDate: '2025-10-31',
+ })
+ expect(getNovemberPeriodDates('2025NovS2')).toEqual({
+ startDate: '2025-05-01',
+ endDate: '2025-10-31',
+ })
+ })
+
+ it.each([
+ ['FinancialNov', '2024-11-01', '2025Nov'],
+ ['FinancialNov', '2025-10-31', '2025Nov'],
+ ['QuarterlyNov', '2024-12-15', '2025NovQ1'],
+ ['QuarterlyNov', '2025-02-01', '2025NovQ2'],
+ ['SixMonthlyNov', '2025-05-01', '2025NovS2'],
+ ])('finds the %s period holding %s: %s', (periodType, date, id) => {
+ expect(getNovemberPeriodByDate(periodType, date).id).toBe(id)
+ })
+})
diff --git a/src/modules/dataItemProfile/periods/__tests__/periodRanges.spec.js b/src/modules/dataItemProfile/periods/__tests__/periodRanges.spec.js
new file mode 100644
index 000000000..c3e87cb30
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/__tests__/periodRanges.spec.js
@@ -0,0 +1,159 @@
+import {
+ getNextPeriod,
+ getPreviousPeriod,
+ getCoveringPeriodRange,
+ getFixedPeriodOfTypeByDate,
+ getPeriodDates,
+ isAlignedWithPeriodType,
+} from '../periodRanges.js'
+
+describe('getPeriodDates', () => {
+ it.each([
+ ['2025W1', '2024-12-30', '2025-01-05'],
+ ['2025WedW1', '2025-01-01', '2025-01-07'],
+ ['2025BiW1', '2024-12-30', '2025-01-12'],
+ ['202501', '2025-01-01', '2025-01-31'],
+ ['2025Q1', '2025-01-01', '2025-03-31'],
+ ['2025AprilS1', '2025-04-01', '2025-09-30'],
+ ['2025April', '2025-04-01', '2026-03-31'],
+ ['20250115', '2025-01-15', '2025-01-15'],
+ ])('%s: %s to %s', (periodId, startDate, endDate) => {
+ expect(getPeriodDates(periodId)).toEqual({ startDate, endDate })
+ })
+
+ it.each([
+ ['2025Nov', '2024-11-01', '2025-10-31'],
+ ['2025NovQ1', '2024-11-01', '2025-01-31'],
+ ['2025NovQ3', '2025-05-01', '2025-07-31'],
+ ['2025NovS1', '2024-11-01', '2025-04-30'],
+ ['2025NovS2', '2025-05-01', '2025-10-31'],
+ ])(
+ 'dates the November type %s as the server does',
+ (periodId, startDate, endDate) => {
+ expect(getPeriodDates(periodId)).toEqual({ startDate, endDate })
+ expect(getPeriodDates(periodId, 'iso8601')).toEqual({
+ startDate,
+ endDate,
+ })
+ }
+ )
+
+ it('gives no dates for November types in other calendars', () => {
+ expect(getPeriodDates('2081Nov', 'nepali')).toBeNull()
+ })
+
+ it('gives dates in the calendar asked for', () => {
+ expect(getPeriodDates('2081W1', 'nepali')).toEqual({
+ startDate: '2081-01-03',
+ endDate: '2081-01-09',
+ })
+ })
+
+ it('is null for an id it cannot read', () => {
+ expect(getPeriodDates('LAST_12_MONTHS')).toBeNull()
+ expect(getPeriodDates('2025X1')).toBeNull()
+ })
+})
+
+describe('getFixedPeriodOfTypeByDate', () => {
+ it('finds the period of a type that holds a date', () => {
+ expect(
+ getFixedPeriodOfTypeByDate('WeeklyWednesday', '2025-01-10')
+ ).toMatchObject({ startDate: '2025-01-08', endDate: '2025-01-14' })
+ })
+
+ it.each([
+ ['FinancialNov', '2025-01-08', '2025Nov', '2024-11-01'],
+ ['FinancialNov', '2024-11-01', '2025Nov', '2024-11-01'],
+ ['FinancialNov', '2024-10-31', '2024Nov', '2023-11-01'],
+ ['QuarterlyNov', '2025-01-08', '2025NovQ1', '2024-11-01'],
+ ['QuarterlyNov', '2025-10-31', '2025NovQ4', '2025-08-01'],
+ ['SixMonthlyNov', '2025-05-01', '2025NovS2', '2025-05-01'],
+ ])('gives %s periods the ids the server uses (%s)', (...args) => {
+ const [periodType, date, id, startDate] = args
+
+ expect(getFixedPeriodOfTypeByDate(periodType, date)).toMatchObject({
+ id,
+ startDate,
+ })
+ })
+
+ it('is null for November types in other calendars', () => {
+ expect(
+ getFixedPeriodOfTypeByDate('QuarterlyNov', '2081-09-24', 'nepali')
+ ).toBeNull()
+ })
+
+ it('is null for a type without an ISO format', () => {
+ expect(getFixedPeriodOfTypeByDate('TwoYearly', '2025-01-10')).toBeNull()
+ })
+
+ it('is null for a date it cannot read', () => {
+ expect(getFixedPeriodOfTypeByDate('Monthly', 'not a date')).toBeNull()
+ expect(getFixedPeriodOfTypeByDate('Monthly', null)).toBeNull()
+ })
+})
+
+describe('getCoveringPeriodRange', () => {
+ it('widens to whole periods of the type', () => {
+ expect(
+ getCoveringPeriodRange(getPeriodDates('2025W2'), 'Monthly')
+ ).toEqual({
+ startDate: '2025-01-01',
+ endDate: '2025-01-31',
+ })
+ expect(
+ getCoveringPeriodRange(getPeriodDates('2025W1'), 'Monthly')
+ ).toEqual({
+ startDate: '2024-12-01',
+ endDate: '2025-01-31',
+ })
+ })
+
+ it('is null when it cannot tell', () => {
+ expect(
+ getCoveringPeriodRange(getPeriodDates('2025W2'), 'TwoYearly')
+ ).toBeNull()
+ })
+})
+
+describe('isAlignedWithPeriodType', () => {
+ it.each([
+ ['2025Q1', 'Monthly', true],
+ ['2025', 'Quarterly', true],
+ ['2025W2', 'Daily', true],
+ ['2025BiW1', 'Weekly', true],
+ ['202501', 'Weekly', false],
+ ['2025', 'WeeklyWednesday', false],
+ ['2025April', 'Quarterly', true],
+ ['2025April', 'SixMonthly', false],
+ ['2025Q1', 'TwoYearly', null],
+ ])('%s on %s data: %s', (periodId, periodType, expected) => {
+ expect(
+ isAlignedWithPeriodType(getPeriodDates(periodId), periodType)
+ ).toBe(expected)
+ })
+})
+
+describe('getPreviousPeriod and getNextPeriod', () => {
+ it('step to the adjacent period of the same type', () => {
+ const january = getFixedPeriodOfTypeByDate('Monthly', '2025-01-15')
+
+ expect(getPreviousPeriod('Monthly', january).id).toBe('202412')
+ expect(getNextPeriod('Monthly', january).id).toBe('202502')
+ })
+
+ it('step across November periods, which the library dates itself', () => {
+ const quarter = getFixedPeriodOfTypeByDate('QuarterlyNov', '2025-01-15')
+
+ expect(getNextPeriod('QuarterlyNov', quarter).id).toBe('2025NovQ2')
+ })
+
+ it('are null when the date of a calendar cannot be converted', () => {
+ const period = { startDate: '2081-01-01', endDate: '2081-01-31' }
+
+ expect(
+ getPreviousPeriod('Monthly', period, 'noSuchCalendar')
+ ).toBeNull()
+ })
+})
diff --git a/src/modules/dataItemProfile/periods/__tests__/periodTypes.spec.js b/src/modules/dataItemProfile/periods/__tests__/periodTypes.spec.js
new file mode 100644
index 000000000..67951e601
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/__tests__/periodTypes.spec.js
@@ -0,0 +1,180 @@
+import { PERIOD_TYPES } from '../../constants.js'
+import {
+ canAggregateInto,
+ getCandidatePeriodTypes,
+ getPeriodTypeOfPeriodId,
+ getRelativePeriodTypeOptions,
+ isPeriodType,
+ isPeriodTypeSupported,
+ sortPeriodTypes,
+} from '../periodTypes.js'
+
+describe('PERIOD_TYPES', () => {
+ it('lists the 24 server period types', () => {
+ expect(PERIOD_TYPES).toHaveLength(24)
+ expect(isPeriodType('TwoYearly')).toBe(true)
+ expect(isPeriodType('WEEKLY')).toBe(false)
+ })
+})
+
+describe('sortPeriodTypes', () => {
+ it('sorts by frequency, then in server order', () => {
+ expect(
+ sortPeriodTypes(['Yearly', 'WeeklyWednesday', 'Monthly', 'Weekly'])
+ ).toEqual(['Weekly', 'WeeklyWednesday', 'Monthly', 'Yearly'])
+ })
+})
+
+describe('getPeriodTypeOfPeriodId', () => {
+ it.each([
+ ['20250115', 'Daily'],
+ ['2025W2', 'Weekly'],
+ ['2025WedW2', 'WeeklyWednesday'],
+ ['2025ThuW2', 'WeeklyThursday'],
+ ['2025FriW2', 'WeeklyFriday'],
+ ['2025SatW2', 'WeeklySaturday'],
+ ['2025SunW2', 'WeeklySunday'],
+ ['2025BiW2', 'BiWeekly'],
+ ['202501', 'Monthly'],
+ ['202501B', 'BiMonthly'],
+ ['2025Q1', 'Quarterly'],
+ ['2025NovQ1', 'QuarterlyNov'],
+ ['2025S1', 'SixMonthly'],
+ ['2025AprilS1', 'SixMonthlyApril'],
+ ['2025NovS1', 'SixMonthlyNov'],
+ ['2025', 'Yearly'],
+ ['2025Feb', 'FinancialFeb'],
+ ['2025April', 'FinancialApril'],
+ ['2025July', 'FinancialJuly'],
+ ['2025Aug', 'FinancialAug'],
+ ['2025Sep', 'FinancialSep'],
+ ['2025Oct', 'FinancialOct'],
+ ['2025Nov', 'FinancialNov'],
+ ])('%s is %s', (periodId, periodType) => {
+ expect(getPeriodTypeOfPeriodId(periodId)).toBe(periodType)
+ })
+
+ it('is null for anything else', () => {
+ expect(getPeriodTypeOfPeriodId('LAST_12_MONTHS')).toBeNull()
+ expect(getPeriodTypeOfPeriodId('2025X1')).toBeNull()
+ })
+})
+
+describe('getCandidatePeriodTypes', () => {
+ it('takes a period type as it is', () => {
+ expect(getCandidatePeriodTypes('TwoYearly')).toEqual(['TwoYearly'])
+ })
+
+ it('reads a fixed period', () => {
+ expect(getCandidatePeriodTypes('2025WedW2')).toEqual([
+ 'WeeklyWednesday',
+ ])
+ })
+
+ it.each([
+ ['LAST_7_DAYS', ['Daily']],
+ ['LAST_4_BIWEEKS', ['BiWeekly']],
+ ['LAST_12_MONTHS', ['Monthly']],
+ ['BIMONTHS_THIS_YEAR', ['BiMonthly']],
+ ['LAST_4_QUARTERS', ['Quarterly']],
+ ['LAST_2_SIXMONTHS', ['SixMonthly']],
+ ['LAST_5_YEARS', ['Yearly']],
+ ])('reads the relative period %s', (periodId, expected) => {
+ expect(getCandidatePeriodTypes(periodId)).toEqual(expected)
+ })
+
+ it('gives every weekly type for relative weeks, unless the setting is known', () => {
+ expect(getCandidatePeriodTypes('LAST_4_WEEKS')).toEqual([
+ 'Weekly',
+ 'WeeklyWednesday',
+ 'WeeklyThursday',
+ 'WeeklyFriday',
+ 'WeeklySaturday',
+ 'WeeklySunday',
+ ])
+ expect(
+ getCandidatePeriodTypes('LAST_4_WEEKS', {
+ weeklyPeriodType: 'WeeklySunday',
+ })
+ ).toEqual(['WeeklySunday'])
+ })
+
+ it('gives every financial type for relative financial years, unless the setting is known', () => {
+ expect(getCandidatePeriodTypes('THIS_FINANCIAL_YEAR')).toHaveLength(7)
+ expect(
+ getCandidatePeriodTypes('THIS_FINANCIAL_YEAR', {
+ financialYearPeriodType: 'FinancialOct',
+ })
+ ).toEqual(['FinancialOct'])
+ })
+
+ it('gives nothing for an id it cannot read', () => {
+ expect(getCandidatePeriodTypes('NEXT_CENTURY')).toEqual([])
+ })
+})
+
+describe('getRelativePeriodTypeOptions', () => {
+ it('maps the system settings to period types', () => {
+ expect(
+ getRelativePeriodTypeOptions({
+ analyticsWeeklyStart: 'WEEKLY_WEDNESDAY',
+ analyticsFinancialYearStart: 'FINANCIAL_YEAR_OCTOBER',
+ })
+ ).toEqual({
+ weeklyPeriodType: 'WeeklyWednesday',
+ financialYearPeriodType: 'FinancialOct',
+ })
+ })
+
+ it('leaves out unknown or missing settings', () => {
+ expect(getRelativePeriodTypeOptions()).toEqual({
+ weeklyPeriodType: undefined,
+ financialYearPeriodType: undefined,
+ })
+ })
+})
+
+describe('isPeriodTypeSupported', () => {
+ it('leaves out QuarterlyNov before 2.41', () => {
+ expect(
+ isPeriodTypeSupported('QuarterlyNov', { major: 2, minor: 40 })
+ ).toBe(false)
+ expect(
+ isPeriodTypeSupported('QuarterlyNov', { major: 2, minor: 41 })
+ ).toBe(true)
+ expect(
+ isPeriodTypeSupported('QuarterlyNov', { major: 3, minor: 0 })
+ ).toBe(true)
+ expect(isPeriodTypeSupported('Monthly', { major: 2, minor: 40 })).toBe(
+ true
+ )
+ })
+
+ it('supports every type without a version', () => {
+ expect(isPeriodTypeSupported('QuarterlyNov')).toBe(true)
+ })
+})
+
+describe('canAggregateInto', () => {
+ it.each([
+ ['Monthly', 'Monthly', true],
+ ['Weekly', 'Monthly', true],
+ ['Daily', 'TwoYearly', true],
+ ['Monthly', 'FinancialApril', true],
+ ['Monthly', 'Weekly', false],
+ ['Yearly', 'Quarterly', false],
+ ['WeeklyWednesday', 'Weekly', false],
+ ['Weekly', 'WeeklyWednesday', false],
+ ['Yearly', 'FinancialApril', false],
+ ['Quarterly', 'QuarterlyNov', false],
+ ['Weekly', 'BiWeekly', true],
+ ['WeeklyWednesday', 'BiWeekly', true],
+ ])('%s data into %s queries: %s', (data, query, expected) => {
+ expect(canAggregateInto(data, query)).toBe(expected)
+ })
+
+ it('is null for an unknown type', () => {
+ expect(canAggregateInto('Hourly', 'Monthly')).toBeNull()
+ expect(canAggregateInto('Monthly', undefined)).toBeNull()
+ })
+})
diff --git a/src/modules/dataItemProfile/periods/__tests__/relativePeriodRanges.spec.js b/src/modules/dataItemProfile/periods/__tests__/relativePeriodRanges.spec.js
new file mode 100644
index 000000000..817cc105d
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/__tests__/relativePeriodRanges.spec.js
@@ -0,0 +1,101 @@
+import { getRelativePeriodFixedPeriods } from '../relativePeriodRanges.js'
+
+const ON_15_JUNE_2025 = { relativePeriodDate: '2025-06-15' }
+const idsOf = (periodId, periodType, options = ON_15_JUNE_2025) =>
+ getRelativePeriodFixedPeriods(periodId, periodType, options)?.map(
+ ({ id }) => id
+ )
+
+describe('getRelativePeriodFixedPeriods', () => {
+ it('resolves this and last periods from the date', () => {
+ expect(idsOf('THIS_MONTH', 'Monthly')).toEqual(['202506'])
+ expect(idsOf('LAST_MONTH', 'Monthly')).toEqual(['202505'])
+ expect(idsOf('LAST_YEAR', 'Yearly')).toEqual(['2024'])
+ })
+
+ it('resolves the periods before this one, oldest first', () => {
+ expect(idsOf('LAST_3_MONTHS', 'Monthly')).toEqual([
+ '202503',
+ '202504',
+ '202505',
+ ])
+ expect(idsOf('LAST_12_MONTHS', 'Monthly')).toHaveLength(12)
+ expect(idsOf('LAST_7_DAYS', 'Daily')).toEqual([
+ '20250608',
+ '20250609',
+ '20250610',
+ '20250611',
+ '20250612',
+ '20250613',
+ '20250614',
+ ])
+ })
+
+ it('resolves the periods of this year, all of them', () => {
+ expect(idsOf('MONTHS_THIS_YEAR', 'Monthly')).toEqual([
+ '202501',
+ '202502',
+ '202503',
+ '202504',
+ '202505',
+ '202506',
+ '202507',
+ '202508',
+ '202509',
+ '202510',
+ '202511',
+ '202512',
+ ])
+ expect(idsOf('QUARTERS_THIS_YEAR', 'Quarterly')).toEqual([
+ '2025Q1',
+ '2025Q2',
+ '2025Q3',
+ '2025Q4',
+ ])
+ })
+
+ it('takes the weeks that belong to this year', () => {
+ const weeks = idsOf('WEEKS_THIS_YEAR', 'Weekly')
+
+ expect(weeks[0]).toBe('2025W1')
+ expect(weeks.at(-1)).toBe('2025W52')
+ })
+
+ it('resolves the type a setting gives', () => {
+ expect(idsOf('THIS_WEEK', 'WeeklyWednesday')).toEqual(['2025WedW24'])
+ expect(idsOf('THIS_FINANCIAL_YEAR', 'FinancialApril')).toEqual([
+ '2025April',
+ ])
+ })
+
+ it('resolves dates of other calendars', () => {
+ expect(
+ idsOf('THIS_MONTH', 'Monthly', {
+ calendar: 'nepali',
+ relativePeriodDate: '2025-06-15',
+ })
+ ).toEqual(['208202'])
+ })
+
+ it('resolves from today by default', () => {
+ expect(idsOf('THIS_YEAR', 'Yearly', {})).toEqual([
+ String(new Date().getFullYear()),
+ ])
+ })
+
+ it('cannot tell for an unknown relative period or period type', () => {
+ expect(idsOf('LAST_7_DECADES', 'Yearly')).toBeUndefined()
+ expect(idsOf('THIS_MONTH', 'Hourly')).toBeUndefined()
+ })
+})
+
+describe('getRelativePeriodFixedPeriods, in a calendar it cannot convert to', () => {
+ it('cannot tell', () => {
+ expect(
+ idsOf('THIS_MONTH', 'Monthly', {
+ calendar: 'noSuchCalendar',
+ relativePeriodDate: '2025-06-15',
+ })
+ ).toBeUndefined()
+ })
+})
diff --git a/src/modules/dataItemProfile/periods/calendarDates.js b/src/modules/dataItemProfile/periods/calendarDates.js
new file mode 100644
index 000000000..d498a6880
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/calendarDates.js
@@ -0,0 +1,65 @@
+import {
+ convertFromIso8601,
+ convertToIso8601,
+} from '@dhis2/multi-calendar-dates'
+
+/* Dates are YYYY-MM-DD strings in the server's calendar. Other calendars are
+ * supported: their dates are converted to ISO for analytics and back for
+ * multi-calendar-dates. These need no conversion (gregorian is the id DHIS2
+ * gives the gregorian calendar). */
+const ISO_CALENDARS = new Set(['gregory', 'gregorian', 'iso8601'])
+
+export const isIsoCalendar = (calendar = 'gregory') =>
+ ISO_CALENDARS.has(calendar)
+
+export const pad = (number, length = 2) => String(number).padStart(length, '0')
+
+export const formatDate = ({ year, month, day }) =>
+ `${pad(year, 4)}-${pad(month)}-${pad(day)}`
+
+export const getYear = (date) => Number(date.slice(0, 4))
+
+const shiftIsoDate = (isoDate, days) => {
+ const date = new Date(`${isoDate}T00:00:00Z`)
+ date.setUTCDate(date.getUTCDate() + days)
+
+ return date.toISOString().slice(0, 10)
+}
+
+// A conversion multi-calendar-dates can't make (an era it doesn't match) gives null
+const convertOrNull = (convert) => {
+ try {
+ return convert()
+ } catch {
+ return null
+ }
+}
+
+// A date of the ISO calendar (YYYY-MM-DD) in the given calendar, or null
+export const fromIsoDate = (isoDate, calendar = 'gregory') => {
+ if (isIsoCalendar(calendar)) {
+ return isoDate
+ }
+
+ return convertOrNull(() => {
+ const { year, eraYear, month, day } = convertFromIso8601(
+ isoDate,
+ calendar
+ )
+
+ return formatDate({ year: eraYear ?? year, month, day })
+ })
+}
+
+// The date `days` later (or earlier, when negative), in the same calendar, or null
+export const shiftDate = (date, days, calendar = 'gregory') => {
+ if (isIsoCalendar(calendar)) {
+ return shiftIsoDate(date, days)
+ }
+
+ const isoDate = convertOrNull(() =>
+ formatDate(convertToIso8601(date, calendar))
+ )
+
+ return isoDate && fromIsoDate(shiftIsoDate(isoDate, days), calendar)
+}
diff --git a/src/modules/dataItemProfile/periods/firstLastValues.js b/src/modules/dataItemProfile/periods/firstLastValues.js
new file mode 100644
index 000000000..5f9097ba9
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/firstLastValues.js
@@ -0,0 +1,153 @@
+import { PERIOD_AGGREGATION_FIRST } from '../constants.js'
+import { getYear, pad } from './calendarDates.js'
+import { memoize } from './memoize.js'
+import {
+ getFixedPeriodOfTypeByDate,
+ getNextPeriod,
+ getPreviousPeriod,
+} from './periodRanges.js'
+
+/* How analytics answers FIRST and LAST data (checked by the test tool on 2.40
+ * to 2.44): a data period counts when it ended by the end of the period asked
+ * for, and its year is one of the calendar years the request's periods touch.
+ * FIRST takes the earliest that counts, LAST the latest; none gives no value.
+ * So FIRST in July gives January's value, and LAST on 1 January gives
+ * nothing. */
+
+/* A data period's year is the year it starts in, except for weeks: the year
+ * in the id. 2025W1, from 30 December 2024, is a 2025 period, but 2025BiW1,
+ * from the same day, and 2025NovQ1, from November 2024, are 2024 periods. */
+const getDataPeriodYear = (period, periodType) =>
+ periodType.startsWith('Weekly')
+ ? Number(period.id.slice(0, 4))
+ : getYear(period.startDate)
+
+// Enough to reach the last periods of the next year in the request, after a jump
+const MAX_STEPS = 20
+
+const getLastPeriodEndingBy = (periodType, date, calendar) => {
+ const holding = getFixedPeriodOfTypeByDate(periodType, date, calendar)
+
+ if (!holding || holding.endDate <= date) {
+ return holding
+ }
+
+ return getPreviousPeriod(periodType, holding, calendar)
+}
+
+/* Over a gap in the years, jump to the period holding 1 January after the
+ * highest year left: it, or the one before it, starts in that year. Periods
+ * of one type don't overlap, so one that starts earlier also ended by then. */
+const getPeriodBefore = (period, { periodType, highestYear, calendar }) => {
+ const jumped = getFixedPeriodOfTypeByDate(
+ periodType,
+ `${pad(highestYear + 1, 4)}-01-01`,
+ calendar
+ )
+
+ return jumped && jumped.startDate < period.startDate
+ ? jumped
+ : getPreviousPeriod(periodType, period, calendar)
+}
+
+const getLatestCounting = ({ periodType, dates, years, calendar }) => {
+ let period = getLastPeriodEndingBy(periodType, dates.endDate, calendar)
+
+ for (let step = 0; period && step < MAX_STEPS; step++) {
+ const year = getDataPeriodYear(period, periodType)
+
+ if (years.includes(year)) {
+ return period
+ }
+
+ const lowerYears = years.filter((otherYear) => otherYear < year)
+
+ if (!lowerYears.length) {
+ return null
+ }
+
+ period = getPeriodBefore(period, {
+ periodType,
+ highestYear: Math.max(...lowerYears),
+ calendar,
+ })
+ }
+
+ return null
+}
+
+const getEarliestCounting = ({ periodType, dates, years, calendar }) => {
+ const firstYear = Math.min(...years)
+ let period = getFixedPeriodOfTypeByDate(
+ periodType,
+ `${pad(firstYear, 4)}-01-01`,
+ calendar
+ )
+
+ for (let step = 0; period && step < MAX_STEPS; step++) {
+ if (getDataPeriodYear(period, periodType) >= firstYear) {
+ return period.endDate <= dates.endDate ? period : null
+ }
+
+ period = getNextPeriod(periodType, period, calendar)
+ }
+
+ return null
+}
+
+/**
+ * The data period whose value analytics returns for FIRST or LAST data of
+ * `periodType`, in a period with `dates`, when the request touches the
+ * calendar `years`; null when there is none.
+ */
+const findFirstOrLastValuePeriod = memoize(
+ ({ periodAggregationType, ...query }) =>
+ periodAggregationType === PERIOD_AGGREGATION_FIRST
+ ? getEarliestCounting(query)
+ : getLatestCounting(query),
+ {
+ getKey: ({
+ periodAggregationType,
+ periodType,
+ dates,
+ years,
+ calendar,
+ }) =>
+ [
+ periodAggregationType,
+ periodType,
+ dates.startDate,
+ dates.endDate,
+ years.join(','),
+ calendar,
+ ].join('|'),
+ }
+)
+
+export const getFirstOrLastValuePeriod = ({
+ periodAggregationType,
+ periodType,
+ dates,
+ years,
+ calendar = 'gregory',
+}) =>
+ years.length
+ ? findFirstOrLastValuePeriod({
+ periodAggregationType,
+ periodType,
+ dates,
+ years,
+ calendar,
+ })
+ : null
+
+// The calendar years a range's dates fall in
+export const getYearsTouched = ({ startDate, endDate }) => {
+ const years = []
+
+ for (let year = getYear(startDate); year <= getYear(endDate); year++) {
+ years.push(year)
+ }
+
+ return years
+}
diff --git a/src/modules/dataItemProfile/periods/memoize.js b/src/modules/dataItemProfile/periods/memoize.js
new file mode 100644
index 000000000..1744af149
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/memoize.js
@@ -0,0 +1,25 @@
+/* A cache for pure functions with a few small arguments. Period lookups in
+ * multi-calendar-dates build a whole year of periods each time, about 7 ms:
+ * the checks make thousands of them. The cache is cleared when it holds
+ * `maxSize` entries, which bounds memory without tracking use. `getKey`
+ * turns the arguments into the cache key (joined by default). */
+export const memoize = (
+ fn,
+ { maxSize = 2000, getKey = (...args) => args.join('|') } = {}
+) => {
+ const cache = new Map()
+
+ return (...args) => {
+ const key = getKey(...args)
+
+ if (!cache.has(key)) {
+ if (cache.size >= maxSize) {
+ cache.clear()
+ }
+
+ cache.set(key, fn(...args))
+ }
+
+ return cache.get(key)
+ }
+}
diff --git a/src/modules/dataItemProfile/periods/multiCalendarPatches.js b/src/modules/dataItemProfile/periods/multiCalendarPatches.js
new file mode 100644
index 000000000..cb5fb6e98
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/multiCalendarPatches.js
@@ -0,0 +1,58 @@
+import { formatDate } from './calendarDates.js'
+
+/* Workarounds for multi-calendar-dates 1.3.2, to remove once it is fixed
+ * upstream. November period types name the year they end in: 2025Nov is
+ * November 2024 to October 2025, 2025NovQ1 November 2024 to January 2025.
+ * The library can't read the quarters and six-months ids, gives them ids the
+ * server doesn't know (2024NovemberQ1), and puts 2025Nov a year late. Only the
+ * ISO calendar is patched. */
+
+const NOVEMBER_PERIOD_ID = /^(\d{4})Nov(?:(Q)([1-4])|(S)([12]))?$/
+
+const NOVEMBER_PERIOD_TYPES = {
+ FinancialNov: { idPart: '', months: 12 },
+ QuarterlyNov: { idPart: 'Q', months: 3 },
+ SixMonthlyNov: { idPart: 'S', months: 6 },
+}
+
+export const isNovemberPeriodId = (periodId) =>
+ NOVEMBER_PERIOD_ID.test(periodId)
+
+const NOVEMBER_PERIOD_TYPE_NAMES = new Set(Object.keys(NOVEMBER_PERIOD_TYPES))
+
+export const isNovemberPeriodType = (periodType) =>
+ NOVEMBER_PERIOD_TYPE_NAMES.has(periodType)
+
+const toDateString = (date) =>
+ formatDate({
+ year: date.getUTCFullYear(),
+ month: date.getUTCMonth() + 1,
+ day: date.getUTCDate(),
+ })
+
+export const getNovemberPeriodDates = (periodId) => {
+ const [, year, quarter, quarterNumber, sixMonths, sixMonthsNumber] =
+ periodId.match(NOVEMBER_PERIOD_ID)
+ const idPart = quarter ?? sixMonths ?? ''
+ const number = quarterNumber ?? sixMonthsNumber
+ const { months } = Object.values(NOVEMBER_PERIOD_TYPES).find(
+ (type) => type.idPart === idPart
+ )
+ const firstMonth = 10 + (Number(number ?? 1) - 1) * months
+ const start = new Date(Date.UTC(Number(year) - 1, firstMonth, 1))
+ const end = new Date(Date.UTC(Number(year) - 1, firstMonth + months, 0))
+
+ return { startDate: toDateString(start), endDate: toDateString(end) }
+}
+
+// The November period that holds an ISO date
+export const getNovemberPeriodByDate = (periodType, date) => {
+ const { idPart, months } = NOVEMBER_PERIOD_TYPES[periodType]
+ const [year, month] = date.split('-').map(Number)
+ const endYear = month >= 11 ? year + 1 : year
+ const monthsSinceNovember = (month + 1) % 12
+ const number = Math.floor(monthsSinceNovember / months) + 1
+ const id = `${endYear}Nov${idPart && idPart + number}`
+
+ return { id, ...getNovemberPeriodDates(id) }
+}
diff --git a/src/modules/dataItemProfile/periods/periodRanges.js b/src/modules/dataItemProfile/periods/periodRanges.js
new file mode 100644
index 000000000..0de87660c
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/periodRanges.js
@@ -0,0 +1,176 @@
+import {
+ createFixedPeriodFromPeriodId,
+ generateFixedPeriods,
+} from '@dhis2/multi-calendar-dates'
+import { SERVER_PT_TO_MULTI_CALENDAR_PT } from '../../../components/PeriodDimension/utils/enabledPeriodTypes.js'
+import { getYear, isIsoCalendar, shiftDate } from './calendarDates.js'
+import { memoize } from './memoize.js'
+import {
+ getNovemberPeriodByDate,
+ getNovemberPeriodDates,
+ isNovemberPeriodId,
+ isNovemberPeriodType,
+} from './multiCalendarPatches.js'
+import { getPeriodTypeOfPeriodId } from './periodTypes.js'
+
+/* A period range is { startDate, endDate }, YYYY-MM-DD strings in one
+ * calendar, so they compare as strings */
+
+const isYearLongType = (libraryPeriodType) =>
+ libraryPeriodType === 'YEARLY' || libraryPeriodType.startsWith('FY')
+
+/* Every period of a type in one year of the calendar (yearly and financial
+ * types: the one starting that year), built once */
+const getPeriodsOfYear = memoize(
+ (libraryPeriodType, year, calendar) => {
+ try {
+ return generateFixedPeriods({
+ year,
+ periodType: libraryPeriodType,
+ calendar,
+ locale: 'en',
+ ...(isYearLongType(libraryPeriodType) && { yearsCount: 1 }),
+ })
+ } catch {
+ return []
+ }
+ },
+ { maxSize: 500 }
+)
+
+const readPeriodDates = memoize((periodId, calendar) => {
+ if (isNovemberPeriodId(periodId)) {
+ return isIsoCalendar(calendar) ? getNovemberPeriodDates(periodId) : null
+ }
+
+ // The id names its year: the period is in that year's list
+ const libraryPeriodType =
+ SERVER_PT_TO_MULTI_CALENDAR_PT[getPeriodTypeOfPeriodId(periodId)]
+ const listed =
+ libraryPeriodType &&
+ getPeriodsOfYear(
+ libraryPeriodType,
+ Number(periodId.slice(0, 4)),
+ calendar
+ ).find(({ id }) => id === periodId)
+
+ if (listed) {
+ return { startDate: listed.startDate, endDate: listed.endDate }
+ }
+
+ try {
+ const { startDate, endDate } = createFixedPeriodFromPeriodId({
+ periodId,
+ calendar,
+ })
+
+ return { startDate, endDate }
+ } catch {
+ return null
+ }
+})
+
+// A fixed period's range, or null for an id that can't be read
+export const getPeriodDates = (periodId, calendar = 'gregory') =>
+ readPeriodDates(periodId, calendar)
+
+// Weeks and financial years can start in the year before or end in the year after
+const findPeriodHolding = (libraryPeriodType, date, calendar) => {
+ const year = getYear(date)
+
+ for (const candidateYear of [year, year - 1, year + 1]) {
+ const period = getPeriodsOfYear(
+ libraryPeriodType,
+ candidateYear,
+ calendar
+ ).find(({ startDate, endDate }) => startDate <= date && date <= endDate)
+
+ if (period) {
+ const { id, startDate, endDate } = period
+
+ return { id, startDate, endDate }
+ }
+ }
+
+ return null
+}
+
+// The period of `periodType` that holds `date` ({ id, startDate, endDate }), or null
+export const getFixedPeriodOfTypeByDate = (
+ periodType,
+ date,
+ calendar = 'gregory'
+) => {
+ if (!date) {
+ return null
+ }
+
+ if (isNovemberPeriodType(periodType)) {
+ return isIsoCalendar(calendar)
+ ? getNovemberPeriodByDate(periodType, date)
+ : null
+ }
+
+ const libraryPeriodType = SERVER_PT_TO_MULTI_CALENDAR_PT[periodType]
+
+ return libraryPeriodType
+ ? findPeriodHolding(libraryPeriodType, date, calendar)
+ : null
+}
+
+// The period of the same type just before or just after `period`, or null
+export const getPreviousPeriod = (periodType, period, calendar = 'gregory') =>
+ getFixedPeriodOfTypeByDate(
+ periodType,
+ shiftDate(period.startDate, -1, calendar),
+ calendar
+ )
+
+export const getNextPeriod = (periodType, period, calendar = 'gregory') =>
+ getFixedPeriodOfTypeByDate(
+ periodType,
+ shiftDate(period.endDate, 1, calendar),
+ calendar
+ )
+
+/**
+ * The range from the start of the `periodType` period holding the start of
+ * `range`, to the end of the one holding its end: the whole periods of that
+ * type that cover it. Null when it can't be told.
+ */
+export const getCoveringPeriodRange = (
+ range,
+ periodType,
+ calendar = 'gregory'
+) => {
+ const first = getFixedPeriodOfTypeByDate(
+ periodType,
+ range.startDate,
+ calendar
+ )
+ const last = getFixedPeriodOfTypeByDate(periodType, range.endDate, calendar)
+
+ if (!first || !last) {
+ return null
+ }
+
+ return { startDate: first.startDate, endDate: last.endDate }
+}
+
+/**
+ * Whether a range starts and ends on the edges of `periodType` periods, so
+ * data of that type fits it exactly (a quarter on monthly data, not a month on
+ * weekly data). Null when it can't be told.
+ */
+export const isAlignedWithPeriodType = (
+ range,
+ periodType,
+ calendar = 'gregory'
+) => {
+ const covering = getCoveringPeriodRange(range, periodType, calendar)
+
+ return covering
+ ? covering.startDate === range.startDate &&
+ covering.endDate === range.endDate
+ : null
+}
diff --git a/src/modules/dataItemProfile/periods/periodTypes.js b/src/modules/dataItemProfile/periods/periodTypes.js
new file mode 100644
index 000000000..114fb1c30
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/periodTypes.js
@@ -0,0 +1,157 @@
+import {
+ FINANCIAL_YEAR_START_TO_PERIOD_TYPE,
+ SERVER_PT_TO_MULTI_CALENDAR_PT,
+ WEEKLY_START_TO_PERIOD_TYPE,
+} from '../../../components/PeriodDimension/utils/enabledPeriodTypes.js'
+import { PERIOD_TYPE_REGEX } from '../../../components/PeriodDimension/utils/fixedPeriods.js'
+import { getRelativePeriodsDetails } from '../../../components/PeriodDimension/utils/relativePeriods.js'
+import { PERIOD_TYPE_FREQUENCY_ORDER, PERIOD_TYPES } from '../constants.js'
+
+const PERIOD_TYPE_NAMES = new Set(PERIOD_TYPES)
+
+export const isPeriodType = (value) => PERIOD_TYPE_NAMES.has(value)
+
+export const getFrequencyOrder = (periodType) =>
+ PERIOD_TYPE_FREQUENCY_ORDER[periodType]
+
+// Shortest first, then in the server's order
+export const sortPeriodTypes = (periodTypes) =>
+ [...periodTypes].sort(
+ (a, b) =>
+ getFrequencyOrder(a) - getFrequencyOrder(b) ||
+ PERIOD_TYPES.indexOf(a) - PERIOD_TYPES.indexOf(b)
+ )
+
+/**
+ * Whether analytics adds up values of data sets with `dataPeriodType` into
+ * periods of `queryPeriodType`: it does into the same type and into any
+ * longer type (a higher frequencyOrder), even when the periods don't nest
+ * (Wednesday weeks into BiWeekly, checked by the test tool). A type of the
+ * same length gets nothing (Wednesday weeks asked by Monday week). Null when
+ * either type is unknown.
+ */
+export const canAggregateInto = (dataPeriodType, queryPeriodType) => {
+ if (!isPeriodType(dataPeriodType) || !isPeriodType(queryPeriodType)) {
+ return null
+ }
+
+ return (
+ dataPeriodType === queryPeriodType ||
+ getFrequencyOrder(queryPeriodType) > getFrequencyOrder(dataPeriodType)
+ )
+}
+
+/* VERSION-TOGGLE: remove when 41 is the lowest supported version. Analytics
+ * fails on QuarterlyNov periods in 2.40 ("Can't find resource for bundle …
+ * key format.QuarterlyNov.startDate"), and answers from 2.41. */
+const MIN_MINOR_VERSION_BY_PERIOD_TYPE = { QuarterlyNov: 41 }
+
+// Without a server version, every type counts as supported
+export const isPeriodTypeSupported = (periodType, serverVersion) =>
+ !serverVersion ||
+ serverVersion.major > 2 ||
+ serverVersion.minor >= (MIN_MINOR_VERSION_BY_PERIOD_TYPE[periodType] ?? 0)
+
+const SERVER_PERIOD_TYPE_BY_LIBRARY_TYPE = Object.fromEntries(
+ Object.entries(SERVER_PT_TO_MULTI_CALENDAR_PT).map(
+ ([serverType, libraryType]) => [libraryType, serverType]
+ )
+)
+
+/* The period picker's PERIOD_TYPE_REGEX leaves out the November quarters and
+ * six-months, since it doesn't offer them; analytics answers them */
+const PERIOD_ID_PATTERNS = [
+ ...Object.entries(PERIOD_TYPE_REGEX).map(([libraryType, regex]) => [
+ SERVER_PERIOD_TYPE_BY_LIBRARY_TYPE[libraryType],
+ regex,
+ ]),
+ ['QuarterlyNov', /^(\d{4})NovQ([1-4])$/],
+ ['SixMonthlyNov', /^(\d{4})NovS([12])$/],
+]
+
+export const getPeriodTypeOfPeriodId = (periodId) =>
+ PERIOD_ID_PATTERNS.find(([, regex]) => regex.test(periodId))?.[0] ?? null
+
+let relativePeriodShapes
+
+/* The type (category), offset and duration of a relative period, or
+ * undefined: PeriodDimension builds its table, with names, on each call */
+export const getRelativePeriodShape = (periodId) => {
+ relativePeriodShapes ??= Object.fromEntries(
+ Object.values(getRelativePeriodsDetails()).map(
+ ({ id, type, offset, duration }) => [id, { type, offset, duration }]
+ )
+ )
+
+ return relativePeriodShapes[periodId]
+}
+
+const WEEKLY_PERIOD_TYPES = PERIOD_TYPES.filter((type) =>
+ type.startsWith('Weekly')
+)
+const FINANCIAL_PERIOD_TYPES = PERIOD_TYPES.filter((type) =>
+ type.startsWith('Financial')
+)
+
+// The period type of each relative period category; weeks and financial years depend on a setting
+const PERIOD_TYPE_BY_RELATIVE_CATEGORY = {
+ DAILY: 'Daily',
+ BIWEEKLY: 'BiWeekly',
+ MONTHLY: 'Monthly',
+ BIMONTHLY: 'BiMonthly',
+ QUARTERLY: 'Quarterly',
+ SIXMONTHLY: 'SixMonthly',
+ YEARLY: 'Yearly',
+}
+
+/* Relative weeks and financial years follow the analyticsWeeklyStart and
+ * analyticsFinancialYearStart settings. Without them, every type they could
+ * be is returned. */
+const getRelativePeriodTypes = (category, options) => {
+ if (category === 'WEEKLY') {
+ return options.weeklyPeriodType
+ ? [options.weeklyPeriodType]
+ : WEEKLY_PERIOD_TYPES
+ }
+
+ if (category === 'FINANCIAL') {
+ return options.financialYearPeriodType
+ ? [options.financialYearPeriodType]
+ : FINANCIAL_PERIOD_TYPES
+ }
+
+ const periodType = PERIOD_TYPE_BY_RELATIVE_CATEGORY[category]
+
+ return periodType ? [periodType] : []
+}
+
+/**
+ * The period types a period can be: one for a fixed period or a period type,
+ * several for a relative period whose type depends on a server setting, none
+ * when it isn't recognized.
+ */
+export const getCandidatePeriodTypes = (period, options = {}) => {
+ if (isPeriodType(period)) {
+ return [period]
+ }
+
+ const fixedPeriodType = getPeriodTypeOfPeriodId(period)
+
+ if (fixedPeriodType) {
+ return [fixedPeriodType]
+ }
+
+ const category = getRelativePeriodShape(period)?.type
+
+ return category ? getRelativePeriodTypes(category, options) : []
+}
+
+// The options getCandidatePeriodTypes needs, from the two server settings
+export const getRelativePeriodTypeOptions = ({
+ analyticsWeeklyStart,
+ analyticsFinancialYearStart,
+} = {}) => ({
+ weeklyPeriodType: WEEKLY_START_TO_PERIOD_TYPE[analyticsWeeklyStart],
+ financialYearPeriodType:
+ FINANCIAL_YEAR_START_TO_PERIOD_TYPE[analyticsFinancialYearStart],
+})
diff --git a/src/modules/dataItemProfile/periods/relativePeriodRanges.js b/src/modules/dataItemProfile/periods/relativePeriodRanges.js
new file mode 100644
index 000000000..654c641ee
--- /dev/null
+++ b/src/modules/dataItemProfile/periods/relativePeriodRanges.js
@@ -0,0 +1,114 @@
+import { fromIsoDate, pad } from './calendarDates.js'
+import { memoize } from './memoize.js'
+import {
+ getFixedPeriodOfTypeByDate,
+ getNextPeriod,
+ getPreviousPeriod,
+} from './periodRanges.js'
+import { getRelativePeriodShape, isPeriodType } from './periodTypes.js'
+
+// Today in the user's time zone, as an ISO date
+const getLocalIsoDate = () => {
+ const now = new Date()
+
+ return [
+ now.getFullYear(),
+ pad(now.getMonth() + 1),
+ pad(now.getDate()),
+ ].join('-')
+}
+
+// Far more than the longest relative period (LAST_52_WEEKS, LAST_180_DAYS…)
+const MAX_PERIODS = 400
+
+const stepPeriods = (period, steps, { periodType, calendar }) => {
+ const step = steps < 0 ? getPreviousPeriod : getNextPeriod
+ let current = period
+
+ for (let i = 0; current && i < Math.abs(steps); i++) {
+ current = step(periodType, current, calendar)
+ }
+
+ return current
+}
+
+// Weeks belong to the year that holds their Thursday: 4 January and 28 December always do
+const getYearEdges = (periodType, year) =>
+ periodType.startsWith('Weekly')
+ ? [`${pad(year, 4)}-01-04`, `${pad(year, 4)}-12-28`]
+ : [`${pad(year, 4)}-01-01`, `${pad(year, 4)}-12-31`]
+
+/* The first and last fixed periods of a relative period: from the period
+ * holding `date`, `offset` periods away for the last one, `duration` periods
+ * long. The "this year" ones (MONTHS_THIS_YEAR…) cover every period of the
+ * year. */
+const getEdgePeriods = (periodId, date, { periodType, calendar }) => {
+ const { offset, duration } = getRelativePeriodShape(periodId)
+
+ if (periodId.endsWith('_THIS_YEAR')) {
+ return getYearEdges(periodType, Number(date.slice(0, 4))).map((edge) =>
+ getFixedPeriodOfTypeByDate(periodType, edge, calendar)
+ )
+ }
+
+ const current = getFixedPeriodOfTypeByDate(periodType, date, calendar)
+ const context = { periodType, calendar }
+ const last = current && stepPeriods(current, offset, context)
+ const first = last && stepPeriods(last, -(duration - 1), context)
+
+ return [first, last]
+}
+
+const resolveRelativePeriod = memoize(
+ (periodId, periodType, { calendar, date }) => {
+ const [first, last] = getEdgePeriods(periodId, date, {
+ periodType,
+ calendar,
+ })
+
+ if (!first || !last) {
+ return null
+ }
+
+ const periods = [first]
+
+ while (periods.at(-1).id !== last.id && periods.length < MAX_PERIODS) {
+ const next = getNextPeriod(periodType, periods.at(-1), calendar)
+
+ if (!next) {
+ return null
+ }
+
+ periods.push(next)
+ }
+
+ return periods
+ },
+ {
+ getKey: (periodId, periodType, { calendar, date }) =>
+ [periodId, periodType, calendar, date].join('|'),
+ }
+)
+
+/**
+ * The fixed periods of `periodType` a relative period covers, as analytics
+ * resolves it on `relativePeriodDate` (an ISO date, today by default), in
+ * date order; null when it can't be told.
+ */
+export const getRelativePeriodFixedPeriods = (
+ periodId,
+ periodType,
+ { calendar = 'gregory', relativePeriodDate } = {}
+) => {
+ const date = fromIsoDate(relativePeriodDate ?? getLocalIsoDate(), calendar)
+
+ if (
+ !getRelativePeriodShape(periodId) ||
+ !isPeriodType(periodType) ||
+ !date
+ ) {
+ return null
+ }
+
+ return resolveRelativePeriod(periodId, periodType, { calendar, date })
+}
diff --git a/src/modules/dataItemProfile/profile/__tests__/assignedOrgUnitLevels.spec.js b/src/modules/dataItemProfile/profile/__tests__/assignedOrgUnitLevels.spec.js
new file mode 100644
index 000000000..7fb8f2f35
--- /dev/null
+++ b/src/modules/dataItemProfile/profile/__tests__/assignedOrgUnitLevels.spec.js
@@ -0,0 +1,87 @@
+import {
+ getAssignedOrgUnitLevels,
+ addAssignedOrgUnitLevels,
+} from '../assignedOrgUnitLevels.js'
+
+const source = (id, assignedOrgUnitCounts) => ({
+ dataSet: id && { id, periodType: 'Monthly' },
+ elements: [],
+ reportingRate: false,
+ ...(assignedOrgUnitCounts && { assignedOrgUnitCounts }),
+})
+
+describe('getAssignedOrgUnitLevels', () => {
+ it('gives the levels assigned, deepest first, and the deepest', () => {
+ expect(
+ getAssignedOrgUnitLevels([source('formA', { 1: 1, 2: 0, 4: 1159 })])
+ ).toEqual({ levels: [4, 1], deepestLevel: 4, hasSeveral: false })
+ })
+
+ it('has several when data sets are assigned at different deepest levels', () => {
+ expect(
+ getAssignedOrgUnitLevels([
+ source('formA', { 4: 10 }),
+ source('formB', { 2: 3 }),
+ ])
+ ).toEqual({ levels: [4, 2], deepestLevel: 4, hasSeveral: true })
+ })
+
+ it('has no level without assignments', () => {
+ expect(
+ getAssignedOrgUnitLevels([source('formA', {}), source(null)])
+ ).toEqual({
+ levels: [],
+ deepestLevel: null,
+ hasSeveral: false,
+ })
+ })
+})
+
+describe('addAssignedOrgUnitLevels', () => {
+ it('gives each source its counts, and the profile its assigned org unit levels', () => {
+ const profile = {
+ sources: [source('formA'), source(null)],
+ unknown: false,
+ reasons: [],
+ assignedPeriodTypes: { types: ['Monthly'] },
+ }
+
+ expect(addAssignedOrgUnitLevels(profile, { formA: { 4: 2 } })).toEqual({
+ ...profile,
+ sources: [source('formA', { 4: 2 }), source(null)],
+ assignedOrgUnitLevels: {
+ levels: [4],
+ deepestLevel: 4,
+ hasSeveral: false,
+ },
+ })
+ expect(
+ addAssignedOrgUnitLevels(profile, {}).sources[0]
+ .assignedOrgUnitCounts
+ ).toEqual({})
+ })
+
+ it('gives no levels to a program indicator placed anywhere', () => {
+ const placedAnywhere = {
+ dataSet: null,
+ program: { id: 'programAAA' },
+ orgUnitField: 'REGISTRATION',
+ elements: [],
+ reportingRate: false,
+ }
+
+ expect(
+ addAssignedOrgUnitLevels(
+ { sources: [placedAnywhere] },
+ { programAAA: { 4: 2 } }
+ )
+ ).toEqual({
+ sources: [placedAnywhere],
+ assignedOrgUnitLevels: {
+ levels: [],
+ deepestLevel: null,
+ hasSeveral: false,
+ },
+ })
+ })
+})
diff --git a/src/modules/dataItemProfile/profile/assignedOrgUnitLevels.js b/src/modules/dataItemProfile/profile/assignedOrgUnitLevels.js
new file mode 100644
index 000000000..1ee8d558f
--- /dev/null
+++ b/src/modules/dataItemProfile/profile/assignedOrgUnitLevels.js
@@ -0,0 +1,56 @@
+import { canBeAtAnyOrgUnit, getSourceId } from '../sources.js'
+
+// The levels with at least one org unit, from counts by level
+export const getLevelsWithOrgUnits = (countsByLevel = {}) =>
+ Object.keys(countsByLevel)
+ .map(Number)
+ .filter((level) => countsByLevel[level] > 0)
+
+/**
+ * The org unit levels an item's data sets and programs are assigned at,
+ * deepest first, from each source's `assignedOrgUnitCounts`; the deepest
+ * (`deepestLevel`); and whether sources have different deepest levels
+ * (`hasSeveral`).
+ */
+export const getAssignedOrgUnitLevels = (sources) => {
+ const levelsBySource = sources
+ .filter(({ assignedOrgUnitCounts }) => assignedOrgUnitCounts)
+ .map(({ assignedOrgUnitCounts }) =>
+ getLevelsWithOrgUnits(assignedOrgUnitCounts)
+ )
+ const levels = [...new Set(levelsBySource.flat())].sort((a, b) => b - a)
+ const deepestOfEach = levelsBySource
+ .filter((sourceLevels) => sourceLevels.length)
+ .map((sourceLevels) => Math.max(...sourceLevels))
+
+ return {
+ levels,
+ deepestLevel: levels[0] ?? null,
+ hasSeveral: new Set(deepestOfEach).size > 1,
+ }
+}
+
+/**
+ * The profile with its assigned org unit levels, from the number of org units
+ * each data set or program is assigned to per level (`{ [sourceId]:
+ * { [level]: count } }`, as fetchAssignedOrgUnitCounts gives them): each
+ * source gains its `assignedOrgUnitCounts`, except program indicators whose
+ * values can be at any org unit.
+ */
+export const addAssignedOrgUnitLevels = (profile, assignedOrgUnitCounts) => {
+ const sources = profile.sources.map((source) =>
+ getSourceId(source) && !canBeAtAnyOrgUnit(source)
+ ? {
+ ...source,
+ assignedOrgUnitCounts:
+ assignedOrgUnitCounts[getSourceId(source)] ?? {},
+ }
+ : source
+ )
+
+ return {
+ ...profile,
+ sources,
+ assignedOrgUnitLevels: getAssignedOrgUnitLevels(sources),
+ }
+}
diff --git a/src/modules/dataItemProfile/profile/assignedPeriodTypes.js b/src/modules/dataItemProfile/profile/assignedPeriodTypes.js
new file mode 100644
index 000000000..cdbcb8850
--- /dev/null
+++ b/src/modules/dataItemProfile/profile/assignedPeriodTypes.js
@@ -0,0 +1,39 @@
+import { PERIOD_TYPES } from '../constants.js'
+import {
+ canAggregateInto,
+ isPeriodType,
+ sortPeriodTypes,
+} from '../periods/periodTypes.js'
+
+// The source's period type, or null for a program, an element in no data set, or an unknown type
+export const getSourcePeriodType = ({ dataSet }) =>
+ isPeriodType(dataSet?.periodType) ? dataSet.periodType : null
+
+/* The shortest query type that every type adds up into: the longest of them
+ * when they nest, the next type up when two have the same length (Monday and
+ * Wednesday weeks: BiWeekly) */
+const getShortestDirectType = (periodTypes) =>
+ sortPeriodTypes(PERIOD_TYPES).find((queryPeriodType) =>
+ periodTypes.every((periodType) =>
+ canAggregateInto(periodType, queryPeriodType)
+ )
+ ) ?? null
+
+/**
+ * The period types of the data sets an item is assigned to, shortest first;
+ * `shortestDirectType`, the shortest type at which every value adds up
+ * directly (shorter ones get repeated or earlier values, or none, see
+ * getDataItemProfilePeriodCompatibility), or null when nothing is assigned by
+ * period (event data); and whether there are several types (`hasSeveral`).
+ */
+export const getAssignedPeriodTypes = (sources) => {
+ const types = sortPeriodTypes([
+ ...new Set(sources.map(getSourcePeriodType).filter(Boolean)),
+ ])
+
+ return {
+ types,
+ shortestDirectType: types.length ? getShortestDirectType(types) : null,
+ hasSeveral: types.length > 1,
+ }
+}
diff --git a/src/modules/dataItemProfile/profile/collectSources.js b/src/modules/dataItemProfile/profile/collectSources.js
new file mode 100644
index 000000000..7169293b2
--- /dev/null
+++ b/src/modules/dataItemProfile/profile/collectSources.js
@@ -0,0 +1,318 @@
+import { REPORTING_RATE } from '../../dataSets.js'
+import {
+ DIMENSION_TYPE_DATA_ELEMENT,
+ DIMENSION_TYPE_DATA_ELEMENT_OPERAND,
+ DIMENSION_TYPE_EVENT_DATA_ITEM,
+ DIMENSION_TYPE_EXPRESSION_DIMENSION_ITEM,
+ DIMENSION_TYPE_INDICATOR,
+ DIMENSION_TYPE_PROGRAM_ATTRIBUTE,
+ DIMENSION_TYPE_PROGRAM_ATTRIBUTE_OPTION,
+ DIMENSION_TYPE_PROGRAM_DATA_ELEMENT,
+ DIMENSION_TYPE_PROGRAM_DATA_ELEMENT_OPTION,
+ DIMENSION_TYPE_PROGRAM_INDICATOR,
+} from '../../dataTypes.js'
+import {
+ NOT_AGGREGATABLE_AGGREGATION_TYPES,
+ SKIP_IF_ALL_VALUES_MISSING,
+ SKIP_IF_ANY_VALUE_MISSING,
+ PERIOD_AGGREGATION_AVERAGE,
+ PERIOD_AGGREGATION_FIRST,
+ PERIOD_AGGREGATION_LAST,
+ OPERAND_TYPE_UNKNOWN,
+ PROFILE_REASON_MISSING_METADATA,
+ PROFILE_REASON_MISSING_PROGRAM,
+ PROFILE_REASON_NO_DATA_SET,
+ PROFILE_REASON_NOT_AGGREGATABLE,
+ PROFILE_REASON_UNKNOWN_OPERAND,
+ PROFILE_REASON_UNSUPPORTED_ITEM_TYPE,
+} from '../constants.js'
+import {
+ getCategoryOptionComboId,
+ parseExpressionOperands,
+} from '../expressionOperands.js'
+import {
+ getElementOperandKey,
+ getProgramOperandKey,
+ getReportingRateOperandKey,
+} from '../sources.js'
+import {
+ addElementToSource,
+ addReason,
+ checkDataSetPeriodType,
+ createCollector,
+ getDataSetSource,
+ getProgramSource,
+ getUnassignedElementSource,
+} from './sourceCollector.js'
+
+/* How each aggregation type aggregates over time, when it differs from the
+ * type itself (dhis2-core AnalyticsAggregationType.fromAggregationType) */
+const PERIOD_AGGREGATION_BY_AGGREGATION_TYPE = {
+ AVERAGE_SUM_ORG_UNIT: PERIOD_AGGREGATION_AVERAGE,
+ LAST_AVERAGE_ORG_UNIT: PERIOD_AGGREGATION_LAST,
+ LAST_LAST_ORG_UNIT: PERIOD_AGGREGATION_LAST,
+ LAST_IN_PERIOD_AVERAGE_ORG_UNIT: 'LAST_IN_PERIOD',
+ FIRST_AVERAGE_ORG_UNIT: PERIOD_AGGREGATION_FIRST,
+ FIRST_FIRST_ORG_UNIT: PERIOD_AGGREGATION_FIRST,
+ MAX_SUM_ORG_UNIT: 'MAX',
+ MIN_SUM_ORG_UNIT: 'MIN',
+}
+
+export const getPeriodAggregationType = (aggregationType) =>
+ PERIOD_AGGREGATION_BY_AGGREGATION_TYPE[aggregationType] ?? aggregationType
+
+/* Each add* function adds the sources of an operand and gives its part of
+ * the item's expression: `{ operand: key }` for an operand (sources.js keys),
+ * `{ missingValueStrategy, parts }` for an expression, null when its metadata
+ * is missing. */
+
+const toPart = (key) => ({ operand: key })
+
+/* A disaggregation (de.coc) is collected only by the data sets whose
+ * category combo holds its option combo: others give the element another
+ * combo. When either combo isn't known, every data set counts. */
+const getCollectingDataSets = (dataSets, { operand, metadata }) => {
+ const optionComboId = getCategoryOptionComboId(operand)
+ const categoryComboId =
+ optionComboId &&
+ metadata.categoryOptionCombos?.[optionComboId]?.categoryComboId
+
+ return categoryComboId
+ ? dataSets.filter(
+ (dataSet) =>
+ !dataSet.categoryComboId ||
+ dataSet.categoryComboId === categoryComboId
+ )
+ : dataSets
+}
+
+const addDataElement = (
+ collector,
+ metadata,
+ { id, operand, aggregationType: aggregationTypeOverride }
+) => {
+ const dataElement = metadata.dataElements?.[id]
+
+ if (!dataElement) {
+ addReason(collector, { code: PROFILE_REASON_MISSING_METADATA, id })
+ return null
+ }
+
+ const aggregationType =
+ aggregationTypeOverride ?? dataElement.aggregationType
+ const dataSets = getCollectingDataSets(dataElement.dataSets ?? [], {
+ operand,
+ metadata,
+ })
+ /* `operand`: the disaggregation analytics is asked for (de.coc), if any.
+ * `aggregationLevels`: the org unit levels values from lower levels stop at */
+ const element = {
+ id,
+ ...(operand && { operand }),
+ aggregationType,
+ periodAggregationType: getPeriodAggregationType(aggregationType),
+ ...(dataElement.aggregationLevels?.length && {
+ aggregationLevels: dataElement.aggregationLevels,
+ }),
+ }
+
+ if (NOT_AGGREGATABLE_AGGREGATION_TYPES.has(aggregationType)) {
+ addReason(collector, { code: PROFILE_REASON_NOT_AGGREGATABLE, id })
+ }
+
+ if (!dataSets.length) {
+ addReason(collector, { code: PROFILE_REASON_NO_DATA_SET, id })
+ addElementToSource(getUnassignedElementSource(collector, id), element)
+ }
+
+ dataSets.forEach((dataSet) => {
+ checkDataSetPeriodType(collector, id, dataSet.periodType)
+ addElementToSource(getDataSetSource(collector, dataSet), element)
+ })
+
+ return toPart(getElementOperandKey(element))
+}
+
+const addReportingRate = (collector, metadata, dataSetId) => {
+ const periodType = metadata.dataSets?.[dataSetId]?.periodType
+
+ if (!periodType) {
+ addReason(collector, {
+ code: PROFILE_REASON_MISSING_METADATA,
+ id: dataSetId,
+ })
+ return null
+ }
+
+ checkDataSetPeriodType(collector, dataSetId, periodType)
+ getDataSetSource(collector, {
+ id: dataSetId,
+ periodType,
+ }).reportingRate = true
+
+ return toPart(getReportingRateOperandKey(dataSetId))
+}
+
+const toProgramPart = (source) =>
+ source ? toPart(getProgramOperandKey(source)) : null
+
+const addProgramIndicator = (collector, metadata, id) => {
+ const programIndicator = metadata.programIndicators?.[id]
+
+ if (!programIndicator?.program) {
+ addReason(collector, { code: PROFILE_REASON_MISSING_METADATA, id })
+ return null
+ }
+
+ return toProgramPart(
+ getProgramSource(collector, metadata, {
+ id: programIndicator.program,
+ orgUnitField: programIndicator.orgUnitField,
+ missingPeriodBoundaries:
+ programIndicator.hasPeriodBoundaries === false,
+ })
+ )
+}
+
+// An event or tracker item named by its program: program.element, program.attribute…
+const addProgramItem = (collector, metadata, id) => {
+ if (!id.includes('.')) {
+ addReason(collector, { code: PROFILE_REASON_MISSING_PROGRAM, id })
+ return null
+ }
+
+ return toProgramPart(
+ getProgramSource(collector, metadata, { id: id.split('.')[0] })
+ )
+}
+
+const addOperand = (collector, metadata, operand) => {
+ switch (operand.type) {
+ case DIMENSION_TYPE_DATA_ELEMENT:
+ return addDataElement(collector, metadata, operand)
+ case REPORTING_RATE:
+ return addReportingRate(collector, metadata, operand.id)
+ case DIMENSION_TYPE_INDICATOR:
+ return addIndicator(collector, metadata, operand.id)
+ case DIMENSION_TYPE_PROGRAM_INDICATOR:
+ return addProgramIndicator(collector, metadata, operand.id)
+ case DIMENSION_TYPE_PROGRAM_DATA_ELEMENT:
+ case DIMENSION_TYPE_PROGRAM_ATTRIBUTE:
+ return addProgramItem(collector, metadata, operand.id)
+ case OPERAND_TYPE_UNKNOWN:
+ addReason(collector, {
+ code: PROFILE_REASON_UNKNOWN_OPERAND,
+ token: operand.token,
+ })
+ return null
+ default:
+ // Constants, org unit groups and [days] have no source, and never miss
+ return null
+ }
+}
+
+const addExpression = (
+ collector,
+ metadata,
+ { expression, missingValueStrategy }
+) => ({
+ missingValueStrategy,
+ parts: parseExpressionOperands(expression)
+ .map((operand) => addOperand(collector, metadata, operand))
+ .filter(Boolean),
+})
+
+// Each side skips only when all its values are missing; the indicator needs both
+const addIndicator = (collector, metadata, id) => {
+ const indicator = metadata.indicators?.[id]
+
+ if (!indicator) {
+ addReason(collector, { code: PROFILE_REASON_MISSING_METADATA, id })
+ return null
+ }
+
+ // Nested indicators (N{}) can refer to each other, which analytics refuses
+ if (collector.indicatorsInProgress.has(id)) {
+ return null
+ }
+
+ collector.indicatorsInProgress.add(id)
+
+ const sides = [indicator.numerator, indicator.denominator].map((side) =>
+ addExpression(collector, metadata, {
+ expression: side,
+ missingValueStrategy: SKIP_IF_ALL_VALUES_MISSING,
+ })
+ )
+
+ collector.indicatorsInProgress.delete(id)
+
+ return { missingValueStrategy: SKIP_IF_ANY_VALUE_MISSING, parts: sides }
+}
+
+/* Analytics evaluates an expression dimension item with
+ * SKIP_IF_ALL_VALUES_MISSING, whatever strategy it is saved with: a missing
+ * operand counts as 0, and no value comes back only when all are missing,
+ * even with NEVER_SKIP (checked by the test tool on 2.40 to 2.44) */
+const addExpressionDimensionItem = (collector, metadata, id) => {
+ const expression = metadata.expressionDimensionItems?.[id]?.expression
+
+ if (expression === undefined) {
+ addReason(collector, { code: PROFILE_REASON_MISSING_METADATA, id })
+ return null
+ }
+
+ return addExpression(collector, metadata, {
+ expression,
+ missingValueStrategy: SKIP_IF_ALL_VALUES_MISSING,
+ })
+}
+
+const addItem = (collector, metadata, { id, dimensionItemType }) => {
+ switch (dimensionItemType) {
+ case DIMENSION_TYPE_DATA_ELEMENT:
+ case DIMENSION_TYPE_DATA_ELEMENT_OPERAND:
+ return addDataElement(collector, metadata, {
+ id: id.split('.')[0],
+ ...(id.includes('.') && { operand: id }),
+ })
+ case REPORTING_RATE:
+ return addReportingRate(collector, metadata, id.split('.')[0])
+ case DIMENSION_TYPE_INDICATOR:
+ return addIndicator(collector, metadata, id)
+ case DIMENSION_TYPE_EXPRESSION_DIMENSION_ITEM:
+ return addExpressionDimensionItem(collector, metadata, id)
+ case DIMENSION_TYPE_PROGRAM_INDICATOR:
+ return addProgramIndicator(collector, metadata, id)
+ case DIMENSION_TYPE_PROGRAM_DATA_ELEMENT:
+ case DIMENSION_TYPE_PROGRAM_DATA_ELEMENT_OPTION:
+ case DIMENSION_TYPE_PROGRAM_ATTRIBUTE:
+ case DIMENSION_TYPE_PROGRAM_ATTRIBUTE_OPTION:
+ case DIMENSION_TYPE_EVENT_DATA_ITEM:
+ return addProgramItem(collector, metadata, id)
+ default:
+ addReason(collector, {
+ code: PROFILE_REASON_UNSUPPORTED_ITEM_TYPE,
+ id,
+ dimensionItemType,
+ })
+ return null
+ }
+}
+
+/**
+ * The sources of a data item ({ id, dimensionItemType }), from its metadata
+ * (fetchDataItemProfileMetadata), with the reasons the profile can't be told
+ * or should note, and for an indicator or expression dimension item its
+ * `expression`: how its operands combine.
+ */
+export const collectSources = (item, metadata) => {
+ const collector = createCollector()
+ const part = addItem(collector, metadata, item)
+
+ return {
+ sources: [...collector.sources.values()],
+ reasons: collector.reasons,
+ ...(part?.parts && { expression: part }),
+ }
+}
diff --git a/src/modules/dataItemProfile/profile/sourceCollector.js b/src/modules/dataItemProfile/profile/sourceCollector.js
new file mode 100644
index 000000000..7ead7f1f6
--- /dev/null
+++ b/src/modules/dataItemProfile/profile/sourceCollector.js
@@ -0,0 +1,96 @@
+import {
+ PROFILE_REASON_MISSING_METADATA,
+ PROFILE_REASON_UNKNOWN_PERIOD_TYPE,
+} from '../constants.js'
+import { isPeriodType } from '../periods/periodTypes.js'
+import { usesProgramOrgUnits } from '../sources.js'
+
+/* Sources, by key: one per data set; one per program, and per way its
+ * indicators place values; one per data element in no data set */
+
+export const createCollector = () => ({
+ sources: new Map(),
+ reasons: [],
+ // The indicators being read, against indicators that refer to each other
+ indicatorsInProgress: new Set(),
+})
+
+export const addReason = (collector, reason) => collector.reasons.push(reason)
+
+const getSource = (collector, key, createSource) => {
+ if (!collector.sources.has(key)) {
+ collector.sources.set(key, createSource())
+ }
+
+ return collector.sources.get(key)
+}
+
+export const getDataSetSource = (collector, { id, periodType }) =>
+ getSource(collector, `dataSet:${id}`, () => ({
+ dataSet: { id, periodType },
+ elements: [],
+ reportingRate: false,
+ }))
+
+export const getUnassignedElementSource = (collector, elementId) =>
+ getSource(collector, `element:${elementId}`, () => ({
+ dataSet: null,
+ elements: [],
+ reportingRate: false,
+ }))
+
+/* A program is a source of its own: events and enrollments are placed by
+ * their own dates, so it has no period type, and by the org units it's
+ * assigned to. A program indicator that places values elsewhere, or has no
+ * period boundaries, is a source apart. */
+export const getProgramSource = (
+ collector,
+ metadata,
+ { id, orgUnitField, missingPeriodBoundaries = false }
+) => {
+ if (!metadata.programs?.[id]) {
+ addReason(collector, { code: PROFILE_REASON_MISSING_METADATA, id })
+ return null
+ }
+
+ const atAnyOrgUnit = !usesProgramOrgUnits(orgUnitField)
+ const key = [
+ `program:${id}`,
+ atAnyOrgUnit && orgUnitField,
+ missingPeriodBoundaries && 'missingPeriodBoundaries',
+ ]
+ .filter(Boolean)
+ .join(':')
+
+ return getSource(collector, key, () => ({
+ dataSet: null,
+ program: { id },
+ ...(atAnyOrgUnit && { orgUnitField }),
+ ...(missingPeriodBoundaries && { missingPeriodBoundaries }),
+ elements: [],
+ reportingRate: false,
+ }))
+}
+
+export const addElementToSource = (source, element) => {
+ const isListed = source.elements.some(
+ ({ id, operand, aggregationType }) =>
+ id === element.id &&
+ operand === element.operand &&
+ aggregationType === element.aggregationType
+ )
+
+ if (!isListed) {
+ source.elements.push(element)
+ }
+}
+
+export const checkDataSetPeriodType = (collector, id, periodType) => {
+ if (!isPeriodType(periodType)) {
+ addReason(collector, {
+ code: PROFILE_REASON_UNKNOWN_PERIOD_TYPE,
+ id,
+ periodType,
+ })
+ }
+}
diff --git a/src/modules/dataItemProfile/sources.js b/src/modules/dataItemProfile/sources.js
new file mode 100644
index 000000000..b0dab7c5a
--- /dev/null
+++ b/src/modules/dataItemProfile/sources.js
@@ -0,0 +1,83 @@
+import { PROGRAM_ORG_UNIT_FIELDS } from './constants.js'
+
+/* A profile source is where an item's data comes from:
+ * - a data set: { dataSet: { id, periodType }, elements, reportingRate };
+ * - a program: { dataSet: null, program: { id }, elements: [], reportingRate: false },
+ * with `orgUnitField` when its values can be at any org unit, and
+ * `missingPeriodBoundaries` for a program indicator without them;
+ * - a data element in no data set: { dataSet: null, elements, reportingRate: false },
+ * assigned nowhere. */
+
+export const isProgramSource = ({ program }) => Boolean(program)
+
+// The id of the data set or program behind a source, or null
+export const getSourceId = ({ dataSet, program }) =>
+ dataSet?.id ?? program?.id ?? null
+
+// The org unit field that lists the org units a source is assigned to
+export const getAssignmentField = (source) =>
+ isProgramSource(source) ? 'programs' : 'dataSets'
+
+// Whether a program indicator's orgUnitField places values where its program is assigned
+export const usesProgramOrgUnits = (orgUnitField) =>
+ !orgUnitField || PROGRAM_ORG_UNIT_FIELDS.has(orgUnitField)
+
+// Whether a source's values can be at any org unit, wherever it is assigned
+export const canBeAtAnyOrgUnit = ({ orgUnitField }) =>
+ !usesProgramOrgUnits(orgUnitField)
+
+/* Operand keys: how a profile's expression (profile.expression) names the
+ * operands getItemOperands gives */
+export const getElementOperandKey = ({ id, aggregationType }) =>
+ `element:${id}:${aggregationType}`
+
+export const getReportingRateOperandKey = (dataSetId) =>
+ `reportingRate:${dataSetId}`
+
+export const getProgramOperandKey = ({
+ program,
+ orgUnitField,
+ missingPeriodBoundaries,
+}) =>
+ [
+ 'program',
+ program.id,
+ orgUnitField ?? '',
+ missingPeriodBoundaries ? 'missingPeriodBoundaries' : '',
+ ].join(':')
+
+/**
+ * The operands an item's value is computed from, each with its `key`: each
+ * data element (by id and aggregation type) with the sources it is in, each
+ * reporting rate, and each program. One element adds up over its sources;
+ * profile.expression says how the operands combine.
+ */
+export const getItemOperands = (profile) => {
+ const elements = new Map()
+
+ profile.sources.forEach((source) =>
+ source.elements.forEach((element) => {
+ const key = getElementOperandKey(element)
+ const operand = elements.get(key) ?? { key, element, sources: [] }
+
+ operand.sources.push(source)
+ elements.set(key, operand)
+ })
+ )
+
+ return [
+ ...elements.values(),
+ ...profile.sources
+ .filter(({ reportingRate }) => reportingRate)
+ .map((source) => ({
+ key: getReportingRateOperandKey(source.dataSet.id),
+ reportingRate: true,
+ sources: [source],
+ })),
+ ...profile.sources.filter(isProgramSource).map((source) => ({
+ key: getProgramOperandKey(source),
+ program: true,
+ sources: [source],
+ })),
+ ]
+}
diff --git a/yarn.lock b/yarn.lock
index 779e1541b..bf90a71b3 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2338,7 +2338,7 @@
"@js-temporal/polyfill" "0.4.3"
classnames "^2.3.2"
-"@dhis2/multi-calendar-dates@^1.2.2":
+"@dhis2/multi-calendar-dates@^1.3.2":
version "1.3.2"
resolved "https://registry.yarnpkg.com/@dhis2/multi-calendar-dates/-/multi-calendar-dates-1.3.2.tgz#34e5896f7fdfb761a2ee6035d848cba00446cde5"
integrity sha512-H37EptumkqZeHUpbR4wl3y2NZjeipxUNUI2VaHX28z2fbVD7O9H+k1InSskeP5nNWzTLMdPAM4lt/zQP8oRbrg==