Skip to content

Commit

Permalink
feat: v21 (#413)
Browse files Browse the repository at this point in the history
BREAKING CHANGE: package is now ESM
  • Loading branch information
wolfy1339 authored Jun 20, 2024
1 parent 32649a8 commit 12b6c65
Show file tree
Hide file tree
Showing 37 changed files with 3,149 additions and 9,782 deletions.
15 changes: 13 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,19 @@ Node
Install with <code>npm install @octokit/rest</code>

```js
const { Octokit } = require("@octokit/rest");
// or: import { Octokit } from "@octokit/rest";
import { Octokit } from "@octokit/rest";
```

</td></tr>
</tbody>
</table>

> [!IMPORTANT]
> As we use [conditional exports](https://nodejs.org/api/packages.html#conditional-exports), you will need to adapt your `tsconfig.json` by setting `"moduleResolution": "node16", "module": "node16"`.
>
> See the TypeScript docs on [package.json "exports"](https://www.typescriptlang.org/docs/handbook/modules/reference.html#packagejson-exports).<br>
> See this [helpful guide on transitioning to ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) from [@sindresorhus](https://github.com/sindresorhus)
```js
const octokit = new Octokit();

Expand All @@ -52,6 +57,12 @@ octokit.rest.repos

See https://octokit.github.io/rest.js for full documentation.

> [!IMPORTANT]
> As we use [conditional exports](https://nodejs.org/api/packages.html#conditional-exports), you will need to adapt your `tsconfig.json` by setting `"moduleResolution": "node16", "module": "node16"`.
>
> See the TypeScript docs on [package.json "exports"](https://www.typescriptlang.org/docs/handbook/modules/reference.html#packagejson-exports).<br>
> See this [helpful guide on transitioning to ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) from [@sindresorhus](https://github.com/sindresorhus)
## Contributing

We would love you to contribute to `@octokit/rest`, pull requests are very welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
Expand Down
5 changes: 2 additions & 3 deletions docs/src/pages/api/00_usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,14 @@ Load <code>@octokit/rest</code> directly from <a href="https://esm.sh">esm.sh</a
Install with <code>npm install @octokit/rest</code>

```js
const { Octokit } = require("@octokit/rest");
// or: import { Octokit } from "@octokit/rest";
import { Octokit } from "@octokit/rest";
```

</div>
<hr />

```js
const { Octokit } = require("@octokit/rest");
import { Octokit } from "@octokit/rest";
```

Now instantiate your octokit API. All options are optional, but authentication is strongly encouraged.
Expand Down
6 changes: 3 additions & 3 deletions docs/src/pages/api/01_authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Learn more about all official and community [authentication strategies](https://
By default, `@octokit/rest` authenticates using the [token authentication strategy](https://github.com/octokit/auth-token.js). Pass in a token using `options.auth`. It can be a personal access token, an OAuth token, an installation access token or a JSON Web Token for GitHub App authentication. The `Authorization` request header will be set according to the type of token.

```js
const { Octokit } = require("@octokit/rest");
import { Octokit } from "@octokit/rest";

const octokit = new Octokit({
auth: "mypersonalaccesstoken123",
Expand All @@ -30,8 +30,8 @@ To use a different authentication strategy, set `options.authStrategy`.
Here is an example for GitHub App authentication

```js
const { Octokit } = require("@octokit/rest");
const { createAppAuth } = require("@octokit/auth-app");
import { Octokit } from "@octokit/rest";
import { createAppAuth } from "@octokit/auth-app";

const appOctokit = new Octokit({
authStrategy: createAppAuth,
Expand Down
26 changes: 0 additions & 26 deletions docs/src/pages/api/02_previews.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/src/pages/api/03_request_formats.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ const { data: prDiff } = await octokit.rest.pulls.get({
});
```

The [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) interface can be used to abort one or more requests as and when desired. When the request is initiated, an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance can be passed as an option inside the request's options object. For usage in Node, the [`abort-controller`](https://github.com/mysticatea/abort-controller) package can be used.
The [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) interface can be used to abort one or more requests as and when desired. When the request is initiated, an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance can be passed as an option inside the request's options object.

```js
const controller = new AbortController();
Expand Down
80 changes: 19 additions & 61 deletions docs/src/pages/api/07_custom_endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,71 +2,29 @@
title: "Custom endpoint methods"
---

**Note**: `octokit.registerEndpoints()` has been deprecated.

Instead of
You can register custom endpoint methods such as `octokit.rest.repos.get()` by extending the octokit object

```js
await octokit.registerEndpoints({
misc: {
getRoot: {
method: "GET",
url: "/",
Object.assign(octokit.foo, {
bar: {
method: "PATCH",
url: "/repos/{owner}/{repo}/foo",
headers: {
accept: "application/vnd.github.foo-bar-preview+json",
},
},
});
```

do

```js
Object.assign(octokit.misc, {
getRoot: octokit.request.defaults({
method: "GET",
url: "/",
}),
});
```

If you use `octokit.registerEndpoints()` in a plugin, return an object instead:

```js
function myPlugin(octokit, options) {
return {
misc: {
octokit.request.defaults({ method: "GET", url: "/" })
}
}
}
```

---

You can register custom endpoint methods such as `octokit.rest.repos.get()` using the `octokit.registerEndpoints(routes)` method

```js
octokit.registerEndpoints({
foo: {
bar: {
method: "PATCH",
url: "/repos/{owner}/{repo}/foo",
headers: {
accept: "application/vnd.github.foo-bar-preview+json",
params: {
owner: {
required: true,
type: "string",
},
repo: {
required: true,
type: "string",
},
params: {
owner: {
required: true,
type: "string",
},
repo: {
required: true,
type: "string",
},
baz: {
required: true,
type: "string",
enum: ["qux", "quux", "quuz"],
},
baz: {
required: true,
type: "string",
enum: ["qux", "quux", "quuz"],
},
},
},
Expand Down
13 changes: 7 additions & 6 deletions docs/src/pages/api/08_plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ You can customize and extend Octokit’s functionality using plugins

```js
// index.js
const { Octokit } = require("@octokit/rest");
const MyOctokit = Octokit.plugin(
require("./lib/my-plugin"),
require("octokit-plugin-example"),
);
import { Octokit } from "@octokit/rest";
import myPlugin from "./lib/my-plugin.js";
import octokitPluginExample from "octokit-plugin-example";

const MyOctokit = Octokit.plugin(myPlugin, octokitPluginExample);

// lib/my-plugin.js
module.exports = (octokit, options = { greeting: "Hello" }) => {
const plugin = (octokit, options = { greeting: "Hello" }) => {
// hook into the request lifecycle
octokit.hook.wrap("request", async (request, options) => {
const time = Date.now();
Expand All @@ -31,6 +31,7 @@ module.exports = (octokit, options = { greeting: "Hello" }) => {
helloWorld: () => console.log(`${options.greeting}, world!`),
};
};
export default plugin;
```

`.plugin` accepts a function or an array of functions.
Expand Down
4 changes: 2 additions & 2 deletions docs/src/pages/api/09_throttling.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ The `throttle.onSecondaryRateLimit` and `throttle.onRateLimit` options are requi
Return `true` from these functions to automatically retry the request after `retryAfter` seconds. Return `false` or `undefined` to skip retry and throw the error. For rate limit errors, `retryAfter` defaults to seconds until `X-RateLimit-Reset`. For abuse errors, `retryAfter` defaults to the `retry-after` header but is a minimum of five seconds.

```js
const { Octokit } = require("@octokit/rest");
const { throttling } = require("@octokit/plugin-throttling");
import { Octokit } from "@octokit/rest";
import { throttling } from "@octokit/plugin-throttling";
const MyOctokit = Octokit.plugin(throttling);

const octokit = new MyOctokit({
Expand Down
4 changes: 2 additions & 2 deletions docs/src/pages/api/10_retries.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ title: "Automatic retries"
Many common request errors can be easily remediated by retrying the request. We recommend installing the [`@octokit/plugin-retry` plugin](https://github.com/octokit/plugin-retry.js) for Automatic retries in these cases

```js
const { Octokit } = require("@octokit/rest");
const { retry } = require("@octokit/plugin-retry");
import { Octokit } from "@octokit/rest";
import { retry } from "@octokit/plugin-retry";
const MyOctokit = Octokit.plugin(retry);

const octokit = new MyOctokit();
Expand Down
9 changes: 6 additions & 3 deletions docs/src/pages/api/12_debug.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ title: "Debug"
The simplest way to receive debug information is to set the `log` client option to `console`.

```js
const octokit = require("@octokit/rest")({
import { Octokit } from "@octokit/rest";
const octokit = new Octokit({
log: console,
});

Expand All @@ -29,8 +30,10 @@ GET / - 200 in 514ms
If you like to support a configurable log level, we recommend using the [console-log-level](https://github.com/watson/console-log-level) module

```js
const octokit = require("@octokit/rest")({
log: require("console-log-level")({ level: "info" }),
import { Octokit } from "@octokit/rest";
import consoleLogLevel from "console-log-level";
const octokit = new Octokit({
log: consoleLogLevel({ level: "info" }),
});

octokit.request("/");
Expand Down
7 changes: 0 additions & 7 deletions greenkeeper.json

This file was deleted.

Loading

0 comments on commit 12b6c65

Please sign in to comment.