time-queues 1.1.0 → 1.1.2

package/README.md

@@ -32,7 +32,7 @@ npm install
 
 ## Usage
 
-The full documentation is available in the project's [wiki](https://github.com/uhop/time-queues/wiki). Below is the most important parts of the documentation:
+The full documentation is available in the project's [wiki](https://github.com/uhop/time-queues/wiki). Below is a summary of the most important parts of the documentation:
 
 ### Resource Management
 
@@ -61,6 +61,8 @@ This project is licensed under the BSD-3-Clause License.
 
 ## Release History
 
+* 1.1.2 *Updated dev dependencies. No need to upgrade.*
+* 1.1.1 *Updates to TS typings.*
 * 1.1.0 *Added `Throttler`, `Retainer`, promise-based convenience time methods.*
 * 1.0.5 *Technical release: updated deps, more tests.*
 * 1.0.4 *Bug fixes and code simplifications.*

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "time-queues",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Time queues to organize multitasking and scheduled tasks.",
   "type": "module",
+  "types": "./src/index.d.ts",
   "exports": {
     "./*": "./src/*"
   },
   "scripts": {
     "test": "tape6 --flags FO",
     "test:bun": "tape6-bun --flags FO",
-    "test:deno-original": "tape6-deno --flags FO",
-    "test:deno": "deno run -A `tape6-runner main` --flags FO",
+    "test:deno": "tape6-deno --flags FO",
     "test:proc": "tape6-proc --flags FO",
     "test:proc:bun": "bun run `npx tape6-proc --self` --flags FO",
     "test:proc:deno": "deno run -A `npx tape6-proc --self` --flags FO --runFileArgs -A",
     "ts-check": "tsc --noEmit",
+    "ts-test": "tape6 --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:bun": "tape6-bun --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:deno": "tape6-deno --flags FO '/ts-tests/test-*.*ts'",
     "lint": "prettier --check src/ tests/ wiki/",
     "lint:fix": "prettier --write src/ tests/ wiki/",
     "start": "tape6-server --trace"
@@ -54,7 +57,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
-    "tape-six": "^1.0.3",
+    "tape-six": "^1.1.1",
     "tape-six-proc": "^1.0.1",
     "typescript": "^5.8.2"
   },

package/src/FrameQueue.d.ts

@@ -5,6 +5,11 @@ import {ListQueue, Task} from './ListQueue';
  * Used in an animation loop or for drawing updates.
  */
 export declare class FrameQueue extends ListQueue {
+  /**
+   * Whether the queue is paused.
+   */
+  paused: boolean;
+
   /**
    * The batch size in milliseconds for running tasks.
    * If `undefined`, all tasks are run in a single frame.
@@ -16,7 +21,7 @@ export declare class FrameQueue extends ListQueue {
    * @param paused Whether the queue should start paused.
    * @param batchInMs The batch size in milliseconds.
    */
-  constructor(paused: boolean = false, batchInMs?: number);
+  constructor(paused?: boolean, batchInMs?: number);
 
   /**
    * Whether the queue is empty.

package/src/IdleQueue.d.ts

@@ -5,6 +5,11 @@ import {ListQueue, Task} from './ListQueue';
  * Used for background tasks.
  */
 export declare class IdleQueue extends ListQueue {
+  /**
+   * Whether the queue is paused.
+   */
+  paused: boolean;
+
   /**
    * The timeout batch size in milliseconds for running tasks.
    * If `undefined`, all tasks are run in a single idle period.
@@ -23,7 +28,7 @@ export declare class IdleQueue extends ListQueue {
    * @param timeoutBatchInMs The timeout batch size in milliseconds.
    * @param options The options passed to `requestIdleCallback()`.
    */
-  constructor(paused: boolean = false, timeoutBatchInMs?: number, options?: IdleCallbackOptions);
+  constructor(paused?: boolean, timeoutBatchInMs?: number, options?: IdleCallbackOptions);
 
   /**
    * Whether the queue is empty.

package/src/ListQueue.d.ts

@@ -7,9 +7,9 @@ import {List} from 'list-toolkit';
  */
 export declare class ListQueue extends MicroTaskQueue {
   /**
-   * The list of tasks.
+   * Whether the queue is paused.
    */
-  list: List<MicroTask>;
+  paused: boolean;
 
   /**
    * The function that stops the queue.
@@ -21,7 +21,7 @@ export declare class ListQueue extends MicroTaskQueue {
    * Creates a new list queue.
    * @param paused Whether the queue should start paused.
    */
-  constructor(paused: boolean);
+  constructor(paused?: boolean);
 
   /**
    * Whether the queue is empty.

package/src/MicroTaskQueue.d.ts

@@ -14,7 +14,7 @@ export declare class MicroTaskQueue {
    * Creates a new microtask queue.
    * @param paused Whether the queue should start paused.
    */
-  constructor(paused: boolean);
+  constructor(paused?: boolean);
 
   /**
    * Whether the queue is empty.

package/src/PageWatcher.d.ts

@@ -9,6 +9,11 @@ export declare type PageState = 'active' | 'passive' | 'hidden' | 'frozen' | 'te
  * A queue that monitors the page's lifecycle.
  */
 export declare class PageWatcher extends ListQueue {
+  /**
+   * Whether the queue is paused.
+   */
+  paused: boolean;
+
   /**
    * The current state of the page.
    */
@@ -18,7 +23,7 @@ export declare class PageWatcher extends ListQueue {
    * Creates a new page watcher.
    * @param started Whether the queue is unpaused initially.
    */
-  constructor(started: boolean = false);
+  constructor(started?: boolean);
 
   /**
    * Whether the queue is empty.

package/src/Retainer.d.ts

@@ -1,15 +1,15 @@
 /**
  * The options for a retainer.
  */
-export declare interface RetainerOptions {
+export declare interface RetainerOptions<T = unknown> {
   /**
    * The function to create a value.
    */
-  create: () => Promise<unknown>;
+  create: () => Promise<T> | T;
   /**
    * The function to destroy a value.
    */
-  destroy: (value: unknown) => Promise<void>;
+  destroy: (value: T) => Promise<void> | void;
   /**
    * The retention period in milliseconds.
    */
@@ -19,22 +19,43 @@ export declare interface RetainerOptions {
 /**
  * Retains a value for a specified time.
  */
-export declare class Retainer implements RetainerOptions {
-  create: () => Promise<unknown>;
-  destroy: (value: unknown) => Promise<void>;
+export declare class Retainer<T = unknown> implements RetainerOptions<T> {
+  /**
+   * The counter for the number of active references.
+   */
+  counter: number;
+
+  /**
+   * The value currently retained.
+   */
+  value: T | null;
+
+  /**
+   * The function to create a value.
+   */
+  create: () => Promise<T> | T;
+
+  /**
+   * The function to destroy a value.
+   */
+  destroy: (value: T) => Promise<void> | void;
+
+  /**
+   * The retention period in milliseconds.
+   */
   retentionPeriod: number;
 
   /**
    * Creates a new retainer.
    * @param options The options for the retainer.
    */
-  constructor(options: RetainerOptions);
+  constructor(options: RetainerOptions<T>);
 
   /**
    * Retrieves the retained value.
    * @returns The retained value as a promise.
    */
-  async get(): Promise<unknown>;
+  async get(): Promise<T>;
 
   /**
    * Releases the retained value.

package/src/Scheduler.d.ts

@@ -5,24 +5,49 @@ import MicroTaskQueue from './MicroTaskQueue';
  * A task that will be executed at a later time by `Scheduler`.
  */
 export declare class Task extends MicroTask {
+  /**
+   * The function to execute.
+   */
+  fn: (task: Task, scheduler: Scheduler) => void;
+
+  /**
+   * The time in milliseconds (Unix timestamp) when the task is scheduled to run.
+   */
+  time: number;
+
+  /**
+   * The delay in milliseconds before the task is executed.
+   */
+  delay: number;
+
   /**
    * Creates a new task.
    * @param delay The delay before the task is executed. It can be a number of milliseconds or a `Date` object as an absolute time.
    * @param fn The function to execute.
    */
-  constructor(delay: number | Date, fn: () => void);
+  constructor(delay: number | Date, fn: (task: Task, scheduler: Scheduler) => void);
 }
 
 /**
  * A scheduler that manages tasks to be executed at a later time.
  */
 export declare class Scheduler extends MicroTaskQueue {
+  /**
+   * Whether the scheduler is paused.
+   */
+  paused: boolean;
+
+  /**
+   * The tolerance for comparing starting time of tasks.
+   */
+  tolerance: number;
+
   /**
    * Creates a new scheduler.
    * @param paused Whether the scheduler should start paused.
    * @param tolerance The tolerance for comparing starting time of tasks.
    */
-  constructor(paused: boolean, tolerance: number = 4);
+  constructor(paused?: boolean, tolerance: number = 4);
 
   /**
    * Whether the scheduler is empty.

package/src/Throttler.d.ts

@@ -5,11 +5,11 @@ export declare type ThrottlerOptions = {
   /**
    * The throttle timeout.
    */
-  throttleTimeout: number;
+  throttleTimeout?: number;
   /**
    * The timeout for keys that have never been seen.
    */
-  neverSeenTimeout: number;
+  neverSeenTimeout?: number;
   /**
    * The vacuum period.
    */
@@ -20,9 +20,25 @@ export declare type ThrottlerOptions = {
  * A throttler that throttles the execution of tasks based on a key.
  */
 export declare class Throttler implements ThrottlerOptions {
+  /**
+   * The throttle timeout.
+   */
   throttleTimeout: number;
+
+  /**
+   * The timeout for keys that have never been seen.
+   */
   neverSeenTimeout: number;
-  vacuumPeriod?: number;
+
+  /**
+   * The vacuum period.
+   */
+  vacuumPeriod: number;
+
+  /**
+   * The last seen times for keys.
+   */
+  lastSeen: Map<unknown, number>;
 
   /**
    * Creates a new throttler.

package/src/audit.d.ts

@@ -7,9 +7,9 @@
  * @param ms The minimum time interval between function calls, in milliseconds.
  * @returns An audited version of the function.
  */
-export declare function audit(
-  fn: (...args: unknown[]) => void,
+export declare function audit<T extends (...args: any[]) => void>(
+  fn: T,
   ms: number
-): (...args: unknown[]) => void;
+): (...args: Parameters<T>) => void;
 
 export default audit;

package/src/debounce.d.ts

@@ -6,9 +6,9 @@
  * @param ms The minimum time interval between function calls, in milliseconds.
  * @returns A debounced version of the function.
  */
-export declare function debounce(
-  fn: (...args: unknown[]) => void,
+export declare function debounce<T extends (...args: any[]) => void>(
+  fn: T,
   ms: number
-): (...args: unknown[]) => void;
+): (...args: Parameters<T>) => void;
 
 export default debounce;

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

@@ -9,9 +9,9 @@
  * @param ms The minimum time interval between function calls, in milliseconds.
  * @returns A sampled version of the function.
  */
-export declare function sample(
-  fn: (...args: unknown[]) => void,
+export declare function sample<T extends (...args: any[]) => void>(
+  fn: T,
   ms: number
-): (...args: unknown[]) => void;
+): (...args: Parameters<T>) => void;
 
 export default sample;

package/src/throttle.d.ts

@@ -7,9 +7,9 @@
  * @param ms The minimum time interval between function calls, in milliseconds.
  * @returns A throttled version of the function.
  */
-export declare function throttle(
-  fn: (...args: unknown[]) => void,
+export declare function throttle<T extends (...args: any[]) => void>(
+  fn: T,
   ms: number
-): (...args: unknown[]) => void;
+): (...args: Parameters<T>) => void;
 
 export default throttle;