@vpmedia/simplify 1.74.0 → 1.76.0

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);
+  });
+});

package/src/util/event_emitter.ts

@@ -0,0 +1,147 @@
+export type EventListener = (...args: any[]) => void;
+
+/**
+ * Internal listener wrapper that stores metadata
+ * about a registered event listener.
+ */
+class Listener {
+  fn: EventListener;
+  context: unknown;
+  once: boolean;
+
+  constructor(fn: EventListener, context: unknown, once = false) {
+    this.fn = fn;
+    this.context = context;
+    this.once = once;
+  }
+}
+
+/**
+ * Event emitter implementation inspired by Node.js/EventEmitter3.
+ */
+export class EventEmitter {
+  #events: Map<string | symbol, Listener[]>;
+
+  constructor() {
+    this.#events = new Map();
+  }
+
+  /**
+   * Get all registered event names.
+   */
+  eventNames(): (string | symbol)[] {
+    return [...this.#events.keys()];
+  }
+
+  /**
+   * Get all listener functions registered for an event.
+   */
+  listeners(event: string | symbol): EventListener[] {
+    const listeners = this.#events.get(event);
+    return listeners ? listeners.map((l) => l.fn) : [];
+  }
+
+  /**
+   * Get the number of listeners registered for an event.
+   */
+  listenerCount(event: string | symbol): number {
+    const listeners = this.#events.get(event);
+    return listeners ? listeners.length : 0;
+  }
+
+  /**
+   * Emit an event, invoking all registered listeners.
+   */
+  emit(event: string | symbol, ...args: unknown[]): boolean {
+    const listeners = this.#events.get(event);
+    if (!listeners || listeners.length === 0) {
+      return false;
+    }
+
+    for (const listener of [...listeners]) {
+      listener.fn.apply(listener.context, args);
+      if (listener.once) {
+        this.off(event, listener.fn, listener.context);
+      }
+    }
+
+    return true;
+  }
+
+  #addListener(event: string | symbol, fn: EventListener, context: unknown, once: boolean): this {
+    if (typeof fn !== 'function') {
+      throw new TypeError('Listener must be a function');
+    }
+
+    const listener = new Listener(fn, context ?? this, once);
+    const listeners = this.#events.get(event);
+
+    if (listeners) {
+      listeners.push(listener);
+    } else {
+      this.#events.set(event, [listener]);
+    }
+
+    return this;
+  }
+
+  /**
+   * Register a persistent listener for an event.
+   */
+  on(event: string | symbol, fn: EventListener, context?: unknown): this {
+    return this.#addListener(event, fn, context, false);
+  }
+
+  /**
+   * Register a one-time listener for an event.
+   */
+  once(event: string | symbol, fn: EventListener, context?: unknown): this {
+    return this.#addListener(event, fn, context, true);
+  }
+
+  /**
+   * Remove a specific listener, or all listeners for an event.
+   */
+  off(event: string | symbol, fn?: EventListener, context?: unknown): this {
+    if (!this.#events.has(event)) {
+      return this;
+    }
+
+    if (!fn) {
+      this.#events.delete(event);
+      return this;
+    }
+
+    const filtered = this.#events.get(event)!.filter((listener) => {
+      if (listener.fn !== fn) {
+        return true;
+      }
+      if (context !== undefined && listener.context !== context) {
+        return true;
+      }
+      return false;
+    });
+
+    if (filtered.length > 0) {
+      this.#events.set(event, filtered);
+    } else {
+      this.#events.delete(event);
+    }
+
+    return this;
+  }
+
+  /**
+   * Remove all listeners from the emitter,
+   * or all listeners for a specific event.
+   */
+  removeAllListeners(event?: string | symbol): this {
+    if (event === undefined) {
+      this.#events.clear();
+    } else {
+      this.#events.delete(event);
+    }
+
+    return this;
+  }
+}

package/src/util/fetch.test.ts

@@ -0,0 +1,62 @@
+import { HTTP_404_NOT_FOUND } from '../const/http_status.js';
+import { fetchRetry, FetchError } from './fetch.js';
+
+describe('FetchError', () => {
+  test('constructor', () => {
+    const error = new FetchError('message', 'url', { method: 'GET' }, null);
+    expect(error.message).toEqual('message');
+    expect(error.resource).toEqual('url');
+    expect(error.fetchOptions).toMatchObject({ method: 'GET' });
+    expect(error.response).toBe(null);
+  });
+});
+
+describe('fetchRetry', () => {
+  test('fetch OK', async () => {
+    const response = await fetchRetry('/test.json', {
+      cache: 'no-cache',
+      keepalive: false,
+      method: 'GET',
+      redirect: 'error',
+    });
+    const json = await response.json();
+    const expectedJSON = {
+      success: true,
+      method: 'GET',
+    };
+    expect(json).toEqual(expectedJSON);
+  });
+  test('fetch unknown scheme', async () => {
+    try {
+      await fetchRetry('htps://', {});
+    } catch (error) {
+      const typedError = error instanceof Error ? error : new Error(String(error));
+      expect(typedError.message).toEqual('fetch failed');
+      const typedErrorCause =
+        typedError.cause instanceof Error ? typedError.cause : new Error(String(typedError.cause));
+      expect(typedErrorCause.message).toEqual('unknown scheme');
+    }
+  });
+  test('fetch 404 error with retry', async () => {
+    try {
+      await fetchRetry(
+        '/test_error.json',
+        {
+          cache: 'no-cache',
+          keepalive: false,
+          method: 'POST',
+          redirect: 'error',
+        },
+        { numTries: 2, statusExcludes: [], delay: 1 }
+      );
+    } catch (error) {
+      const typedError = error instanceof Error ? error : new Error(String(error));
+      expect(typedError).toBeInstanceOf(FetchError);
+      if (typedError instanceof FetchError) {
+        expect(typedError.message).toBe('Fetch error 404');
+        expect(typedError.response?.status).toBe(HTTP_404_NOT_FOUND);
+        expect(typedError.cause).toBe(HTTP_404_NOT_FOUND);
+      }
+    }
+  });
+});

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

@@ -12,15 +12,23 @@ const logger = new Logger('fetch');
 
 export const HTTP_0_ANY = 0;
 
+export interface FetchRetryOptions {
+  delay?: number;
+  numTries?: number;
+  statusExcludes?: number[];
+  timeout?: number;
+}
+
 export class FetchError extends Error {
+  resource: string | URL | Request;
+  fetchOptions: RequestInit;
+  response: Response | null;
+  override cause: number | null;
+
   /**
    * Creates a new FetchError instance.
-   * @param {string} message - Error message.
-   * @param {string | URL | Request} resource - Fetch URL.
-   * @param {RequestInit} fetchOptions - Fetch options.
-   * @param {Response} response - Fetch response.
    */
-  constructor(message, resource, fetchOptions, response) {
+  constructor(message: string, resource: string | URL | Request, fetchOptions: RequestInit, response: Response | null) {
     super(message);
     this.name = 'FetchError';
     this.resource = resource;
@@ -32,31 +40,32 @@ export class FetchError extends Error {
 
 /**
  * Fetch with retry.
- * @param {string | URL | Request} resource - Fetch URL.
- * @param {RequestInit} fetchOptions - Fetch options.
- * @param {{delay?: number, numTries?: number, statusExcludes?: number[], timeout?: number}} [retryOptions] - Retry options.
- * @returns {Promise<Response>} Fetch result.
  */
-export const fetchRetry = async (resource, fetchOptions, retryOptions) => {
-  retryOptions ??= {};
-  retryOptions.timeout = Math.max(retryOptions.timeout ?? 30000, 1);
-  retryOptions.delay = Math.max(retryOptions.delay ?? 1000, 1);
-  retryOptions.numTries = Math.max(retryOptions.numTries ?? 1, 1);
-  retryOptions.statusExcludes ??= [
-    HTTP_401_UNAUTHORIZED,
-    HTTP_403_FORBIDDEN,
-    HTTP_405_METHOD_NOT_ALLOWED,
-    HTTP_422_UNPROCESSABLE_CONTENT,
-  ];
-  while (retryOptions.numTries > 0) {
+export const fetchRetry = async (
+  resource: string | URL | Request,
+  fetchOptions: RequestInit,
+  retryOptions?: FetchRetryOptions
+): Promise<Response> => {
+  const opts: Required<FetchRetryOptions> = {
+    timeout: Math.max(retryOptions?.timeout ?? 30_000, 1),
+    delay: Math.max(retryOptions?.delay ?? 1000, 1),
+    numTries: Math.max(retryOptions?.numTries ?? 1, 1),
+    statusExcludes: retryOptions?.statusExcludes ?? [
+      HTTP_401_UNAUTHORIZED,
+      HTTP_403_FORBIDDEN,
+      HTTP_405_METHOD_NOT_ALLOWED,
+      HTTP_422_UNPROCESSABLE_CONTENT,
+    ],
+  };
+  while (opts.numTries > 0) {
     const isOnline = globalThis.navigator?.onLine;
-    logger.info('request', { resource, fetchOptions, retryOptions, isOnline });
+    logger.info('request', { resource: String(resource), fetchOptions, retryOptions: { ...opts }, isOnline });
     const controller = new AbortController();
     const timeoutId = setTimeout(
       () => controller.abort(new DOMException('Fetch timed out', 'AbortError')),
-      retryOptions.timeout
+      opts.timeout
     );
-    const options = {
+    const options: RequestInit = {
       ...fetchOptions,
       signal: controller.signal,
     };
@@ -65,22 +74,22 @@ export const fetchRetry = async (resource, fetchOptions, retryOptions) => {
       if (!response.ok) {
         throw new FetchError(`Fetch error ${response.status}`, resource, options, response);
       }
-      logger.info('response', response);
+      logger.info('response', { status: response.status });
       return response;
     } catch (error) {
       const typedError = error instanceof Error ? error : new Error(String(error));
       logger.debug('error', getErrorDetails(typedError));
-      retryOptions.numTries -= 1;
+      opts.numTries -= 1;
       if (
-        retryOptions.numTries === 0 ||
+        opts.numTries === 0 ||
         (typedError instanceof FetchError &&
-          (retryOptions.statusExcludes.includes(typedError.response.status) ||
-            retryOptions.statusExcludes.includes(HTTP_0_ANY)))
+          (opts.statusExcludes.includes(typedError.response?.status ?? -1) ||
+            opts.statusExcludes.includes(HTTP_0_ANY)))
       ) {
         throw error;
       }
-      await delayPromise(retryOptions.delay);
-      retryOptions.delay *= 2;
+      await delayPromise(opts.delay);
+      opts.delay *= 2;
     } finally {
       clearTimeout(timeoutId);
     }