@autometa/http 1.2.0 → 1.3.0

package/src/http-request.spec.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import { HTTPRequest, HTTPRequestBuilder } from "./http-request";
+
+describe("HTTP Request", () => {
+  it("should derive a detailed request", () => {
+    const request = new HTTPRequest();
+    request.baseUrl = "https://example.com";
+    request.route.push("foo", "bar");
+    request.params = { foo: "bar" };
+    request.data = { foo: "bar" };
+    request.headers = { foo: "bar" };
+    request.method = "GET";
+
+    const derived = HTTPRequest.derive(request);
+    expect(derived).toEqual({
+      baseUrl: "https://example.com",
+      route: ["foo", "bar"],
+      params: { foo: "bar" },
+      data: { foo: "bar" },
+      headers: { foo: "bar" },
+      method: "GET"
+    });
+  });
+
+  describe("HTTPRequestBuilder", () => {
+    it("should build a request from a base", () => {
+      const request = new HTTPRequest();
+      request.baseUrl = "https://example.com";
+      request.route.push("foo", "bar");
+      request.params = { foo: "bar" };
+      request.data = { foo: "bar" };
+      request.headers = { foo: "bar" };
+      request.method = "GET";
+      const builder = new HTTPRequestBuilder(request);
+      expect(builder.request).toEqual(request);
+    });
+
+    it("should build a request from scratch", () => {
+      const builder = new HTTPRequestBuilder()
+        .url("https://example.com")
+        .route("foo", "bar")
+        .param("foo", "bar")
+        .data({ foo: "bar" })
+        .header("foo", "bar")
+        .method("GET");
+      expect(builder.request).toEqual({
+        baseUrl: "https://example.com",
+        route: ["foo", "bar"],
+        params: { foo: "bar" },
+        data: { foo: "bar" },
+        headers: { foo: "bar" },
+        method: "GET"
+      });
+    });
+
+    it("should derive a request builder", () => {
+      const builder = new HTTPRequestBuilder()
+        .url("https://example.com")
+        .route("foo", "bar")
+        .param("foo", "bar")
+        .data({ foo: "bar" })
+        .header("foo", "bar")
+        .method("GET");
+      const derived = builder.derive();
+      expect(derived.request).toEqual(builder.request);
+      expect(derived.request).not.toBe(builder.request);
+    });
+  });
+
+  describe("build", () => {
+    it("should build a request", () => {
+      const request = new HTTPRequestBuilder()
+        .url("https://example.com")
+        .route("foo", "bar")
+        .param("foo", "bar")
+        .data({ foo: "bar" })
+        .header("foo", "bar")
+        .method("GET")
+        .build();
+      expect(request).toEqual({
+        baseUrl: "https://example.com",
+        route: ["foo", "bar"],
+        params: { foo: "bar" },
+        data: { foo: "bar" },
+        headers: { foo: "bar" },
+        method: "GET"
+      });
+    });
+  });
+
+  describe("paramList", () => {
+    it("should build a request with a list of params", () => {
+      const request = new HTTPRequestBuilder()
+        .url("https://example.com")
+        .route("foo", "bar")
+        .param("foo", ["bar", "baz"])
+        .data({ foo: "bar" })
+        .header("foo", "bar")
+        .method("GET")
+        .build();
+      expect(request).toEqual({
+        baseUrl: "https://example.com",
+        route: ["foo", "bar"],
+        params: { foo: ["bar", "baz"] },
+        data: { foo: "bar" },
+        headers: { foo: "bar" },
+        method: "GET"
+      });
+    });
+  });
+
+  describe("fullUrl", () => {
+    it("should have a full url with routes", () => {
+      const request = new HTTPRequestBuilder()
+        .url("https://example.com")
+        .route("foo")
+        .build()
+        .fullUrl();
+      expect(request).toEqual("https://example.com/foo");
+    });
+    it("should have a full url with routes and params", () => {
+      const request = new HTTPRequestBuilder()
+        .url("https://example.com")
+        .route("foo")
+        .param("gru", "bar")
+        .build()
+        .fullUrl();
+      expect(request).toEqual("https://example.com/foo?gru=bar");
+    });
+
+    it("should have a full url with a route and a param list", () => {
+      const request = new HTTPRequestBuilder()
+        .url("https://example.com")
+        .route("foo")
+        .param("bob", ["bar", "baz"])
+        .build()
+        .fullUrl();
+      expect(request).toEqual("https://example.com/foo?bob=bar%2Cbaz");
+    });
+  });
+});

package/src/http-request.ts

@@ -0,0 +1,164 @@
+import { RequestConfig, RequestConfigBasic } from "./request.config";
+import { HTTPMethod } from "./types";
+import { urlJoinP } from "url-join-ts";
+export class HTTPRequest<T = unknown> implements RequestConfig<T> {
+  headers: Record<string, string> = {};
+  params: Record<string, string | string[] | Record<string, unknown>> = {};
+  baseUrl?: string;
+  route: string[] = [];
+  method: HTTPMethod;
+  data: T;
+
+  constructor(config?: RequestConfigBasic) {
+    Object.assign(this, config);
+  }
+
+  /**
+   * Returns the full URL of the request, including the base url,
+   * routes, and query parameters.
+   *
+   * ```ts
+   *  console.log(request.fullUrl())// https://example.com/foo?bar=baz?array=1,2,3
+   * ```
+   *
+   * Note characters may be converted to escape codes. I.e (space => %20) and (comma => %2C)
+   *
+   * N.B this method estimates what the url will be. The actual value
+   * might be different depending on your underlying HTTPClient and
+   * configuration. For example, query parameters might
+   * use different array formats.
+   */
+  fullUrl() {
+    return urlJoinP(this.baseUrl, this.route, this.params);
+  }
+
+  /**
+   * Returns a new independent copy of the request.
+   */
+  static derive(original: HTTPRequest<unknown>) {
+    const request = new HTTPRequest();
+    request.headers = { ...original.headers };
+    request.params = { ...original.params };
+    request.baseUrl = original.baseUrl;
+    request.route = [...original.route];
+    request.method = original.method;
+    request.data = original.data;
+    return request;
+  }
+}
+
+export class HTTPRequestBuilder<T extends HTTPRequest<unknown>> {
+  #request: T;
+  #dynamicHeaders = new Map<string, () => string | number | boolean | null>();
+
+  constructor(request: T | (() => T) = () => new HTTPRequest() as T) {
+    if (typeof request === "function") {
+      this.#request = request();
+      return;
+    }
+    this.#request = request;
+  }
+
+  static create<T extends HTTPRequest<unknown>>() {
+    return new HTTPRequestBuilder<T>();
+  }
+
+  get request() {
+    return this.#request;
+  }
+
+  resolveDynamicHeaders() {
+    for (const [name, value] of this.#dynamicHeaders) {
+      try {
+        this.#request.headers[name] = String(value());
+      } catch (e) {
+        const cause = e as Error;
+        const msg = `Failed to resolve dynamic header "${name}": 
+${cause}`;
+        throw new Error(msg);
+      }
+    }
+    return this;
+  }
+
+  url(url: string) {
+    this.#request.baseUrl = url;
+    return this;
+  }
+
+  route(...route: string[]) {
+    this.#request.route.push(...route);
+    return this;
+  }
+
+  param(
+    name: string,
+    value:
+      | string
+      | number
+      | boolean
+      | (string | number | boolean)[]
+      | Record<string, string | number | boolean>
+  ) {
+    if (Array.isArray(value)) {
+      const asStr = value.map(String);
+      this.#request.params[name] = asStr;
+      return this;
+    }
+    if (!Array.isArray(value) && typeof value === "object") {
+      this.#request.params[name] = value;
+      return this;
+    }
+    this.#request.params[name] = String(value);
+    return this;
+  }
+
+  params(dict: Record<string, unknown>) {
+    Object.assign(this.#request.params, dict);
+    return this;
+  }
+
+  data<T>(data: T) {
+    this.#request.data = data;
+    return this;
+  }
+
+  header(
+    name: string,
+    value:
+      | string
+      | number
+      | boolean
+      | null
+      | (() => string | number | boolean | null)
+  ) {
+    if (typeof value === "function") {
+      value = value();
+    }
+    this.#request.headers[name] = String(value);
+    return this;
+  }
+
+  headers(dict: Record<string, string>) {
+    Object.assign(this.#request.headers, dict);
+    return this;
+  }
+
+  get() {
+    return this.#request;
+  }
+
+  method(method: HTTPMethod) {
+    this.#request.method = method;
+    return this;
+  }
+
+  derive(): HTTPRequestBuilder<T> {
+    const request = HTTPRequest.derive(this.#request);
+    return new HTTPRequestBuilder(request) as HTTPRequestBuilder<T>;
+  }
+
+  build(): HTTPRequest<T> {
+    return this.#request as HTTPRequest<T>;
+  }
+}

package/src/http-response.ts

@@ -0,0 +1,107 @@
+import { HTTPRequest } from "./http-request";
+import { StatusCode } from "./types";
+
+export class HTTPResponse<T = unknown> {
+  status: StatusCode;
+  statusText: string;
+  data: T;
+  headers: Record<string, string>;
+  request: HTTPRequest<unknown>;
+
+  constructor() {
+    this.headers = {};
+  }
+
+  static fromRaw<T>(response: HTTPResponse<T>) {
+    const newResponse = new HTTPResponse<T>();
+    Object.assign(newResponse, response);
+    return response;
+  }
+
+  /**
+   * Decomposes a response, creating an exact copy of the current response,
+   * but with a new data value. The data can be provided directly as is, or it
+   * can be generated through a callback function which receives the current
+   * response data as an argument.
+   *
+   * ```ts
+   * const response = await http.get("/products");
+   *
+   * // direct value
+   * const products = response.data;
+   * const firstProduct = response.decompose(products[0]);
+   * // callback transformer
+   * const secondProduct = response.decompose((products) => products[1]);
+   * // callback transformer with destructuring
+   * const secondProduct = response.decompose(([product]) => product);
+   * ```
+   * @param value 
+   */
+  decompose<K>(value: K): HTTPResponse<K>;
+  decompose<K>(transformFn: (response: T) => K): HTTPResponse<K>;
+  decompose<K>(transformFn: K | ((response: T) => K)): HTTPResponse<K> {
+    const value = getDecompositionValue<T>(this.data, transformFn);
+    return new HTTPResponseBuilder()
+      .status(this.status)
+      .statusText(this.statusText)
+      .headers(this.headers)
+      .request(this.request)
+      .data(value)
+      .build() as HTTPResponse<K>;
+  }
+}
+
+function getDecompositionValue<T>(data: unknown, transformFn: unknown): T {
+  return typeof transformFn === "function" ? transformFn(data) : transformFn;
+}
+
+export class HTTPResponseBuilder {
+  #response = new HTTPResponse();
+
+  static create() {
+    return new HTTPResponseBuilder();
+  }
+
+  derive() {
+    return HTTPResponseBuilder.create()
+      .data(this.#response.data)
+      .headers(this.#response.headers)
+      .request(this.#response.request)
+      .status(this.#response.status)
+      .statusText(this.#response.statusText);
+  }
+
+  status(code: StatusCode) {
+    this.#response.status = code;
+    return this;
+  }
+
+  statusText(text: string) {
+    this.#response.statusText = text;
+    return this;
+  }
+
+  data<T>(data: T) {
+    this.#response.data = data;
+    return this;
+  }
+
+  headers(dict: Record<string, string>) {
+    this.#response.headers = dict;
+    return this;
+  }
+
+  header(name: string, value: string) {
+    this.#response.headers[name] = value;
+    return this;
+  }
+
+  request(request: HTTPRequest<unknown>) {
+    this.#response.request = request;
+    return this;
+  }
+
+  build() {
+    return this.#response;
+  }
+}

package/src/http.spec.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi } from "vitest";
+import { HTTP } from "./http";
+import { HTTPClient } from "./http-client";
+import { HTTPRequest, HTTPRequestBuilder } from "./http-request";
+import { HTTPResponse, HTTPResponseBuilder } from "./http-response";
+import { HTTPAdditionalOptions } from "./types";
+
+describe("HTTP", () => {
+  describe("create", () => {
+    it("should create a new instance of the HTTP Client", () => {
+      const client = HTTP.create();
+      expect(client).toBeInstanceOf(HTTP);
+    });
+  });
+  class MockClient extends HTTPClient {
+    constructor(readonly testFn: ReturnType<typeof vi.fn>) {
+      super();
+    }
+    async request<TRequestType, TResponseType>(
+      request: HTTPRequest<TRequestType>,
+      options?: HTTPAdditionalOptions<unknown> | undefined
+    ): Promise<HTTPResponse<TResponseType>> {
+      return this.testFn(request, options) as HTTPResponse<TResponseType>;
+    }
+  }
+  describe("allowPlainText", () => {
+    it("should throw an error when allowPlainText is false", async () => {
+      const response = HTTPResponseBuilder.create().data("Hello World").build();
+      const fn = vi.fn().mockReturnValue(response);
+      const client = new MockClient(fn);
+      const http = new HTTP(client).allowPlainText(false);
+      await expect(() => http.get()).rejects.toThrowError(
+        `Could not parse a response as json, and this request was not configured to allow plain text responses.
+To allow plain text responses, use the 'allowPlainText' method on the HTTP client.
+
+Hello World`
+      );
+    });
+
+    it("should return the response when allowPlainText is true", async () => {
+      const response = HTTPResponseBuilder.create().data("Hello World").build();
+      const fn = vi.fn().mockReturnValue(response);
+      const client = new MockClient(fn);
+      const http = new HTTP(client).allowPlainText(true);
+      const result = await http.get();
+      expect(result).toBe(response);
+    });
+
+    it("should return a new HTTP instance", () => {
+      const response = HTTPResponseBuilder.create().data("Hello World").build();
+      const fn = vi.fn().mockReturnValue(response);
+      const client = new MockClient(fn);
+      const http = new HTTP(client).allowPlainText(true);
+      const result = http.allowPlainText(false);
+      expect(result).toBeInstanceOf(HTTP);
+      expect(result).not.toBe(http);
+    });
+  });
+
+  describe("hooks", () => {
+    describe("onSend", () => {
+      it("should call the hook when the request is sent", async () => {
+        const request = HTTPRequestBuilder.create()
+          .url(undefined as unknown as string)
+          .method("GET")
+          .data(undefined as unknown as string)
+          .build();
+        const response = HTTPResponseBuilder.create().build();
+        const fn = vi.fn().mockReturnValue(response);
+        const hook = vi
+          .fn()
+          .mockImplementation((data: HTTPResponse<unknown>) => {
+            expect(data).toStrictEqual(request);
+          });
+        const client = new MockClient(fn);
+        const http = new HTTP(client).onSend("test hook", hook);
+        await http.get();
+        expect(hook).toHaveBeenCalledWith(request);
+      });
+
+      it("should propagate errors from the hook", async () => {
+        const response = HTTPResponseBuilder.create().build();
+        const fn = vi.fn().mockReturnValue(response);
+        const hook = vi.fn().mockImplementation((_: HTTPResponse<unknown>) => {
+          throw new Error("test error");
+        });
+        const client = new MockClient(fn);
+        const http = new HTTP(client).onSend("test hook", hook);
+        await expect(() => http.get()).rejects.toThrowError(
+          "An error occurred while sending a request in hook: 'test hook'"
+        );
+      });
+    });
+
+    describe("onReceive", () => {
+      it("should call the hook when the response is received", async () => {
+        const response = HTTPResponseBuilder.create().build();
+        const fn = vi.fn().mockReturnValue(response);
+        const hook = vi
+          .fn()
+          .mockImplementation((data: HTTPResponse<unknown>) => {
+            expect(data).toStrictEqual(response);
+          });
+        const client = new MockClient(fn);
+        const http = new HTTP(client).onReceive("test hook", hook);
+        await http.get();
+        expect(hook).toHaveBeenCalledWith(response);
+      });
+
+      it("should propagate errors from the hook", async () => {
+        const response = HTTPResponseBuilder.create().build();
+        const fn = vi.fn().mockReturnValue(response);
+        const hook = vi.fn().mockImplementation((_: HTTPResponse<unknown>) => {
+          throw new Error("test error");
+        });
+        const client = new MockClient(fn);
+        const http = new HTTP(client).onReceive("test hook", hook);
+        await expect(() => http.get()).rejects.toThrowError(
+          "An error occurred while receiving a response in hook: 'test hook'"
+        );
+      });
+    });
+  });
+
+  describe("schemas", () => {
+    it("should throw an error if there is no schema and requireSchema is true", () => {
+      const response = HTTPResponseBuilder.create().status(200).build();
+      const fn = vi.fn().mockReturnValue(response);
+      const client = new MockClient(fn);
+      const http = new HTTP(client).requireSchema(true);
+      expect(() => http.get()).rejects.toThrowError(
+        `No parser registered for status code 200 but 'requireSchema' is true`
+      );
+    });
+
+    it("should throw an error if the response status does not match a schema", () => {
+      const response = HTTPResponseBuilder.create().status(200).build();
+      const fn = vi.fn().mockReturnValue(response);
+      const client = new MockClient(fn);
+      const http = new HTTP(client).requireSchema(true).schema(vi.fn(), 400);
+      expect(() => http.get()).rejects.toThrowError(
+        `No parser registered for status code 200 but 'requireSchema' is true`
+      );
+    });
+
+    it("should return the response if the status matches a schema", async () => {
+      const response = HTTPResponseBuilder.create().status(200).build();
+      const fn = vi.fn().mockReturnValue(response);
+      const client = new MockClient(fn);
+      const http = new HTTP(client).requireSchema(true).schema(vi.fn(), 200);
+      const result = await http.get();
+      expect(result).toBe(response);
+    });
+
+    it("should return the validated response if the status matches a schema", async () => {
+      const response = HTTPResponseBuilder.create().status(200).data("FooBar");
+      const validated = response.derive().data("Hello World").build();
+      const fn = vi.fn().mockReturnValue(response.build());
+      const client = new MockClient(fn);
+      const schema = vi.fn().mockReturnValue(validated);
+      const http = new HTTP(client)
+        .requireSchema(true)
+        .allowPlainText(true)
+        .schema(schema, 200);
+      const { data } = await http.get();
+      expect(data).toBe(validated);
+    });
+  });
+});