[42] Convert to single-version branch by eperedo · Pull Request #184 · EyeSeeTea/d2-api

eperedo · 2026-03-08T23:33:45Z

📌 References

Issue: Closes https://app.clickup.com/t/869beeny2 #869beeny2

📝 Implementation

In v42 in order to filter tracker entities by org. units you need to pass the params orgUnits and orgUnitMode.

https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-242/tracker.html#tracked-entity-collections

Parameters orgUnit and ouMode are removed and no longer supported in v42.

📹 Screenshots/Screen capture

🔥 Notes to the tester

can you help me with a beta version please?

bundlemon · 2026-03-08T23:34:37Z

BundleMon

No change in files bundle size

Unchanged groups (1)

Status	Path	Size	Limits
✅	Build Folder _./*/	266.2KB	+20%

Final result: ✅

View report in BundleMon website ➡️

Current branch size history | Target branch size history

tokland

In-line:

tokland · 2026-03-09T08:55:02Z

src/api/trackerTrackedEntities.ts

    attribute: CommaDelimitedListOfUid;
    filter: CommaDelimitedListOfAttributeFilter;
-    orgUnit: SemiColonDelimitedListOfUid;
-    ouMode: "SELECTED" | "CHILDREN" | "DESCENDANTS" | "ACCESSIBLE" | "CAPTURE" | "ALL";


From the description of the PR:

Parameters orgUnit and orgUnitMode are removed and no longer supported in v42.

orgUnitMode should read ouMode in the description, right?

tokland · 2026-03-09T09:09:36Z

src/api/trackerTrackedEntities.ts

+    // https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-242/tracker.html#tracked-entity-collections
+    // This is a breaking change, but upgrade should be as easy as find and replace
+    orgUnits: CommaDelimitedListOfUid;
+    orgUnitMode: "SELECTED" | "CHILDREN" | "DESCENDANTS" | "ACCESSIBLE" | "CAPTURE" | "ALL";


This would be a breaking change. With this change, we would no longer be able to use d2-api with DHIS2 versions earlier than 2.42 (or we would, but it will silently not work as expected)

We already have infrastructure to support different DHIS2 versions within the same codebase (src/VERSION/index.ts → D2Api extends D2ApiVersioned). Currently, this is only used to support different schemas (D2ModelSchemas), which is essential. But we have not used the infrastructure for anything else so far.

In this case, supporting multiple versions would require creating split implementations of tracker.ts, trackerTrackedEntities.ts, and trackerEnrollments.ts, ideally with some parent abstraction to avoid duplication.

This is something that has been on my mind for a while. Let me check with @adrianq whether we should go down this path, or instead change course and move to versioned d2-api releases.

My bad I thought these parameters were added from v40 to v42, but they are valid only in v41 and v42, but not 40.

Also, are we going to validate the required parameters? They are different per version:

v40

https://play.im.dhis2.org/stable-2-40-11/api/tracker/trackedEntities -> "Either Program or Tracked entity type should be specified"
https://play.im.dhis2.org/stable-2-40-11/api/enrollments.json -> At least one organisation unit must be specified"
https://play.im.dhis2.org/stable-2-40-11/api/events.json -> no parameters required

v41

https://play.im.dhis2.org/stable-2-41-7/api/tracker/trackedEntities -> Either program, trackedEntityType or trackedEntities should be specified"
https://play.im.dhis2.org/stable-2-41-7/api/tracker/enrollments -> no parameters required
https://play.im.dhis2.org/stable-2-41-7/api/tracker/events -> no parameters required

v42

https://play.im.dhis2.org/stable-2-42-4/api/tracker/trackedEntities -> Either program, trackedEntityType or trackedEntities should be specified"
https://play.im.dhis2.org/stable-2-41-7/api/tracker/enrollments -> no parameters required
https://play.im.dhis2.org/stable-2-41-7/api/tracker/events -> no parameters required

No problem, it's a good opportunity to re-think the approach to versioned d2-api, we'll get back to that.

About the filters: for the time being, let's keep it simple and make the type require only the props required by all versions. But we'll also get back to that after the decision.

tokland · 2026-03-09T09:11:15Z

src/api/trackerTrackedEntities.ts

+    // removing orgUnit and ouMode because they are being deprecated in v42
+    // https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-242/tracker.html#tracked-entity-collections
+    // This is a breaking change, but upgrade should be as easy as find and replace
+    orgUnits: CommaDelimitedListOfUid;


From the docs, I extracted this (is it correct?):

events: orgUnit, orgUnitMode

enrollments: orgUnits, orgUnitMode

trackedEntities: orgUnits, orgUnitMode

So probably it's a good time to do the same for the enrollments endpoint, right?

tokland · 2026-03-10T13:55:09Z

@eperedo So we have decided to take way 2: 1 branch per version in github + npm @eyeseetea/d2-api@DHISVERSION.x.y per version.

On each branch:

keep only the schemas for that branch
review hacks and workaround (known: "response" wrapper, "instances" prop for tracker) and keep what we actually need for that particular version.
Implement this feature, it will serve as an example.
README: Add a note for developers on how to support multiple versions (that will be useful for metadata-sync, user-extended-app, ...)

…ance implementations

tokland

In-line:

tokland · 2026-03-19T11:23:07Z

README.md


 ```ts
-import { D2Api } from "d2-api/2.36";
+import { D2Api } from "d2-api/2.42";


We had an old reference here: d2-api -> @eyeseetea/d2-api

Also, what do you think if we allow the user to write import ... from " @eyeseetea/d2-api";, now that the branches are single-version? It's ok to keep the folder in the source, but some kind of re-export.

tokland · 2026-03-19T11:29:47Z

README.md

+            pageCount: 10;
+            total: 500;
+        },
+        trackedEntities: []


Minor, but just to veer in the right direction: as DHIS2 has a very stable demo database (Sierra Leone), I think it's nice to use real IDs and such in the examples. Here we could put a tracker program ID + pageSize=2 and have a real response shown.

tokland · 2026-03-20T12:06:31Z

package.json

    "name": "@eyeseetea/d2-api",
    "description": "Typed wrapper over DHIS2 API",
-    "version": "1.21.0-beta.3",
+    "version": "1.21.0-dhis2.42",


I've been thinking about the version schema. The problem with 1.21.0-dhis2.42 is that dhis2.42 is treated as a "prerelease" identifier, which semantically isn't what we have. Also, you can no longer use ^1.21.0 to specify a minimum API version.

An alternative would be to use the DHIS2 version as the major: 42.21.0.

I've seen this done in some npm packages. Maybe you've already discussed it with the PM.

@tokland @eperedo I am realeasing a new version as beta.5. This is just for Eduardo to test...

I think using 42.x.x is a good idea. The only downside is that it could be weird the big jump from 1.x.x to 42, but not really a big deal. What do you think @adrianq ?

I agree with you guys - 42.x. is a good option

src/api/system.ts

src/api/trackerEnrollments.ts

src/api/trackerEvents.ts

tokland · 2026-03-20T12:47:28Z

src/api/trackerEvents.ts

@@ -159,10 +152,10 @@ export interface DataValue {
    providedElsewhere?: boolean;


I passed the DHIS2 new tracker docs and our types to Claude and it found a bunch of things (missing props, renamed props, deprecated props. ex: attributeCc/attributeCos/assignedUser-vs-assignedUsers).

However, I don't think this PR is the place to do all this review, let's focus on the versioning and the orgUnit/orgUnitMode.

It's just to be aware that we can now use AI to review this kind of things, it's hard for a human not to miss something. At some point we will have tests, but it's not realistic to expect that they check every prop in the types.

src/api/trackerEvents.ts

tokland · 2026-03-24T12:03:43Z

We can change the name of the PR, something like "[42] Convert to single-version branch". Do we want to keep the orgUnit reference? Or maybe [v42] for the version, or the version at the end, many ways to do it. And we'll keep that style for future versioned PRs.

…essary types for trackers

…om:EyeSeeTea/d2-api into feature/tracker-orgunitparams-42-869beeny2

tokland

Let's wait for @adrianq feedback on the versioning.

Otherwise, code looks good to me, I just got some warnings when running the linter. Additionally, something seems to be wrong in the infrastructure (as it signals errors on lines 0:0). Can you check it?

$ yarn lint
yarn run v1.22.22
$ eslint src --ext .js,.jsx,.ts,.tsx

/home/arnau/src/d2-api/src/api/appHub.ts
  0:0  error  Parsing error: Cannot read properties of undefined (reading 'map')

/home/arnau/src/d2-api/src/api/common.ts
  0:0  error  Parsing error: Cannot read properties of undefined (reading 'map')

/home/arnau/src/d2-api/src/api/trackerEnrollments.ts
  4:10  error  'parseTrackerPager' is defined but never used  @typescript-eslint/no-unused-vars

/home/arnau/src/d2-api/src/data/FetchHttpClientRepository.ts
  170:57  error  'globalThis' is not defined  no-undef

/home/arnau/src/d2-api/src/schemas/base.ts
  0:0  error  Parsing error: Cannot read properties of undefined (reading 'map')

/home/arnau/src/d2-api/src/utils/misc.ts
  0:0  error  Parsing error: Cannot read properties of undefined (reading 'map')

✖ 6 problems (6 errors, 0 warnings)

eperedo · 2026-03-30T14:49:17Z

Let's wait for @adrianq feedback on the versioning.

Otherwise, code looks good to me, I just got some warnings when running the linter. Additionally, something seems to be wrong in the infrastructure (as it signals errors on lines 0:0). Can you check it?

$ yarn lint
yarn run v1.22.22
$ eslint src --ext .js,.jsx,.ts,.tsx

/home/arnau/src/d2-api/src/api/appHub.ts
  0:0  error  Parsing error: Cannot read properties of undefined (reading 'map')

/home/arnau/src/d2-api/src/api/common.ts
  0:0  error  Parsing error: Cannot read properties of undefined (reading 'map')

/home/arnau/src/d2-api/src/api/trackerEnrollments.ts
  4:10  error  'parseTrackerPager' is defined but never used  @typescript-eslint/no-unused-vars

/home/arnau/src/d2-api/src/data/FetchHttpClientRepository.ts
  170:57  error  'globalThis' is not defined  no-undef

/home/arnau/src/d2-api/src/schemas/base.ts
  0:0  error  Parsing error: Cannot read properties of undefined (reading 'map')

/home/arnau/src/d2-api/src/utils/misc.ts
  0:0  error  Parsing error: Cannot read properties of undefined (reading 'map')

✖ 6 problems (6 errors, 0 warnings)

I've updated the eslint parser and plugin versions. Some other errors showed up so I fixed them as well. I've disabled the rule @typescript-eslint/ban-types because it was used for internal things like the cache.ts implementation and I think is not worth the upgrade right now.

…itparams-42-869beeny2

tokland

All good. I just pushed some minor changes, removed dead code and merged with base.

EDIT: Eduardo, just the major version 42 to be used in package.json and that's it.

adrianq · 2026-03-31T11:46:20Z

@tokland @eperedo Just commented above... 42.x.x sounds like the way to go to me

tokland · 2026-04-01T09:48:38Z

@eperedo We've discussed it with Adrian and decided to use old minor version as the new minor version. We won't bother with subversions of DHIS2 (42.x), we expect to target the latest stable . So 1.21 -> 42.21. I've pushed the change (with minor 22, the next release).

Release to npm: 42.22.0-beta.1

eperedo added 2 commits March 8, 2026 18:27

add org. unit params compatible with tracker for v42

1e473ef

bump version

3f80585

eperedo requested review from adrianq and tokland March 8, 2026 23:33

tokland reviewed Mar 9, 2026

View reviewed changes

add v42 parameters for events and enrollments

67e1626

add v42 implementation and delete deprecated events/trackedEntityInst…

ae3cc7e

…ance implementations

eperedo changed the base branch from development to 2.42 March 17, 2026 02:05

eperedo requested a review from tokland March 17, 2026 02:06

ifoche mentioned this pull request Mar 19, 2026

fix(tracker): use d2-api typed tracker API for v42 org unit params EyeSeeTea/Bulk-Load#392

Open

5 tasks

tokland reviewed Mar 20, 2026

View reviewed changes

bump version

74d07c5

tokland mentioned this pull request Mar 25, 2026

[feature] Migration to DHIS2 v42 EyeSeeTea/vaccination-app#346

Draft

5 tasks

eperedo changed the title ~~add org. unit params compatible with tracker for v42~~ [42] Convert to single-version branch Mar 30, 2026

eperedo added 3 commits March 29, 2026 19:40

improve examples on readme. Add single version export. Remove not nec…

713cc9e

…essary types for trackers

remove deprecated TEI_IMPORT and EVENT_IMPORT types

497b1f8

Merge branch 'feature/tracker-orgunitparams-42-869beeny2' of github.c…

e0159b2

…om:EyeSeeTea/d2-api into feature/tracker-orgunitparams-42-869beeny2

eperedo requested a review from tokland March 30, 2026 01:18

tokland reviewed Mar 30, 2026

View reviewed changes

fixed eslint errors

acd5151

eperedo requested a review from tokland March 30, 2026 14:49

tokland added 2 commits March 31, 2026 13:40

chore: delete unused code

b9906ac

Merge remote-tracking branch 'origin/2.42' into feature/tracker-orgun…

7669add

…itparams-42-869beeny2

tokland approved these changes Mar 31, 2026

View reviewed changes

bump version

44c13ae

chore: Use old minor as new minor version

06d5484

		@@ -159,10 +152,10 @@ export interface DataValue {
		providedElsewhere?: boolean;

Conversation

eperedo commented Mar 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📌 References

📝 Implementation

📹 Screenshots/Screen capture

🔥 Notes to the tester

Uh oh!

bundlemon bot commented Mar 8, 2026

BundleMon

Uh oh!

tokland left a comment

Choose a reason for hiding this comment

Uh oh!

tokland Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tokland Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eperedo Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

tokland Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tokland Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

tokland commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tokland left a comment

Choose a reason for hiding this comment

Uh oh!

tokland Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tokland Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

tokland Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adrianq Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

eperedo Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adrianq Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tokland Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tokland commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tokland left a comment

Choose a reason for hiding this comment

Uh oh!

eperedo commented Mar 30, 2026

Uh oh!

tokland left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adrianq commented Mar 31, 2026

eperedo commented Mar 8, 2026 •

edited

Loading

tokland Mar 9, 2026 •

edited

Loading

tokland Mar 9, 2026 •

edited

Loading

tokland Mar 10, 2026 •

edited

Loading

tokland commented Mar 10, 2026 •

edited

Loading

tokland Mar 19, 2026 •

edited

Loading

tokland Mar 20, 2026 •

edited

Loading

eperedo Mar 30, 2026 •

edited

Loading

tokland Mar 20, 2026 •

edited

Loading

tokland commented Mar 24, 2026 •

edited

Loading

tokland left a comment •

edited

Loading