readFragment type definition: handling array with null/undefined

[3ru]

I have a question regarding the type definition of the readFragment function. I noticed that there are no specific overloads for handling arrays that might be null or undefined.

Currently, the type definition includes:

gql.tada/src/api.ts

Lines 554 to 557 in 010a4f3

	function readFragment<const Document extends FragmentShape>(
	_document: Document,
	fragment: readonly resultOrFragmentOf<Document>[]
	): readonly ResultOf<Document>[];

However, it doesn't include overloads for the following cases:

declare function readFragment<const Document extends FragmentShape>(
  _document: Document,
  fragment: readonly resultOrFragmentOf<Document>[] | null
): readonly ResultOf<Document>[] | null;

declare function readFragment<const Document extends FragmentShape>(
  _document: Document,
  fragment: readonly resultOrFragmentOf<Document>[] | undefined
): readonly ResultOf<Document>[] | undefined;

declare function readFragment<const Document extends FragmentShape>(
  _document: Document,
  fragment: readonly resultOrFragmentOf<Document>[] | null | undefined
): readonly ResultOf<Document>[] | null | undefined;

I'm wondering if this is the expected behavior or if these cases were intentionally omitted.

For context, I'm in the process of migrating from @graphql-codegen to gql.tada, and I encountered type errors due to this difference in type definitions.

[kitten]

This is really a maintenance problem.

We have some more use-cases pending for readFragment, but currently, every added case exponentially increase the amount of overloads, of course. So, for a new case we're considering, we'd have to double all overloads. If we add some more then this quickly gets out of hand.

The underlying problem is that while we've tried non-overload patterns, they're simply not as performant for TypeScript to evaluate for this specific case, or don't represent the API we want. So, we'll need some time to find some alternatives and/or also check the implications of adding a huge amount of overloads (in terms of inference performance as well) before adding more cases.

This said, just to point this out. These are all helpers. There's nothing stopping you from calling readFragment on individual items.