@dr.pogodin/js-utils 0.0.14 → 0.0.15

package/babel.config.js

@@ -1,6 +1,6 @@
 // Babel is used for Jest testing.
 
-module.exports = {
+export default {
   presets: [
     ['@babel/preset-env', { targets: { node: 'current' } }],
     '@babel/preset-typescript',

package/jest.config.js

@@ -1,4 +1,4 @@
-module.exports = {
+export default {
   collectCoverage: true,
   coverageDirectory: '__coverage__',
   testPathIgnorePatterns: [

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@dr.pogodin/js-utils",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "Collection of JavaScript (TypeScript) utilities.",
   "main": "build/index",
-  "react-native": "src/index",
-  "source": "src/index",
+  "type": "module",
   "types": "build/index.d.ts",
   "scripts": {
     "build": "rimraf build && tsc",

package/src/Barrier.ts

@@ -1,116 +0,0 @@
-export type Executor<T> = ConstructorParameters<typeof Promise<T>>[0];
-
-type Resolver<T> = Parameters<Executor<T>>[0];
-type Rejecter = Parameters<Executor<unknown>>[1];
-
-enum STATE {
-  PENDING = 'PENDING',
-  REJECTED = 'REJECTED',
-  RESOLVED = 'RESOLVED',
-}
-
-/**
- * Barrier is just a Promise which has resolve and reject exposed as instance
- * methods.
- *
- * It has two generic arguments T and TR which correspond to the argument of
- * the .resolve() method, and to the value resolved by the promise (barrier).
- * For a simple barrier TR equals to T, however for barriers created via .then()
- * chain, T corresponds to the argument of the original barrier, and TR to
- * the value resolved by the latest promise in the chain. Consider this:
- *
- * const b = new Barrier<string>();
- * b.resolve('result');
- * const s = await b; // `s` has `string` type, and equals "result".
- *
- * const b = (new Barrier<string>()).then((s) => s.length);
- * b.resolve('result'); // Chained barrier exposes .resolve() method of
- *                      // the first barrier in the chain, which expects
- *                      // `string` arugment (T), but the chained barrier
- *                      // resolves to `number` (TR).
- * const n = await b; // `n` has `number` type, and equals 6.
- *
- * Docs: https://dr.pogodin.studio/docs/react-utils/docs/api/classes/Barrier
- */
-export default class Barrier<T = unknown, TR = T> extends Promise<TR> {
-  private p_resolve: Resolver<T>;
-
-  private p_reject: Rejecter;
-
-  private p_state = STATE.PENDING;
-
-  constructor(executor?: Executor<TR>) {
-    let resolveRef: Resolver<TR>;
-    let rejectRef: Rejecter;
-
-    super((resolve, reject) => {
-      // Note: Enforcing `void` return type because of the BEWARE note below.
-      resolveRef = (value: TR | PromiseLike<TR>): void => {
-        resolve(value);
-        this.p_state = STATE.RESOLVED;
-
-        // BEWARE: Don't try to return `this` here, it will easily cause
-        // infinite loops in React Native, which are extremely difficult
-        // to troubleshoot (I wasn't able to figure out, are they due to
-        // internal Promise implementation in RN, or because of some bad
-        // patterns in the host code).
-      };
-
-      // Note: Enforcing `void` return type because of the BEWARE note below.
-      rejectRef = (reason?: any): void => {
-        reject(reason);
-        this.p_state = STATE.REJECTED;
-      };
-
-      if (executor) executor(resolveRef, rejectRef);
-    });
-
-    // NOTE: We assume, the only scenario where TR is not equal T is when
-    // the Barrier is constructed by a .then() call on a "parent" barrier,
-    // and in that scenario .then() itself will replace .p_resolve by another
-    // resolver immediately after this constructor returns.
-    this.p_resolve = resolveRef! as Resolver<T>;
-
-    this.p_reject = rejectRef!;
-  }
-
-  get resolve() {
-    return (arg: Parameters<Resolver<T>>[0]) => {
-      this.p_resolve(arg);
-      return this;
-    };
-  }
-
-  get reject() {
-    return (arg: Parameters<Rejecter>[0]) => {
-      this.p_reject(arg);
-      return this;
-    };
-  }
-
-  get resolved() { return this.p_state === STATE.RESOLVED; }
-
-  get rejected() { return this.p_state === STATE.REJECTED; }
-
-  get settled() { return this.p_state !== STATE.PENDING; }
-
-  catch<TR1>(
-    onRejected?: ((reason: any) => TR1 | PromiseLike<TR1>) | null,
-  ): Barrier<T, TR1> {
-    return <Barrier<T, TR1>> super.catch(onRejected);
-  }
-
-  finally(onFinally?: (() => void) | null): Barrier<TR> {
-    return <Barrier<TR>> super.finally(onFinally);
-  }
-
-  then<TR1, TR2>(
-    onFulfilled?: ((value: TR) => TR1 | PromiseLike<TR1>) | null,
-    onRejected?: ((reason: any) => TR2 | PromiseLike<TR2>) | null,
-  ): Barrier<T, TR1 | TR2> {
-    const res = <Barrier<T, TR1 | TR2>> super.then(onFulfilled, onRejected);
-    res.p_resolve = this.resolve;
-    res.p_reject = this.reject;
-    return res;
-  }
-}

package/src/Emitter.ts

@@ -1,57 +0,0 @@
-export type Listener<T extends unknown[] = unknown[]> = (...args: T) => void;
-
-/**
- * Simple listeneable data Emitter.
- */
-export class Emitter<T extends unknown[] = unknown[]> {
-  private p_listeners: Listener<T>[] = [];
-
-  /**
-   * Returns "true" if any listener is connected; "false" otherwise.
-   * @return {boolean}
-   */
-  get hasListeners(): boolean {
-    return !!this.p_listeners.length;
-  }
-
-  get listeners(): ReadonlyArray<Listener<T>> { return this.p_listeners; }
-
-  /**
-   * Adds `listener` if it is not already connected.
-   * @param {function} listener
-   * @return {function} Unsubscribe function.
-   */
-  addListener(listener: Listener<T>): () => void {
-    if (!this.p_listeners.includes(listener)) {
-      this.p_listeners.push(listener);
-    }
-    return () => this.removeListener(listener);
-  }
-
-  /**
-   * Calls every connected listener with the given arguments.
-   * @param args
-   */
-  emit(...args: T) {
-    const listeners = this.p_listeners.slice();
-    for (let i = 0; i < listeners.length; ++i) {
-      listeners[i](...args);
-    }
-  }
-
-  /**
-   * Removes all connected listeners.
-   */
-  removeAllListeners() {
-    this.p_listeners = [];
-  }
-
-  /**
-   * Removes specified `listener`, if connected.
-   * @param listener
-   */
-  removeListener(listener: Listener<T>) {
-    const idx = this.p_listeners.indexOf(listener);
-    if (idx >= 0) this.p_listeners.splice(idx, 1);
-  }
-}

package/src/Semaphore.ts

@@ -1,78 +0,0 @@
-import Barrier from './Barrier';
-
-/**
- * Implements a simple semaphore for async code logic.
- */
-export default class Semaphore {
-  constructor(ready = false) {
-    this.p_ready = !!ready;
-  }
-
-  get ready() { return this.p_ready; }
-
-  setReady(ready: boolean) {
-    const bool = !!ready;
-    if (this.p_ready !== bool) {
-      this.p_ready = bool;
-      if (bool && !this.p_draining && this.p_queue.length) {
-        this.p_drainQueue();
-      }
-    }
-  }
-
-  /**
-   * Waits until the semaphore is ready, and marks it as non-ready (seizes it).
-   * @return {Promise}
-   */
-  async seize() {
-    return this.waitReady(true);
-  }
-
-  async waitReady(seize = false) {
-    if (!this.p_ready || this.p_queue.length) {
-      const barrier = new Barrier<void>();
-      this.p_queue.push(barrier);
-      await barrier;
-      if (seize) this.p_ready = false;
-      this.p_drainLock!.resolve();
-    } else if (seize) this.p_ready = false;
-  }
-
-  // Private members below this point.
-
-  /**
-   * If semaphore is ready, it releases the next barrier in the queue, if any,
-   * and reschedules itself for a call in the next event loop iteration.
-   * Otherwise, it breaks the queue draining loop, which will be restarted
-   * the next time the semaphore is set ready.
-   */
-  async p_drainQueue() {
-    this.p_draining = true;
-    while (this.p_ready && this.p_queue.length) {
-      this.p_drainLock = new Barrier();
-      this.p_queue[0].resolve();
-      await this.p_drainLock; // eslint-disable-line no-await-in-loop
-      this.p_queue.shift();
-    }
-    this.p_draining = false;
-    this.p_drainLock = null;
-  }
-
-  // "true" when the drain queue process is running (and thus no need to start
-  // a new one).
-  private p_draining = false;
-
-  // Each time a Promise from drain queue is resolved this drainLock is set
-  // to block further queue draining until the promise resolution handler
-  // (.seize() or .waitReady()) unlocks it, thus confirming it is fine
-  // to continue the draining. This is specifically important for .seize(),
-  // which should have a chance to switch semaphore state to non-ready prior
-  // to next Promise in the queue being unlocked.
-  private p_drainLock: Barrier<void> | null = null;
-
-  // The array of barriers set for each async code flow awaiting for
-  // the Semaphore to become ready.
-  private p_queue: Barrier<void>[] = [];
-
-  private p_ready: boolean;
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-export { default as Barrier } from './Barrier';
-export * from './Emitter';
-export { default as Semaphore } from './Semaphore';
-export * from './time';
-export { default as withRetries } from './withRetries';

package/src/time.ts

@@ -1,77 +0,0 @@
-import Barrier, { type Executor } from './Barrier';
-
-// This is not very elegant, but as of now TypeScript does not support type
-// arithmetic, thus we can't have constants assigned like `MIN_MS = 60 * SEC_MS`
-// and have the result type to be 60000 (number literal), it would be just
-// the generic number type.
-export const SEC_MS = 1000;
-export const MIN_MS = 60000; // 60 * SEC_MS
-export const HOUR_MS = 3600000; // 60 * MIN_MS
-export const DAY_MS = 86400000; // 24 * HOUR_MS
-export const YEAR_MS = 31536000000; // 365 * DAY_MS
-
-// TODO: Ok, as we have ended up with a Timer class, mostly to achieve a good
-// TypeScript typing for timer() function, it makes sense to expose the class
-// from the library as well, and it should be documented later.
-export class Timer<T> extends Barrier<void, T> {
-  private p_abort: () => void;
-
-  private p_timeout?: number;
-
-  get abort(): () => void { return this.p_abort; }
-
-  get timeout(): number | undefined { return this.p_timeout; }
-
-  /**
-   * Creates a new, non-initialized instance of Timer. Call .init() method
-   * to actually initialize and launch the timer.
-   *
-   * NOTE: Although it might be tempting to accept `timeout` value as
-   * a constructor's argument, it won't work well, because Timer is an
-   * extension of Promise (via Barrier), and the way Promises works (in
-   * particular their .then() method, which internally calls constructor()
-   * with special executor) does not play along with initalization depending
-   * on custom parameters done in constructor().
-   *
-   * @param executor
-   */
-  constructor(executor?: Executor<T>) {
-    super(executor);
-    this.p_abort = () => {};
-  }
-
-  init(timeout: number): Timer<T> {
-    if (this.p_timeout !== undefined) {
-      throw Error('This Timer is initialized already');
-    }
-    this.p_timeout = timeout;
-    if (timeout > 0) {
-      const id = setTimeout(super.resolve.bind(this), timeout);
-      this.p_abort = () => clearTimeout(id);
-    } else {
-      super.resolve();
-    }
-    return this;
-  }
-
-  then<TR1, TR2>(
-    onFulfilled?: ((value: T) => TR1 | PromiseLike<TR1>) | null,
-    onRejected?: ((reason: any) => TR2 | PromiseLike<TR2>) | null,
-  ): Timer<TR1 | TR2> {
-    const res = <Timer<TR1 | TR2>> super.then(onFulfilled, onRejected);
-    if (this.timeout !== undefined) res.init(this.timeout);
-    return res;
-  }
-}
-
-/**
- * Creates a Promise, which resolves after the given timeout.
- * @param {number} timeout Timeout [ms].
- * @return {Barrier} Resolves after the timeout. It has additional
- *  .abort() method attached, which cancels the pending timer resolution
- *  (without resolving or rejecting the barrier).
- */
-export function timer(timeout: number): Timer<void> {
-  const t = new Timer<void>();
-  return t.init(timeout);
-}

package/src/withRetries.ts

@@ -1,30 +0,0 @@
-import { timer } from './time';
-
-/**
- * Attempts to perform the given async `action` up to `maxRetries` times with
- * the specified `interval`, stopping at the first successful (non-throwing)
- * execution.
- * @param action
- * @param maxRetries Optional. The maximum number of re-tries. Defaults 3.
- * @param interval Optional. The interval between re-tries (in milliseconds).
- *  Defaults to 300ms.
- * @returns Resolves to the result of the successful `action` execution;
- *  or rejects with the error from the last faileda attempt.
- */
-export default async function withRetries<T>(
-  action: () => T,
-  maxRetries = 3,
-  interval = 300,
-): Promise<Awaited<T>> {
-  /* eslint-disable no-await-in-loop */
-  for (let n = 1; ; ++n) {
-    try {
-      const res = action();
-      return res instanceof Promise ? await res : (res as Awaited<T>);
-    } catch (error) {
-      if (n < maxRetries) await timer(interval);
-      else throw error;
-    }
-  }
-  /* eslint-enable no-await-in-loop */
-}