feat: RestApiClient example

Author: gr2m

examples/rest-api-client-dts/README.md

@@ -0,0 +1,20 @@
+# Custom class with defaults and plugins (TypeScript Declaration example)
+
+This example does not implement any code, it's meant as a reference for types only.
+
+Usage example:
+
+```js
+import { RestApiClient } from "javascript-plugin-architecture-with-typescript-definitions/examples/rest-api-client-dts";
+
+const client = new RestApiClient({
+  baseUrl: "https://api.github.com",
+  userAgent: "my-app/1.0.0",
+  headers: {
+    authorization: "token ghp_aB3...",
+  },
+});
+
+const { data } = await client.request("GET /user");
+console.log("You are logged in as %s", data.login);
+```

examples/rest-api-client-dts/index.d.ts

@@ -0,0 +1,9 @@
+import { Base } from "../../index.js";
+
+import { requestPlugin } from "./request-plugin.js";
+
+declare type Constructor<T> = new (...args: any[]) => T;
+
+export class RestApiClient extends Base {
+  request: ReturnType<typeof requestPlugin>["request"];
+}

examples/rest-api-client-dts/index.js

@@ -0,0 +1,5 @@
+import { Base } from "../../index.js";
+
+export const RestApiClient = Base.withPlugins([requestPlugin]).withDefaults({
+  userAgent: "rest-api-client/1.0.0",
+});

examples/rest-api-client-dts/index.test-d.ts

@@ -0,0 +1,45 @@
+import { expectType } from "tsd";
+
+import { RestApiClient } from "./index.js";
+
+// @ts-expect-error - An argument for 'options' was not provided
+new RestApiClient();
+
+expectType<{ userAgent: string }>(RestApiClient.defaults);
+
+// @ts-expect-error - Type '{}' is missing the following properties from type 'Options': myRequiredUserOption
+new RestApiClient({});
+
+new RestApiClient({
+  baseUrl: "https://api.github.com",
+  userAgent: "my-app/v1.0.0",
+});
+
+export async function test() {
+  const client = new RestApiClient({
+    baseUrl: "https://api.github.com",
+    headers: {
+      authorization: "token 123456789",
+    },
+  });
+
+  expectType<
+    Promise<{
+      status: number;
+      headers: Record<string, string>;
+      data?: Record<string, unknown>;
+    }>
+  >(client.request(""));
+
+  const getUserResponse = await client.request("GET /user");
+  expectType<{
+    status: number;
+    headers: Record<string, string>;
+    data?: Record<string, unknown>;
+  }>(getUserResponse);
+
+  client.request("GET /repos/{owner}/{repo}", {
+    owner: "gr2m",
+    repo: "javascript-plugin-architecture-with-typescript-definitions",
+  });
+}

examples/rest-api-client-dts/request-plugin.d.ts

@@ -0,0 +1,48 @@
+import { Base } from "../../index.js";
+
+declare module "../.." {
+  namespace Base {
+    interface Options {
+      /**
+       * Base URL for all http requests
+       */
+      baseUrl: string;
+
+      /**
+       * Set a custom user agent. Defaults to "rest-api-client/1.0.0"
+       */
+      userAgent?: string;
+
+      /**
+       * Optional http request headers that will be set on all requsets
+       */
+      headers?: {
+        authorization?: string;
+        accept?: string;
+        [key: string]: string | undefined;
+      };
+    }
+  }
+}
+
+interface Response {
+  status: number;
+  headers: Record<string, string>;
+  data?: Record<string, unknown>;
+}
+
+interface Parameters {
+  headers?: Record<string, string>;
+  [parameter: string]: unknown;
+}
+
+interface RequestInterface {
+  (route: string, parameters?: Parameters): Promise<Response>;
+}
+
+export declare function requestPlugin(
+  base: Base,
+  options: Base.Options
+): {
+  request: RequestInterface;
+};

examples/rest-api-client-dts/request-plugin.js

@@ -0,0 +1,12 @@
+/**
+ * This example does not implement any logic, it's just meant as
+ * a reference for its types
+ *
+ * @param {Base} base
+ * @param {Base.Options} options
+ */
+export function requestPlugin(base, options) {
+  return {
+    async request(route, parameters) {},
+  };
+}