Merge pull request #7 from DouglasNeuroInformatics/neverthrow

implement neverthrow in libjs

Author: joshunrau

eslint.config.js

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

package.json

@@ -30,6 +30,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "neverthrow": "^8.2.0",
     "type-fest": "^4.34.1",
     "zod": "^3.22.6"
   },

pnpm-lock.yaml

@@ -59,10 +59,12 @@ describe('sleep', () => {
 
 describe('parseDuration', () => {
   it('should fail to parse a negative duration', () => {
-    expect(() => parseDuration(-1)).toThrow('Cannot parse negative length of time: -1');
+    const result = parseDuration(-1);
+    expect(result.isErr());
   });
   it('should parse a duration of zero', () => {
-    expect(parseDuration(0)).toEqual({
+    const result = parseDuration(0);
+    expect(result.isOk() && result.value).toEqual({
       days: 0,
       hours: 0,
       milliseconds: 0,
@@ -71,14 +73,16 @@ describe('parseDuration', () => {
     });
   });
   it('should parse a duration less than a second', () => {
-    expect(parseDuration(50)).toEqual({
+    let result = parseDuration(50);
+    expect(result.isOk() && result.value).toEqual({
       days: 0,
       hours: 0,
       milliseconds: 50,
       minutes: 0,
       seconds: 0
     });
-    expect(parseDuration(500)).toEqual({
+    result = parseDuration(500);
+    expect(result.isOk() && result.value).toEqual({
       days: 0,
       hours: 0,
       milliseconds: 500,
@@ -87,7 +91,8 @@ describe('parseDuration', () => {
     });
   });
   it('should parse a duration less than one minute but more than one second', () => {
-    expect(parseDuration(11_100)).toEqual({
+    const result = parseDuration(11_100);
+    expect(result.isOk() && result.value).toEqual({
       days: 0,
       hours: 0,
       milliseconds: 100,
@@ -96,24 +101,26 @@ describe('parseDuration', () => {
     });
   });
   it('should parse a duration less than one hour but more than one minute', () => {
-    expect(parseDuration(60_000)).toEqual({
+    let result = parseDuration(60_000);
+    expect(result.isOk() && result.value).toEqual({
       days: 0,
       hours: 0,
       milliseconds: 0,
       minutes: 1,
       seconds: 0
     });
-    expect(parseDuration(62_500)).toEqual({
+    result = parseDuration(62_500);
+    expect(result.isOk() && result.value).toEqual({
       days: 0,
       hours: 0,
       milliseconds: 500,
       minutes: 1,
       seconds: 2
     });
   });
-
   it('should parse a duration less than one day but more than one hour', () => {
-    expect(parseDuration(3_600_000)).toEqual({
+    const result = parseDuration(3_600_000);
+    expect(result.isOk() && result.value).toEqual({
       days: 0,
       hours: 1,
       milliseconds: 0,
@@ -122,14 +129,16 @@ describe('parseDuration', () => {
     });
   });
   it('should parse a duration greater than one day', () => {
-    expect(parseDuration(86_400_000)).toEqual({
+    let result = parseDuration(86_400_000);
+    expect(result.isOk() && result.value).toEqual({
       days: 1,
       hours: 0,
       milliseconds: 0,
       minutes: 0,
       seconds: 0
     });
-    expect(parseDuration(4_351_505_030)).toEqual({
+    result = parseDuration(4_351_505_030);
+    expect(result.isOk() && result.value).toEqual({
       days: 50,
       hours: 8,
       milliseconds: 30,

src/__tests__/datetime.test.ts

@@ -1,9 +1,9 @@
 import type { Simplify } from 'type-fest';
 import { describe, expect, expectTypeOf, it, test } from 'vitest';
 
-import { BaseException, ExceptionBuilder } from '../exception.js';
+import { BaseException, ExceptionBuilder, OutOfRangeException, ValueException } from '../exception.js';
 
-import type { ExceptionConstructor, ExceptionInstance } from '../exception.js';
+import type { ExceptionConstructor } from '../exception.js';
 
 type ExceptionOptionsWithCode = Simplify<ErrorOptions & { details: { code: number } }>;
 type ExceptionOptionsWithCause = Simplify<ErrorOptions & { cause: Error }>;
@@ -13,31 +13,28 @@ type ExceptionParams = { name: 'TestException' };
 type ExceptionParamsWithMessage = Simplify<ExceptionParams & { message: string }>;
 
 test('ExceptionConstructor', () => {
-  expectTypeOf<ExceptionConstructor<ExceptionParams, ErrorOptions>>().toEqualTypeOf<
-    new (message?: string, options?: ErrorOptions) => ExceptionInstance<ExceptionParams, ErrorOptions>
+  expectTypeOf<ExceptionConstructor<ExceptionParams, ErrorOptions>>().toMatchTypeOf<
+    new (message?: string, options?: ErrorOptions) => BaseException<ExceptionParams, ErrorOptions>
   >();
-  expectTypeOf<ExceptionConstructor<ExceptionParams, ExceptionOptionsWithCode>>().toEqualTypeOf<
-    new (
-      message: string,
-      options: ExceptionOptionsWithCode
-    ) => ExceptionInstance<ExceptionParams, ExceptionOptionsWithCode>
+  expectTypeOf<ExceptionConstructor<ExceptionParams, ExceptionOptionsWithCode>>().toMatchTypeOf<
+    new (message: string, options: ExceptionOptionsWithCode) => BaseException<ExceptionParams, ExceptionOptionsWithCode>
   >();
-  expectTypeOf<ExceptionConstructor<ExceptionParams, ExceptionOptionsWithCause>>().toEqualTypeOf<
+  expectTypeOf<ExceptionConstructor<ExceptionParams, ExceptionOptionsWithCause>>().toMatchTypeOf<
     new (
       message: string,
       options: ExceptionOptionsWithCause
-    ) => ExceptionInstance<ExceptionParams, ExceptionOptionsWithCause>
+    ) => BaseException<ExceptionParams, ExceptionOptionsWithCause>
   >();
-  expectTypeOf<ExceptionConstructor<ExceptionParams, ExceptionOptionsWithCodeAndCause>>().toEqualTypeOf<
+  expectTypeOf<ExceptionConstructor<ExceptionParams, ExceptionOptionsWithCodeAndCause>>().toMatchTypeOf<
     new (
       message: string,
       options: ExceptionOptionsWithCodeAndCause
-    ) => ExceptionInstance<ExceptionParams, ExceptionOptionsWithCodeAndCause>
+    ) => BaseException<ExceptionParams, ExceptionOptionsWithCodeAndCause>
   >();
-  expectTypeOf<ExceptionConstructor<ExceptionParamsWithMessage, ExceptionOptionsWithCodeAndCause>>().toEqualTypeOf<
+  expectTypeOf<ExceptionConstructor<ExceptionParamsWithMessage, ExceptionOptionsWithCodeAndCause>>().toMatchTypeOf<
     new (
       options: ExceptionOptionsWithCodeAndCause
-    ) => ExceptionInstance<ExceptionParamsWithMessage, ExceptionOptionsWithCodeAndCause>
+    ) => BaseException<ExceptionParamsWithMessage, ExceptionOptionsWithCodeAndCause>
   >();
 });
 
@@ -58,12 +55,12 @@ describe('BaseException', () => {
 
 describe('ExceptionBuilder', () => {
   it('should return never for the build method if no name is specified', () => {
-    const fn = () => new ExceptionBuilder().build();
+    const fn = (): never => new ExceptionBuilder().build();
     expect(fn).toThrow('Cannot build exception: params is undefined');
     expectTypeOf<ReturnType<typeof fn>>().toBeNever();
   });
   it('should build an exception with the provided name and message', () => {
-    const TestException = new ExceptionBuilder().setParams({ name: 'TestException' }).build();
+    const { TestException } = new ExceptionBuilder().setParams({ name: 'TestException' }).build();
     expect(Object.getPrototypeOf(TestException)).toBe(BaseException);
     expectTypeOf<Pick<InstanceType<typeof TestException>, 'name'>>().toEqualTypeOf<{ name: 'TestException' }>();
     const error = new TestException('This is a test');
@@ -73,8 +70,8 @@ describe('ExceptionBuilder', () => {
   });
 
   it('should create distinct constructors', () => {
-    const TestException = new ExceptionBuilder().setParams({ name: 'TestException' }).build();
-    const OtherException = new ExceptionBuilder().setParams({ name: 'OtherException' }).build();
+    const { TestException } = new ExceptionBuilder().setParams({ name: 'TestException' }).build();
+    const { OtherException } = new ExceptionBuilder().setParams({ name: 'OtherException' }).build();
     const e1 = new TestException('This is a test');
     const e2 = new OtherException('This is a test');
     expect(e1).toBeInstanceOf(BaseException);
@@ -84,7 +81,7 @@ describe('ExceptionBuilder', () => {
   });
 
   it('should allow creating an exception with additional details', () => {
-    const TestException = new ExceptionBuilder()
+    const { TestException } = new ExceptionBuilder()
       .setParams({ name: 'TestException' })
       .setOptionsType<{ details: { code: number } }>()
       .build();
@@ -96,7 +93,7 @@ describe('ExceptionBuilder', () => {
   });
 
   it('should allow creating an error with a custom cause', () => {
-    const TestException = new ExceptionBuilder()
+    const { TestException } = new ExceptionBuilder()
       .setParams({ name: 'TestException' })
       .setOptionsType<{ cause: Error }>()
       .build();
@@ -108,7 +105,7 @@ describe('ExceptionBuilder', () => {
   });
 
   it('should allow creating an error with a default message', () => {
-    const TestException = new ExceptionBuilder()
+    const { TestException } = new ExceptionBuilder()
       .setParams({ message: 'Custom message', name: 'TestException' })
       .setOptionsType<{ cause: Error }>()
       .build();
@@ -117,3 +114,33 @@ describe('ExceptionBuilder', () => {
     expectTypeOf<ConstructorParameters<typeof TestException>>().toEqualTypeOf<[options: { cause: Error }]>();
   });
 });
+
+describe('ValueException', () => {
+  it('should have the correct prototype', () => {
+    expect(Object.getPrototypeOf(ValueException)).toBe(BaseException);
+  });
+});
+
+describe('OutOfRangeException', () => {
+  it('should have the correct prototype', () => {
+    expect(Object.getPrototypeOf(OutOfRangeException)).toBe(ValueException);
+  });
+  describe('constructor', () => {
+    it('should create the correct message', () => {
+      const error = new OutOfRangeException({
+        details: {
+          max: Infinity,
+          min: 0,
+          value: -1
+        }
+      });
+      expect(error.message).toBe('Value -1 is out of range (0 - Infinity)');
+    });
+  });
+  describe('ForNonPositive', () => {
+    it('should create the correct message', () => {
+      const error = OutOfRangeException.forNonPositive(-1);
+      expect(error.message).toBe('Value -1 is out of range (0 - Infinity)');
+    });
+  });
+});

src/__tests__/exception.test.ts

@@ -1,6 +1,14 @@
 import { describe, expect, it } from 'vitest';
 
-import { deepFreeze, filterObject, isAllUndefined, isObject, isObjectLike, isPlainObject } from '../object.js';
+import {
+  deepFreeze,
+  filterObject,
+  isAllUndefined,
+  isObject,
+  isObjectLike,
+  isPlainObject,
+  objectify
+} from '../object.js';
 
 describe('deepFreeze', () => {
   it('should not allow mutating a primitive value', () => {
@@ -96,3 +104,9 @@ describe('filterValues', () => {
     });
   });
 });
+
+describe('objectify', () => {
+  it('should create a single key map', () => {
+    expect(objectify('foo', 'bar')).toStrictEqual({ foo: 'bar' });
+  });
+});

src/__tests__/object.test.ts

@@ -6,48 +6,48 @@ describe('randomInt', () => {
   it('should return an integer value within the range', () => {
     const min = 5;
     const max = 8;
-    const result = randomInt(min, max);
+    const result = randomInt(min, max)._unsafeUnwrap();
     expect(result).toBeGreaterThanOrEqual(min);
     expect(result).toBeLessThan(8);
     expect(Number.isInteger(result)).toBe(true);
   });
-  it('should throw if the min value is larger than the max', () => {
-    expect(() => randomInt(10, 5)).toThrow();
+  it('should return an error if the min value is larger than the max', () => {
+    expect(randomInt(10, 5).isErr()).toBe(true);
   });
-  it('should throw if the min value equals the max', () => {
-    expect(() => randomInt(10, 10)).toThrow();
+  it('should return an error if the min value equals the max', () => {
+    expect(randomInt(10, 10).isErr()).toBe(true);
   });
   it('should handle negative values', () => {
     const min = -5;
     const max = -3;
-    const result = randomInt(min, max);
+    const result = randomInt(min, max)._unsafeUnwrap();
     expect(result).toBeGreaterThanOrEqual(min);
     expect(result).toBeLessThan(8);
     expect(Number.isInteger(result)).toBe(true);
-    expect(() => randomInt(max, min)).toThrow();
+    expect(randomInt(max, min).isErr()).toBe(true);
   });
 });
 
 describe('randomDate', () => {
   it('should return a date within the range', () => {
     const start = new Date(2000, 0, 1);
     const end = new Date();
-    const random = randomDate(start, end);
+    const random = randomDate(start, end)._unsafeUnwrap();
     expect(random.getTime() >= start.getTime()).toBe(true);
     expect(random.getTime() <= end.getTime()).toBe(true);
   });
-  it('should throw if the end is before the start', () => {
-    expect(() => randomDate(new Date(), new Date(2000, 0, 1))).toThrow();
+  it('should return an error if the end is before the start', () => {
+    expect(randomDate(new Date(), new Date(2000, 0, 1)).isErr()).toBe(true);
   });
 });
 
 describe('randomValue', () => {
-  it('should throw if given an empty array', () => {
-    expect(() => randomValue([])).toThrow();
+  it('should return an error if given an empty array', () => {
+    expect(randomValue([]).isErr()).toBe(true);
   });
   it('should return a value in the array', () => {
     const arr = [-10, -20, -30];
-    expect(arr.includes(randomValue(arr)!));
+    expect(arr.includes(randomValue(arr)._unsafeUnwrap()));
   });
   it('should not mutate the array', () => {
     const arr = [-10, -20, -30];

src/__tests__/random.test.ts

@@ -4,10 +4,10 @@ import { range } from '../range.js';
 
 describe('range', () => {
   it('should return an array equal in length to the range', () => {
-    const arr = range(10);
+    const arr = range(10)._unsafeUnwrap();
     expect(arr.length).toBe(10);
   });
-  it('should throw an error if the start is equal to the end', () => {
-    expect(() => range(1, 1)).toThrow();
+  it('should return an error if the start is equal to the end', () => {
+    expect(range(1, 1).isErr()).toBe(true);
   });
 });