Why are interfaces e.g. `TableProps`, part of the top-level external API, not exported?

[craigkovatch]

Trying to define a component with an external API e.g.:

import * as React from 'react';
import { useTable } from 'react-aria';
import { useTableState } from 'react-stately';

export type ContentTableProps = TableProps & {

}

export const ContentTable: React.FC<ContentTableProps> = props => {
  return <div>

  </div>;
};

The necessary TableProps here is used in the parameters of the useTable signature, so it should be exported so I can define a new type based on it. Or just so I can create a type-safe object of it. Is there a reason it's not exported?

TableProps here is just an example, from what I can see there are lots of exported APIs which are defined against non-exported interfaces.

FWIW Microsoft makes a TypeScript analysis tool called API Extractor; it's Number 2 Headline Feature is designed to help detect and correct this situation: https://api-extractor.com/

Missing exports: Suppose the awesome-widgets package exports an API function AwesomeButton.draw() that requires a parameter of type DrawStyle, but you forgot to export this enum. Things seem fine at first, but when a developer tries to call that function, they discover that there’s no way to specify the DrawStyle. How to avoid these oversights?

[craigkovatch]

Same issue trying to just rest an empty props object so I can make progress (as in the docs) -- children is a required prop in TableStateProps (from CollectionBase):

But children is defined against complicated types which are not library-exported, so there's no opportunity for me to define anything as part of my component's own API, I have to set children internally:

export type CollectionElement<T> = SectionElement<T> | ItemElement<T>;
export type CollectionChildren<T> = CollectionElement<T> | CollectionElement<T>[] | ((item: T) => CollectionElement<T>);
export interface CollectionBase<T> {
  /** The contents of the collection. */
  children: CollectionChildren<T>,

[LFDanLu]

Thanks for reporting this, this looks like something we missed on our end, I don't see a reason why TableProps shouldn't be exported from useTable. That tool seems promising, thanks for letting us know about it!

[craigkovatch]

Great, thanks @LFDanLu ! I would send you a PR if it was just this type missing, but I think yeah probably dozens (hundreds?) of exports missed in this way. So I figured a systemic solution from someone who knows the code base is the better path :) Appreciate your quick response!

[devongovett]

We can of course export more things when needed, but in general we are very careful about it so we aren't locked into a giant API surface area we cannot change. In this case, those are options for the useTable hook. If you're building a table component, you probably don't want to expose them as your public API because they contain internal things. The @react-types/table package contains a type for the public API:

react-spectrum/packages/@react-types/table/src/index.d.ts

Lines 17 to 22 in f4a887e

	export interface TableProps<T> extends MultipleSelection, Sortable {
	/** The elements that make up the table. Includes the TableHeader, TableBody, Columns, and Rows. */
	children: [ReactElement<TableHeaderProps<T>>, ReactElement<TableBodyProps<T>>],
	/** A list of row keys to disable. */
	disabledKeys?: Iterable<Key>
	}

.

[craigkovatch]

@devongovett Thanks for looking at this!

I’m not sure that approach accomplishes the stated goal, though. If your API breaks/changes in the future, not exporting the typedefs doesn’t make anything safer. In fact it makes changes more difficult because the consumer doesn’t benefit from the type safety.

Please don’t focus on my comments about API “re” export. That’s not the primary issue here. The problem is that right now I cannot create a type-safe object for any parameters used in these exported functions. The types can only be inferred in-line.

Any type that is part of an exported function or class definition is already public, and so it needs to be exported. Not exporting them only makes it painful and/or type-unsafe to use them. At the risk of repeating myself, this is a serious and common enough mistake that Microsoft wrote a tool which has a primary function of catching it.

And I just want to be clear that I’m super super excited to use this project and have been for some time now :) but this is a blocking issue for me to do so.

(PS at the bottom so as not to be a distraction — with regard to re-exporting types, I agree that I’d rather not take such a direct dependency. But the type definitions are complex enough that it’s not easy to tease out what I’d need to redefine myself. Especially because they’re not exported so I can’t use intellisense to guide me 😅)

[craigkovatch]

Btw please let me know if a screen recording or a zoom call would help. Sometimes I find it hard to fully describe nuanced issues like this on text

[devongovett]

This should definitely not be a blocker for anyone.

a) Type inference is often good enough. You don't need to annotate every variable, e.g. when calling useTable and passing an options object, TypeScript already knows what the type will be so there is no need to name it. This is how we use most of the hooks ourselves.
b) If you really do need a named type for some reason and it isn't exported, you can do things like use typeof. Example

The example for API extractor that you gave is a case where exporting the type is actually required, because it's an enum which has runtime semantics, rather than a type that is stripped at build time. So you actually couldn't construct an enum value without it being exported. With types, this is less of an issue, because type inference covers most cases.

I’m not sure that approach accomplishes the stated goal, though. If your API breaks/changes in the future, not exporting the typedefs doesn’t make anything safer. In fact it makes changes more difficult because the consumer doesn’t benefit from the type safety.

TypeScript is a structural type system, not a nominal one, so two types may be equivalent but have different names, or be composed of different parts nominally. For example, we often refactor types to break them apart and reuse different pieces via extends or other mechanisms. If we exported every individual type, this would no longer be possible because refactoring would become a breaking change.

We are open to exporting more types where needed, and I agree things are inconsistent today, but we need to be intentional and systematic about it.

[craigkovatch]

I am definitely not requesting or suggesting that you export every single internal type :) Just those which are named in other library-level exports. I want to sit down and look at this again so I can either revisit my assumptions or give you much clearer feedback about what the stumbling blocks were. Unfortunately I’m out sick right now, so it might be a week or two. Thanks again for jumping in.

…

-Craig (mobile)

________________________________ From: Devon Govett ***@***.***> Sent: Friday, June 17, 2022 4:58:01 PM To: adobe/react-spectrum ***@***.***> Cc: Craig Kovatch ***@***.***>; Author ***@***.***> Subject: Re: [adobe/react-spectrum] Why are interfaces e.g. `TableProps`, part of the top-level external API, not exported? (Issue #3087) This should definitely not be a blocker for anyone. a) Type inference is often good enough. You don't need to annotate every variable, e.g. when calling useTable and passing an options object, TypeScript already knows what the type will be so there is no need to name it. This is how we use most of the hooks ourselves. b) If you really do need a named type for some reason and it isn't exported, you can do things like use typeof. Example<https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBDAnmApnA3gVwM4oCoCGARgDYoC+cAZlBCHAOQACUKBAxjALQFTAEB6GMTIMA3ACgJSVHEKkUABVphsAHjwA+OAF44i3gRAoYKKOpkoIVODnwiUGzZoDaABgC6koA> The example for API extractor that you gave is a case where exporting the type is actually required, because it's an enum which has runtime semantics, rather than a type that is stripped at build time. So you actually couldn't construct an enum value without it being exported. With types, this is less of an issue, because type inference covers most cases. I’m not sure that approach accomplishes the stated goal, though. If your API breaks/changes in the future, not exporting the typedefs doesn’t make anything safer. In fact it makes changes more difficult because the consumer doesn’t benefit from the type safety. TypeScript is a structural type system, not a nominal one, so two types may be equivalent but have different names, or be composed of different parts nominally. For example, we often refactor types to break them apart and reuse different pieces via extends or other mechanisms. If we exported every individual type, this would no longer be possible because refactoring would become a breaking change. We are open to exporting more types where needed, and I agree things are inconsistent today, but we need to be intentional and systematic about it. — Reply to this email directly, view it on GitHub<#3087 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ACTWJEIRCWXB6IK7ZAFDZD3VPUGITANCNFSM5UUPVNUA>. You are receiving this because you authored the thread.Message ID: ***@***.***>