Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Separate types from code and make types composable/extendable #2127

Open
18 of 40 tasks
Tracked by #2218 ...
gr2m opened this issue Jul 9, 2021 · 3 comments
Open
18 of 40 tasks
Tracked by #2218 ...

Separate types from code and make types composable/extendable #2127

gr2m opened this issue Jul 9, 2021 · 3 comments
Assignees
Labels
project typescript Relevant to TypeScript users only

Comments

@gr2m
Copy link
Contributor

gr2m commented Jul 9, 2021

Currently all JS Octokit modules depend on @ocotkit/types. @octokit/types include definitions for all 600+ REST API endpoints for api.github.com and primitives such as types for Requests and responses that are not extendable.

Problems

  1. All endpoint types are for api.github.com. They cannot be replaced for GHAE or a specific GHES version. They cannot be imported selectively.
  2. The types cannot be extended by plugins. Plugins often time introduce new Octokit options such as throttle, extend request options and/or responses. Authentication strategies are a special kind of plugins that provide custom auth options, but they cannot define the options in a way that would provide IntelliSense to users of the authentication strategy. Plugins also hook into the request life cycle and amend requests/responses, but the types for requests/responses provided by @octokit/types cannot be extended at this point.

Solution

Take advantage of declaration merging and global augmentation to make it possible for imported code to amend the global Octokit Types.

For the endpoint types, I see two approaches:

  1. Create entirely separate types for api.github.com, GHES-3.0, GHES-3.1
  2. Use types for api.github.com as the starting point, then create types for the GHES/GHAE versions as an extension of that. Endpoints that do not (yet) exist in the target version can be set to never with an explanation. If the endpoint exists in both environments but differs in its request parameters or response, create a union of both types. We could introduce a new option such as request.version which defaults to "api.github.com" but which can be set to whatever version of the REST API endpoint types were loaded. So when it's set to "ghes-3.1" then the types from that version are used explicitly, instead of the union between the types of api.github.com and ghes-3.1.

I'd prefer the 2nd approach as I'd expect it to be a better developer experience.

For developers who write code that is meant to run against both api.github.com and a minimal version of GHES, we could create virtual versions such as ghes-3.0-compatible, which will either only include types that are covered by both environments, or make clear which endpoints/properties do not exist in either.

Benefits

  • Make developing for GHAE and GHES a first-class experience

Steps

@octokit-next/* packages

Implement changes in Octokit

  • Setup octokit/types-rest-api.ts repository as a monorepo that publishes all the @octokit/types-rest-api-* packages with all the update-automation
  • Migrate @octokit/types to the new version in the beta branch
  • Migrate @octokit/endpoint (the lowest-level @octokit/* package that uses the endpoints types) in the beta branch
  • Migrate @octokit/request in the beta branch
  • Migrate @octokit/graphql in the beta branch
  • Migrate @octokit/core in the beta branch
  • Migrate the plugins loaded by octokit. Extend Octokit.Options as needed
  • Migrate the @octokit/* authentication strategies
  • Migrate octokit
  • Migrate or rather re-create @octokit/plugin-enterprise-server to utilize the new types. Only generate methods for the latest GHES version that do not exist on github.com

Backlog

  • remove the default GET / route types. Instead implement an override of request(route, parameters) that only applies if Octokit.ApiVersions["github.com"] is an empty object (if that is possible at all). Use that override's description to recommend installing one of the types packages
@gr2m gr2m added typescript Relevant to TypeScript users only project labels Jul 9, 2021
@gr2m gr2m changed the title Separate types from code / make types composable/extendable Separate types from code and make types composable/extendable Jul 9, 2021
@gr2m
Copy link
Contributor Author

gr2m commented Jul 9, 2021

This will unlock octokit/core.js#323

@gr2m
Copy link
Contributor Author

gr2m commented Aug 16, 2021

For the curious ones, here's what this is all about

2021-08-16.16-07-49.mp4

@gr2m gr2m pinned this issue Aug 16, 2021
@gr2m
Copy link
Contributor Author

gr2m commented Sep 18, 2021

Another update, in 4 parts, because

  1. There is more to show
  2. I'm giving TypeScript a hard time

Part I: upcoming @octokit/core without any REST API types and with types for github.com

part-1.mp4

Part II: types for GitHub Enterprise Server (GHES)

part-2.mov

Part III: set API version on new Octokit() constructor

part-3.mp4

Part IV: types for GHES-compatible versions

part-4.mp4

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
project typescript Relevant to TypeScript users only
Projects
None yet
Development

No branches or pull requests

1 participant