search

gr2m / helpdesk

Answering all your GitHub API/automation questions live on Twitch
https://twitch.tv/gregorcodes
Creative Commons Zero v1.0 Universal
22 stars 11 forks source link

📅 6/18 @ 12:30pm PT - Advanced TypeScript for the future Octokit SDK with @orta #29

Closed gr2m closed 3 years ago

gr2m commented 3 years ago

💁🏻 Advanced TypeScript for the future Octokit SDK 📅 Friday, June 18, 2021 🕐 12:30pm Pacific Time (in your timezone) 🎙️ with @orta 📍 https://twitch.tv/gregorcodes 🏷️ TypeScript, Octokit

Extending constructor options by plugins.

The Octokit SDK is built using a modular plugin architecture. The core package is @octokit/core, which can be extended using plugins, e.g. like this

// plugin.js
module.exports = function helloWorldPlugin(octokit, options = { greeting: "Hello" }) => {
  // add a custom method
  return {
    helloWorld: () => console.log(`${options.greeting}, world!`);
  }
};

// index.js
const { Octokit } = require("@octokit/core")
const helloWorldPlugin = require("./plugin")

const MyOctokit = Octokit.plugin(helloWorldPlugin);

const octokit = new MyOctokit({ greeting: "Moin moin" });
octokit.helloWorld(); // logs "Moin moin, world!"

The important bit is that typing octokit. will suggest both Octokit's core methods such as octokit.request and octokit.graphql, but also octokit.helloWorld().

But something that is not currently possible is to extend the types the types for Octokit's constructor options so that when I type new Octokit({ it would suggest { greeting } as an option.

I started a pull request at https://github.com/gr2m/javascript-plugin-architecture-with-typescript-definitions/pull/56 to implement it with Orta.

Inherit constructor options

Currently Octokit has no required options. But one thing we want to improve is the developer experience to build code for GitHub Enterprise Server or GitHub AE. In order to differentiate between the two we will probably add some kind of version parameter that can be set to api.github.com, ghes3.2 or ghes-3.1-compatible.

The other reason that we will require constructor options inheritance will be types for the Authentication strategies (see next section).

So given that version will be a required parameter, this code should be possible without any type errors

const OctokitGHE31 = Octokit.defaults({ version: 'ghe-3.1' })
const octokit = new OctokitGHE31()

Types for Authentication strategies

I have a long standing open issue for this one: https://github.com/octokit/core.js/issues/323

Basically what I want a better developer experience when using authentication strategies such as @octokit/auth-app

import { Octokit } from "@octokit/core";
import { createAppAuth } from "@octokit/auth-app"
const octokit = new Octokit({
  authStrategy: createAppAuth,
  auth: {
    // should provide IntelliSense for createAppAuth options:
    // https://github.com/octokit/auth-app.js/#createappauthoptions-or-new-octokit-auth-
  }
})

This should work together with the inheritence of options types from Octokit.defaults() so this will be possible

import { Octokit } from "@octokit/core";
import { createAppAuth } from "@octokit/auth-app"

const AppOctokit = Octokit.defaults({
  authStrategy: createAppAuth
})

const octokit = new AppOctokit({
  auth: {
    // should provide IntelliSense for createAppAuth options:
    // https://github.com/octokit/auth-app.js/#createappauthoptions-or-new-octokit-auth-
  }
})

Outline

  1. The TypeScript for today's @octokit and where it falls short
  2. Make Types extendable by plugins (gr2m/javascript-plugin-architecture-with-typescript-definitions#56)
  3. Remember default options set with Octokit.defaults()

Preparation

Recording

will be added after the show

Shownotes

gr2m commented 3 years ago

Video is now available on Twitch: https://www.twitch.tv/videos/1060393045

oscard0m commented 3 years ago

Linking these tweets following up the show: