@tanstack/pacer 0.21.1 → 0.23.0

package/dist/queuer.js

@@ -112,207 +112,13 @@ const defaultOptions = {
 * ```
 */
 var Queuer = class {
-	#timeoutId;
+	fn;
+	store = new Store(getDefaultQueuerState());
+	key;
+	options;
+	#timeoutId = null;
 	constructor(fn, initialOptions = {}) {
 		this.fn = fn;
-		this.store = new Store(getDefaultQueuerState());
-		this.#timeoutId = null;
-		this.setOptions = (newOptions) => {
-			this.options = {
-				...this.options,
-				...newOptions
-			};
-		};
-		this.#setState = (newState) => {
-			this.store.setState((state) => {
-				const combinedState = {
-					...state,
-					...newState
-				};
-				const { items, isRunning } = combinedState;
-				const size = items.length;
-				const isFull = size >= (this.options.maxSize ?? Infinity);
-				const isEmpty = size === 0;
-				const isIdle = isRunning && isEmpty;
-				const status = isIdle ? "idle" : isRunning ? "running" : "stopped";
-				return {
-					...combinedState,
-					isEmpty,
-					isFull,
-					isIdle,
-					size,
-					status
-				};
-			});
-			emitChange("Queuer", this);
-		};
-		this.#getWait = () => {
-			return parseFunctionOrValue(this.options.wait ?? 0, this);
-		};
-		this.#tick = () => {
-			if (!this.store.state.isRunning) {
-				this.#setState({ pendingTick: false });
-				return;
-			}
-			this.#setState({ pendingTick: true });
-			this.#checkExpiredItems();
-			while (this.store.state.items.length > 0) {
-				if (this.execute(this.options.getItemsFrom ?? "front") === void 0) break;
-				const wait = this.#getWait();
-				if (wait > 0) {
-					this.#timeoutId = setTimeout(() => this.#tick(), wait);
-					return;
-				}
-				this.#tick();
-			}
-			this.#setState({ pendingTick: false });
-		};
-		this.addItem = (item, position = this.options.addItemsTo ?? "back", runOnItemsChange = true) => {
-			this.#setState({ addItemCount: this.store.state.addItemCount + 1 });
-			if (this.store.state.items.length >= (this.options.maxSize ?? Infinity)) {
-				this.#setState({ rejectionCount: this.store.state.rejectionCount + 1 });
-				this.options.onReject?.(item, this);
-				return false;
-			}
-			const priority = this.options.getPriority !== defaultOptions.getPriority ? this.options.getPriority(item) : item.priority;
-			const items = this.store.state.items;
-			const itemTimestamps = this.store.state.itemTimestamps;
-			if (priority !== void 0) {
-				const insertIndex = items.findIndex((existing) => {
-					return (this.options.getPriority !== defaultOptions.getPriority ? this.options.getPriority(existing) : existing.priority) < priority;
-				});
-				if (insertIndex === -1) {
-					items.push(item);
-					itemTimestamps.push(Date.now());
-				} else {
-					items.splice(insertIndex, 0, item);
-					itemTimestamps.splice(insertIndex, 0, Date.now());
-				}
-			} else if (position === "front") {
-				items.unshift(item);
-				itemTimestamps.unshift(Date.now());
-			} else {
-				items.push(item);
-				itemTimestamps.push(Date.now());
-			}
-			this.#setState({
-				items,
-				itemTimestamps
-			});
-			if (runOnItemsChange) this.options.onItemsChange?.(this);
-			if (this.store.state.isRunning && !this.store.state.pendingTick) {
-				this.#setState({ pendingTick: true });
-				this.#tick();
-			}
-			return true;
-		};
-		this.getNextItem = (position = this.options.getItemsFrom ?? "front") => {
-			const { items, itemTimestamps } = this.store.state;
-			let item;
-			if (this.options.getPriority !== defaultOptions.getPriority || position === "front") {
-				item = items[0];
-				if (item !== void 0) this.#setState({
-					items: items.slice(1),
-					itemTimestamps: itemTimestamps.slice(1)
-				});
-			} else {
-				item = items[items.length - 1];
-				if (item !== void 0) this.#setState({
-					items: items.slice(0, -1),
-					itemTimestamps: itemTimestamps.slice(0, -1)
-				});
-			}
-			if (item !== void 0) this.options.onItemsChange?.(this);
-			return item;
-		};
-		this.#getAllItems = () => {
-			const items = this.peekAllItems();
-			this.clear();
-			return items;
-		};
-		this.execute = (position) => {
-			const item = this.getNextItem(position);
-			if (item !== void 0) {
-				this.fn(item);
-				this.#setState({ executionCount: this.store.state.executionCount + 1 });
-				this.options.onExecute?.(item, this);
-			}
-			return item;
-		};
-		this.flush = (numberOfItems = this.store.state.items.length, position) => {
-			this.#clearTimeout();
-			for (let i = 0; i < numberOfItems; i++) this.execute(position);
-			this.#tick();
-		};
-		this.flushAsBatch = (batchFunction) => {
-			const items = this.#getAllItems();
-			this.clear();
-			batchFunction(items);
-		};
-		this.#checkExpiredItems = () => {
-			if ((this.options.expirationDuration ?? Infinity) === Infinity && this.options.getIsExpired === defaultOptions.getIsExpired) return;
-			const now = Date.now();
-			const expiredIndices = [];
-			for (let i = 0; i < this.store.state.items.length; i++) {
-				const timestamp = this.store.state.itemTimestamps[i];
-				if (timestamp === void 0) continue;
-				const item = this.store.state.items[i];
-				if (item === void 0) continue;
-				if (this.options.getIsExpired !== defaultOptions.getIsExpired ? this.options.getIsExpired(item, timestamp) : now - timestamp > (this.options.expirationDuration ?? Infinity)) expiredIndices.push(i);
-			}
-			for (let i = expiredIndices.length - 1; i >= 0; i--) {
-				const index = expiredIndices[i];
-				if (index === void 0) continue;
-				const expiredItem = this.store.state.items[index];
-				if (expiredItem === void 0) continue;
-				const newItems = [...this.store.state.items];
-				const newTimestamps = [...this.store.state.itemTimestamps];
-				newItems.splice(index, 1);
-				newTimestamps.splice(index, 1);
-				this.#setState({
-					items: newItems,
-					itemTimestamps: newTimestamps,
-					expirationCount: this.store.state.expirationCount + 1
-				});
-				this.options.onExpire?.(expiredItem, this);
-			}
-			if (expiredIndices.length > 0) this.options.onItemsChange?.(this);
-		};
-		this.peekNextItem = (position = "front") => {
-			if (position === "front") return this.store.state.items[0];
-			return this.store.state.items[this.store.state.items.length - 1];
-		};
-		this.peekAllItems = () => {
-			return [...this.store.state.items];
-		};
-		this.start = () => {
-			this.#setState({ isRunning: true });
-			if (!this.store.state.pendingTick && this.store.state.items.length > 0) this.#tick();
-		};
-		this.stop = () => {
-			this.#clearTimeout();
-			this.#setState({
-				isRunning: false,
-				pendingTick: false
-			});
-		};
-		this.#clearTimeout = () => {
-			if (this.#timeoutId) {
-				clearTimeout(this.#timeoutId);
-				this.#timeoutId = null;
-			}
-		};
-		this.clear = () => {
-			this.#setState({
-				items: [],
-				itemTimestamps: []
-			});
-			this.options.onItemsChange?.(this);
-		};
-		this.reset = () => {
-			this.#setState(getDefaultQueuerState());
-			this.options.onItemsChange?.(this);
-		};
 		this.key = initialOptions.key;
 		this.options = {
 			...defaultOptions,
@@ -336,23 +142,288 @@ var Queuer = class {
 			this.setOptions(event.payload.options);
 		});
 	}
-	#setState;
+	/**
+	* Updates the queuer options. New options are merged with existing options.
+	*/
+	setOptions = (newOptions) => {
+		this.options = {
+			...this.options,
+			...newOptions
+		};
+	};
+	#setState = (newState) => {
+		this.store.setState((state) => {
+			const combinedState = {
+				...state,
+				...newState
+			};
+			const { items, isRunning } = combinedState;
+			const size = items.length;
+			const isFull = size >= (this.options.maxSize ?? Infinity);
+			const isEmpty = size === 0;
+			const isIdle = isRunning && isEmpty;
+			const status = isIdle ? "idle" : isRunning ? "running" : "stopped";
+			return {
+				...combinedState,
+				isEmpty,
+				isFull,
+				isIdle,
+				size,
+				status
+			};
+		});
+		emitChange("Queuer", this);
+	};
 	/**
 	* Returns the current wait time (in milliseconds) between processing items.
 	* If a function is provided, it is called with the queuer instance.
 	*/
-	#getWait;
+	#getWait = () => {
+		return parseFunctionOrValue(this.options.wait ?? 0, this);
+	};
 	/**
 	* Processes items in the queue up to the wait interval. Internal use only.
 	*/
-	#tick;
-	#getAllItems;
+	#tick = () => {
+		if (!this.store.state.isRunning) {
+			this.#setState({ pendingTick: false });
+			return;
+		}
+		this.#setState({ pendingTick: true });
+		this.#checkExpiredItems();
+		while (this.store.state.items.length > 0) {
+			if (this.execute(this.options.getItemsFrom ?? "front") === void 0) break;
+			const wait = this.#getWait();
+			if (wait > 0) {
+				this.#timeoutId = setTimeout(() => this.#tick(), wait);
+				return;
+			}
+			this.#tick();
+		}
+		this.#setState({ pendingTick: false });
+	};
+	/**
+	* Adds an item to the queue. If the queue is full, the item is rejected and onReject is called.
+	* `undefined` cannot be queued (it is the internal "no item" sentinel) and is always rejected.
+	* Items can be inserted based on priority or at the front/back depending on configuration.
+	*
+	* Returns true if the item was added, false if the queue is full.
+	*
+	* Example usage:
+	* ```ts
+	* queuer.addItem('task');
+	* queuer.addItem('task2', 'front');
+	* ```
+	*/
+	addItem = (item, position = this.options.addItemsTo ?? "back", runOnItemsChange = true) => {
+		this.#setState({ addItemCount: this.store.state.addItemCount + 1 });
+		if (item === void 0) {
+			this.#setState({ rejectionCount: this.store.state.rejectionCount + 1 });
+			this.options.onReject?.(item, this);
+			return false;
+		}
+		if (this.store.state.items.length >= (this.options.maxSize ?? Infinity)) {
+			this.#setState({ rejectionCount: this.store.state.rejectionCount + 1 });
+			this.options.onReject?.(item, this);
+			return false;
+		}
+		const priority = this.options.getPriority !== defaultOptions.getPriority ? this.options.getPriority(item) : item?.priority;
+		const items = this.store.state.items;
+		const itemTimestamps = this.store.state.itemTimestamps;
+		if (priority !== void 0) {
+			const insertIndex = items.findIndex((existing) => {
+				return (this.options.getPriority !== defaultOptions.getPriority ? this.options.getPriority(existing) : existing?.priority) < priority;
+			});
+			if (insertIndex === -1) {
+				items.push(item);
+				itemTimestamps.push(Date.now());
+			} else {
+				items.splice(insertIndex, 0, item);
+				itemTimestamps.splice(insertIndex, 0, Date.now());
+			}
+		} else if (position === "front") {
+			items.unshift(item);
+			itemTimestamps.unshift(Date.now());
+		} else {
+			items.push(item);
+			itemTimestamps.push(Date.now());
+		}
+		this.#setState({
+			items,
+			itemTimestamps
+		});
+		if (runOnItemsChange) this.options.onItemsChange?.(this);
+		if (this.store.state.isRunning && !this.store.state.pendingTick) {
+			this.#setState({ pendingTick: true });
+			this.#tick();
+		}
+		return true;
+	};
+	/**
+	* 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 usage:
+	* ```ts
+	* // FIFO
+	* queuer.getNextItem();
+	* // LIFO
+	* queuer.getNextItem('back');
+	* ```
+	*/
+	getNextItem = (position = this.options.getItemsFrom ?? "front") => {
+		const { items, itemTimestamps } = this.store.state;
+		let item;
+		if (this.options.getPriority !== defaultOptions.getPriority || position === "front") {
+			item = items[0];
+			if (item !== void 0) this.#setState({
+				items: items.slice(1),
+				itemTimestamps: itemTimestamps.slice(1)
+			});
+		} else {
+			item = items[items.length - 1];
+			if (item !== void 0) this.#setState({
+				items: items.slice(0, -1),
+				itemTimestamps: itemTimestamps.slice(0, -1)
+			});
+		}
+		if (item !== void 0) this.options.onItemsChange?.(this);
+		return item;
+	};
+	#getAllItems = () => {
+		const items = this.peekAllItems();
+		this.clear();
+		return items;
+	};
+	/**
+	* Removes and returns the next item from the queue and processes it using the provided function.
+	*
+	* Example usage:
+	* ```ts
+	* queuer.execute();
+	* // LIFO
+	* queuer.execute('back');
+	* ```
+	*/
+	execute = (position) => {
+		const item = this.getNextItem(position);
+		if (item !== void 0) {
+			this.fn(item);
+			this.#setState({ executionCount: this.store.state.executionCount + 1 });
+			this.options.onExecute?.(item, this);
+		}
+		return item;
+	};
+	/**
+	* Processes a specified number of items to execute immediately with no wait time
+	* If no numberOfItems is provided, all items will be processed
+	*/
+	flush = (numberOfItems = this.store.state.items.length, position) => {
+		this.#clearTimeout();
+		for (let i = 0; i < numberOfItems; i++) this.execute(position);
+		this.#tick();
+	};
+	/**
+	* Processes all items in the queue as a batch using the provided function as an argument
+	* The queue is cleared after processing
+	*/
+	flushAsBatch = (batchFunction) => {
+		const items = this.#getAllItems();
+		this.clear();
+		batchFunction(items);
+	};
 	/**
 	* Checks for expired items in the queue and removes them. Calls onExpire for each expired item.
 	* Internal use only.
 	*/
-	#checkExpiredItems;
-	#clearTimeout;
+	#checkExpiredItems = () => {
+		if ((this.options.expirationDuration ?? Infinity) === Infinity && this.options.getIsExpired === defaultOptions.getIsExpired) return;
+		const now = Date.now();
+		const expiredIndices = [];
+		for (let i = 0; i < this.store.state.items.length; i++) {
+			const timestamp = this.store.state.itemTimestamps[i];
+			if (timestamp === void 0) continue;
+			const item = this.store.state.items[i];
+			if (item === void 0) continue;
+			if (this.options.getIsExpired !== defaultOptions.getIsExpired ? this.options.getIsExpired(item, timestamp) : now - timestamp > (this.options.expirationDuration ?? Infinity)) expiredIndices.push(i);
+		}
+		for (let i = expiredIndices.length - 1; i >= 0; i--) {
+			const index = expiredIndices[i];
+			if (index === void 0) continue;
+			const expiredItem = this.store.state.items[index];
+			if (expiredItem === void 0) continue;
+			const newItems = [...this.store.state.items];
+			const newTimestamps = [...this.store.state.itemTimestamps];
+			newItems.splice(index, 1);
+			newTimestamps.splice(index, 1);
+			this.#setState({
+				items: newItems,
+				itemTimestamps: newTimestamps,
+				expirationCount: this.store.state.expirationCount + 1
+			});
+			this.options.onExpire?.(expiredItem, this);
+		}
+		if (expiredIndices.length > 0) this.options.onItemsChange?.(this);
+	};
+	/**
+	* Returns the next item in the queue without removing it.
+	*
+	* Example usage:
+	* ```ts
+	* queuer.peekNextItem(); // front
+	* queuer.peekNextItem('back'); // back
+	* ```
+	*/
+	peekNextItem = (position = "front") => {
+		if (position === "front") return this.store.state.items[0];
+		return this.store.state.items[this.store.state.items.length - 1];
+	};
+	/**
+	* Returns a copy of all items in the queue.
+	*/
+	peekAllItems = () => {
+		return [...this.store.state.items];
+	};
+	/**
+	* Starts processing items in the queue. If already isRunning, does nothing.
+	*/
+	start = () => {
+		this.#setState({ isRunning: true });
+		if (!this.store.state.pendingTick && this.store.state.items.length > 0) this.#tick();
+	};
+	/**
+	* Stops processing items in the queue. Does not clear the queue.
+	*/
+	stop = () => {
+		this.#clearTimeout();
+		this.#setState({
+			isRunning: false,
+			pendingTick: false
+		});
+	};
+	#clearTimeout = () => {
+		if (this.#timeoutId) {
+			clearTimeout(this.#timeoutId);
+			this.#timeoutId = null;
+		}
+	};
+	/**
+	* Removes all pending items from the queue. Does not affect items being processed.
+	*/
+	clear = () => {
+		this.#setState({
+			items: [],
+			itemTimestamps: []
+		});
+		this.options.onItemsChange?.(this);
+	};
+	/**
+	* Resets the queuer state to its default values
+	*/
+	reset = () => {
+		this.#setState(getDefaultQueuerState());
+		this.options.onItemsChange?.(this);
+	};
 };
 /**
 * Creates a queue that processes items immediately upon addition.
@@ -394,5 +465,4 @@ function queue(fn, initialOptions) {
 }
 
 //#endregion
-export { Queuer, queue, queuerOptions };
-//# sourceMappingURL=queuer.js.map
+export { Queuer, queue, queuerOptions };

package/dist/rate-limiter.d.ts

@@ -1,8 +1,7 @@
 import { AnyFunction } from "./types.js";
 import { Store } from "@tanstack/store";
-
 //#region src/rate-limiter.d.ts
-interface RateLimiterState {
+export interface RateLimiterState {
   /**
    * Number of function executions that have been completed
    */
@@ -31,7 +30,7 @@ interface RateLimiterState {
 /**
  * Options for configuring a rate-limited function
  */
-interface RateLimiterOptions<TFn extends AnyFunction> {
+export interface RateLimiterOptions<TFn extends AnyFunction> {
   /**
    * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -75,7 +74,7 @@ interface RateLimiterOptions<TFn extends AnyFunction> {
 /**
  * Utility function for sharing common `RateLimiterOptions` options between different `RateLimiter` instances.
  */
-declare function rateLimiterOptions<TFn extends AnyFunction = AnyFunction, TOptions extends Partial<RateLimiterOptions<TFn>> = Partial<RateLimiterOptions<TFn>>>(options: TOptions): TOptions;
+export declare function rateLimiterOptions<TFn extends AnyFunction = AnyFunction, TOptions extends Partial<RateLimiterOptions<TFn>> = Partial<RateLimiterOptions<TFn>>>(options: TOptions): TOptions;
 /**
  * A class that creates a rate-limited function.
  *
@@ -121,7 +120,7 @@ declare function rateLimiterOptions<TFn extends AnyFunction = AnyFunction, TOpti
  * rateLimiter.maybeExecute('123');
  * ```
  */
-declare class RateLimiter<TFn extends AnyFunction> {
+export declare class RateLimiter<TFn extends AnyFunction> {
   #private;
   fn: TFn;
   readonly store: Store<Readonly<RateLimiterState>>;
@@ -209,7 +208,5 @@ declare class RateLimiter<TFn extends AnyFunction> {
  * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
  * ```
  */
-declare function rateLimit<TFn extends AnyFunction>(fn: TFn, initialOptions: RateLimiterOptions<TFn>): (...args: Parameters<TFn>) => boolean;
-//#endregion
-export { RateLimiter, RateLimiterOptions, RateLimiterState, rateLimit, rateLimiterOptions };
-//# sourceMappingURL=rate-limiter.d.ts.map
+export declare function rateLimit<TFn extends AnyFunction>(fn: TFn, initialOptions: RateLimiterOptions<TFn>): (...args: Parameters<TFn>) => boolean;
+//#endregion