@tanstack/pacer-lite 0.2.1 → 0.3.0

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 };

package/dist/lite-rate-limiter.d.ts

@@ -1,11 +1,9 @@
-import { AnyFunction } from "@tanstack/pacer/types";
-
+import { AnyFunction } from "./pacer/dist/types.js";
 //#region src/lite-rate-limiter.d.ts
-
 /**
  * Options for configuring a lite rate-limited function
  */
-interface LiteRateLimiterOptions<TFn extends AnyFunction = AnyFunction> {
+export interface LiteRateLimiterOptions<TFn extends AnyFunction = AnyFunction> {
   /**
    * Maximum number of executions allowed within the time window.
    */
@@ -68,7 +66,7 @@ interface LiteRateLimiterOptions<TFn extends AnyFunction = AnyFunction> {
  * }
  * ```
  */
-declare class LiteRateLimiter<TFn extends AnyFunction> {
+export declare class LiteRateLimiter<TFn extends AnyFunction> {
   fn: TFn;
   options: LiteRateLimiterOptions<TFn>;
   private executionTimes;
@@ -143,7 +141,5 @@ declare class LiteRateLimiter<TFn extends AnyFunction> {
  * });
  * ```
  */
-declare function liteRateLimit<TFn extends AnyFunction>(fn: TFn, options: LiteRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => boolean;
-//#endregion
-export { LiteRateLimiter, LiteRateLimiterOptions, liteRateLimit };
-//# sourceMappingURL=lite-rate-limiter.d.ts.map
+export declare function liteRateLimit<TFn extends AnyFunction>(fn: TFn, options: LiteRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => boolean;
+//#endregion

package/dist/lite-rate-limiter.js

@@ -38,72 +38,99 @@
 * ```
 */
 var LiteRateLimiter = class {
+	fn;
+	options;
+	executionTimes = [];
+	timeoutIds = /* @__PURE__ */ new Set();
 	constructor(fn, options) {
 		this.fn = fn;
 		this.options = options;
-		this.executionTimes = [];
-		this.timeoutIds = /* @__PURE__ */ new Set();
-		this.maybeExecute = (...args) => {
-			this.cleanupOldExecutions();
-			if (this.getExecutionTimesInWindow().length < this.options.limit) {
-				this.execute(...args);
-				return true;
-			}
-			this.options.onReject?.(this);
-			return false;
-		};
-		this.execute = (...args) => {
-			const now = Date.now();
-			this.fn(...args);
-			this.options.onExecute?.(args, this);
-			this.executionTimes.push(now);
-			this.setCleanupTimeout(now);
-		};
-		this.getExecutionTimesInWindow = () => {
-			if (this.options.windowType === "sliding") return this.executionTimes.filter((time) => time > Date.now() - this.options.window);
-			else {
-				if (this.executionTimes.length === 0) return [];
-				const windowStart = Math.min(...this.executionTimes);
-				const windowEnd = windowStart + this.options.window;
-				if (Date.now() > windowEnd) return [];
-				return this.executionTimes.filter((time) => time >= windowStart && time <= windowEnd);
-			}
-		};
-		this.setCleanupTimeout = (executionTime) => {
-			if (this.options.windowType === "sliding" || this.timeoutIds.size === 0) {
-				const timeUntilExpiration = executionTime - Date.now() + this.options.window + 1;
-				const timeoutId = setTimeout(() => {
-					this.cleanupOldExecutions();
-					this.clearTimeout(timeoutId);
-				}, timeUntilExpiration);
-				this.timeoutIds.add(timeoutId);
-			}
-		};
-		this.clearTimeout = (timeoutId) => {
-			clearTimeout(timeoutId);
-			this.timeoutIds.delete(timeoutId);
-		};
-		this.clearTimeouts = () => {
-			this.timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId));
-			this.timeoutIds.clear();
-		};
-		this.cleanupOldExecutions = () => {
-			this.executionTimes = this.getExecutionTimesInWindow();
-		};
-		this.getRemainingInWindow = () => {
-			const relevantExecutionTimes = this.getExecutionTimesInWindow();
-			return Math.max(0, this.options.limit - relevantExecutionTimes.length);
-		};
-		this.getMsUntilNextWindow = () => {
-			if (this.getRemainingInWindow() > 0) return 0;
-			return (this.executionTimes[0] ?? Infinity) + this.options.window - Date.now();
-		};
-		this.reset = () => {
-			this.executionTimes = [];
-			this.clearTimeouts();
-		};
 		if (this.options.windowType === void 0) this.options.windowType = "fixed";
 	}
+	/**
+	* Attempts to execute the rate-limited function if within the configured limits.
+	* Returns true if executed, false if rejected due to rate limiting.
+	*
+	* @example
+	* ```ts
+	* const rateLimiter = new LiteRateLimiter(fn, { limit: 5, window: 1000 });
+	*
+	* // First 5 calls return true
+	* rateLimiter.maybeExecute('arg1', 'arg2'); // true
+	*
+	* // Additional calls within the window return false
+	* rateLimiter.maybeExecute('arg1', 'arg2'); // false
+	* ```
+	*/
+	maybeExecute = (...args) => {
+		this.cleanupOldExecutions();
+		if (this.getExecutionTimesInWindow().length < this.options.limit) {
+			this.execute(...args);
+			return true;
+		}
+		this.options.onReject?.(this);
+		return false;
+	};
+	execute = (...args) => {
+		const now = Date.now();
+		this.fn(...args);
+		this.options.onExecute?.(args, this);
+		this.executionTimes.push(now);
+		this.setCleanupTimeout(now);
+	};
+	getExecutionTimesInWindow = () => {
+		if (this.options.windowType === "sliding") return this.executionTimes.filter((time) => time > Date.now() - this.options.window);
+		else {
+			if (this.executionTimes.length === 0) return [];
+			const windowStart = Math.min(...this.executionTimes);
+			const windowEnd = windowStart + this.options.window;
+			if (Date.now() > windowEnd) return [];
+			return this.executionTimes.filter((time) => time >= windowStart && time <= windowEnd);
+		}
+	};
+	setCleanupTimeout = (executionTime) => {
+		if (this.options.windowType === "sliding" || this.timeoutIds.size === 0) {
+			const timeUntilExpiration = executionTime - Date.now() + this.options.window + 1;
+			const timeoutId = setTimeout(() => {
+				this.cleanupOldExecutions();
+				this.clearTimeout(timeoutId);
+			}, timeUntilExpiration);
+			this.timeoutIds.add(timeoutId);
+		}
+	};
+	clearTimeout = (timeoutId) => {
+		clearTimeout(timeoutId);
+		this.timeoutIds.delete(timeoutId);
+	};
+	clearTimeouts = () => {
+		this.timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId));
+		this.timeoutIds.clear();
+	};
+	cleanupOldExecutions = () => {
+		this.executionTimes = this.getExecutionTimesInWindow();
+	};
+	/**
+	* Returns the number of remaining executions allowed in the current window.
+	*/
+	getRemainingInWindow = () => {
+		const relevantExecutionTimes = this.getExecutionTimesInWindow();
+		return Math.max(0, this.options.limit - relevantExecutionTimes.length);
+	};
+	/**
+	* Returns the number of milliseconds until the next execution will be possible.
+	* Returns 0 if executions are currently allowed.
+	*/
+	getMsUntilNextWindow = () => {
+		if (this.getRemainingInWindow() > 0) return 0;
+		return (this.executionTimes[0] ?? Infinity) + this.options.window - Date.now();
+	};
+	/**
+	* Resets the rate limiter state, clearing all execution history.
+	*/
+	reset = () => {
+		this.executionTimes = [];
+		this.clearTimeouts();
+	};
 };
 /**
 * Creates a lightweight rate-limited function that will execute the provided function up to a maximum number of times within a time window.
@@ -143,5 +170,4 @@ function liteRateLimit(fn, options) {
 }
 
 //#endregion
-export { LiteRateLimiter, liteRateLimit };
-//# sourceMappingURL=lite-rate-limiter.js.map
+export { LiteRateLimiter, liteRateLimit };

package/dist/lite-throttler.d.ts

@@ -1,11 +1,9 @@
-import { AnyFunction } from "@tanstack/pacer/types";
-
+import { AnyFunction } from "./pacer/dist/types.js";
 //#region src/lite-throttler.d.ts
-
 /**
  * Options for configuring a lite throttled function
  */
-interface LiteThrottlerOptions<TFn extends AnyFunction = AnyFunction> {
+export interface LiteThrottlerOptions<TFn extends AnyFunction = AnyFunction> {
   /**
    * Whether to execute on the leading edge of the timeout.
    * Defaults to true.
@@ -65,7 +63,7 @@ interface LiteThrottlerOptions<TFn extends AnyFunction = AnyFunction> {
  * });
  * ```
  */
-declare class LiteThrottler<TFn extends AnyFunction> {
+export declare class LiteThrottler<TFn extends AnyFunction> {
   fn: TFn;
   options: LiteThrottlerOptions<TFn>;
   private timeoutId;
@@ -128,7 +126,5 @@ declare class LiteThrottler<TFn extends AnyFunction> {
  * }, { wait: 250, leading: true, trailing: false });
  * ```
  */
-declare function liteThrottle<TFn extends AnyFunction>(fn: TFn, options: LiteThrottlerOptions<TFn>): (...args: Parameters<TFn>) => void;
-//#endregion
-export { LiteThrottler, LiteThrottlerOptions, liteThrottle };
-//# sourceMappingURL=lite-throttler.d.ts.map
+export declare function liteThrottle<TFn extends AnyFunction>(fn: TFn, options: LiteThrottlerOptions<TFn>): (...args: Parameters<TFn>) => void;
+//#endregion

package/dist/lite-throttler.js

@@ -40,52 +40,76 @@
 * ```
 */
 var LiteThrottler = class {
+	fn;
+	options;
+	timeoutId;
+	lastArgs;
+	lastExecutionTime = 0;
+	isPending = false;
 	constructor(fn, options) {
 		this.fn = fn;
 		this.options = options;
-		this.lastExecutionTime = 0;
-		this.isPending = false;
-		this.maybeExecute = (...args) => {
-			const timeSinceLastExecution = Date.now() - this.lastExecutionTime;
-			if (this.options.leading && timeSinceLastExecution >= this.options.wait) this.execute(...args);
-			else {
-				this.lastArgs = args;
-				if (!this.timeoutId && this.options.trailing) {
-					const timeoutDuration = this.options.wait - timeSinceLastExecution;
-					this.isPending = true;
-					this.timeoutId = setTimeout(() => {
-						if (this.lastArgs !== void 0) this.execute(...this.lastArgs);
-					}, timeoutDuration);
-				}
-			}
-		};
-		this.execute = (...args) => {
-			this.fn(...args);
-			this.options.onExecute?.(args, this);
-			this.lastExecutionTime = Date.now();
-			this.clearTimeout();
-			this.lastArgs = void 0;
-			this.isPending = false;
-		};
-		this.flush = () => {
-			if (this.isPending && this.lastArgs) this.execute(...this.lastArgs);
-		};
-		this.cancel = () => {
-			this.clearTimeout();
-			this.lastArgs = void 0;
-			this.isPending = false;
-		};
-		this.clearTimeout = () => {
-			if (this.timeoutId) {
-				clearTimeout(this.timeoutId);
-				this.timeoutId = void 0;
-			}
-		};
 		if (this.options.leading === void 0 && this.options.trailing === void 0) {
 			this.options.leading = true;
 			this.options.trailing = true;
 		}
 	}
+	/**
+	* Attempts to execute the throttled function. The execution behavior depends on the throttler options:
+	*
+	* - If enough time has passed since the last execution (>= wait period):
+	*   - With leading=true: Executes immediately
+	*   - With leading=false: Waits for the next trailing execution
+	*
+	* - If within the wait period:
+	*   - With trailing=true: Schedules execution for end of wait period
+	*   - With trailing=false: Drops the execution
+	*/
+	maybeExecute = (...args) => {
+		const timeSinceLastExecution = Date.now() - this.lastExecutionTime;
+		if (this.options.leading && timeSinceLastExecution >= this.options.wait) this.execute(...args);
+		else {
+			this.lastArgs = args;
+			if (!this.timeoutId && this.options.trailing) {
+				const timeoutDuration = this.options.wait - timeSinceLastExecution;
+				this.isPending = true;
+				this.timeoutId = setTimeout(() => {
+					if (this.lastArgs !== void 0) this.execute(...this.lastArgs);
+				}, timeoutDuration);
+			}
+		}
+	};
+	execute = (...args) => {
+		this.fn(...args);
+		this.options.onExecute?.(args, this);
+		this.lastExecutionTime = Date.now();
+		this.clearTimeout();
+		this.lastArgs = void 0;
+		this.isPending = false;
+	};
+	/**
+	* 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.isPending && this.lastArgs) this.execute(...this.lastArgs);
+	};
+	/**
+	* Cancels any pending trailing execution and clears internal state.
+	* If a trailing execution is scheduled, this will prevent that execution from occurring.
+	*/
+	cancel = () => {
+		this.clearTimeout();
+		this.lastArgs = void 0;
+		this.isPending = false;
+	};
+	clearTimeout = () => {
+		if (this.timeoutId) {
+			clearTimeout(this.timeoutId);
+			this.timeoutId = void 0;
+		}
+	};
 };
 /**
 * Creates a lightweight throttled function that limits how often the provided function can execute.
@@ -121,5 +145,4 @@ function liteThrottle(fn, options) {
 }
 
 //#endregion
-export { LiteThrottler, liteThrottle };
-//# sourceMappingURL=lite-throttler.js.map
+export { LiteThrottler, liteThrottle };

package/dist/pacer/dist/types.d.ts

@@ -0,0 +1,7 @@
+//#region ../pacer/dist/types.d.ts
+//#region src/types.d.ts
+/**
+ * Represents a function that can be called with any arguments and returns any value.
+ */
+export type AnyFunction = (...args: Array<any>) => any;
+//#endregion