async-utils-ts - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

dist/index.d.ts

 /**
- * Creates a promise that is resolved in the microtask queue.
- * @returns A promise that is resolved in the microtask queue.
+ * Creates a new Promise which resolves by queueing a microtask.
+ * A microtask is a short function which runs after the function or event that created it exits and only if JavaScript
+ * is not currently executing anything else. Use this function when you want to asynchronously execute code
+ * but want it to run as soon as possible, without a delay duration.
+ *
+ * @returns A Promise object that represents a microtask.
+ *
+ * @example
+ * microtask().then(() => {
+ *   console.log("This will run as soon as possible, asynchronously.");
+ * });
  */
 export declare const microtask: () => Promise<void>;
 /**
- * Creates a promise that is resolved after a macro task (using `setTimeout`).
- * @returns A promise that is resolved after a macro task.
+ * Creates a promise that resolves after the current event loop has been processed
+ * (i.e., after all microtasks have been completed). This can be thought of as making
+ * an asynchronous task that executes after the current `macrotask`.
+ *
+ * @returns A new Promise that resolves after the current event loop.
+ *
+ * @example
+ *
+ * macrotask().then(() => {
+ *   // This function will execute after all the current microtasks
+ *   console.log('This is a macrotask');
+ * });
+ *
  */
 export declare const macrotask: () => Promise<void>;
 /**
- * Creates a promise that is resolved in the next animation frame.
- * @returns A promise that is resolved in the next animation frame.
+ * Creates a new Promise that is resolved using `requestAnimationFrame`.
+ *
+ * This function can be used for delaying execution of code until the next frame,
+ * which is useful in animation-related operations.
+ *
+ * @returns A new Promise that is resolved with `requestAnimationFrame`.
+ *
+ * @example
+ *
+ * async function animate() {
+ *   // ...some animation logic...
+ *
+ *   // Wait for the next frame
+ *   await animationFrame();
+ *
+ *   // ...more animation logic...
+ * }
  */
 export declare const animationFrame: () => Promise<void>;
 /**
- * Creates a promise that is resolved after a specified timeout in milliseconds.
- * @param ms The timeout duration in milliseconds.
- * @returns A promise that is resolved after the specified timeout.
+ * Creates a Promise that resolves after a specified duration.
+ *
+ * @param ms - The amount of time (in milliseconds) to wait before the Promise resolves.
+ * @returns A Promise that resolves after the specified duration.
+ *
+ * @example
+ * //Wait for 1 second (1000 ms)
+ * await timeout(1000);
  */
 export declare const timeout: (ms: number) => Promise<unknown>;
 /**
- * Filters an array asynchronously based on a given predicate.
- * @param arr The array to filter.
- * @param predicate The asynchronous predicate function.
- * @returns A promise that resolves to a new array containing only the elements that satisfy the predicate.
+ * Filters elements of the input array asynchronously based on the provided predicate function.
+ *
+ * @param arr - The input array to filter.
+ * @param predicate - Asynchronous function to test each element of the array. Returns `true` to keep the element, `false` otherwise.
+ * @returns A new array with the elements that pass the test implemented by the provided asynchronous function.
+ *
+ * @template T - The type of the elements in the input array.
+ *
+ * @example
+ * const arr = [1, 2, 3, 4, 5];
+ *
+ * // Predicate function to check if a number is even
+ * async function isEven(num) {
+ *   return num % 2 === 0;
+ * }
+ *
+ * // Usage
+ * const result = await filter(arr, isEven);
+ * console.log(result); // outputs: [2, 4]
  */
 export declare function filter<T>(arr: T[], predicate: (value: T) => Promise<boolean>): Promise<T[]>;
 /**
- * Returns a promise that resolves to `true` if at least one element in the array satisfies the predicate.
- * @param arr The array to check.
- * @param pred The asynchronous predicate function.
- * @returns A promise that resolves to `true` if at least one element satisfies the predicate; otherwise, resolves to `false`.
+ * Takes an iterable iterator and checks if any of its elements satisfy the provided predicate function.
+ * Function pSome<T> runs asynchronously.
+ *
+ * @param iter - The iterable object to be iterated.
+ * @param pred - The function to apply to each item to test for a condition.
+ * @returns `true` if at least one element passes the condition check, `false` otherwise.
+ *
+ * @template T - The type of items in the iterable object.
+ *
+ * @example
+ * const iter = [1, 2, 3, 4, 5];
+ *
+ * //Predicate function to check if a number is even
+ * async function isEven(num) {
+ *   return num % 2 === 0;
+ * }
+ *
+ * //Usage
+ * const result = await pSome(iter, isEven);
+ * console.log(result); // outputs: true
  */
-export declare function pSome<T>(arr: T[], pred: (value: T) => Promise<boolean>): Promise<unknown>;
+export declare function pSome<T>(iter: Iterable<T>, pred: (value: T) => Promise<boolean>): Promise<boolean>;
 /**
- * Returns a promise that resolves to `true` if none of the elements in the array satisfy the predicate.
- * @param arr The array to check.
- * @param pred The asynchronous predicate function.
- * @returns A promise that resolves to `true` if none of the elements satisfy the predicate; otherwise, resolves to `false`.
+ * Asynchronously checks if none of the elements from the provided iterable iterator pass the provided predicate function.
+ *
+ * @template T - The type of items in the iterable object.
+ *
+ * @param iter - The iterable object to be iterated.
+ * @param pred - The function to validate each item in the iterable object.
+ * @returns `true` if no element passes the condition check, `false` otherwise.
+ *
+ * @example
+ * const iter = [1, 2, 3, 4, 5];
+ *
+ * // Predicate function to check if a number is even
+ * async function isEven(num) {
+ *   return num % 2 === 0;
+ * }
+ *
+ * //Usage
+ * const result = await pNone(iter, isEven);
+ * console.log(result); // outputs: false
  */
-export declare function pNone<T>(arr: T[], pred: (value: T) => Promise<boolean>): Promise<unknown>;
+export declare function pNone<T>(iter: Iterable<T>, pred: (value: T) => Promise<boolean>): Promise<boolean>;
 /**
- * Returns a promise that resolves to `true` if every element in the array satisfies the predicate.
- * @param arr The array to check.
- * @param pred The asynchronous predicate function.
- * @returns A promise that resolves to `true` if every element satisfies the predicate; otherwise, resolves to `false`.
+ * Takes an iterable iterator and checks every element with the provided predicate function.
+ * Function pEvery<T> runs asynchronously.
+ *
+ * @param iter - The iterable object to be iterated.
+ * @param pred - The function to apply to each item to test for a condition.
+ * @returns `true` if all elements pass the condition check, `false` otherwise.
+ *
+ * @template T - The type of items in the iterable object.
+ *
+ * @example
+ * const iter = [1, 2, 3, 4, 5];
+ *
+ * //Predicate function to check if a number is even
+ * async function isEven(num) {
+ *   return num % 2 === 0;
+ * }
+ *
+ * //Usage
+ * const result = await pEvery(iter, isEven);
+ * console.log(result); // outputs: false
  */
-export declare function pEvery<T>(arr: T[], pred: (value: T) => Promise<boolean>): Promise<unknown>;
+export declare function pEvery<T>(iter: Iterable<T>, pred: (value: T) => Promise<boolean>): Promise<boolean>;
 /**
- * Returns a promise that resolves to the first value produced by an asynchronous generator.
- * @param gen  The asynchronous generator.
- * @returns A promise that resolves to the first value produced by the generator, or undefined if the generator is exhausted.
+ * Retrieves the first value from an asynchronous generator. After extraction, the generator is closed.
+ *
+ * @param gen - The async generator from which to get the first value.
+ * @returns A promise that resolves with the first value from the generator or `undefined` if the generator doesn't yield any values.
+ *
+ * @template T - The type of items yielded by the generator.
+ *
+ * @example
+ * async function* asyncGen() {
+ *   yield 1;
+ *   yield 2;
+ *   yield 3;
+ * }
+ *
+ * //Usage
+ * const result = await first(asyncGen());
+ * console.log(result); // outputs: 1
  */
 export declare function first<T>(gen: AsyncGenerator<T>): Promise<T | undefined>;

dist/index.js

@@ -1,34 +0,25 @@
-const r = () => new Promise(queueMicrotask), s = () => new Promise((t) => setTimeout(t)), o = () => new Promise((t) => requestAnimationFrame(() => t())), m = (t) => new Promise((e) => setTimeout(e, t));
-async function u(t, e) {
-  const a = await Promise.all(t.map(e));
-  return t.filter((n, i) => a[i]);
+const a = () => new Promise(queueMicrotask), i = () => new Promise((t) => setTimeout(t)), s = () => new Promise((t) => requestAnimationFrame(() => t())), u = (t) => new Promise((e) => setTimeout(e, t));
+async function c(t, e) {
+  const n = await Promise.all(t.map(e));
+  return t.filter((o, r) => n[r]);
 }
-function c(t, e) {
-  return new Promise(async (a) => {
-    await Promise.all(
-      t.map(async (n) => {
-        await e(n) && a(!0);
-      })
-    ), a(!1);
-  });
+async function f(t, e) {
+  for (const n of t)
+    if (await e(n))
+      return !0;
+  return !1;
 }
-function f(t, e) {
-  return new Promise(async (a) => {
-    await Promise.all(
-      t.map(async (n) => {
-        await e(n) && a(!1);
-      })
-    ), a(!0);
-  });
+async function m(t, e) {
+  for (const n of t)
+    if (await e(n))
+      return !1;
+  return !0;
 }
-function w(t, e) {
-  return new Promise(async (a) => {
-    await Promise.all(
-      t.map(async (n) => {
-        await e(n) || a(!1);
-      })
-    ), a(!0);
-  });
+async function l(t, e) {
+  for (const n of t)
+    if (!await e(n))
+      return !1;
+  return !0;
 }
-async function l(t) {
+async function w(t) {
   try {
@@ -41,11 +32,11 @@ return (await t.next()).value;
 export {
-  o as animationFrame,
-  u as filter,
-  l as first,
-  s as macrotask,
-  r as microtask,
-  w as pEvery,
-  f as pNone,
-  c as pSome,
-  m as timeout
+  s as animationFrame,
+  c as filter,
+  w as first,
+  i as macrotask,
+  a as microtask,
+  l as pEvery,
+  m as pNone,
+  f as pSome,
+  u as timeout
 };

package.json

 {
   "name": "async-utils-ts",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A collection of utility functions for asynchronous operations in TypeScript.",
@@ -53,2 +53,3 @@ "author": "Dmitrii Baranov <[e-mail]>",
     "preview": "vite preview",
+    "test": "vitest",
     "pub": "npm run build && npm version patch --force && npm publish"
@@ -65,4 +66,5 @@ },
     "vite": "^4.4.5",
-    "vite-plugin-dts": "^3.6.3"
+    "vite-plugin-dts": "^3.6.3",
+    "vitest": "^1.2.2"
   }
 }

README.md

 # async-utils-ts
 
-A collection of utility functions for asynchronous operations in TypeScript.
+This is a collection of TypeScript utility functions for handling asynchronous
+tasks.cript.
 
@@ -10,19 +11,23 @@ [![npm version](https://badge.fury.io/js/async-utils-ts.svg)](https://badge.fury.io/js/async-utils-ts)
 
+Using npm:
+
 ```bash
 npm install async-utils-ts
-# or
+```
+
+Using yarn:
+
+```bash
 yarn add async-utils-ts
 ```
 
-## Usage
+## API
 
 ### microtask
 
-Creates a promise that is resolved in the microtask queue.
+Creates a new Promise which resolves by queueing a microtask.
 
-```typescript
-import { microtask } from 'async-utils-ts';
-
+```ts
 microtask().then(() => {
-  // Your microtask logic here
+  console.log('This will run as soon as possible, asynchronously.');
 });
@@ -33,9 +38,8 @@ ```
 
-Creates a promise that is resolved after a macro task (using `setTimeout`).
+Creates a promise that resolves after the current event loop has been processed
+(i.e., after all microtasks have been completed).
 
-```typescript
-import { macrotask } from 'async-utils-ts';
-
+```ts
 macrotask().then(() => {
-  // Your macrotask logic here
+  console.log('This is a macrotask');
 });
@@ -46,10 +50,9 @@ ```
 
-Creates a promise that is resolved in the next animation frame.
+Creates a new Promise that is resolved using `requestAnimationFrame`.
 
-```typescript
-import { animationFrame } from 'async-utils-ts';
-
-animationFrame().then(() => {
-  // Your animation frame logic here
-});
+```ts
+async function animate() {
+  // Wait for the next frame
+  await animationFrame();
+}
 ```
@@ -59,10 +62,7 @@
 
-Creates a promise that is resolved after a specified timeout in milliseconds.
+Creates a Promise that resolves after a specified duration.
 
-```typescript
-import { timeout } from 'async-utils-ts';
-
-timeout(1000).then(() => {
-  // Your timeout logic here after 1000 milliseconds
-});
+```ts
+// Wait for 1 second (1000 ms)
+await timeout(1000);
 ```
@@ -72,15 +72,16 @@
 
-Filters an array asynchronously based on a given predicate.
+Filters elements of the input array asynchronously based on the provided
+predicate function.
 
-```typescript
-import { filter } from 'async-utils-ts';
-
+```ts
 const arr = [1, 2, 3, 4, 5];
 
-filter(arr, async value => {
-  // Your asynchronous predicate logic here
-  return value > 2;
-}).then(result => {
-  // result will be [3, 4, 5]
-});
+// Predicate function to check if a number is even
+async function isEven(num) {
+  return num % 2 === 0;
+}
+
+// Usage
+const result = await filter(arr, isEven);
+console.log(result); // outputs: [2, 4]
 ```
@@ -90,16 +91,16 @@
 
-Returns a promise that resolves to `true` if at least one element in the array
-satisfies the predicate.
+Checks if any of the elements from the iterable satisfy the condition of the
+provided predicate function.
 
-```typescript
-import { pSome } from 'async-utils-ts';
+```ts
+const iter = [1, 2, 3, 4, 5];
 
-const arr = [1, 2, 3, 4, 5];
+// Predicate function to check if a number is even
+async function isEven(num) {
+  return num % 2 === 0;
+}
 
-pSome(arr, async value => {
-  // Your asynchronous predicate logic here
-  return value > 2;
-}).then(result => {
-  // result will be true
-});
+// Usage
+const result = await pSome(iter, isEven);
+console.log(result); // outputs: true
 ```
@@ -109,16 +110,16 @@
 
-Returns a promise that resolves to `true` if none of the elements in the array
-satisfy the predicate.
+Checks if none of the elements from the iterable pass the condition of the
+provided predicate function.
 
-```typescript
-import { pNone } from 'async-utils-ts';
+```ts
+const iter = [1, 2, 3, 4, 5];
 
-const arr = [1, 2, 3, 4, 5];
+// Predicate function to check if a number is even
+async function isEven(num) {
+  return num % 2 === 0;
+}
 
-pNone(arr, async value => {
-  // Your asynchronous predicate logic here
-  return value > 5;
-}).then(result => {
-  // result will be true
-});
+// Usage
+const result = await pNone(iter, isEven);
+console.log(result); // outputs: false
 ```
@@ -128,16 +129,16 @@
 
-Returns a promise that resolves to `true` if every element in the array
-satisfies the predicate.
+Checks if all elements from the iterable satisfy the condition of the provided
+predicate function.
 
-```typescript
-import { pEvery } from 'async-utils-ts';
+```ts
+const iter = [1, 2, 3, 4, 5];
 
-const arr = [1, 2, 3, 4, 5];
+// Predicate function to check if a number is even
+async function isEven(num) {
+  return num % 2 === 0;
+}
 
-pEvery(arr, async value => {
-  // Your asynchronous predicate logic here
-  return value > 0;
-}).then(result => {
-  // result will be true
-});
+// Usage
+const result = await pEvery(iter, isEven);
+console.log(result); // outputs: false
 ```
@@ -147,9 +148,6 @@
 
-Returns a promise that resolves to the first value produced by an asynchronous
-generator.
+Retrieves the first value from an async generator.
 
-```typescript
-import { first } from 'async-utils-ts';
-
-async function* myGenerator() {
+```ts
+async function* asyncGen() {
   yield 1;
@@ -160,5 +158,5 @@ yield 2;
 
-first(myGenerator()).then(result => {
-  // result will be 1
-});
+// Usage
+const result = await first(asyncGen());
+console.log(result); // outputs: 1
 ```
@@ -165,0 +163,0 @@

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

13742

increased by24.64%

Lines of code

216

increased by98.17%

Worsened metrics

Dev dependency count

10

increased by11.11%

Number of lines in readme file

167

decreased by-1.18%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes