RTK 2.0: Export All Internal Types and Functions

[eric-crowell]

Roadmap

Title	PR	Description	Blockers
Publish CI for Node16 ESM & TS	#3682	Adds a new isolated project that tests the rtk artifacts against a NodeJS project using Node16 module resolution and declaration exports
Throw Error if Internal Resource is Exported	#3687	Leverages @microsoft/api-extractor to catch the public exporting of internal resources from Supported Public APIs
Add New @reduxjs/toolkit/internal export	-	Resolves portability issues by exposing internal types explicitly from an unsupported entry point (Initially, just to see how well it'll work)	#3682 #3687

The Idea

With the move to ESM in version 2.0, I'd like to propose an idea to export all types and functions in RTK. This idea should resolve many (if not, all of) those pesky...

The inferred type of 'X' cannot be named without a reference to '../node_modules/@reduxjs/toolkit/<some path>.ts'. This is likely not portable. A type annotation is necessary.

...that appear everywhere when declarations are enabled in tsconfig.json, while still not having to give provide continual support to every type/function export.

The advantage of ESM packages is the use of the 'exports" property: bundle outputs separately and define their path. I propose outputting a new @redux/toolkit/internal export.

Name	Bundle	Export	Import	Purpose
Redux Toolkit	-	.	@reduxjs/toolkit	Supported modules for fundamental Redux Toolkit features
Redux Toolkit Query	-	./query	@reduxjs/toolkit/query	Supported modules for RTK Query features
Redux Toolkit Query (React)	-	./query/react	@reduxjs/toolkit/query/react	RTK Query with tools for React
(NEW) Redux Toolkit Internal	rtkInternal.(js/cjs)	./internal	@reduxjs/toolkit/internal	Unsupported RTK Internal types and resources

Advantages

In summary, I think this provides the following advantages:

• All types can be referenced and compiled in declarations
• Enables the use of the package's internal types and modules (if necessary)
• Clarity and distinction of unsupported internal features
• Resolves many typescript portability issues for library maintainers using RTK
• Cleans up many relative imports within the package itself. All Internal utilities can imported with @reduxjs/toolkit/internal

Final Thoughts

This idea is motivated by finding myself in situations that I would be willing to take the unsupported risk of using certain internal types. * BUT MAINLY * because I keep encountering so many TS portability errors when using RTK for a library-type projects.

I already see an @internal in the configurations pointed to the src root. It would required some reorganization to put the internal resources into its own sub directory with an index: src/internal/index.ts.

If you read this, thank you for your time. I appreciate it! Very excited for 2.0.

[markerikson]

Are there any additional import/type errors you're seeing with the current 2.0-beta.1 release?

[eric-crowell]

The most recent I've now encountered is when passing an adapter function directly as a case reducer.

Code Sandbox: https://codesandbox.io/s/inspiring-pond-5vr7tg?file=/src/createSlice.ts

// ...
export const mySlice = createSlice({
  name: "item",
  initialState: adapter.getInitialState(),
  reducers: {
    // Produces portability error
    add: adapter.addOne,
    // Does not produce portability error
    // add: (state, action: PayloadAction<Item>) => {
    //   adapter.addOne(state, action.payload);
    // }
  }
});

[eric-crowell]

If continuing to export additional types on your Publicly Supported APIs is okay, then this idea wouldn't be useful.

This idea is to help avoid the increasing amount of APIs you need to maintain the stability and support for (nearly indefinitely). This addresses feedback provided by @phryneas on #3569 (comment)

As a bonus, I think it could help with organization within the package itself as well.

[markerikson]

This admittedly isn't immediately on my priority list, but could you try filing a PR that adds this and we can see what happens? (It would be especially helpful if we could add another project or two under examples/publish-ci that would actually catch this kind of error, so we know that the behavior works correctly.)

[eric-crowell]

I added a new project, PR #3682, under examples/publish-ci that fails on the additional portability issues I'm experiencing.

I'll work on the subsequent PR that tries out @reduxjs/toolkit/internal; while, of course, also adding more RTK implementations to the examples/public-ci.

Nonetheless, the issue is captured on CI. Should definitely help!

[eric-crowell]

@markerikson I noticed a package called @microsoft/api-extractor is installed but seemly unused.

I'd like to add a step in the CI workflow that leverages @microsoft/api-extractor to throw an error if any resource marked with @internal is exported publicly. Is that alright?

It'll sure help me catch anything I should/shouldn't be exporting.

[phryneas]

api-extractor was a bit broken with RTKs types in the past, but you can try :)

[eric-crowell]

Alight! I made an attempt on PR #3687. So far, it appears to be catching bad exports.

I didn't attempt to fix anything that exists, so the workflow does fail. I might need some help from you or @markerikson to determine how to fix the export error on the PR.

[eric-crowell]

@phryneas I understand I don't have the knowledge or authority to properly mark what should/shouldn't considered external. However, if you are short on time, I'd like to go through and add the proper annotations by looking at what's already publicly exported... and using that as my guide. Would that be a worthwhile effort on PR #3687?

Otherwise, I don't think I can continue without the proper tests that keep me from exporting the wrong things.

[phryneas]

You can consider everything that is directly exported from /, /query and /query/react as "public" - the rest should be considered internal until we find a good reason to move it to one of the bundle entry points.