time-queues 1.0.5 → 1.1.1

package/src/defer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Delays the execution of a function until the next available time.
+ * It will use available system functions in the following order:
+ * - `requestIdleCallback()`
+ * - `setImmediate()`
+ * - `setTimeout()`
+ *
+ * @param fn The function to delay.
+ * @returns A function that, when called, will execute the provided function.
+ */
+export declare function defer(fn: () => void): () => void;
+
+export default defer;

package/src/defer.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./defer.d.ts"
+
 'use strict';
 
 let deferImplementation = setTimeout;

package/src/index.d.ts

@@ -0,0 +1,22 @@
+declare module 'time-queues' {
+  export * from './audit';
+  export * from './debounce';
+  export * from './defer';
+  export * from './sample';
+  export * from './sleep';
+  export * from './throttle';
+
+  export * from './MicroTask';
+  export * from './MicroTaskQueue';
+  export * from './ListQueue';
+  export * from './FrameQueue';
+  export * from './IdleQueue';
+
+  export * from './PageWatcher';
+  export * from './Scheduler';
+  export * from './Retainer';
+  export * from './Throttler';
+
+  export * from './when-dom-loaded';
+  export * from './when-loaded';
+}

package/src/sample.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Samples a function by ensuring it is not called more often than the specified interval.
+ * The last seen arguments are passed to the function after the specified time interval.
+ * Unlike `audit()`, intervals are not reset by the function calls and never stops.
+ * If no call was made to the sampled function within the specified time interval,
+ * no calls are made after the specified time interval.
+ *
+ * @param fn The function to sample.
+ * @param ms The minimum time interval between function calls, in milliseconds.
+ * @returns A sampled version of the function.
+ */
+export declare function sample<T extends (...args: any[]) => void>(
+  fn: T,
+  ms: number
+): (...args: Parameters<T>) => void;
+
+export default sample;

package/src/sample.js

@@ -0,0 +1,25 @@
+// @ts-self-types="./sample.d.ts"
+
+'use strict';
+
+export const sample = (fn, ms) => {
+  const started = Date.now();
+  let handle = null,
+    lastSeenArgs = null,
+    timeout = ms;
+  return (...args) => {
+    lastSeenArgs = [...args];
+    if (handle) return;
+    const diff = (Date.now() - started) % ms,
+      delay = diff ? ms - diff : timeout;
+    timeout = 0;
+    handle = setTimeout(() => {
+      handle = null;
+      const args = lastSeenArgs;
+      lastSeenArgs = null;
+      fn(...args);
+    }, delay);
+  };
+};
+
+export default sample;

package/src/sleep.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Suspends the execution for a specified time.
+ *
+ * @param ms The time to suspend the execution for, in milliseconds or a date as an absolute time.
+ * @returns A promise that resolves after the specified time.
+ */
+export declare function sleep(ms: number | Date): Promise<void>;
+
+export default sleep;

package/src/sleep.js

@@ -0,0 +1,13 @@
+// @ts-self-types="./sleep.d.ts"
+
+'use strict';
+
+export const sleep = ms => {
+  if (ms instanceof Date) {
+    ms = ms.getTime() - Date.now();
+  }
+  ms = Math.max(0, ms);
+  return new Promise(resolve => setTimeout(resolve, ms));
+};
+
+export default sleep;

package/src/throttle.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Throttles a function by ensuring it is not called more often than the specified interval.
+ * The first call calls the function and starts a timeout. Until the timeout expires, any subsequent calls are ignored.
+ * This function is similar to `audit()`, but the first seen arguments are passed to the function.
+ *
+ * @param fn The function to throttle.
+ * @param ms The minimum time interval between function calls, in milliseconds.
+ * @returns A throttled version of the function.
+ */
+export declare function throttle<T extends (...args: any[]) => void>(
+  fn: T,
+  ms: number
+): (...args: Parameters<T>) => void;
+
+export default throttle;

package/src/throttle.js

@@ -0,0 +1,14 @@
+// @ts-self-types="./throttle.d.ts"
+
+'use strict';
+
+export const throttle = (fn, ms) => {
+  let handle = null;
+  return (...args) => {
+    if (handle) return;
+    handle = setTimeout(() => (handle = null), ms);
+    fn(...args);
+  };
+};
+
+export default throttle;

package/src/when-dom-loaded.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Adds a function to the list of functions to be called when the DOM is loaded.
+ * If the DOM is already loaded, the function is called immediately.
+ *
+ * @param fn The function to add.
+ */
+export declare function whenDomLoaded(fn: () => void): void;
+
+/**
+ * Removes a function from the list of functions to be called when the DOM is loaded.
+ *
+ * @param fn The function to remove.
+ * @returns `true` if the function was removed, `false` otherwise.
+ */
+export declare function remove(fn: () => void): boolean;
+
+export default whenDomLoaded;

package/src/when-dom-loaded.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./when-dom-loaded.d.ts"
+
 'use strict';
 
 import ValueList from 'list-toolkit/value-list.js';
@@ -12,7 +14,7 @@ export const remove = fn => {
     }
   }
   return false;
-}
+};
 
 const handleDomLoaded = () => {
   while (!waitingForDom.isEmpty) waitingForDom.pop()();

package/src/when-loaded.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Adds a function to the list of functions to be called when the document is loaded.
+ * If the document is already loaded, the function is called immediately.
+ *
+ * @param fn The function to add.
+ */
+export declare function whenLoaded(fn: () => void): void;
+
+/**
+ * Removes a function from the list of functions to be called when the document is loaded.
+ *
+ * @param fn The function to remove.
+ * @returns `true` if the function was removed, `false` otherwise.
+ */
+export declare function remove(fn: () => void): boolean;
+
+export default whenLoaded;

package/src/when-loaded.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./when-loaded.d.ts"
+
 'use strict';
 
 import ValueList from 'list-toolkit/value-list.js';
@@ -12,7 +14,7 @@ export const remove = fn => {
     }
   }
   return false;
-}
+};
 
 const handleLoaded = () => {
   while (!waitingForLoad.isEmpty) waitingForLoad.pop()();