[@types/react] Remove calculateChangedBits from createContext

[gaearon]

Authors: @johnnyreilly @bbenezech @pzavolinsky @digiguru @ericanderson @DovydasNavickas @theruther4d @guilhermehubner @ferdaber @jrakotoharisoa @pascaloliv @Hotell @franklixuefei @Jessidhia @saranshkataria @lukyth @eps1lon @zieka @dancerphil @dimitropoulos @disjukr @vhfmag

---

I've just noticed createContext has a second argument in the type definition. This doesn't make sense and is misleading. That second argument is an unstable API that will likely be removed. It's called unstable_calculateChangedBits but the definition just calls it calculateChangedBits. What's worse, VS Code autocomplete offers to supply it. Could we remove the unstable API from typings or move this overload to the experimental definition?

[dimitropoulos]

would you be satisfied if it were just named appropriately (without moving it)? We did so for other such examples recently.

Or is moving to the experimental definition the main thing you'd like to achieve here?

It seems to me (and would be my 2 cents) that removing it altogether is a last resort - and it instead belongs in the experimental.d.ts

[illusionalsagacity]

Would be happy to contribute either of these options; I think the experimental.d.ts option makes a bit more sense personally.

On the other hand removing it entirely from the main definition could very likely make some CI builds break.

[eps1lon]

Would be happy to contribute either of these options; I think the experimental.d.ts option makes a bit more sense personally.

experimental.d.ts is specifically for react@experimental. We shouldn't abuse these declarations because people might switch to the experimental declarations and use APIs that are not part of the stable bundle.

It would make more sense to just remove it and advise people to use declaration merging for unstable APIs. This would at least work for this specific case:

import * as React from 'react';

// unstable APIs
declare module 'react' {
    function createContext<T>(
        defaultValue: T,
        unstable_calculateChangedBits?: (prev: T, next: T) => number
    ): Context<T>;
}

@gaearon What about other unstable APIs in the stable bundle like <Suspense unstable_avoidThisFallback /> or <Context.Consumer unstable_observedBits={bits} />. Should these be stripped as well or is the concern more about naming these unstable APIs correctly?

[gaearon]

My main concern is Code aggressively autocompleting parameters that aren't supposed to be used. Which arguably is more of a Code issue. I guess for function arguments this is worse than for JSX props.

Overall, I think if something is not in the docs, it should not be in the typings either. People who want to use it can always any it.

[ferdaber]

An alternative would also be to use JSDoc to specifically mark the second parameter as deprecated, though it would do less to prevent people from using it.

[eps1lon]

I guess for function arguments this is worse than for JSX props.

I think that it's even worse for props than for function arguments if unstable parameters are added via function overload.

For props you always get the full interface which lists the unstable props. For functions you either have to explicitly start typing the additional parameter or go through each overload:

-- demo

Personally I'm fine with removing unstable APIs from the typings and recommend declaration merging. It's what we recommend for non-standard HTML attributes as well.

I was never a fan of the recommended "link to source to justify typings"-approach of DefinitelyTyped. If React core members support this we have an easier time defending the change.

[gaearon]

Personally I'm fine with removing unstable APIs from the typings and recommend declaration merging. It's what we recommend for non-standard HTML attributes as well.

👍