Skip to content

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

Open
@gr2m

Description

@gr2m

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

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions