feat(types): add returnNull and returnEptyString options to TypeOptions interface

[ImADrafter]

Working with react-i18next and typescript, I found that returnNull and returnEptyString options were not represented in typescript signatures.

By providing keys for these values inside the CustomTypeOptions, we can refine the return types for TFunction.

const dictionary = {
    ...
    nullValue: null,
    emptyString: "",
}

t('nullValue') // By default, signature returns null.
t('emptyString') // By default, signature returns ""

declare module 'react-i18next' {
    interface CustomTypeOptions extends MyCustomTypeOptions {
        returnNull: false,
        returnEmptyString: false,
    }
}

t('nullValue') // After moduleAugmentation, signature returns string, representing the key.
t('emptyString') // After moduleAugmentation, signature returns string, representing the key.

Notice that these keys must be aligned with the actual options in the i18next instance in order to represent the actual behaviour of the library on runtime.

Checklist

• only relevant code is changed (make a diff before you submit the PR)
• run tests npm run test
• tests are included
• documentation is changed or added

[coveralls]

Coverage increased (+0.2%) to 96.583% when pulling 228deb7 on ImADrafter:feat-return-null-and-return-empty-string into 7cfab97 on i18next:master.

[pedrodurek]

As both helpers are pretty much the same, you could make it more reusable, something like:

Suggested change

	type NonNullableTranslation<
	T,
	U extends Partial<CustomTypeParameters>
	> = U['returnNull'] extends false ? (T extends null ? string : T) : T;
	type NonEmptyStringTranslation<
	T,
	U extends Partial<CustomTypeParameters>
	> = U['returnEmptyString'] extends false ? (T extends '' ? string : T) : T;
	/**
	* Checks if user has enabled `returnEmptyString` and `returnNull` options to retrieve correct values.
	*/
	export type NormalizeByTypeOptions<
	T,
	U extends Partial<CustomTypeParameters> = TypeOptions
	> = NonNullableTranslation<NonEmptyStringTranslation<T, U>, U>;
	type TypeOptionsFallback<T, U, R> = U extends false ? (T extends R ? string : T) : T
	/**
	* Checks if user has enabled `returnEmptyString` and `returnNull` options to retrieve correct values.
	*/
	export type NormalizeByTypeOptions<
	T,
	U extends Partial<CustomTypeParameters> = TypeOptions,
	R = TypeOptionsFallback<T, U['returnEmptyString'], ''>
	> = TypeOptionsFallback<R, U['returnNull'], null>;

[ImADrafter]

Yup! I applied your suggestion, but changing the generic parameters naming. What do you think ? @pedrodurek

[pedrodurek]

Sounds good to me!

[pedrodurek]

Can't we simply rely on type CustomTypeParameters = Pick<TypeOptions, 'returnNull' | 'returnEmptyString'>;?

In case we can't, we can make both parameters optional instead of using partial in three different places:

type CustomTypeParameters = {
  returnNull?: boolean;
  returnEmptyString?: boolean;
};

[ImADrafter]

We can't make that Pick, because the types for returnNull and returnEmptyString would be true, not boolean :(

Applied your suggestion about making the keys optional and remove that Partial @pedrodurek

[pedrodurek]

I'm always in favour of testing everything integrated by testing both flags in the useTranslation, but I'm afraid it's not possible to toggle them on/off 🤔

[ImADrafter]

Yep, I don't know if there's a way to make the augmentation twice to check both flags. If you have any idea, just let me know :) @pedrodurek

[adrai]

is this ready to merge?

[pedrodurek]

LGTM! 🎉

[jamuhl]

published in react-i18next@11.11.4