[TypeScript] access parameters/responses subtypes

[ianwremmel]

I've been making use of the types AppsListAccountsUserOrOrgOnPlanResponse, AppsListAccountsUserOrOrgOnPlanResponseItem, and AppsListAccountsUserOrOrgOnPlanResponseItemMarketplacePurchasePlan.

With V17, I can do

export type AppsListAccountsUserOrOrgOnPlanResponse = RestEndpointMethodTypes['apps']['listAccountsUserOrOrgOnPlan']['response']['data'];

But to get to the subtypes, I need to do

export type AppsListAccountsUserOrOrgOnPlanResponse = RestEndpointMethodTypes['apps']['listAccountsUserOrOrgOnPlan']['response']['data'];
export type AppsListAccountsUserOrOrgOnPlanResponseItem = AppsListAccountsUserOrOrgOnPlanResponse[0];
export type AppsListAccountsUserOrOrgOnPlanResponseItemMarketplacePurchasePlan = AppsListAccountsUserOrOrgOnPlanResponseItem['marketplace_purchase']['plan']

In articular, the AppsListAccountsUserOrOrgOnPlanResponse[0] seems strange.

[gr2m]

Sorry Ian for not getting back to you. My time for Octokit is very limited, and I don't have a good answer. But I do agree that the current solution is not sufficient.

I am considering to export the types similar to how they have been exported in v16. I'm not quite sure what the right approach would be, maybe export aOctokit namespace with an Endpoints interface on it, which would then have all the different keys for requests and responses on it?

Can you think of a project similar to Octokit which does a good job with that? Or anyone I could reach out to for help?

[ianwremmel]

Sorry Ian for not getting back to you.

Well, as long as you won't hold the same against me :)

Can you think of a project similar to Octokit which does a good job with that?

The only other project I'm aware that would expect to use a typescript setup like octokit is the AWS SDK. I don't know if it's generated in a similar way, but I do believe quite a lot if its code is generated.

[robsonmeemo]

It gets uglier with optional types:

type ChecksCreateParamsOutputAnnotations = NonNullable<
  NonNullable<
    RestEndpointMethodTypes["checks"]["create"]["parameters"]["output"]
  >["annotations"]
>[0];

Is it feasible to just have aliases for those types?

[hipstersmoothie]

I've had to do this too. The NonNullable makes it very ugly.

[gr2m]

I have a question: say I do export all the types and sub types for the endpoint parameters and responses, such as AppsListAccountsUserOrOrgOnPlanResponseItemMarketplacePurchasePlan

What happens frequently is that the endpoint names are changing. Now octokit.apps.listAccountsUserOrOrgOnPlan got renamed octokit.apps.listAccountsForPlan. For the methods, I keep track of these renames, I keep both methods working and log a deprecation message for the former. With v18, I plan to only remove previously deprecated messages.

For TypeScript, I don't know how to communicate that a type was deprecated. Is there such a possibility? I think it's possible for methods, but not types? Any thoughts on that?

[ianwremmel]

As far as renaming things, it seems like an @deprecated jsdoc is the preferred way, even thought it's not quite standard yet.

• @‌deprecated JSDoc tag microsoft/TypeScript#390
• show @deprecated in editor microsoft/vscode#53514

[ianwremmel]

Oh, I see, you were concerned about deprecating interfaces. I'm not sure if @deprecated works there or not.

[ianwremmel]

maybe it's just a matter of maintaining all names for some amount of time, and when it reaches an annoying level of maintenance, put out a major update?

[gr2m]

when it reaches an annoying level of maintenance, put out a major update

That is basically how I do versions today already. I avoid breaking changes at all costs, but eventually bump the major version to get rid of all the deprecations. As part of the migration to the new version, I ask folks to update to the latest version of the previous major version and address all deprecations they see in their tests.

But I think there are no deprecation messages for TypeScript interfaces, so people will have to look up the new names manually. Not ideal, but also not the end of the world :)

[ecraig12345]

Coming in late here, but I'd personally prefer to have explicit interfaces even if I sometimes have to update the names after major releases. If the interface names correspond to method names, and the methods do log deprecation warnings at runtime, that would hopefully help clue people in to update the interface names in their code at the same as they update the method names.

Another way to get type deprecation warnings is that if you add @deprecated to the JSDoc, eslint-plugin-deprecation (or tslint's deprecation rule) can be used to get lint errors about usage of deprecated things, though of course not everyone has that set up.