@tanstack/pacer-lite 0.2.2 → 0.3.0

package/README.md

@@ -1,5 +1,19 @@
 <div align="center">
-  <img src="./media/header_pacer.png" >
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/pacer.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/pacer.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/pacer.png"
+      alt="TanStack Pacer"
+      width="900"
+    />
+  </picture>
 </div>
 
 <br />
@@ -29,8 +43,9 @@
 </div>
 
 <div align="center">
-  
+
 ### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
+
 </div>
 
 # TanStack Pacer
@@ -88,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim
 > [!NOTE]
 > You may know **TanStack Pacer** by our adapter names, too!
 >
-> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer)
-> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer)
-> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer)
-> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer)
+> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react)
+> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact)
+> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid)
+> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular)
 > - Svelte Pacer - needs a contributor!
 > - Vue Pacer - needs a contributor!
 

package/dist/lite-batcher.d.ts

@@ -2,7 +2,7 @@
 /**
  * Options for configuring a lite batcher instance
  */
-interface LiteBatcherOptions<TValue> {
+export interface LiteBatcherOptions<TValue> {
   /**
    * Custom function to determine if a batch should be processed
    * Return true to process the batch immediately
@@ -103,7 +103,7 @@ interface LiteBatcherOptions<TValue> {
  * batcher.addItem({ name: 'urgent', urgent: true }); // Triggers immediate processing
  * ```
  */
-declare class LiteBatcher<TValue> {
+export declare class LiteBatcher<TValue> {
   fn: (items: Array<TValue>) => void;
   options: LiteBatcherOptions<TValue>;
   private items;
@@ -178,7 +178,5 @@ declare class LiteBatcher<TValue> {
  * batchItems(3); // Triggers batch processing
  * ```
  */
-declare function liteBatch<TValue>(fn: (items: Array<TValue>) => void, options?: LiteBatcherOptions<TValue>): (item: TValue) => void;
-//#endregion
-export { LiteBatcher, LiteBatcherOptions, liteBatch };
-//# sourceMappingURL=lite-batcher.d.ts.map
+export declare function liteBatch<TValue>(fn: (items: Array<TValue>) => void, options?: LiteBatcherOptions<TValue>): (item: TValue) => void;
+//#endregion

package/dist/lite-batcher.js

@@ -69,52 +69,14 @@
 * ```
 */
 var LiteBatcher = class {
+	fn;
+	options;
+	items = [];
+	timeoutId = null;
+	_isPending = false;
 	constructor(fn, options = {}) {
 		this.fn = fn;
 		this.options = options;
-		this.items = [];
-		this.timeoutId = null;
-		this._isPending = false;
-		this.addItem = (item) => {
-			this.items.push(item);
-			this._isPending = this.options.wait !== Infinity;
-			this.options.onItemsChange?.(this);
-			if (this.items.length >= this.options.maxSize || this.options.getShouldExecute(this.items, this)) this.execute();
-			else if (this.options.wait !== Infinity) {
-				this.clearTimeout();
-				this.timeoutId = setTimeout(() => this.execute(), this.getWait());
-			}
-		};
-		this.execute = () => {
-			if (this.items.length === 0) return;
-			const batch = this.peekAllItems();
-			this.clear();
-			this.fn(batch);
-			this.options.onExecute?.(batch, this);
-		};
-		this.flush = () => {
-			this.clearTimeout();
-			this.execute();
-		};
-		this.peekAllItems = () => {
-			return [...this.items];
-		};
-		this.clearTimeout = () => {
-			if (this.timeoutId) {
-				clearTimeout(this.timeoutId);
-				this.timeoutId = null;
-			}
-		};
-		this.clear = () => {
-			const hadItems = this.items.length > 0;
-			this.items = [];
-			this._isPending = false;
-			if (hadItems) this.options.onItemsChange?.(this);
-		};
-		this.cancel = () => {
-			this.clearTimeout();
-			this._isPending = false;
-		};
 		this.options.maxSize = this.options.maxSize ?? Infinity;
 		this.options.started = this.options.started ?? true;
 		this.options.wait = this.options.wait ?? Infinity;
@@ -142,6 +104,72 @@ var LiteBatcher = class {
 		if (typeof this.options.wait === "function") return this.options.wait(this);
 		return this.options.wait;
 	}
+	/**
+	* Adds an item to the batcher
+	* If the batch size is reached, timeout occurs, or getShouldExecute returns true, the batch will be processed
+	*/
+	addItem = (item) => {
+		this.items.push(item);
+		this._isPending = this.options.wait !== Infinity;
+		this.options.onItemsChange?.(this);
+		if (this.items.length >= this.options.maxSize || this.options.getShouldExecute(this.items, this)) this.execute();
+		else if (this.options.wait !== Infinity) {
+			this.clearTimeout();
+			this.timeoutId = setTimeout(() => this.execute(), this.getWait());
+		}
+	};
+	/**
+	* Processes the current batch of items.
+	* This method will automatically be triggered if the batcher is running and any of these conditions are met:
+	* - The number of items reaches maxSize
+	* - The wait duration has elapsed
+	* - The getShouldExecute function returns true upon adding an item
+	*
+	* You can also call this method manually to process the current batch at any time.
+	*/
+	execute = () => {
+		if (this.items.length === 0) return;
+		const batch = this.peekAllItems();
+		this.clear();
+		this.fn(batch);
+		this.options.onExecute?.(batch, this);
+	};
+	/**
+	* Processes the current batch of items immediately
+	*/
+	flush = () => {
+		this.clearTimeout();
+		this.execute();
+	};
+	/**
+	* Returns a copy of all items in the batcher
+	*/
+	peekAllItems = () => {
+		return [...this.items];
+	};
+	clearTimeout = () => {
+		if (this.timeoutId) {
+			clearTimeout(this.timeoutId);
+			this.timeoutId = null;
+		}
+	};
+	/**
+	* Removes all items from the batcher
+	*/
+	clear = () => {
+		const hadItems = this.items.length > 0;
+		this.items = [];
+		this._isPending = false;
+		if (hadItems) this.options.onItemsChange?.(this);
+	};
+	/**
+	* Cancels any pending execution that was scheduled.
+	* Does NOT clear out the items.
+	*/
+	cancel = () => {
+		this.clearTimeout();
+		this._isPending = false;
+	};
 };
 /**
 * Creates a batcher that processes items in batches.
@@ -169,5 +197,4 @@ function liteBatch(fn, options = {}) {
 }
 
 //#endregion
-export { LiteBatcher, liteBatch };
-//# sourceMappingURL=lite-batcher.js.map
+export { LiteBatcher, liteBatch };

package/dist/lite-debouncer.d.ts

@@ -1,10 +1,9 @@
 import { AnyFunction } from "./pacer/dist/types.js";
-
 //#region src/lite-debouncer.d.ts
 /**
  * Options for configuring a lite debounced function
  */
-interface LiteDebouncerOptions<TFn extends AnyFunction = AnyFunction> {
+export interface LiteDebouncerOptions<TFn extends AnyFunction = AnyFunction> {
   /**
    * Whether to execute on the leading edge of the timeout.
    * The first call will execute immediately and the rest will wait the delay.
@@ -65,7 +64,7 @@ interface LiteDebouncerOptions<TFn extends AnyFunction = AnyFunction> {
  * });
  * ```
  */
-declare class LiteDebouncer<TFn extends AnyFunction> {
+export declare class LiteDebouncer<TFn extends AnyFunction> {
   fn: TFn;
   options: LiteDebouncerOptions<TFn>;
   private timeoutId;
@@ -120,7 +119,5 @@ declare class LiteDebouncer<TFn extends AnyFunction> {
  * }, { wait: 300, leading: true });
  * ```
  */
-declare function liteDebounce<TFn extends AnyFunction>(fn: TFn, options: LiteDebouncerOptions<TFn>): (...args: Parameters<TFn>) => void;
-//#endregion
-export { LiteDebouncer, LiteDebouncerOptions, liteDebounce };
-//# sourceMappingURL=lite-debouncer.d.ts.map
+export declare function liteDebounce<TFn extends AnyFunction>(fn: TFn, options: LiteDebouncerOptions<TFn>): (...args: Parameters<TFn>) => void;
+//#endregion

package/dist/lite-debouncer.js

@@ -40,50 +40,69 @@
 * ```
 */
 var LiteDebouncer = class {
+	fn;
+	options;
+	timeoutId;
+	lastArgs;
+	canLeadingExecute = true;
 	constructor(fn, options) {
 		this.fn = fn;
 		this.options = options;
-		this.canLeadingExecute = true;
-		this.maybeExecute = (...args) => {
-			let didLeadingExecute = false;
-			if (this.options.leading && this.canLeadingExecute) {
-				this.canLeadingExecute = false;
-				didLeadingExecute = true;
-				this.fn(...args);
-				this.options.onExecute?.(args, this);
-			}
-			this.lastArgs = args;
-			if (this.timeoutId) clearTimeout(this.timeoutId);
-			this.timeoutId = setTimeout(() => {
-				this.canLeadingExecute = true;
-				if (this.options.trailing && !didLeadingExecute && this.lastArgs) {
-					this.fn(...this.lastArgs);
-					this.options.onExecute?.(this.lastArgs, this);
-				}
-				this.lastArgs = void 0;
-			}, this.options.wait);
-		};
-		this.flush = () => {
-			if (this.timeoutId && this.lastArgs) {
-				clearTimeout(this.timeoutId);
-				this.timeoutId = void 0;
-				const args = this.lastArgs;
-				this.fn(...args);
-				this.options.onExecute?.(args, this);
-				this.lastArgs = void 0;
-				this.canLeadingExecute = true;
-			}
-		};
-		this.cancel = () => {
-			if (this.timeoutId) {
-				clearTimeout(this.timeoutId);
-				this.timeoutId = void 0;
+		if (this.options.leading === void 0 && this.options.trailing === void 0) this.options.trailing = true;
+	}
+	/**
+	* Attempts to execute the debounced function.
+	* If leading is true and this is the first call, executes immediately.
+	* Otherwise, queues the execution for after the wait time.
+	* Each new call resets the timer.
+	*/
+	maybeExecute = (...args) => {
+		let didLeadingExecute = false;
+		if (this.options.leading && this.canLeadingExecute) {
+			this.canLeadingExecute = false;
+			didLeadingExecute = true;
+			this.fn(...args);
+			this.options.onExecute?.(args, this);
+		}
+		this.lastArgs = args;
+		if (this.timeoutId) clearTimeout(this.timeoutId);
+		this.timeoutId = setTimeout(() => {
+			this.canLeadingExecute = true;
+			if (this.options.trailing && !didLeadingExecute && this.lastArgs) {
+				this.fn(...this.lastArgs);
+				this.options.onExecute?.(this.lastArgs, this);
 			}
 			this.lastArgs = void 0;
+		}, this.options.wait);
+	};
+	/**
+	* Processes the current pending execution immediately.
+	* If there's a pending execution, it will be executed right away
+	* and the timeout will be cleared.
+	*/
+	flush = () => {
+		if (this.timeoutId && this.lastArgs) {
+			clearTimeout(this.timeoutId);
+			this.timeoutId = void 0;
+			const args = this.lastArgs;
+			this.fn(...args);
+			this.options.onExecute?.(args, this);
+			this.lastArgs = void 0;
 			this.canLeadingExecute = true;
-		};
-		if (this.options.leading === void 0 && this.options.trailing === void 0) this.options.trailing = true;
-	}
+		}
+	};
+	/**
+	* Cancels any pending execution.
+	* Clears the timeout and resets the internal state.
+	*/
+	cancel = () => {
+		if (this.timeoutId) {
+			clearTimeout(this.timeoutId);
+			this.timeoutId = void 0;
+		}
+		this.lastArgs = void 0;
+		this.canLeadingExecute = true;
+	};
 };
 /**
 * Creates a lightweight debounced function that delays invoking the provided function until after a specified wait time.
@@ -119,5 +138,4 @@ function liteDebounce(fn, options) {
 }
 
 //#endregion
-export { LiteDebouncer, liteDebounce };
-//# sourceMappingURL=lite-debouncer.js.map
+export { LiteDebouncer, liteDebounce };

package/dist/lite-queuer.d.ts

@@ -5,11 +5,11 @@
  * - 'front': Operate on the front of the queue (FIFO for getNextItem)
  * - 'back': Operate on the back of the queue (LIFO for getNextItem)
  */
-type QueuePosition = 'front' | 'back';
+export type QueuePosition = 'front' | 'back';
 /**
  * Options for configuring a lite queuer instance
  */
-interface LiteQueuerOptions<TValue> {
+export interface LiteQueuerOptions<TValue> {
   /**
    * Default position to add items to the queue
    * @default 'back'
@@ -105,7 +105,7 @@ interface LiteQueuerOptions<TValue> {
  * // Processes high priority task first
  * ```
  */
-declare class LiteQueuer<TValue> {
+export declare class LiteQueuer<TValue> {
   fn: (item: TValue) => void;
   options: LiteQueuerOptions<TValue>;
   private items;
@@ -237,7 +237,5 @@ declare class LiteQueuer<TValue> {
  * // Processes each item with 1 second delay between them
  * ```
  */
-declare function liteQueue<TValue>(fn: (item: TValue) => void, options?: LiteQueuerOptions<TValue>): (item: TValue) => boolean;
-//#endregion
-export { LiteQueuer, LiteQueuerOptions, QueuePosition, liteQueue };
-//# sourceMappingURL=lite-queuer.d.ts.map
+export declare function liteQueue<TValue>(fn: (item: TValue) => void, options?: LiteQueuerOptions<TValue>): (item: TValue) => boolean;
+//#endregion

package/dist/lite-queuer.js

@@ -60,96 +60,15 @@
 * ```
 */
 var LiteQueuer = class {
+	fn;
+	options;
+	items = [];
+	timeoutId = null;
+	isRunning = true;
+	pendingTick = false;
 	constructor(fn, options = {}) {
 		this.fn = fn;
 		this.options = options;
-		this.items = [];
-		this.timeoutId = null;
-		this.isRunning = true;
-		this.pendingTick = false;
-		this.addItem = (item, position = this.options.addItemsTo, startProcessing = true) => {
-			if (this.items.length >= this.options.maxSize) return false;
-			if (this.options.getPriority) {
-				const priority = this.options.getPriority(item);
-				if (priority !== void 0) {
-					const insertIndex = this.items.findIndex((existing) => {
-						return (this.options.getPriority(existing) ?? -Infinity) < priority;
-					});
-					if (insertIndex === -1) this.items.push(item);
-					else this.items.splice(insertIndex, 0, item);
-				} else this.insertAtPosition(item, position);
-			} else this.insertAtPosition(item, position);
-			if (startProcessing && this.isRunning && !this.pendingTick) this.tick();
-			return true;
-		};
-		this.insertAtPosition = (item, position) => {
-			if (position === "front") this.items.unshift(item);
-			else this.items.push(item);
-		};
-		this.getNextItem = (position = this.options.getItemsFrom) => {
-			if (this.items.length === 0) return;
-			let item;
-			if (this.options.getPriority || position === "front") item = this.items.shift();
-			else item = this.items.pop();
-			return item;
-		};
-		this.execute = (position) => {
-			const item = this.getNextItem(position);
-			if (item !== void 0) this.fn(item);
-			return item;
-		};
-		this.tick = () => {
-			if (!this.isRunning) {
-				this.pendingTick = false;
-				return;
-			}
-			this.pendingTick = true;
-			while (this.items.length > 0) {
-				if (this.execute(this.options.getItemsFrom) === void 0) break;
-				const wait = this.options.wait;
-				if (wait > 0) {
-					this.timeoutId = setTimeout(() => this.tick(), wait);
-					return;
-				}
-			}
-			this.pendingTick = false;
-		};
-		this.start = () => {
-			this.isRunning = true;
-			if (!this.pendingTick && this.items.length > 0) this.tick();
-		};
-		this.stop = () => {
-			this.clearTimeout();
-			this.isRunning = false;
-			this.pendingTick = false;
-		};
-		this.clearTimeout = () => {
-			if (this.timeoutId) {
-				clearTimeout(this.timeoutId);
-				this.timeoutId = null;
-			}
-		};
-		this.peekNextItem = (position = "front") => {
-			if (this.items.length === 0) return;
-			if (this.options.getPriority || position === "front") return this.items[0];
-			else return this.items[this.items.length - 1];
-		};
-		this.peekAllItems = () => {
-			return [...this.items];
-		};
-		this.flush = (numberOfItems = this.items.length, position) => {
-			this.clearTimeout();
-			for (let i = 0; i < numberOfItems && this.items.length > 0; i++) this.execute(position);
-			if (this.isRunning && this.items.length > 0 && !this.pendingTick) this.tick();
-		};
-		this.flushAsBatch = (batchFunction) => {
-			const items = this.peekAllItems();
-			this.clear();
-			batchFunction(items);
-		};
-		this.clear = () => {
-			this.items = [];
-		};
 		this.options.addItemsTo = this.options.addItemsTo ?? "back";
 		this.options.getItemsFrom = this.options.getItemsFrom ?? "front";
 		this.options.maxSize = this.options.maxSize ?? Infinity;
@@ -177,6 +96,169 @@ var LiteQueuer = class {
 	get isQueueRunning() {
 		return this.isRunning;
 	}
+	/**
+	* Adds an item to the queue. If the queue is full, the item is rejected.
+	* Items can be inserted at the front or back, and priority ordering is applied if getPriority is configured.
+	*
+	* Returns true if the item was added, false if the queue is full.
+	*
+	* @example
+	* ```ts
+	* queue.addItem('task1');           // Add to default position (back)
+	* queue.addItem('task2', 'front');  // Add to front
+	* ```
+	*/
+	addItem = (item, position = this.options.addItemsTo, startProcessing = true) => {
+		if (this.items.length >= this.options.maxSize) return false;
+		if (this.options.getPriority) {
+			const priority = this.options.getPriority(item);
+			if (priority !== void 0) {
+				const insertIndex = this.items.findIndex((existing) => {
+					return (this.options.getPriority(existing) ?? -Infinity) < priority;
+				});
+				if (insertIndex === -1) this.items.push(item);
+				else this.items.splice(insertIndex, 0, item);
+			} else this.insertAtPosition(item, position);
+		} else this.insertAtPosition(item, position);
+		if (startProcessing && this.isRunning && !this.pendingTick) this.tick();
+		return true;
+	};
+	insertAtPosition = (item, position) => {
+		if (position === "front") this.items.unshift(item);
+		else this.items.push(item);
+	};
+	/**
+	* Removes and returns the next item from the queue without executing the function.
+	* Use for manual queue management. Normally, use execute() to process items.
+	*
+	* @example
+	* ```ts
+	* const nextItem = queue.getNextItem();        // Get from default position (front)
+	* const lastItem = queue.getNextItem('back');  // Get from back (LIFO)
+	* ```
+	*/
+	getNextItem = (position = this.options.getItemsFrom) => {
+		if (this.items.length === 0) return;
+		let item;
+		if (this.options.getPriority || position === "front") item = this.items.shift();
+		else item = this.items.pop();
+		return item;
+	};
+	/**
+	* Removes and returns the next item from the queue and processes it using the provided function.
+	*
+	* @example
+	* ```ts
+	* queue.execute();        // Execute from default position
+	* queue.execute('back');  // Execute from back (LIFO)
+	* ```
+	*/
+	execute = (position) => {
+		const item = this.getNextItem(position);
+		if (item !== void 0) this.fn(item);
+		return item;
+	};
+	/**
+	* Internal method that processes items in the queue with wait intervals
+	*/
+	tick = () => {
+		if (!this.isRunning) {
+			this.pendingTick = false;
+			return;
+		}
+		this.pendingTick = true;
+		while (this.items.length > 0) {
+			if (this.execute(this.options.getItemsFrom) === void 0) break;
+			const wait = this.options.wait;
+			if (wait > 0) {
+				this.timeoutId = setTimeout(() => this.tick(), wait);
+				return;
+			}
+		}
+		this.pendingTick = false;
+	};
+	/**
+	* Starts processing items in the queue. If already running, does nothing.
+	*/
+	start = () => {
+		this.isRunning = true;
+		if (!this.pendingTick && this.items.length > 0) this.tick();
+	};
+	/**
+	* Stops processing items in the queue. Does not clear the queue.
+	*/
+	stop = () => {
+		this.clearTimeout();
+		this.isRunning = false;
+		this.pendingTick = false;
+	};
+	/**
+	* Clears any pending timeout
+	*/
+	clearTimeout = () => {
+		if (this.timeoutId) {
+			clearTimeout(this.timeoutId);
+			this.timeoutId = null;
+		}
+	};
+	/**
+	* Returns the next item in the queue without removing it.
+	*
+	* @example
+	* ```ts
+	* const next = queue.peekNextItem();        // Peek at front
+	* const last = queue.peekNextItem('back');  // Peek at back
+	* ```
+	*/
+	peekNextItem = (position = "front") => {
+		if (this.items.length === 0) return;
+		if (this.options.getPriority || position === "front") return this.items[0];
+		else return this.items[this.items.length - 1];
+	};
+	/**
+	* Returns a copy of all items in the queue.
+	*/
+	peekAllItems = () => {
+		return [...this.items];
+	};
+	/**
+	* Processes a specified number of items immediately with no wait time.
+	* If no numberOfItems is provided, all items will be processed.
+	*
+	* @example
+	* ```ts
+	* queue.flush();     // Process all items immediately
+	* queue.flush(3);    // Process next 3 items immediately
+	* ```
+	*/
+	flush = (numberOfItems = this.items.length, position) => {
+		this.clearTimeout();
+		for (let i = 0; i < numberOfItems && this.items.length > 0; i++) this.execute(position);
+		if (this.isRunning && this.items.length > 0 && !this.pendingTick) this.tick();
+	};
+	/**
+	* Processes all items in the queue as a batch using the provided function.
+	* The queue is cleared after processing.
+	*
+	* @example
+	* ```ts
+	* queue.flushAsBatch((items) => {
+	*   console.log('Processing batch:', items);
+	*   // Process all items together
+	* });
+	* ```
+	*/
+	flushAsBatch = (batchFunction) => {
+		const items = this.peekAllItems();
+		this.clear();
+		batchFunction(items);
+	};
+	/**
+	* Removes all items from the queue. Does not affect items being processed.
+	*/
+	clear = () => {
+		this.items = [];
+	};
 };
 /**
 * Creates a lightweight queue that processes items using the provided function.
@@ -202,5 +284,4 @@ function liteQueue(fn, options = {}) {
 }
 
 //#endregion
-export { LiteQueuer, liteQueue };
-//# sourceMappingURL=lite-queuer.js.map
+export { LiteQueuer, liteQueue };