@vpmedia/simplify 1.74.0 → 1.75.0

package/src/typecheck/TypeChecker.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { typeChecker } from './TypeChecker.js';
+import { TypeCheckError } from './TypeCheckError.js';
+
+const stringValidator = (value: unknown): value is string => typeof value === 'string';
+
+describe('TypeChecker', () => {
+  it('should check value type correctly', () => {
+    const result = typeChecker.check('test', stringValidator);
+    expect(result).toBe('test');
+  });
+
+  it('should throw TypeCheckError for invalid type', () => {
+    expect(() => typeChecker.check(123, stringValidator)).toThrow(TypeCheckError);
+  });
+
+  it('should swallow errors when enabled', () => {
+    typeChecker.setSwallowErrors(true);
+    const result = typeChecker.check(123, stringValidator);
+    expect(result).toBe(123);
+    typeChecker.setSwallowErrors(false);
+  });
+
+  it('should check array type correctly', () => {
+    const result = typeChecker.checkArray(['a', 'b', 'c'], stringValidator);
+    expect(result).toEqual(['a', 'b', 'c']);
+  });
+
+  it('should throw TypeCheckError for invalid array type', () => {
+    expect(() => typeChecker.checkArray([1, 2, 3], stringValidator)).toThrow(TypeCheckError);
+  });
+
+  it('should swallow array errors when enabled', () => {
+    typeChecker.setSwallowErrors(true);
+    const result = typeChecker.checkArray([1, 2, 3], stringValidator);
+    expect(result).toEqual([1, 2, 3]);
+    typeChecker.setSwallowErrors(false);
+  });
+
+  it('should check enum value correctly', () => {
+    const choices = ['option1', 'option2', 'option3'];
+    const result = typeChecker.checkEnum('option2', choices);
+    expect(result).toBe('option2');
+  });
+
+  it('should throw TypeCheckError for invalid enum value', () => {
+    const choices = ['option1', 'option2', 'option3'];
+    expect(() => typeChecker.checkEnum('invalid', choices)).toThrow(TypeCheckError);
+  });
+
+  it('should swallow enum errors when enabled', () => {
+    typeChecker.setSwallowErrors(true);
+    const choices = ['option1', 'option2', 'option3'];
+    const result = typeChecker.checkEnum('invalid', choices);
+    expect(result).toBe('invalid');
+    typeChecker.setSwallowErrors(false);
+  });
+
+  it('should handle number enum values', () => {
+    const choices = [1, 2, 3];
+    const result = typeChecker.checkEnum(2, choices);
+    expect(result).toBe(2);
+  });
+
+  it('should handle mixed string and number enum values', () => {
+    const choices = ['option1', 2, 'option3'];
+    const result = typeChecker.checkEnum(2, choices);
+    expect(result).toBe(2);
+  });
+});

package/src/typecheck/{TypeChecker.js → TypeChecker.ts}

@@ -1,14 +1,12 @@
-import { TypeCheckError } from './TypeCheckError.js';
 import { Logger } from '../logging/Logger.js';
-import { typeCheck, typeCheckArray, typeCheckEnum } from './util.js';
+import { TypeCheckError } from './TypeCheckError.js';
+import { typeCheck, typeCheckArray, typeCheckEnum, type EnumChoices } from './util.js';
 
 const logger = new Logger('typechecker');
 
 class TypeChecker {
-  /** @type {TypeChecker} */
-  static #instance;
+  static #instance: TypeChecker | undefined;
 
-  /** @type {boolean} */
   #swallowErrors = false;
 
   constructor() {
@@ -19,27 +17,21 @@ class TypeChecker {
 
   /**
    * Enable or disable swallowing of TypeCheckErrors.
-   * @param {boolean} value - Swallow errors flag.
    */
-  setSwallowErrors(value) {
+  setSwallowErrors(value: boolean): void {
     this.#swallowErrors = Boolean(value);
   }
 
   /**
    * Type check a single value.
-   * @template T
-   * @param {unknown} value - The value to check.
-   * @param {(value: unknown) => value is T} validator - The validator to check with.
-   * @returns {T} - The type checked value.
    */
-  check(value, validator) {
+  check<T>(value: unknown, validator: (value: unknown) => value is T): T {
     try {
       return typeCheck(value, validator);
     } catch (error) {
       if (this.#swallowErrors && error instanceof TypeCheckError) {
         logger.exception('check', error);
-        // @ts-expect-error
-        return value;
+        return value as T;
       }
       throw error;
     }
@@ -47,32 +39,23 @@ class TypeChecker {
 
   /**
    * Type check an array of values.
-   * @template T
-   * @param {unknown[]} value - The value to check.
-   * @param {(value: unknown) => value is T} validator - The validator to check the array with.
-   * @returns {T[]} - The type checked value.
    */
-  checkArray(value, validator) {
+  checkArray<T>(value: unknown[], validator: (value: unknown) => value is T): T[] {
     try {
       return typeCheckArray(value, validator);
     } catch (error) {
       if (this.#swallowErrors && error instanceof TypeCheckError) {
         logger.exception('checkArray', error);
-        // @ts-expect-error
-        return value;
+        return value as T[];
       }
       throw error;
     }
   }
 
   /**
-   * Type check an array of values.
-   * @template T
-   * @param {string | number} value - The value to check.
-   * @param {(string | number)[] | Set<string | number> | Record<string | number, string | number>} choices - Enum list.
-   * @returns {string | number} - The type checked value.
+   * Type check an enum.
    */
-  checkEnum(value, choices) {
+  checkEnum(value: string | number, choices: EnumChoices): string | number {
     try {
       return typeCheckEnum(value, choices);
     } catch (error) {

package/src/typecheck/util.test.ts

@@ -0,0 +1,36 @@
+import { isNumber, isPositiveInteger } from '../util/validate.js';
+import { TypeCheckError } from './TypeCheckError.js';
+import { typeCheck, typeCheckArray, typeCheckEnum } from './util.js';
+
+describe('typecheck', () => {
+  test('typeCheck', () => {
+    expect(() => typeCheck(0.1, isNumber)).not.toThrowError(TypeCheckError);
+    expect(() => typeCheck(-0.1, isPositiveInteger)).toThrowError(TypeCheckError);
+    expect(() => typeCheck('string', isNumber)).toThrowError(TypeCheckError);
+  });
+
+  test('typeCheckArray', () => {
+    expect(() => typeCheckArray([0.1], isNumber)).not.toThrowError(TypeCheckError);
+    expect(() => typeCheckArray(['string'], isNumber)).toThrowError(TypeCheckError);
+    // @ts-expect-error
+    expect(() => typeCheckArray(-0.1, isPositiveInteger)).toThrowError(TypeCheckError);
+    // @ts-expect-error
+    expect(() => typeCheckArray('string', isNumber)).toThrowError(TypeCheckError);
+  });
+
+  test('typeCheckEnum', () => {
+    expect(() => typeCheckEnum('AA', ['AA'])).not.toThrowError(TypeCheckError);
+    expect(() => typeCheckEnum('AA', ['BB'])).toThrowError(TypeCheckError);
+    // @ts-expect-error
+    expect(() => typeCheckEnum(null, ['BB'])).toThrowError(TypeCheckError);
+    // @ts-expect-error
+    expect(() => typeCheckEnum(['AA'], null)).toThrowError(TypeCheckError);
+    try {
+      typeCheckEnum('AA', ['BB']);
+    } catch (error) {
+      if (error instanceof Error) {
+        expect(error.message).toBe('Validation failed: isEnum - "AA" (string)');
+      }
+    }
+  });
+});

package/src/typecheck/util.ts

@@ -0,0 +1,50 @@
+import { getDisplayValue, getTypeFromValue } from '../util/string.js';
+import { isArrayOf, isEnum } from '../util/validate.js';
+import { TypeCheckError } from './TypeCheckError.js';
+
+export type EnumChoices =
+  | ReadonlyArray<string | number>
+  | ReadonlySet<string | number>
+  | Readonly<Record<string | number, string | number>>;
+
+/**
+ * Get error message for validator exceptions.
+ */
+const getErrorMessage = (validatorName: string, value: unknown): never => {
+  const displayValue = getDisplayValue(value);
+  const displayType = getTypeFromValue(value);
+  throw new TypeCheckError(`Validation failed: ${validatorName || '<anonymous>'} - ${displayValue} (${displayType})`);
+};
+
+/**
+ * Type check a value using a validator.
+ * @throws {TypeCheckError}
+ */
+export const typeCheck = <T>(value: unknown, validator: (value: unknown) => value is T): T => {
+  if (!validator(value)) {
+    getErrorMessage(validator.name, value);
+  }
+  return value as T;
+};
+
+/**
+ * Type check an array of values using a validator.
+ * @throws {TypeCheckError}
+ */
+export const typeCheckArray = <T>(value: unknown[], validator: (value: unknown) => value is T): T[] => {
+  if (!isArrayOf(value, validator)) {
+    getErrorMessage(validator.name, value);
+  }
+  return value as T[];
+};
+
+/**
+ * Type check an enum.
+ * @throws {TypeCheckError}
+ */
+export const typeCheckEnum = (value: string | number, choices: EnumChoices): string | number => {
+  if (!isEnum(value, choices)) {
+    getErrorMessage('isEnum', value);
+  }
+  return value;
+};

package/src/util/async.test.ts

@@ -0,0 +1,74 @@
+import { delayPromise, loadJSON, retryAsync } from './async.js';
+
+describe('delayPromise', () => {
+  test('Returns a promise that resolves after specified delay', async () => {
+    const start = Date.now();
+    await delayPromise(10);
+    const end = Date.now();
+
+    expect(end - start).toBeGreaterThanOrEqual(9);
+  });
+
+  test('delayPromise with zero delay', async () => {
+    const start = Date.now();
+    await delayPromise(0);
+    const end = Date.now();
+
+    expect(end - start).toBeGreaterThanOrEqual(0);
+  });
+});
+
+describe('loadJSON', () => {
+  test('Load JSON data', async () => {
+    const data = await loadJSON('/test.json');
+    expect(data).toMatchObject({
+      method: 'GET',
+      success: true,
+    });
+  });
+});
+
+describe('retryAsync', () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('returns result when method succeeds immediately', async () => {
+    const method = vi.fn().mockResolvedValue('success');
+    const result = await retryAsync(method, 1, 100);
+    expect(result).toBe('success');
+    expect(method).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries once and then succeeds', async () => {
+    const method = vi.fn().mockRejectedValueOnce(new Error('fail')).mockResolvedValueOnce('success');
+    const promise = retryAsync(method, 1, 100);
+    const result = await promise;
+    expect(result).toBe('success');
+    expect(method).toHaveBeenCalledTimes(2);
+  });
+
+  it('throws after exceeding retries', async () => {
+    const method = vi.fn().mockRejectedValue(new Error('fail'));
+    const promise = retryAsync(method, 1, 100);
+    await expect(promise).rejects.toThrow('fail');
+    expect(method).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not retry when numTries is 0', async () => {
+    const method = vi.fn().mockRejectedValue(new Error('fail'));
+    await expect(retryAsync(method, 0, 100)).rejects.toThrow('fail');
+    expect(method).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not wait when delayMs is 0', async () => {
+    const method = vi.fn().mockRejectedValueOnce(new Error('fail')).mockResolvedValueOnce('success');
+    const result = await retryAsync(method, 1, 0);
+    expect(result).toBe('success');
+    expect(method).toHaveBeenCalledTimes(2);
+  });
+});

package/src/util/{async.js → async.ts}

@@ -2,23 +2,16 @@ import { getTypedError } from './error.js';
 
 /**
  * Returns a promise with delayed resolve.
- * @param {number} delayMS - Promise resolve delay in milliseconds.
- * @returns {Promise<void>} Delayed resolve promise.
  */
-export const delayPromise = (delayMS) =>
+export const delayPromise = (delayMS: number): Promise<void> =>
   new Promise((resolve) => {
     setTimeout(resolve, delayMS);
   });
 
 /**
  * Async method call retry helper.
- * @template T
- * @param {() => Promise<T>} method - Async function to call.
- * @param {number} numTries - Max retries.
- * @param {number} delayMs - Delay between attempts in ms.
- * @returns {Promise<T>} Async function result.
  */
-export const retryAsync = async (method, numTries = 1, delayMs = 100) => {
+export const retryAsync = async <T>(method: () => Promise<T>, numTries = 1, delayMs = 100): Promise<T> => {
   for (let attempt = 0; attempt <= numTries; attempt += 1) {
     try {
       // oxlint-disable-next-line no-await-in-loop
@@ -38,10 +31,8 @@ export const retryAsync = async (method, numTries = 1, delayMs = 100) => {
 
 /**
  * Load JSON file using a fetch GET request.
- * @param {string} url - URL to load.
- * @returns {Promise<unknown>} The parsed JSON data.
  */
-export const loadJSON = async (url) => {
+export const loadJSON = async (url: string): Promise<unknown> => {
   const response = await fetch(url);
   if (!response.ok) {
     throw new DOMException(`Fetch error ${response.status}`, 'FetchError');

package/src/util/error.test.ts

@@ -0,0 +1,32 @@
+import { getErrorDetails, getTypedError } from './error.js';
+
+describe('error', () => {
+  test('getErrorDetails', () => {
+    const error = new Error('Test error', { cause: 'Test cause' });
+    const errorDetails = getErrorDetails(error);
+    expect(errorDetails.type).toBe('Error');
+    expect(errorDetails.message).toBe('Test error');
+    expect(errorDetails.cause).toBe('Test cause');
+    expect(errorDetails['stack']).toBe(undefined);
+  });
+
+  test('getErrorDetails with Error cause', () => {
+    const error = new SyntaxError('Test error', { cause: new TypeError('Cause error') });
+    const errorDetails = getErrorDetails(error);
+    expect(errorDetails.type).toBe('SyntaxError');
+    expect(errorDetails.message).toBe('Test error');
+    expect(errorDetails.cause instanceof Error).toBe(true);
+    if (errorDetails.cause instanceof Error) {
+      expect(errorDetails.cause.message).toBe('Cause error');
+    }
+  });
+
+  test('getTypedError', () => {
+    expect(getTypedError(new Error('Error message')).message).toBe('Error message');
+    expect(getTypedError('Error message').message).toBe('Error message');
+    expect(getTypedError(1).message).toBe('1');
+    expect(getTypedError(true).message).toBe('true');
+    expect(getTypedError(null).message).toBe('null');
+    expect(getTypedError(undefined).message).toBe('undefined');
+  });
+});

package/src/util/error.ts

@@ -0,0 +1,37 @@
+const DEFAULT_EXCLUDES = new Set(['stack']);
+
+export interface ErrorDetails {
+  name: string;
+  type: string;
+  message?: string;
+  cause?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Retrieves detailed information from an error object.
+ */
+export const getErrorDetails = (error: Error, excludes?: string[] | null): ErrorDetails => {
+  const errorDetails: ErrorDetails = {
+    name: error.name,
+    type: error.constructor?.name ?? typeof error,
+  };
+  if (error.message) {
+    errorDetails.message = error.message;
+  }
+  if (error.cause) {
+    errorDetails.cause = error.cause;
+  }
+  for (const key of Object.getOwnPropertyNames(error)) {
+    if (!excludes?.includes(key) && !DEFAULT_EXCLUDES.has(key)) {
+      errorDetails[key] = (error as unknown as Record<string, unknown>)[key];
+    }
+  }
+  return errorDetails;
+};
+
+/**
+ * Get typed error from an unknown type.
+ */
+export const getTypedError = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));

package/src/util/event_emitter.test.ts

@@ -0,0 +1,228 @@
+import { describe, it, expect } from 'vitest';
+import { EventEmitter } from './event_emitter.js';
+
+describe('EventEmitter3 basics', () => {
+  it('can be instantiated', () => {
+    const e = new EventEmitter();
+    expect(e).toBeInstanceOf(EventEmitter);
+  });
+
+  it('supports subclassing', () => {
+    class Beast extends EventEmitter {}
+    const beast = new Beast();
+
+    expect(beast).toBeInstanceOf(Beast);
+    expect(beast).toBeInstanceOf(EventEmitter);
+  });
+});
+
+describe('emit()', () => {
+  it('returns false when no listeners exist', () => {
+    const e = new EventEmitter();
+    expect(e.emit('foo')).toBe(false);
+  });
+
+  it('returns true when listeners exist', () => {
+    const e = new EventEmitter();
+    e.on('foo', () => {});
+    expect(e.emit('foo')).toBe(true);
+  });
+
+  it('invokes listeners with provided arguments', async () => {
+    const e = new EventEmitter();
+
+    await new Promise<void>((resolve) => {
+      e.on('foo', (a: number, b: number) => {
+        expect(a).toBe(1);
+        expect(b).toBe(2);
+        resolve();
+      });
+
+      e.emit('foo', 1, 2);
+    });
+  });
+
+  it('binds the correct context', async () => {
+    const e = new EventEmitter();
+    const ctx = { value: 42 };
+
+    await new Promise<void>((resolve) => {
+      e.on(
+        'foo',
+        function (this: typeof ctx) {
+          expect(this).toBe(ctx);
+          resolve();
+        },
+        ctx
+      );
+
+      e.emit('foo');
+    });
+  });
+
+  it('supports many listeners for the same event', () => {
+    const e = new EventEmitter();
+    const calls: number[] = [];
+
+    e.on('foo', () => calls.push(1));
+    e.on('foo', () => calls.push(2));
+
+    e.emit('foo');
+
+    expect(calls).toEqual([1, 2]);
+  });
+});
+
+describe('once()', () => {
+  it('fires the listener only once', () => {
+    const e = new EventEmitter();
+    let calls = 0;
+
+    e.once('foo', () => {
+      calls += 1;
+    });
+
+    e.emit('foo');
+    e.emit('foo');
+
+    expect(calls).toBe(1);
+    expect(e.listenerCount('foo')).toBe(0);
+  });
+
+  it('passes arguments correctly', async () => {
+    const e = new EventEmitter();
+
+    await new Promise<void>((resolve) => {
+      e.once('foo', (...args: unknown[]) => {
+        expect(args).toEqual([1, 2, 3]);
+        resolve();
+      });
+
+      e.emit('foo', 1, 2, 3);
+    });
+  });
+});
+
+describe('listeners() and listenerCount()', () => {
+  it('returns an empty array when no listeners exist', () => {
+    const e = new EventEmitter();
+    expect(e.listeners('foo')).toEqual([]);
+    expect(e.listenerCount('foo')).toBe(0);
+  });
+
+  it('returns only listener functions (not internals)', () => {
+    const e = new EventEmitter();
+    function fn() {}
+
+    e.on('foo', fn);
+
+    expect(e.listeners('foo')).toEqual([fn]);
+  });
+
+  it('does not expose internal listener storage', () => {
+    const e = new EventEmitter();
+    function fn() {}
+
+    e.on('foo', fn);
+    const listeners = e.listeners('foo');
+    listeners.push(() => {});
+
+    expect(e.listeners('foo')).toEqual([fn]);
+  });
+});
+
+describe('off()', () => {
+  it('removes all listeners for an event when fn is omitted', () => {
+    const e = new EventEmitter();
+
+    e.on('foo', () => {});
+    e.on('foo', () => {});
+
+    e.off('foo');
+
+    expect(e.listenerCount('foo')).toBe(0);
+  });
+
+  it('removes a specific listener', () => {
+    const e = new EventEmitter();
+    function fn() {}
+
+    e.on('foo', fn);
+    e.off('foo', fn);
+
+    expect(e.listeners('foo')).toEqual([]);
+  });
+
+  it('removes listeners matching both function and context', () => {
+    const e = new EventEmitter();
+    const ctx1 = {};
+    const ctx2 = {};
+    function fn() {}
+
+    e.on('foo', fn, ctx1);
+    e.on('foo', fn, ctx2);
+
+    e.off('foo', fn, ctx1);
+
+    expect(e.listenerCount('foo')).toBe(1);
+  });
+});
+
+describe('removeAllListeners()', () => {
+  it('removes listeners for a single event', () => {
+    const e = new EventEmitter();
+
+    e.on('foo', () => {});
+    e.on('bar', () => {});
+
+    e.removeAllListeners('foo');
+
+    expect(e.listenerCount('foo')).toBe(0);
+    expect(e.listenerCount('bar')).toBe(1);
+  });
+
+  it('removes all listeners when no event is specified', () => {
+    const e = new EventEmitter();
+
+    e.on('foo', () => {});
+    e.on('bar', () => {});
+
+    e.removeAllListeners();
+
+    expect(e.eventNames()).toEqual([]);
+  });
+});
+
+describe('eventNames()', () => {
+  it('returns an empty array when no events exist', () => {
+    const e = new EventEmitter();
+    expect(e.eventNames()).toEqual([]);
+  });
+
+  it('returns all registered event names', () => {
+    const e = new EventEmitter();
+
+    e.on('foo', () => {});
+    e.on('bar', () => {});
+
+    expect(e.eventNames()).toContain('foo');
+    expect(e.eventNames()).toContain('bar');
+  });
+
+  it('supports symbol event names', () => {
+    const e = new EventEmitter();
+    const sym = Symbol('test');
+
+    e.on(sym, () => {});
+    expect(e.eventNames()).toContain(sym);
+  });
+
+  it('events map is instance field', () => {
+    const e1 = new EventEmitter();
+    const e2 = new EventEmitter();
+    e1.on('event', () => {});
+    expect(e1.listenerCount('event')).toBe(1);
+    expect(e1.listenerCount('no-event')).toBe(0);
+    expect(e2.listenerCount('event')).toBe(0);
+  });
+});