@dr.pogodin/js-utils 0.1.3 → 0.1.5

package/README.md

@@ -46,6 +46,12 @@ and used in the same way):
   — One year expressed in milliseconds.
 
 ### Types
+- `Extends<Base, T extends Base>` &mdash; Validates compile-time the type **T**
+  extends (is assignable to) the type **Base**; returns **T** if successful.
+- `Implements<Base, T extends Base & ...>` &mdash; Validates compile-time
+  the type **T** extends (is assignable to) the type **Base**, and also has
+  all (if any) optional fields defined in the **Base**; returns **T** if
+  the validation passes.
 - `ObjectKey` &mdash; **string** | **number** | **symbol** &mdash;
   The most generic valid type of an object key in TypeScript.
 

package/babel.module.config.js

@@ -1,6 +1,9 @@
 // Babel is used for Jest testing.
 
 export default {
+  plugins: [
+    'babel-plugin-add-import-extension',
+  ],
   presets: [
     ['./config/babel/preset', {
       modules: false,

package/build/common/types.js

@@ -12,4 +12,18 @@ exports.assertEmptyObject = assertEmptyObject;
 function assertEmptyObject(object) {
   if (Object.keys(object).length) throw Error('The object is not empty');
 }
+
+/**
+ * Validates compile-time that the type T extends Base, and returns T.
+ *
+ * BEWARE: In the case Base has some optional fields missing in T, T still
+ * extends Base (as "extends" means T is assignable to Base)! The Implements
+ * util below also checks that T has all optional fields defined in Base.
+ */
+
+/**
+ * Validates compile-time that the type T extends (is assignable to) the type
+ * Base, and also that it has defined all (if any) optional fields defined in
+ * the Base. Returns T if the validation passes.
+ */
 //# sourceMappingURL=types.js.map

package/build/common/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":["assertEmptyObject","object","Object","keys","length","Error"],"sources":["../../src/types.ts"],"sourcesContent":["// Misc TypeScript-specific utilities.\n\n/** The most permissive object key type. */\nexport type ObjectKey = string | number | symbol;\n\n/** Asserts given object is empty, both compile- and run-time. */\nexport function assertEmptyObject(object: Record<ObjectKey, never>): void {\n  if (Object.keys(object).length) throw Error('The object is not empty');\n}\n"],"mappings":";;;;;;AAAA;;AAEA;;AAGA;AACO,SAASA,iBAAiBA,CAACC,MAAgC,EAAQ;EACxE,IAAIC,MAAM,CAACC,IAAI,CAACF,MAAM,CAAC,CAACG,MAAM,EAAE,MAAMC,KAAK,CAAC,yBAAyB,CAAC;AACxE","ignoreList":[]}
+{"version":3,"file":"types.js","names":["assertEmptyObject","object","Object","keys","length","Error"],"sources":["../../src/types.ts"],"sourcesContent":["// Misc TypeScript-specific utilities.\n\n/** The most permissive object key type. */\nexport type ObjectKey = string | number | symbol;\n\n/** Asserts given object is empty, both compile- and run-time. */\nexport function assertEmptyObject(object: Record<ObjectKey, never>): void {\n  if (Object.keys(object).length) throw Error('The object is not empty');\n}\n\n/**\n * Validates compile-time that the type T extends Base, and returns T.\n *\n * BEWARE: In the case Base has some optional fields missing in T, T still\n * extends Base (as \"extends\" means T is assignable to Base)! The Implements\n * util below also checks that T has all optional fields defined in Base.\n */\nexport type Extends<Base, T extends Base> = T;\n\n/**\n * Validates compile-time that the type T extends (is assignable to) the type\n * Base, and also that it has defined all (if any) optional fields defined in\n * the Base. Returns T if the validation passes.\n */\nexport type Implements<\n  Base,\n  T extends Required<T> extends Required<Base> ? Base : Required<Base>,\n> = T;\n"],"mappings":";;;;;;AAAA;;AAEA;;AAGA;AACO,SAASA,iBAAiBA,CAACC,MAAgC,EAAQ;EACxE,IAAIC,MAAM,CAACC,IAAI,CAACF,MAAM,CAAC,CAACG,MAAM,EAAE,MAAMC,KAAK,CAAC,yBAAyB,CAAC;AACxE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA","ignoreList":[]}

package/build/module/Semaphore.js

@@ -1,5 +1,4 @@
-import Barrier from './Barrier';
-
+import Barrier from "./Barrier.js";
 /**
  * Implements a simple semaphore for async code logic.
  */

package/build/module/Semaphore.js.map

@@ -1 +1 @@
-{"version":3,"file":"Semaphore.js","names":["Barrier","Semaphore","constructor","ready","pReady","setReady","bool","pDraining","pQueue","length","pDrainQueue","seize","waitReady","barrier","push","pDrainLock","resolve","shift"],"sources":["../../src/Semaphore.ts"],"sourcesContent":["import Barrier from './Barrier';\n\n/**\n * Implements a simple semaphore for async code logic.\n */\nexport default class Semaphore {\n  constructor(ready = false) {\n    // TODO: Boolean conversion is performed for backward compatibility with\n    // plain JS projects. Drop it in future.\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-conversion\n    this.pReady = !!ready;\n  }\n\n  get ready(): boolean {\n    return this.pReady;\n  }\n\n  setReady(ready: boolean): void {\n    // TODO: Boolean conversion is performed for backward compatibility with\n    // plain JS projects. Drop it in future.\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-conversion\n    const bool = !!ready;\n    if (this.pReady !== bool) {\n      this.pReady = bool;\n      if (bool && !this.pDraining && this.pQueue.length) {\n        void this.pDrainQueue();\n      }\n    }\n  }\n\n  /**\n   * Waits until the semaphore is ready, and marks it as non-ready (seizes it).\n   */\n  async seize(): Promise<void> {\n    return this.waitReady(true);\n  }\n\n  async waitReady(seize = false): Promise<void> {\n    if (!this.pReady || this.pQueue.length) {\n      const barrier = new Barrier<void>();\n      this.pQueue.push(barrier);\n      await barrier;\n      if (seize) this.pReady = false;\n      void this.pDrainLock!.resolve();\n    } else if (seize) this.pReady = false;\n  }\n\n  // Private members below this point.\n\n  /**\n   * If semaphore is ready, it releases the next barrier in the queue, if any,\n   * and reschedules itself for a call in the next event loop iteration.\n   * Otherwise, it breaks the queue draining loop, which will be restarted\n   * the next time the semaphore is set ready.\n   */\n  async pDrainQueue(): Promise<void> {\n    this.pDraining = true;\n    while (this.pReady && this.pQueue.length) {\n      this.pDrainLock = new Barrier();\n      void this.pQueue[0]!.resolve();\n      await this.pDrainLock;\n      void this.pQueue.shift();\n    }\n    this.pDraining = false;\n    this.pDrainLock = null;\n  }\n\n  // \"true\" when the drain queue process is running (and thus no need to start\n  // a new one).\n  private pDraining = false;\n\n  // Each time a Promise from drain queue is resolved this drainLock is set\n  // to block further queue draining until the promise resolution handler\n  // (.seize() or .waitReady()) unlocks it, thus confirming it is fine\n  // to continue the draining. This is specifically important for .seize(),\n  // which should have a chance to switch semaphore state to non-ready prior\n  // to next Promise in the queue being unlocked.\n  private pDrainLock: Barrier<void> | null = null;\n\n  // The array of barriers set for each async code flow awaiting for\n  // the Semaphore to become ready.\n  private pQueue: Array<Barrier<void>> = [];\n\n  private pReady: boolean;\n}\n"],"mappings":"AAAA,OAAOA,OAAO,MAAM,WAAW;;AAE/B;AACA;AACA;AACA,eAAe,MAAMC,SAAS,CAAC;EAC7BC,WAAWA,CAACC,KAAK,GAAG,KAAK,EAAE;IACzB;IACA;IACA;IACA,IAAI,CAACC,MAAM,GAAG,CAAC,CAACD,KAAK;EACvB;EAEA,IAAIA,KAAKA,CAAA,EAAY;IACnB,OAAO,IAAI,CAACC,MAAM;EACpB;EAEAC,QAAQA,CAACF,KAAc,EAAQ;IAC7B;IACA;IACA;IACA,MAAMG,IAAI,GAAG,CAAC,CAACH,KAAK;IACpB,IAAI,IAAI,CAACC,MAAM,KAAKE,IAAI,EAAE;MACxB,IAAI,CAACF,MAAM,GAAGE,IAAI;MAClB,IAAIA,IAAI,IAAI,CAAC,IAAI,CAACC,SAAS,IAAI,IAAI,CAACC,MAAM,CAACC,MAAM,EAAE;QACjD,KAAK,IAAI,CAACC,WAAW,CAAC,CAAC;MACzB;IACF;EACF;;EAEA;AACF;AACA;EACE,MAAMC,KAAKA,CAAA,EAAkB;IAC3B,OAAO,IAAI,CAACC,SAAS,CAAC,IAAI,CAAC;EAC7B;EAEA,MAAMA,SAASA,CAACD,KAAK,GAAG,KAAK,EAAiB;IAC5C,IAAI,CAAC,IAAI,CAACP,MAAM,IAAI,IAAI,CAACI,MAAM,CAACC,MAAM,EAAE;MACtC,MAAMI,OAAO,GAAG,IAAIb,OAAO,CAAO,CAAC;MACnC,IAAI,CAACQ,MAAM,CAACM,IAAI,CAACD,OAAO,CAAC;MACzB,MAAMA,OAAO;MACb,IAAIF,KAAK,EAAE,IAAI,CAACP,MAAM,GAAG,KAAK;MAC9B,KAAK,IAAI,CAACW,UAAU,CAAEC,OAAO,CAAC,CAAC;IACjC,CAAC,MAAM,IAAIL,KAAK,EAAE,IAAI,CAACP,MAAM,GAAG,KAAK;EACvC;;EAEA;;EAEA;AACF;AACA;AACA;AACA;AACA;EACE,MAAMM,WAAWA,CAAA,EAAkB;IACjC,IAAI,CAACH,SAAS,GAAG,IAAI;IACrB,OAAO,IAAI,CAACH,MAAM,IAAI,IAAI,CAACI,MAAM,CAACC,MAAM,EAAE;MACxC,IAAI,CAACM,UAAU,GAAG,IAAIf,OAAO,CAAC,CAAC;MAC/B,KAAK,IAAI,CAACQ,MAAM,CAAC,CAAC,CAAC,CAAEQ,OAAO,CAAC,CAAC;MAC9B,MAAM,IAAI,CAACD,UAAU;MACrB,KAAK,IAAI,CAACP,MAAM,CAACS,KAAK,CAAC,CAAC;IAC1B;IACA,IAAI,CAACV,SAAS,GAAG,KAAK;IACtB,IAAI,CAACQ,UAAU,GAAG,IAAI;EACxB;;EAEA;EACA;EACQR,SAAS,GAAG,KAAK;;EAEzB;EACA;EACA;EACA;EACA;EACA;EACQQ,UAAU,GAAyB,IAAI;;EAE/C;EACA;EACQP,MAAM,GAAyB,EAAE;AAG3C","ignoreList":[]}
+{"version":3,"file":"Semaphore.js","names":["Barrier","Semaphore","constructor","ready","pReady","setReady","bool","pDraining","pQueue","length","pDrainQueue","seize","waitReady","barrier","push","pDrainLock","resolve","shift"],"sources":["../../src/Semaphore.ts"],"sourcesContent":["import Barrier from './Barrier';\n\n/**\n * Implements a simple semaphore for async code logic.\n */\nexport default class Semaphore {\n  constructor(ready = false) {\n    // TODO: Boolean conversion is performed for backward compatibility with\n    // plain JS projects. Drop it in future.\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-conversion\n    this.pReady = !!ready;\n  }\n\n  get ready(): boolean {\n    return this.pReady;\n  }\n\n  setReady(ready: boolean): void {\n    // TODO: Boolean conversion is performed for backward compatibility with\n    // plain JS projects. Drop it in future.\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-conversion\n    const bool = !!ready;\n    if (this.pReady !== bool) {\n      this.pReady = bool;\n      if (bool && !this.pDraining && this.pQueue.length) {\n        void this.pDrainQueue();\n      }\n    }\n  }\n\n  /**\n   * Waits until the semaphore is ready, and marks it as non-ready (seizes it).\n   */\n  async seize(): Promise<void> {\n    return this.waitReady(true);\n  }\n\n  async waitReady(seize = false): Promise<void> {\n    if (!this.pReady || this.pQueue.length) {\n      const barrier = new Barrier<void>();\n      this.pQueue.push(barrier);\n      await barrier;\n      if (seize) this.pReady = false;\n      void this.pDrainLock!.resolve();\n    } else if (seize) this.pReady = false;\n  }\n\n  // Private members below this point.\n\n  /**\n   * If semaphore is ready, it releases the next barrier in the queue, if any,\n   * and reschedules itself for a call in the next event loop iteration.\n   * Otherwise, it breaks the queue draining loop, which will be restarted\n   * the next time the semaphore is set ready.\n   */\n  async pDrainQueue(): Promise<void> {\n    this.pDraining = true;\n    while (this.pReady && this.pQueue.length) {\n      this.pDrainLock = new Barrier();\n      void this.pQueue[0]!.resolve();\n      await this.pDrainLock;\n      void this.pQueue.shift();\n    }\n    this.pDraining = false;\n    this.pDrainLock = null;\n  }\n\n  // \"true\" when the drain queue process is running (and thus no need to start\n  // a new one).\n  private pDraining = false;\n\n  // Each time a Promise from drain queue is resolved this drainLock is set\n  // to block further queue draining until the promise resolution handler\n  // (.seize() or .waitReady()) unlocks it, thus confirming it is fine\n  // to continue the draining. This is specifically important for .seize(),\n  // which should have a chance to switch semaphore state to non-ready prior\n  // to next Promise in the queue being unlocked.\n  private pDrainLock: Barrier<void> | null = null;\n\n  // The array of barriers set for each async code flow awaiting for\n  // the Semaphore to become ready.\n  private pQueue: Array<Barrier<void>> = [];\n\n  private pReady: boolean;\n}\n"],"mappings":"OAAOA,OAAO;AAEd;AACA;AACA;AACA,eAAe,MAAMC,SAAS,CAAC;EAC7BC,WAAWA,CAACC,KAAK,GAAG,KAAK,EAAE;IACzB;IACA;IACA;IACA,IAAI,CAACC,MAAM,GAAG,CAAC,CAACD,KAAK;EACvB;EAEA,IAAIA,KAAKA,CAAA,EAAY;IACnB,OAAO,IAAI,CAACC,MAAM;EACpB;EAEAC,QAAQA,CAACF,KAAc,EAAQ;IAC7B;IACA;IACA;IACA,MAAMG,IAAI,GAAG,CAAC,CAACH,KAAK;IACpB,IAAI,IAAI,CAACC,MAAM,KAAKE,IAAI,EAAE;MACxB,IAAI,CAACF,MAAM,GAAGE,IAAI;MAClB,IAAIA,IAAI,IAAI,CAAC,IAAI,CAACC,SAAS,IAAI,IAAI,CAACC,MAAM,CAACC,MAAM,EAAE;QACjD,KAAK,IAAI,CAACC,WAAW,CAAC,CAAC;MACzB;IACF;EACF;;EAEA;AACF;AACA;EACE,MAAMC,KAAKA,CAAA,EAAkB;IAC3B,OAAO,IAAI,CAACC,SAAS,CAAC,IAAI,CAAC;EAC7B;EAEA,MAAMA,SAASA,CAACD,KAAK,GAAG,KAAK,EAAiB;IAC5C,IAAI,CAAC,IAAI,CAACP,MAAM,IAAI,IAAI,CAACI,MAAM,CAACC,MAAM,EAAE;MACtC,MAAMI,OAAO,GAAG,IAAIb,OAAO,CAAO,CAAC;MACnC,IAAI,CAACQ,MAAM,CAACM,IAAI,CAACD,OAAO,CAAC;MACzB,MAAMA,OAAO;MACb,IAAIF,KAAK,EAAE,IAAI,CAACP,MAAM,GAAG,KAAK;MAC9B,KAAK,IAAI,CAACW,UAAU,CAAEC,OAAO,CAAC,CAAC;IACjC,CAAC,MAAM,IAAIL,KAAK,EAAE,IAAI,CAACP,MAAM,GAAG,KAAK;EACvC;;EAEA;;EAEA;AACF;AACA;AACA;AACA;AACA;EACE,MAAMM,WAAWA,CAAA,EAAkB;IACjC,IAAI,CAACH,SAAS,GAAG,IAAI;IACrB,OAAO,IAAI,CAACH,MAAM,IAAI,IAAI,CAACI,MAAM,CAACC,MAAM,EAAE;MACxC,IAAI,CAACM,UAAU,GAAG,IAAIf,OAAO,CAAC,CAAC;MAC/B,KAAK,IAAI,CAACQ,MAAM,CAAC,CAAC,CAAC,CAAEQ,OAAO,CAAC,CAAC;MAC9B,MAAM,IAAI,CAACD,UAAU;MACrB,KAAK,IAAI,CAACP,MAAM,CAACS,KAAK,CAAC,CAAC;IAC1B;IACA,IAAI,CAACV,SAAS,GAAG,KAAK;IACtB,IAAI,CAACQ,UAAU,GAAG,IAAI;EACxB;;EAEA;EACA;EACQR,SAAS,GAAG,KAAK;;EAEzB;EACA;EACA;EACA;EACA;EACA;EACQQ,UAAU,GAAyB,IAAI;;EAE/C;EACA;EACQP,MAAM,GAAyB,EAAE;AAG3C","ignoreList":[]}

package/build/module/index.js

@@ -1,8 +1,8 @@
-export { default as Barrier } from './Barrier';
-export * from './Cached';
-export * from './Emitter';
-export { default as Semaphore } from './Semaphore';
-export * from './time';
-export * from './types';
-export { default as withRetries } from './withRetries';
+export { default as Barrier } from "./Barrier.js";
+export * from "./Cached.js";
+export * from "./Emitter.js";
+export { default as Semaphore } from "./Semaphore.js";
+export * from "./time.js";
+export * from "./types.js";
+export { default as withRetries } from "./withRetries.js";
 //# sourceMappingURL=index.js.map

package/build/module/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["default","Barrier","Semaphore","withRetries"],"sources":["../../src/index.ts"],"sourcesContent":["export { default as Barrier } from './Barrier';\nexport * from './Cached';\nexport * from './Emitter';\nexport { default as Semaphore } from './Semaphore';\nexport * from './time';\nexport * from './types';\nexport { default as withRetries } from './withRetries';\n"],"mappings":"AAAA,SAASA,OAAO,IAAIC,OAAO,QAAQ,WAAW;AAC9C,cAAc,UAAU;AACxB,cAAc,WAAW;AACzB,SAASD,OAAO,IAAIE,SAAS,QAAQ,aAAa;AAClD,cAAc,QAAQ;AACtB,cAAc,SAAS;AACvB,SAASF,OAAO,IAAIG,WAAW,QAAQ,eAAe","ignoreList":[]}
+{"version":3,"file":"index.js","names":["default","Barrier","Semaphore","withRetries"],"sources":["../../src/index.ts"],"sourcesContent":["export { default as Barrier } from './Barrier';\nexport * from './Cached';\nexport * from './Emitter';\nexport { default as Semaphore } from './Semaphore';\nexport * from './time';\nexport * from './types';\nexport { default as withRetries } from './withRetries';\n"],"mappings":"SAASA,OAAO,IAAIC,OAAO;AAAA;AAAA;AAAA,SAGlBD,OAAO,IAAIE,SAAS;AAAA;AAAA;AAAA,SAGpBF,OAAO,IAAIG,WAAW","ignoreList":[]}

package/build/module/time.js

@@ -1,6 +1,4 @@
-import Barrier from './Barrier';
-
-// This is not very elegant, but as of now TypeScript does not support type
+import Barrier from "./Barrier.js"; // 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.

package/build/module/time.js.map

@@ -1 +1 @@
-{"version":3,"file":"time.js","names":["Barrier","SEC_MS","MIN_MS","HOUR_MS","DAY_MS","YEAR_MS","Timer","abort","pAbort","timeout","pTimeout","constructor","executor","undefined","init","Error","id","setTimeout","resolve","clearTimeout","then","onFulfilled","onRejected","res","timer","t"],"sources":["../../src/time.ts"],"sourcesContent":["import Barrier, { type Executor } from './Barrier';\n\n// This is not very elegant, but as of now TypeScript does not support type\n// arithmetic, thus we can't have constants assigned like `MIN_MS = 60 * SEC_MS`\n// and have the result type to be 60000 (number literal), it would be just\n// the generic number type.\nexport const SEC_MS = 1000;\nexport const MIN_MS = 60000; // 60 * SEC_MS\nexport const HOUR_MS = 3600000; // 60 * MIN_MS\nexport const DAY_MS = 86400000; // 24 * HOUR_MS\nexport const YEAR_MS = 31536000000; // 365 * DAY_MS\n\n// TODO: Ok, as we have ended up with a Timer class, mostly to achieve a good\n// TypeScript typing for timer() function, it makes sense to expose the class\n// from the library as well, and it should be documented later.\nexport class Timer<T> extends Barrier<void, T> {\n  private pAbort: () => void;\n\n  private pTimeout?: number;\n\n  get abort(): () => void {\n    return this.pAbort;\n  }\n\n  get timeout(): number | undefined {\n    return this.pTimeout;\n  }\n\n  /**\n   * Creates a new, non-initialized instance of Timer. Call .init() method\n   * to actually initialize and launch the timer.\n   *\n   * NOTE: Although it might be tempting to accept `timeout` value as\n   * a constructor's argument, it won't work well, because Timer is an\n   * extension of Promise (via Barrier), and the way Promises works (in\n   * particular their .then() method, which internally calls constructor()\n   * with special executor) does not play along with initalization depending\n   * on custom parameters done in constructor().\n   *\n   * @param executor\n   */\n  constructor(executor?: Executor<T>) {\n    super(executor);\n    this.pAbort = () => undefined;\n  }\n\n  init(timeout: number): this {\n    if (this.pTimeout !== undefined) {\n      throw Error('This Timer is initialized already');\n    }\n    this.pTimeout = timeout;\n    if (timeout > 0) {\n      const id = setTimeout(() => {\n        void super.resolve();\n      }, timeout);\n      this.pAbort = () => {\n        clearTimeout(id);\n      };\n    } else {\n      void super.resolve();\n    }\n    return this;\n  }\n\n  // TODO: For async functions TS requires the return type to be the global\n  // Promise, thus not allowing to return our Timer type extending that via\n  // Barrier. Thus, we don't mark this method async for now, disabling the rule,\n  // and we should think more about it in future.\n  // eslint-disable-next-line @typescript-eslint/promise-function-async\n  then<TR1, TR2>(\n    onFulfilled?: ((value: T) => TR1 | PromiseLike<TR1>) | null,\n    onRejected?: ((reason: unknown) => TR2 | PromiseLike<TR2>) | null,\n  ): Timer<TR1 | TR2> {\n    const res = super.then(onFulfilled, onRejected) as Timer<TR1 | TR2>;\n    if (this.timeout !== undefined) void res.init(this.timeout);\n    return res;\n  }\n}\n\n/**\n * Creates a Promise, which resolves after the given timeout.\n * @param {number} timeout Timeout [ms].\n * @return {Barrier} Resolves after the timeout. It has additional\n *  .abort() method attached, which cancels the pending timer resolution\n *  (without resolving or rejecting the barrier).\n */\n// TODO: For async functions TS requires the return type to be the global\n// Promise, thus not allowing to return our Timer type extending that via\n// Barrier. Thus, we don't mark this method async for now, disabling the rule,\n// and we should think more about it in future.\n// eslint-disable-next-line @typescript-eslint/promise-function-async\nexport function timer(timeout: number): Timer<void> {\n  const t = new Timer<void>();\n  return t.init(timeout);\n}\n"],"mappings":"AAAA,OAAOA,OAAO,MAAyB,WAAW;;AAElD;AACA;AACA;AACA;AACA,OAAO,MAAMC,MAAM,GAAG,IAAI;AAC1B,OAAO,MAAMC,MAAM,GAAG,KAAK,CAAC,CAAC;AAC7B,OAAO,MAAMC,OAAO,GAAG,OAAO,CAAC,CAAC;AAChC,OAAO,MAAMC,MAAM,GAAG,QAAQ,CAAC,CAAC;AAChC,OAAO,MAAMC,OAAO,GAAG,WAAW,CAAC,CAAC;;AAEpC;AACA;AACA;AACA,OAAO,MAAMC,KAAK,SAAYN,OAAO,CAAU;EAK7C,IAAIO,KAAKA,CAAA,EAAe;IACtB,OAAO,IAAI,CAACC,MAAM;EACpB;EAEA,IAAIC,OAAOA,CAAA,EAAuB;IAChC,OAAO,IAAI,CAACC,QAAQ;EACtB;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACEC,WAAWA,CAACC,QAAsB,EAAE;IAClC,KAAK,CAACA,QAAQ,CAAC;IACf,IAAI,CAACJ,MAAM,GAAG,MAAMK,SAAS;EAC/B;EAEAC,IAAIA,CAACL,OAAe,EAAQ;IAC1B,IAAI,IAAI,CAACC,QAAQ,KAAKG,SAAS,EAAE;MAC/B,MAAME,KAAK,CAAC,mCAAmC,CAAC;IAClD;IACA,IAAI,CAACL,QAAQ,GAAGD,OAAO;IACvB,IAAIA,OAAO,GAAG,CAAC,EAAE;MACf,MAAMO,EAAE,GAAGC,UAAU,CAAC,MAAM;QAC1B,KAAK,KAAK,CAACC,OAAO,CAAC,CAAC;MACtB,CAAC,EAAET,OAAO,CAAC;MACX,IAAI,CAACD,MAAM,GAAG,MAAM;QAClBW,YAAY,CAACH,EAAE,CAAC;MAClB,CAAC;IACH,CAAC,MAAM;MACL,KAAK,KAAK,CAACE,OAAO,CAAC,CAAC;IACtB;IACA,OAAO,IAAI;EACb;;EAEA;EACA;EACA;EACA;EACA;EACAE,IAAIA,CACFC,WAA2D,EAC3DC,UAAiE,EAC/C;IAClB,MAAMC,GAAG,GAAG,KAAK,CAACH,IAAI,CAACC,WAAW,EAAEC,UAAU,CAAqB;IACnE,IAAI,IAAI,CAACb,OAAO,KAAKI,SAAS,EAAE,KAAKU,GAAG,CAACT,IAAI,CAAC,IAAI,CAACL,OAAO,CAAC;IAC3D,OAAOc,GAAG;EACZ;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAACf,OAAe,EAAe;EAClD,MAAMgB,CAAC,GAAG,IAAInB,KAAK,CAAO,CAAC;EAC3B,OAAOmB,CAAC,CAACX,IAAI,CAACL,OAAO,CAAC;AACxB","ignoreList":[]}
+{"version":3,"file":"time.js","names":["Barrier","SEC_MS","MIN_MS","HOUR_MS","DAY_MS","YEAR_MS","Timer","abort","pAbort","timeout","pTimeout","constructor","executor","undefined","init","Error","id","setTimeout","resolve","clearTimeout","then","onFulfilled","onRejected","res","timer","t"],"sources":["../../src/time.ts"],"sourcesContent":["import Barrier, { type Executor } from './Barrier';\n\n// This is not very elegant, but as of now TypeScript does not support type\n// arithmetic, thus we can't have constants assigned like `MIN_MS = 60 * SEC_MS`\n// and have the result type to be 60000 (number literal), it would be just\n// the generic number type.\nexport const SEC_MS = 1000;\nexport const MIN_MS = 60000; // 60 * SEC_MS\nexport const HOUR_MS = 3600000; // 60 * MIN_MS\nexport const DAY_MS = 86400000; // 24 * HOUR_MS\nexport const YEAR_MS = 31536000000; // 365 * DAY_MS\n\n// TODO: Ok, as we have ended up with a Timer class, mostly to achieve a good\n// TypeScript typing for timer() function, it makes sense to expose the class\n// from the library as well, and it should be documented later.\nexport class Timer<T> extends Barrier<void, T> {\n  private pAbort: () => void;\n\n  private pTimeout?: number;\n\n  get abort(): () => void {\n    return this.pAbort;\n  }\n\n  get timeout(): number | undefined {\n    return this.pTimeout;\n  }\n\n  /**\n   * Creates a new, non-initialized instance of Timer. Call .init() method\n   * to actually initialize and launch the timer.\n   *\n   * NOTE: Although it might be tempting to accept `timeout` value as\n   * a constructor's argument, it won't work well, because Timer is an\n   * extension of Promise (via Barrier), and the way Promises works (in\n   * particular their .then() method, which internally calls constructor()\n   * with special executor) does not play along with initalization depending\n   * on custom parameters done in constructor().\n   *\n   * @param executor\n   */\n  constructor(executor?: Executor<T>) {\n    super(executor);\n    this.pAbort = () => undefined;\n  }\n\n  init(timeout: number): this {\n    if (this.pTimeout !== undefined) {\n      throw Error('This Timer is initialized already');\n    }\n    this.pTimeout = timeout;\n    if (timeout > 0) {\n      const id = setTimeout(() => {\n        void super.resolve();\n      }, timeout);\n      this.pAbort = () => {\n        clearTimeout(id);\n      };\n    } else {\n      void super.resolve();\n    }\n    return this;\n  }\n\n  // TODO: For async functions TS requires the return type to be the global\n  // Promise, thus not allowing to return our Timer type extending that via\n  // Barrier. Thus, we don't mark this method async for now, disabling the rule,\n  // and we should think more about it in future.\n  // eslint-disable-next-line @typescript-eslint/promise-function-async\n  then<TR1, TR2>(\n    onFulfilled?: ((value: T) => TR1 | PromiseLike<TR1>) | null,\n    onRejected?: ((reason: unknown) => TR2 | PromiseLike<TR2>) | null,\n  ): Timer<TR1 | TR2> {\n    const res = super.then(onFulfilled, onRejected) as Timer<TR1 | TR2>;\n    if (this.timeout !== undefined) void res.init(this.timeout);\n    return res;\n  }\n}\n\n/**\n * Creates a Promise, which resolves after the given timeout.\n * @param {number} timeout Timeout [ms].\n * @return {Barrier} Resolves after the timeout. It has additional\n *  .abort() method attached, which cancels the pending timer resolution\n *  (without resolving or rejecting the barrier).\n */\n// TODO: For async functions TS requires the return type to be the global\n// Promise, thus not allowing to return our Timer type extending that via\n// Barrier. Thus, we don't mark this method async for now, disabling the rule,\n// and we should think more about it in future.\n// eslint-disable-next-line @typescript-eslint/promise-function-async\nexport function timer(timeout: number): Timer<void> {\n  const t = new Timer<void>();\n  return t.init(timeout);\n}\n"],"mappings":"OAAOA,OAAO,sBAEd;AACA;AACA;AACA;AACA,OAAO,MAAMC,MAAM,GAAG,IAAI;AAC1B,OAAO,MAAMC,MAAM,GAAG,KAAK,CAAC,CAAC;AAC7B,OAAO,MAAMC,OAAO,GAAG,OAAO,CAAC,CAAC;AAChC,OAAO,MAAMC,MAAM,GAAG,QAAQ,CAAC,CAAC;AAChC,OAAO,MAAMC,OAAO,GAAG,WAAW,CAAC,CAAC;;AAEpC;AACA;AACA;AACA,OAAO,MAAMC,KAAK,SAAYN,OAAO,CAAU;EAK7C,IAAIO,KAAKA,CAAA,EAAe;IACtB,OAAO,IAAI,CAACC,MAAM;EACpB;EAEA,IAAIC,OAAOA,CAAA,EAAuB;IAChC,OAAO,IAAI,CAACC,QAAQ;EACtB;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACEC,WAAWA,CAACC,QAAsB,EAAE;IAClC,KAAK,CAACA,QAAQ,CAAC;IACf,IAAI,CAACJ,MAAM,GAAG,MAAMK,SAAS;EAC/B;EAEAC,IAAIA,CAACL,OAAe,EAAQ;IAC1B,IAAI,IAAI,CAACC,QAAQ,KAAKG,SAAS,EAAE;MAC/B,MAAME,KAAK,CAAC,mCAAmC,CAAC;IAClD;IACA,IAAI,CAACL,QAAQ,GAAGD,OAAO;IACvB,IAAIA,OAAO,GAAG,CAAC,EAAE;MACf,MAAMO,EAAE,GAAGC,UAAU,CAAC,MAAM;QAC1B,KAAK,KAAK,CAACC,OAAO,CAAC,CAAC;MACtB,CAAC,EAAET,OAAO,CAAC;MACX,IAAI,CAACD,MAAM,GAAG,MAAM;QAClBW,YAAY,CAACH,EAAE,CAAC;MAClB,CAAC;IACH,CAAC,MAAM;MACL,KAAK,KAAK,CAACE,OAAO,CAAC,CAAC;IACtB;IACA,OAAO,IAAI;EACb;;EAEA;EACA;EACA;EACA;EACA;EACAE,IAAIA,CACFC,WAA2D,EAC3DC,UAAiE,EAC/C;IAClB,MAAMC,GAAG,GAAG,KAAK,CAACH,IAAI,CAACC,WAAW,EAAEC,UAAU,CAAqB;IACnE,IAAI,IAAI,CAACb,OAAO,KAAKI,SAAS,EAAE,KAAKU,GAAG,CAACT,IAAI,CAAC,IAAI,CAACL,OAAO,CAAC;IAC3D,OAAOc,GAAG;EACZ;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAACf,OAAe,EAAe;EAClD,MAAMgB,CAAC,GAAG,IAAInB,KAAK,CAAO,CAAC;EAC3B,OAAOmB,CAAC,CAACX,IAAI,CAACL,OAAO,CAAC;AACxB","ignoreList":[]}

package/build/module/types.js

@@ -6,4 +6,18 @@
 export function assertEmptyObject(object) {
   if (Object.keys(object).length) throw Error('The object is not empty');
 }
+
+/**
+ * Validates compile-time that the type T extends Base, and returns T.
+ *
+ * BEWARE: In the case Base has some optional fields missing in T, T still
+ * extends Base (as "extends" means T is assignable to Base)! The Implements
+ * util below also checks that T has all optional fields defined in Base.
+ */
+
+/**
+ * Validates compile-time that the type T extends (is assignable to) the type
+ * Base, and also that it has defined all (if any) optional fields defined in
+ * the Base. Returns T if the validation passes.
+ */
 //# sourceMappingURL=types.js.map

package/build/module/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":["assertEmptyObject","object","Object","keys","length","Error"],"sources":["../../src/types.ts"],"sourcesContent":["// Misc TypeScript-specific utilities.\n\n/** The most permissive object key type. */\nexport type ObjectKey = string | number | symbol;\n\n/** Asserts given object is empty, both compile- and run-time. */\nexport function assertEmptyObject(object: Record<ObjectKey, never>): void {\n  if (Object.keys(object).length) throw Error('The object is not empty');\n}\n"],"mappings":"AAAA;;AAEA;;AAGA;AACA,OAAO,SAASA,iBAAiBA,CAACC,MAAgC,EAAQ;EACxE,IAAIC,MAAM,CAACC,IAAI,CAACF,MAAM,CAAC,CAACG,MAAM,EAAE,MAAMC,KAAK,CAAC,yBAAyB,CAAC;AACxE","ignoreList":[]}
+{"version":3,"file":"types.js","names":["assertEmptyObject","object","Object","keys","length","Error"],"sources":["../../src/types.ts"],"sourcesContent":["// Misc TypeScript-specific utilities.\n\n/** The most permissive object key type. */\nexport type ObjectKey = string | number | symbol;\n\n/** Asserts given object is empty, both compile- and run-time. */\nexport function assertEmptyObject(object: Record<ObjectKey, never>): void {\n  if (Object.keys(object).length) throw Error('The object is not empty');\n}\n\n/**\n * Validates compile-time that the type T extends Base, and returns T.\n *\n * BEWARE: In the case Base has some optional fields missing in T, T still\n * extends Base (as \"extends\" means T is assignable to Base)! The Implements\n * util below also checks that T has all optional fields defined in Base.\n */\nexport type Extends<Base, T extends Base> = T;\n\n/**\n * Validates compile-time that the type T extends (is assignable to) the type\n * Base, and also that it has defined all (if any) optional fields defined in\n * the Base. Returns T if the validation passes.\n */\nexport type Implements<\n  Base,\n  T extends Required<T> extends Required<Base> ? Base : Required<Base>,\n> = T;\n"],"mappings":"AAAA;;AAEA;;AAGA;AACA,OAAO,SAASA,iBAAiBA,CAACC,MAAgC,EAAQ;EACxE,IAAIC,MAAM,CAACC,IAAI,CAACF,MAAM,CAAC,CAACG,MAAM,EAAE,MAAMC,KAAK,CAAC,yBAAyB,CAAC;AACxE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA","ignoreList":[]}

package/build/module/withRetries.js

@@ -1,5 +1,4 @@
-import { timer } from './time';
-
+import { timer } from "./time.js";
 /**
  * Attempts to perform the given async `action` up to `maxRetries` times with
  * the specified `interval`, stopping at the first successful (non-throwing)

package/build/module/withRetries.js.map

@@ -1 +1 @@
-{"version":3,"file":"withRetries.js","names":["timer","withRetries","action","maxRetries","interval","n","res","Promise","error"],"sources":["../../src/withRetries.ts"],"sourcesContent":["import { timer } from './time';\n\n/**\n * Attempts to perform the given async `action` up to `maxRetries` times with\n * the specified `interval`, stopping at the first successful (non-throwing)\n * execution.\n * @param action\n * @param maxRetries Optional. The maximum number of re-tries. Defaults 3.\n * @param interval Optional. The interval between re-tries (in milliseconds).\n *  Defaults to 300ms.\n * @returns Resolves to the result of the successful `action` execution;\n *  or rejects with the error from the last faileda attempt.\n */\nexport default async function withRetries<T>(\n  action: () => T,\n  maxRetries = 3,\n  interval = 300,\n): Promise<Awaited<T>> {\n  for (let n = 1; ; ++n) {\n    try {\n      const res = action();\n      return res instanceof Promise ? await res : (res as Awaited<T>);\n    } catch (error) {\n      if (n < maxRetries) await timer(interval);\n      else throw error;\n    }\n  }\n}\n"],"mappings":"AAAA,SAASA,KAAK,QAAQ,QAAQ;;AAE9B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,eAAe,eAAeC,WAAWA,CACvCC,MAAe,EACfC,UAAU,GAAG,CAAC,EACdC,QAAQ,GAAG,GAAG,EACO;EACrB,KAAK,IAAIC,CAAC,GAAG,CAAC,GAAI,EAAEA,CAAC,EAAE;IACrB,IAAI;MACF,MAAMC,GAAG,GAAGJ,MAAM,CAAC,CAAC;MACpB,OAAOI,GAAG,YAAYC,OAAO,GAAG,MAAMD,GAAG,GAAIA,GAAkB;IACjE,CAAC,CAAC,OAAOE,KAAK,EAAE;MACd,IAAIH,CAAC,GAAGF,UAAU,EAAE,MAAMH,KAAK,CAACI,QAAQ,CAAC,CAAC,KACrC,MAAMI,KAAK;IAClB;EACF;AACF","ignoreList":[]}
+{"version":3,"file":"withRetries.js","names":["timer","withRetries","action","maxRetries","interval","n","res","Promise","error"],"sources":["../../src/withRetries.ts"],"sourcesContent":["import { timer } from './time';\n\n/**\n * Attempts to perform the given async `action` up to `maxRetries` times with\n * the specified `interval`, stopping at the first successful (non-throwing)\n * execution.\n * @param action\n * @param maxRetries Optional. The maximum number of re-tries. Defaults 3.\n * @param interval Optional. The interval between re-tries (in milliseconds).\n *  Defaults to 300ms.\n * @returns Resolves to the result of the successful `action` execution;\n *  or rejects with the error from the last faileda attempt.\n */\nexport default async function withRetries<T>(\n  action: () => T,\n  maxRetries = 3,\n  interval = 300,\n): Promise<Awaited<T>> {\n  for (let n = 1; ; ++n) {\n    try {\n      const res = action();\n      return res instanceof Promise ? await res : (res as Awaited<T>);\n    } catch (error) {\n      if (n < maxRetries) await timer(interval);\n      else throw error;\n    }\n  }\n}\n"],"mappings":"SAASA,KAAK;AAEd;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,eAAe,eAAeC,WAAWA,CACvCC,MAAe,EACfC,UAAU,GAAG,CAAC,EACdC,QAAQ,GAAG,GAAG,EACO;EACrB,KAAK,IAAIC,CAAC,GAAG,CAAC,GAAI,EAAEA,CAAC,EAAE;IACrB,IAAI;MACF,MAAMC,GAAG,GAAGJ,MAAM,CAAC,CAAC;MACpB,OAAOI,GAAG,YAAYC,OAAO,GAAG,MAAMD,GAAG,GAAIA,GAAkB;IACjE,CAAC,CAAC,OAAOE,KAAK,EAAE;MACd,IAAIH,CAAC,GAAGF,UAAU,EAAE,MAAMH,KAAK,CAACI,QAAQ,CAAC,CAAC,KACrC,MAAMI,KAAK;IAClB;EACF;AACF","ignoreList":[]}

package/build/types/types.d.ts

@@ -2,3 +2,17 @@
 export type ObjectKey = string | number | symbol;
 /** Asserts given object is empty, both compile- and run-time. */
 export declare function assertEmptyObject(object: Record<ObjectKey, never>): void;
+/**
+ * Validates compile-time that the type T extends Base, and returns T.
+ *
+ * BEWARE: In the case Base has some optional fields missing in T, T still
+ * extends Base (as "extends" means T is assignable to Base)! The Implements
+ * util below also checks that T has all optional fields defined in Base.
+ */
+export type Extends<Base, T extends Base> = T;
+/**
+ * Validates compile-time that the type T extends (is assignable to) the type
+ * Base, and also that it has defined all (if any) optional fields defined in
+ * the Base. Returns T if the validation passes.
+ */
+export type Implements<Base, T extends Required<T> extends Required<Base> ? Base : Required<Base>> = T;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dr.pogodin/js-utils",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Collection of JavaScript (TypeScript) utilities.",
   "main": "./build/module/index.js",
   "module": "./build/module/index.js",
   "types": "./build/types/index.d.ts",
   "exports": {
-    "require": "./build/common/index.js",
     "types": "./build/types/index.d.ts",
+    "require": "./build/common/index.js",
     "default": "./build/module/index.js"
   },
   "scripts": {
@@ -16,7 +16,7 @@
     "build:module": "rimraf build/module && babel src -x .ts --out-dir build/module --source-maps --config-file ./babel.module.config.js",
     "build:types": "rimraf build/types && tsc --project tsconfig.types.json",
     "jest": "npm run jest:types && npm run jest:logic",
-    "jest:logic": "jest --config jest.config.js",
+    "jest:logic": "jest --config jest.config.js --no-cache",
     "jest:types": "tstyche",
     "lint": "eslint",
     "test": "npm run lint && npm run typecheck && npm run jest",
@@ -38,22 +38,23 @@
   },
   "homepage": "https://github.com/birdofpreyru/js-utils#readme",
   "devDependencies": {
-    "@babel/cli": "^7.28.0",
-    "@babel/core": "^7.28.0",
-    "@babel/plugin-transform-runtime": "^7.28.0",
-    "@babel/preset-env": "^7.28.0",
-    "@babel/preset-typescript": "^7.27.1",
-    "@dr.pogodin/eslint-configs": "^0.0.9",
-    "@tsconfig/recommended": "^1.0.10",
+    "@babel/cli": "^7.28.3",
+    "@babel/core": "^7.28.5",
+    "@babel/plugin-transform-runtime": "^7.28.5",
+    "@babel/preset-env": "^7.28.5",
+    "@babel/preset-typescript": "^7.28.5",
+    "@dr.pogodin/eslint-configs": "^0.1.2",
+    "@tsconfig/recommended": "^1.0.13",
     "@types/jest": "^30.0.0",
-    "babel-jest": "^30.0.5",
-    "jest": "^30.0.5",
+    "babel-jest": "^30.2.0",
+    "babel-plugin-add-import-extension": "^1.6.0",
+    "jest": "^30.2.0",
     "mockdate": "^3.0.5",
-    "rimraf": "^6.0.1",
-    "tstyche": "^4.3.0",
-    "typescript": "^5.8.3"
+    "rimraf": "^6.1.2",
+    "tstyche": "^5.0.1",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@babel/runtime": "^7.27.6"
+    "@babel/runtime": "^7.28.4"
   }
 }

package/tstyche.config.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://tstyche.org/schemas/config.json",
+  "checkDeclarationFiles": true,
   "checkSuppressedErrors": true,
-  "checkSourceFiles": false,
   "testFileMatch": [
     "__tests__/**/*.{ts, tsx}"
   ]