@dr.pogodin/js-utils 0.0.13 → 0.0.15

package/LICENSE.md

@@ -1,7 +1,7 @@
 # MIT License
 
-_Copyright © 2023, Dr. Sergey Pogodin_
-  &mdash; <doc@pogodin.studio> (https://dr.pogodin.studio) \
+_Copyright &copy; 2023&ndash;2025, Dr. Sergey Pogodin_
+  &mdash; <doc@pogodin.studio> (https://dr.pogodin.studio)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/babel.config.js

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

package/build/Barrier.js

@@ -1,5 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
 var STATE;
 (function (STATE) {
     STATE["PENDING"] = "PENDING";
@@ -29,7 +27,7 @@ var STATE;
  *
  * Docs: https://dr.pogodin.studio/docs/react-utils/docs/api/classes/Barrier
  */
-class Barrier extends Promise {
+export default class Barrier extends Promise {
     constructor(executor) {
         let resolveRef;
         let rejectRef;
@@ -88,4 +86,3 @@ class Barrier extends Promise {
         return res;
     }
 }
-exports.default = Barrier;

package/build/Emitter.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Emitter = void 0;
 /**
  * Simple listeneable data Emitter.
  */
-class Emitter {
+export class Emitter {
     constructor() {
         this.p_listeners = [];
     }
@@ -53,4 +50,3 @@ class Emitter {
             this.p_listeners.splice(idx, 1);
     }
 }
-exports.Emitter = Emitter;

package/build/Semaphore.js

@@ -1,4 +1,3 @@
-"use strict";
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -8,15 +7,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const Barrier_1 = __importDefault(require("./Barrier"));
+import Barrier from './Barrier';
 /**
  * Implements a simple semaphore for async code logic.
  */
-class Semaphore {
+export default class Semaphore {
     constructor(ready = false) {
         // "true" when the drain queue process is running (and thus no need to start
         // a new one).
@@ -55,7 +50,7 @@ class Semaphore {
     waitReady() {
         return __awaiter(this, arguments, void 0, function* (seize = false) {
             if (!this.p_ready || this.p_queue.length) {
-                const barrier = new Barrier_1.default();
+                const barrier = new Barrier();
                 this.p_queue.push(barrier);
                 yield barrier;
                 if (seize)
@@ -77,7 +72,7 @@ class Semaphore {
         return __awaiter(this, void 0, void 0, function* () {
             this.p_draining = true;
             while (this.p_ready && this.p_queue.length) {
-                this.p_drainLock = new Barrier_1.default();
+                this.p_drainLock = new Barrier();
                 this.p_queue[0].resolve();
                 yield this.p_drainLock; // eslint-disable-line no-await-in-loop
                 this.p_queue.shift();
@@ -87,4 +82,3 @@ class Semaphore {
         });
     }
 }
-exports.default = Semaphore;

package/build/index.js

@@ -1,28 +1,5 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.withRetries = exports.Semaphore = exports.Barrier = void 0;
-var Barrier_1 = require("./Barrier");
-Object.defineProperty(exports, "Barrier", { enumerable: true, get: function () { return __importDefault(Barrier_1).default; } });
-__exportStar(require("./Emitter"), exports);
-var Semaphore_1 = require("./Semaphore");
-Object.defineProperty(exports, "Semaphore", { enumerable: true, get: function () { return __importDefault(Semaphore_1).default; } });
-__exportStar(require("./time"), exports);
-var withRetries_1 = require("./withRetries");
-Object.defineProperty(exports, "withRetries", { enumerable: true, get: function () { return __importDefault(withRetries_1).default; } });
+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/build/time.js

@@ -1,24 +1,17 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Timer = exports.YEAR_MS = exports.DAY_MS = exports.HOUR_MS = exports.MIN_MS = exports.SEC_MS = void 0;
-exports.timer = timer;
-const Barrier_1 = __importDefault(require("./Barrier"));
+import Barrier 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.
-exports.SEC_MS = 1000;
-exports.MIN_MS = 60000; // 60 * SEC_MS
-exports.HOUR_MS = 3600000; // 60 * MIN_MS
-exports.DAY_MS = 86400000; // 24 * HOUR_MS
-exports.YEAR_MS = 31536000000; // 365 * DAY_MS
+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.
-class Timer extends Barrier_1.default {
+export class Timer extends Barrier {
     get abort() { return this.p_abort; }
     get timeout() { return this.p_timeout; }
     /**
@@ -59,7 +52,6 @@ class Timer extends Barrier_1.default {
         return res;
     }
 }
-exports.Timer = Timer;
 /**
  * Creates a Promise, which resolves after the given timeout.
  * @param {number} timeout Timeout [ms].
@@ -67,7 +59,7 @@ exports.Timer = Timer;
  *  .abort() method attached, which cancels the pending timer resolution
  *  (without resolving or rejecting the barrier).
  */
-function timer(timeout) {
+export function timer(timeout) {
     const t = new Timer();
     return t.init(timeout);
 }

package/build/withRetries.js

@@ -1,4 +1,3 @@
-"use strict";
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -8,9 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = withRetries;
-const time_1 = require("./time");
+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)
@@ -22,7 +19,7 @@ const time_1 = require("./time");
  * @returns Resolves to the result of the successful `action` execution;
  *  or rejects with the error from the last faileda attempt.
  */
-function withRetries(action_1) {
+export default function withRetries(action_1) {
     return __awaiter(this, arguments, void 0, function* (action, maxRetries = 3, interval = 300) {
         /* eslint-disable no-await-in-loop */
         for (let n = 1;; ++n) {
@@ -32,7 +29,7 @@ function withRetries(action_1) {
             }
             catch (error) {
                 if (n < maxRetries)
-                    yield (0, time_1.timer)(interval);
+                    yield timer(interval);
                 else
                     throw error;
             }

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.13",
+  "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",
@@ -31,8 +30,8 @@
   },
   "homepage": "https://github.com/birdofpreyru/js-utils#readme",
   "devDependencies": {
-    "@babel/core": "^7.26.0",
-    "@babel/preset-env": "^7.26.0",
+    "@babel/core": "^7.26.9",
+    "@babel/preset-env": "^7.26.9",
     "@babel/preset-typescript": "^7.26.0",
     "@tsconfig/recommended": "^1.0.8",
     "@types/jest": "^29.5.14",
@@ -40,12 +39,12 @@
     "eslint": "^8.57.1",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-airbnb-typescript": "^18.0.0",
-    "eslint-import-resolver-typescript": "^3.7.0",
+    "eslint-import-resolver-typescript": "^3.8.3",
     "eslint-plugin-import": "^2.31.0",
     "jest": "^29.7.0",
     "rimraf": "^6.0.1",
-    "tstyche": "^3.2.0",
-    "typescript": "^5.7.2",
-    "typescript-eslint": "^8.18.2"
+    "tstyche": "^3.5.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.24.1"
   }
 }

package/tsconfig.json

@@ -3,6 +3,7 @@
   "include": ["src/**/*"],
   "compilerOptions": {
     "declaration": true,
+    "module": "Preserve",
     "outDir": "build"
   }
 }

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 */
-}