feat: add http module

Author: joshunrau

src/__tests__/http.test.ts

@@ -0,0 +1,106 @@
+import type { Err } from 'neverthrow';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import * as datetime from '../datetime.js';
+import { safeFetch, waitForServer } from '../http.js';
+
+const fetch = vi.hoisted(() => vi.fn());
+const networkError = new Error('Network Error');
+
+vi.stubGlobal('fetch', fetch);
+
+afterEach(() => {
+  vi.resetAllMocks();
+});
+
+describe('safeFetch', () => {
+  it('should return an Ok result when the request succeeds', async () => {
+    const mockResponse = { ok: true, status: 200, statusText: 'OK' };
+    fetch.mockResolvedValueOnce(mockResponse);
+    const result = await safeFetch('http://localhost:6789', { method: 'GET' });
+    expect(result.isOk()).toBe(true);
+    if (result.isOk()) {
+      expect(result.value).toBe(mockResponse);
+    }
+  });
+
+  it('should return an Err result with HTTP_ERROR when the response is not ok', async () => {
+    const mockResponse = { ok: false, status: 404, statusText: 'Not Found' };
+    fetch.mockResolvedValueOnce(mockResponse);
+    const result = await safeFetch('http://localhost:6789', { method: 'GET' });
+    expect(result.isErr()).toBe(true);
+    if (result.isErr()) {
+      expect(result.error).toMatchObject({
+        details: {
+          kind: 'HTTP_ERROR',
+          status: 404,
+          statusText: 'Not Found',
+          url: 'http://localhost:6789'
+        },
+        name: 'FetchException'
+      });
+    }
+  });
+
+  it('should return an Err result with NETWORK_ERROR when fetch throws', async () => {
+    fetch.mockRejectedValueOnce(networkError);
+    const result = await safeFetch('http://localhost:6789', { method: 'GET' });
+    expect(result.isErr()).toBe(true);
+    if (result.isErr()) {
+      expect(result.error).toMatchObject({
+        cause: networkError,
+        details: {
+          kind: 'NETWORK_ERROR',
+          url: 'http://localhost:6789'
+        },
+        name: 'FetchException'
+      });
+    }
+  });
+
+  it('should pass through the RequestInit options to fetch', async () => {
+    const mockResponse = { ok: true, status: 200, statusText: 'OK' };
+    fetch.mockResolvedValueOnce(mockResponse);
+    const init = {
+      body: JSON.stringify({ test: 'data' }),
+      headers: { 'Content-Type': 'application/json' },
+      method: 'POST'
+    };
+    await safeFetch('http://localhost:6789', init);
+    expect(fetch).toHaveBeenCalledWith('http://localhost:6789', init);
+  });
+});
+
+describe('waitForServer', () => {
+  it('should return an Ok result when server becomes available', async () => {
+    fetch.mockRejectedValueOnce(networkError);
+    fetch.mockRejectedValueOnce(networkError);
+    fetch.mockResolvedValueOnce({ ok: true });
+    const time = Date.now();
+    const result = await waitForServer('http://localhost:6789', { interval: 0.1, timeout: 0.3 });
+    expect(result.isOk()).toBe(true);
+    expect(Date.now() - time).toBeGreaterThanOrEqual(200);
+    expect(Date.now() - time).toBeLessThan(300);
+    expect(fetch).toHaveBeenCalledTimes(3);
+  });
+
+  it('should return an Err result after the timeout if the server never becomes available', async () => {
+    fetch.mockRejectedValue(networkError);
+    const result = (await waitForServer('http://localhost:6789', { interval: 0.1, timeout: 0.3 })) as Err<void, Error>;
+    expect(result.error.message).toBe("Failed to connect to 'http://localhost:6789' after timeout of 0.3s");
+  });
+
+  it('should use a default timeout of 10 seconds and interval of 1 second', async () => {
+    fetch.mockRejectedValue(networkError);
+    vi.spyOn(datetime, 'sleep').mockResolvedValue();
+    const result = (await waitForServer('http://localhost:6789')) as Err<void, Error>;
+    expect(result.error.message).toBe("Failed to connect to 'http://localhost:6789' after timeout of 10s");
+    expect(fetch).toHaveBeenCalledTimes(10);
+  });
+
+  it('should return an Err result if the HTTP request succeeds, but is not a 200-level response', async () => {
+    fetch.mockResolvedValueOnce({ ok: false, status: 500 });
+    const result = (await waitForServer('http://localhost:6789', { interval: 0.1, timeout: 0.3 })) as Err<void, Error>;
+    expect(result.error.message).toBe("Request to 'http://localhost:6789' returned status code 500");
+  });
+});

src/http.ts

@@ -0,0 +1,83 @@
+import { ok, ResultAsync } from 'neverthrow';
+
+import { sleep } from './datetime.js';
+import { ExceptionBuilder, RuntimeException } from './exception.js';
+import { asyncResultify } from './result.js';
+
+import type { ExceptionLike } from './exception.js';
+
+type NetworkErrorOptions = {
+  cause: unknown;
+  details: {
+    kind: 'NETWORK_ERROR';
+    url: string;
+  };
+};
+
+type HttpErrorOptions = {
+  details: {
+    kind: 'HTTP_ERROR';
+    status: number;
+    statusText: string;
+    url: string;
+  };
+};
+
+export const { FetchException } = new ExceptionBuilder()
+  .setOptionsType<HttpErrorOptions | NetworkErrorOptions>()
+  .setParams({
+    message: (details) => `HTTP request to '${details.url}' failed`,
+    name: 'FetchException'
+  })
+  .build();
+
+export function safeFetch(url: string, init: RequestInit): ResultAsync<Response, typeof FetchException.Instance> {
+  return asyncResultify(async () => {
+    try {
+      const response = await fetch(url, init);
+      if (response.ok) {
+        return ok(response);
+      }
+      return FetchException.asErr({
+        details: {
+          kind: 'HTTP_ERROR',
+          status: response.status,
+          statusText: response.statusText,
+          url
+        }
+      });
+    } catch (err) {
+      return FetchException.asErr({
+        cause: err,
+        details: {
+          kind: 'NETWORK_ERROR',
+          url
+        }
+      });
+    }
+  });
+}
+
+export function waitForServer(
+  url: string,
+  { interval = 1, timeout = 10 }: { interval?: number; timeout?: number } = {}
+): ResultAsync<void, ExceptionLike> {
+  return asyncResultify(async () => {
+    let secondsElapsed = 0;
+    while (secondsElapsed < timeout) {
+      const fetchResult = await safeFetch(url, { method: 'GET' });
+      if (fetchResult.isOk()) {
+        return ok();
+      }
+      const { error } = fetchResult;
+      if (error.details.kind === 'HTTP_ERROR') {
+        return RuntimeException.asErr(`Request to '${url}' returned status code ${error.details.status}`, {
+          cause: fetchResult.error
+        });
+      }
+      await sleep(interval);
+      secondsElapsed += interval;
+    }
+    return RuntimeException.asErr(`Failed to connect to '${url}' after timeout of ${timeout}s`);
+  });
+}