-
Notifications
You must be signed in to change notification settings - Fork 1k
-
Notifications
You must be signed in to change notification settings - Fork 1k
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
Labels
Comments
10 tasks
gr2m
changed the title
Separate types from code / make types composable/extendable
Separate types from code and make types composable/extendable
Jul 9, 2021
This will unlock octokit/core.js#323 |
For the curious ones, here's what this is all about 2021-08-16.16-07-49.mp4 |
Another update, in 4 parts, because
Part I: upcoming
|
1 task
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Currently all JS Octokit modules depend on
@ocotkit/types
.@octokit/types
include definitions for all 600+ REST API endpoints forapi.github.com
and primitives such as types for Requests and responses that are not extendable.Problems
throttle
, extend request options and/or responses. Authentication strategies are a special kind of plugins that provide customauth
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:
api.github.com
,GHES-3.0
,GHES-3.1
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 asrequest.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 ofapi.github.com
andghes-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
Steps
@octokit-next/*
packagesoctokit-next.js
repository with the minimal set of features needed to implement the extendable & composable types. I already started working on parts of it in https://github.com/gr2m/javascript-plugin-architecture-with-typescript-definitions/.octokit-next.js
could build upon that to test the composability features ofBase.defaults()
andBase.plugins()
and implement a.request()
method which implements a few of GitHub's endpoints to test a setup that works against different environments (api.github.com
,ghes-3.1
,ghes-3.0
)Base
constructor options with plugins gr2m/javascript-plugin-architecture-with-typescript-definitions#56.defaults()
: feat: derive constructor options from chainableBase.defaults()
calls gr2m/javascript-plugin-architecture-with-typescript-definitions#57octokit-next.js
repository with anoctokit.request
method which utilizes endpoint typesoctokit.request
based on theversion
option passed to the constructor octokit-next.js#3api.github.com
,ghes-3.1
,ghes-3.0
. Make the types forapi.github.com
load by default.options.version
parameter for theOctokit
constructor and aoptions.request.version
option when callingoctokit.request(options)
. The type should be an extendableenum
. By default it will only permitapi.github.com
. When importing types forghes-3.0
, it can be set toapi.github.com
andghes-3.0
(and if it makes the implementation easier because of the cascade:ghes-3.1
)authStrategy
,auth
) and make the types forauth
depend on whatauthStrategy
is set to, either as part of the same options object or via.defaults()
octokit-next.js#18ghes-3.1-compatible
andghes-3.0-compatible
versions octokit-next.js#14github.com
,ghes-3.1
, andghes-3.0
octokit-next.js#15ghes-3.1-compatible
andghes-3.0-compatible
versions octokit-next.js#16ghae
andghae-compatible
octokit-next.js#17@octokit/endpoint
in@octokit-next/endpoint
octokit-next.js#36@octokit/request
in@octokit-next/request
octokit-next.js#41@octokit/graphql
in@octokit-next/graphql
octokit-next.js#70@octokit/core
in@octokit-next/core
octokit-next.js#72octokit
@octokit/oauth-methods
@octokit/oauth-app
@octokit/webhooks-methods
@octokit/webhooks
@octokit/app
@octokit/plugin-paginate-rest
@octokit/plugin-rest-endpoint-methods
@octokit/plugin-retry
@octokit/plugin-throttling
Implement changes in Octokit
octokit/types-rest-api.ts
repository as a monorepo that publishes all the@octokit/types-rest-api-*
packages with all the update-automation@octokit/types
to the new version in thebeta
branch@octokit/endpoint
(the lowest-level@octokit/*
package that uses the endpoints types) in thebeta
branch@octokit/request
in thebeta
branch@octokit/graphql
in thebeta
branch@octokit/core
in thebeta
branchoctokit
. ExtendOctokit.Options
as needed@octokit/*
authentication strategiesoctokit
@octokit/plugin-enterprise-server
to utilize the new types. Only generate methods for the latest GHES version that do not exist on github.comBacklog
GET /
route types. Instead implement an override ofrequest(route, parameters)
that only applies ifOctokit.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 packagesThe text was updated successfully, but these errors were encountered: