Merge pull request #8 from DouglasNeuroInformatics/dev

add new functions

Author: joshunrau

eslint.config.js

@@ -1,10 +1,8 @@
 import { config } from '@douglasneuroinformatics/eslint-config';
 
-export default config(
-  {},
-  {
-    rules: {
-      '@typescript-eslint/explicit-function-return-type': 'error'
-    }
+export default config({
+  typescript: {
+    enabled: true,
+    explicitReturnTypes: true
   }
-);
+});

package.json

@@ -40,7 +40,7 @@
     "type-fest": "^4.34.1"
   },
   "devDependencies": {
-    "@douglasneuroinformatics/eslint-config": "^5.3.1",
+    "@douglasneuroinformatics/eslint-config": "^5.3.2",
     "@douglasneuroinformatics/prettier-config": "^0.0.1",
     "@douglasneuroinformatics/semantic-release": "^0.2.1",
     "@douglasneuroinformatics/tsconfig": "^1.0.2",

pnpm-lock.yaml

@@ -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/__tests__/http.test.ts

@@ -0,0 +1,31 @@
+import { Err, err, Ok, ok } from 'neverthrow';
+import { describe, expect, it } from 'vitest';
+
+import { asyncResultify } from '../result.js';
+
+describe('asyncResultify', () => {
+  it('should convert a successful Result to ResultAsync', async () => {
+    const fn = () => Promise.resolve(ok(42));
+    const result = (await asyncResultify(fn)) as Ok<number, never>;
+    expect(result.isOk()).toBe(true);
+    expect(result.value).toBe(42);
+  });
+
+  it('should convert an error Result to ResultAsync', async () => {
+    const error = new Error('test error');
+    const fn = () => Promise.resolve(err(error));
+    const result = (await asyncResultify(fn)) as Err<never, Error>;
+    expect(result.isErr()).toBe(true);
+    expect(result.error).toBe(error);
+  });
+
+  it('should handle async operations correctly', async () => {
+    const fn = async () => {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return ok('delayed result');
+    };
+    const result = (await asyncResultify(fn)) as Ok<string, never>;
+    expect(result.isOk()).toBe(true);
+    expect(result.value).toBe('delayed result');
+  });
+});

src/__tests__/result.test.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/consistent-type-definitions */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable no-dupe-class-members */
 
@@ -55,7 +56,17 @@ type ExceptionType<
   TStaticProps = unknown
 > = ExceptionConstructor<TParams, TOptions> & ExceptionStatic<TParams, TOptions> & TStaticProps;
 
-abstract class BaseException<TParams extends ExceptionParams, TOptions extends ExceptionOptions> extends Error {
+interface ExceptionLike extends Error, ExceptionOptions {
+  name: string;
+  toAsyncErr(): ResultAsync<never, this>;
+  toErr(): Result<never, this>;
+  toString(): string;
+}
+
+abstract class BaseException<TParams extends ExceptionParams, TOptions extends ExceptionOptions>
+  extends Error
+  implements ExceptionLike
+{
   override cause: TOptions['cause'];
   details: TOptions['details'];
   abstract override name: TParams['name'];
@@ -206,6 +217,7 @@ export const { ValidationException } = new ExceptionBuilder()
 export type {
   ExceptionConstructor,
   ExceptionConstructorArgs,
+  ExceptionLike,
   ExceptionName,
   ExceptionOptions,
   ExceptionParams,

src/exception.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`);
+  });
+}

src/http.ts

@@ -1,11 +1,13 @@
 export * from './array.js';
 export * from './datetime.js';
 export * from './exception.js';
+export * from './http.js';
 export * from './json.js';
 export * from './number.js';
 export * from './object.js';
 export * from './random.js';
 export * from './range.js';
+export * from './result.js';
 export * from './string.js';
 export * from './types.js';
 export * from './zod.js';

src/index.ts

@@ -0,0 +1,5 @@
+import { Result, ResultAsync } from 'neverthrow';
+
+export function asyncResultify<T, E>(fn: () => Promise<Result<T, E>>): ResultAsync<T, E> {
+  return new ResultAsync(fn());
+}

src/result.ts

@@ -11,7 +11,8 @@ export default defineConfig({
         functions: 100,
         lines: 100,
         statements: 100
-      }
+      },
+      skipFull: true
     },
     watch: false
   }