I'm not a big fan of this callback style.

We've been doing this pattern for all the REST endpoints that call cht-datasource. What's the alternative?

IMHO doOrError is a nice way to reduce duplicated code and ensure we are handling errors consistently.

I think a try-catch block is not so much duplication, and it's more transparent than a nested callback.
I understand this already exists. I'm not a fan.

this seems strange that we assign a random non-truthy value (as in: whatever is in req.query.limit) instead of being specific.
Same applies to the reports controller.

The false is a random pick.

The reason why req.query.limit is being passed when the conditional is falsy is that in the cht-datasource there is already a validation for this and also a default value. This is to ensure that the validation does not happen twice and also the default value.
Reference.

Then why not have cht-datasource also do the Number conversion then? Why have this validation here? Is limit ever expected to not be a number?

Is limit ever expected to not be a number?

Yeah, in cases like the one above, where it is passed as a query param in REST API, it is expected to be a stringified number. However, cht-datasource can also be used in non-REST API codes where end-users will have to pass in a number to cht-datasource because PouchDB expects the limit value to be a number. I think that's a reasonable approach to make the limit variable an explicit Number type, as that would align with the expected input for the PouchDB Adapter. This would provide better type safety and clarity in the code. The validation being present in cht-datasource still makes sense, and whether to apply the same validation elsewhere should be at the discretion of the end-user, based on their specific use case.

So even if it's a stringified number or a number, we still only ever evaluate it as a number. so it makes sense to only have validation in one spot, right?

Yes. Are you considering a type conversion from string to number a validation?

Ok, I'll use a different word than validation: processing.
It's possible to only do processing of the limit parameter in a single place: this includes validation, conversion and all the other things. We should do processing in a single place.

In most cases, I agree but I'm not sure why the conversion of limit from string to number should be designated to cht-datasource, it's not its concern.
Edit 1:
I might have misunderstood the above. Are you suggesting we do both conversion and validation in another place than both the API controller and cht-datasource?

I'm suggesting that conversion and validation can both be done in a single place: cht-datasource.

So ... this endpoint .. if it doesn't get neither a freetext query param or a limit query param, it will end up returning ALL reports?

nope. it returns a 400 - Bad request error because freetext is required whereas limit is set to a default of 10000.

maybe /api/v1/contact/ids is more suitable.
The idea is that the URL isn't suggestive at all, without reading the implementation, I would never guess what this endpoint does.

Yes, REST API conventions are to name the API endpoint in a plural way like /api/v1/contacts or /api/v1/contacts/ids but this design decision had already been taken even before this ticket. I couldn't find the link to the conversation for this though.

That discussion happened in the parent ticket before we spun off the child isssue: #9544 (comment)

Thanks @jkuester . Your argument here is that "we've already decided and your input is not welcome?"

Sorry for being aggressive and confrontational in the above comment.

I maintain my comment about /api/v1/contact/id being quite unsuggestive, we shouldn't need thorough explanations and reasoning behind the naming choice in order for an api name to make sense.

I was just trying to provide the context for the discussion that Sugat referenced. 😬

I am happy to continue the design discussion here to come to an agreed upon approach. It will just be most efficient if we all understand what was already said to get us here. When starting work on new REST endpoints for the cht-datasource code, we chose to go with the pattern of singular entity names (so /api/v1/person instead of /api/v1/persons). When the endpoint can return 0-n entities I do not really see a compelling reason to prefer either singular or plural (since either might make more sense depending on the context). Two things seem clear to me though:

• Under normal circumstances, we should not duplicate endpoints for the same resource (e.g. having both /api/v1/contact/id and /api/v1/contact/ids).
• We should be consistent with our naming across our go-forward REST endpoints. Either using singular or plural, but not mixing both.

Same comment about assertions in afterEach and afterEach run order.

All these tests should call the API endpoints, instead of requesting datasource code.

This was heavily discussed with QA when laying down the original pattern for these tests. The summary of the the IRL convos is here: #9090 (comment)

TLDR is we could duplicate tests, but the value of that seems nearly non-existant (while adding a non-zero cost in terms of additional tests to run).

Pleaaaase duplicate the tests :)

@sugat009 How feasible would it be to parameterize the tests where we are currently using cht-datasource so that we run the same test with both the cht-datasource remote wrapper and with the test utils making the same REST call?

I am thinking of something like this (but have not actually tried to run this yet):

    [
      (placeId) => Place.v1.get(dataContext)(Qualifier.byUuid(placeId)),
      (placeId) => {
        const opts = {
          path: `/api/v1/place/${placeId}`,
        };
        return utils.request(opts);
      }
    ].forEach((getPlace) => {
      it('returns the place matching the provided UUID', async () => {
        const place = await getPlace(place0._id);
        expect(place).excluding(['_rev', 'reported_date']).to.deep.equal(place0);
      });
    });

That would ensure we test both the cht-datasource Remote adapter as well as just using the test utils to hit the REST api "directly" without actually needing to duplicate every test...

This is a nice workaround and would probably be feasible and runnable but let's just duplicate the test code, it probably will be more maintainable and readable, and usually, test code doesn't need reusability.

All these tests should call the api endpoints, instead of request datasource code.