@tanstack/pacer-lite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+<div align="center">
+  <img src="./media/header_pacer.png" >
+</div>
+
+<br />
+
+<div align="center">
+	<a href="https://www.npmjs.com/package/@tanstack/pacer" target="\_parent">
+	  <img alt="" src="https://img.shields.io/npm/dm/@tanstack/pacer.svg" alt="npm downloads" />
+	</a>
+- <a href="https://github.com/TanStack/pacer" target="\_parent">
+	  <img alt="" src="https://img.shields.io/github/stars/TanStack/pacer.svg?style=social&label=Star" alt="GitHub stars" />
+	</a>
+	<a href="https://bundlephobia.com/result?p=@tanstack/react-pacer@latest" target="\_parent">
+  <img alt="" src="https://badgen.net/bundlephobia/minzip/@tanstack/react-pacer@latest" alt="Bundle size" />
+</a>
+</div>
+
+<div align="center">
+<a href="#badge">
+  <img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
+</a>
+	<a href="#badge">
+		<img src="https://img.shields.io/github/v/release/tanstack/pacer" alt="Release"/>
+	</a>
+	<a href="https://twitter.com/tan_stack">
+		<img src="https://img.shields.io/twitter/follow/tan_stack.svg?style=social" alt="Follow @TanStack"/>
+	</a>
+</div>
+
+<div align="center">
+  
+### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
+</div>
+
+# TanStack Pacer
+
+A lightweight timing and scheduling library for debouncing, throttling, rate limiting, queuing, and batching.
+
+> [!NOTE]
+> TanStack Pacer is currently mostly a client-side only library, but it is being designed to be able to potentially be used on the server-side as well.
+
+- **Debouncing**
+  - Delay execution until after a period of inactivity for when you only care about the last execution in a sequence.
+  - Synchronous or Asynchronous Debounce utilities with promise support and error handling
+  - Control of leading, trailing, and enabled options
+- **Throttling**
+  - Smoothly limit the rate at which a function can fire
+  - Synchronous or Asynchronous Throttle utilities with promise support and error handling
+  - Control of leading, trailing, and enabled options.
+- **Rate Limiting**
+  - Limit the rate at which a function can fire over a period of time
+  - Synchronous or Asynchronous Rate Limiting utilities with promise support and error handling
+  - Fixed or Sliding Window variations of Rate Limiting
+- **Queuing**
+  - Queue functions to be executed in a specific order
+  - Choose from FIFO, LIFO, and Priority queue implementations
+  - Control processing speed with configurable wait times or concurrency limits
+  - Manage queue execution with start/stop capabilities
+  - Expire items from the queue after a configurable duration
+- **Batching**
+  - Chunk up multiple operations into larger batches to reduce total back-and-forth operations
+  - Batch by time period, batch size, whichever comes first, or a custom condition to trigger batch executions
+- **Async or Sync Variations**
+  - Choose between synchronous and asynchronous versions of each utility
+  - Optional error, success, and settled handling for async variations
+  - Retry and Abort support for async variations
+- **State Management**
+  - Uses TanStack Store under the hood for state management with fine-grained reactivity
+  - Easily integrate with your own state management library of choice
+  - Persist state to local or session storage for some utilities like rate limiting and queuing
+- **Convenient Hooks**
+  - Reduce boilerplate code with pre-built hooks like `useDebouncedCallback`, `useThrottledValue`, and `useQueuedState`, and more.
+  - Multiple layers of abstraction to choose from depending on your use case.
+  - Works with each framework's default state management solutions, or with whatever custom state management library that you prefer.
+- **Type Safety**
+  - Full type safety with TypeScript that makes sure that your functions will always be called with the correct arguments
+  - Generics for flexible and reusable utilities
+- **Framework Adapters**
+  - React, Solid, and more
+- **Tree Shaking**
+  - We, of course, get tree-shaking right for your applications by default, but we also provide extra deep imports for each utility, making it easier to embed these utilities into your libraries without increasing the bundle-phobia reports of your library.
+
+### <a href="https://tanstack.com/pacer">Read the docs →</b></a>
+
+<br />
+
+> [!NOTE]
+> You may know **TanSack Pacer** by our adapter names, too!
+>
+> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer)
+> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer)
+> - Angular Pacer - needs a contributor!
+> - Preact Pacer - Coming soon! (After React Pacer is more fleshed out)
+> - Svelte Pacer - needs a contributor!
+> - Vue Pacer - needs a contributor!
+
+## Get Involved
+
+- We welcome issues and pull requests!
+- Participate in [GitHub discussions](https://github.com/TanStack/pacer/discussions)
+- Chat with the community on [Discord](https://discord.com/invite/WrRKjPJ)
+- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions
+
+## Partners
+
+<table align="center">
+  <tr>
+    <td>
+      <a href="https://www.coderabbit.ai/?via=tanstack&dub_id=aCcEEdAOqqutX6OS" >
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/coderabbit-dark-CMcuvjEy.svg" height="40" />
+          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" />
+          <img src="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" alt="CodeRabbit" />
+        </picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.cloudflare.com?utm_source=tanstack">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/cloudflare-white-DQDB7UaL.svg" height="60" />
+          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" />
+          <img src="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" alt="Cloudflare" />
+        </picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.unkey.com/?utm_source=tanstack">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="./media/unkey_dark.svg" height="60" />
+          <source media="(prefers-color-scheme: light)" srcset="./media/unkey_logo.svg" height="60" />
+          <img src="./media/unkey_logo.svg" height="60" alt="Unkey"/>
+        </picture>
+      </a>
+    </td>
+  </tr>
+</table>
+
+<div align="center">
+<img src="./media/partner_logo.svg" alt="Pacer & you?" height="65">
+<p>
+We're looking for TanStack Pacer Partners to join our mission! Partner with us to push the boundaries of TanStack Pacer and build amazing things together.
+</p>
+<a href="mailto:partners@tanstack.com?subject=TanStack Pacer Partnership"><b>LET'S CHAT</b></a>
+</div>
+
+</div>
+
+## Explore the TanStack Ecosystem
+
+- <a href="https://github.com/tanstack/config"><b>TanStack Config</b></a> – Tooling for JS/TS packages
+- <a href="https://github.com/tanstack/db"><b>TanStack DB</b></a> – Reactive sync client store
+- <a href="https://github.com/tanstack/devtools"><b>TanStack DevTools</b></a> – Unified devtools panel
+- <a href="https://github.com/tanstack/form"><b>TanStack Form</b></a> – Type‑safe form state
+- <a href="https://github.com/tanstack/query"><b>TanStack Query</b></a> – Async state & caching
+- <a href="https://github.com/tanstack/ranger"><b>TanStack Ranger</b></a> – Range & slider primitives
+- <a href="https://github.com/tanstack/router"><b>TanStack Router</b></a> – Type‑safe routing, caching & URL state
+- <a href="https://github.com/tanstack/router"><b>TanStack Start</b></a> – Full‑stack SSR & streaming
+- <a href="https://github.com/tanstack/store"><b>TanStack Store</b></a> – Reactive data store
+- <a href="https://github.com/tanstack/table"><b>TanStack Table</b></a> – Headless datagrids
+- <a href="https://github.com/tanstack/virtual"><b>TanStack Virtual</b></a> – Virtualized rendering
+
+… and more at <a href="https://tanstack.com"><b>TanStack.com »</b></a>
+
+<!-- USE THE FORCE LUKE -->

package/dist/cjs/index.cjs

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const liteDebouncer = require("./lite-debouncer.cjs");
+const liteThrottler = require("./lite-throttler.cjs");
+const liteRateLimiter = require("./lite-rate-limiter.cjs");
+const liteQueuer = require("./lite-queuer.cjs");
+const liteBatcher = require("./lite-batcher.cjs");
+exports.LiteDebouncer = liteDebouncer.LiteDebouncer;
+exports.liteDebounce = liteDebouncer.liteDebounce;
+exports.LiteThrottler = liteThrottler.LiteThrottler;
+exports.liteThrottle = liteThrottler.liteThrottle;
+exports.LiteRateLimiter = liteRateLimiter.LiteRateLimiter;
+exports.liteRateLimit = liteRateLimiter.liteRateLimit;
+exports.LiteQueuer = liteQueuer.LiteQueuer;
+exports.liteQueue = liteQueuer.liteQueue;
+exports.LiteBatcher = liteBatcher.LiteBatcher;
+exports.liteBatch = liteBatcher.liteBatch;
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -0,0 +1,5 @@
+export * from './lite-debouncer.cjs';
+export * from './lite-throttler.cjs';
+export * from './lite-rate-limiter.cjs';
+export * from './lite-queuer.cjs';
+export * from './lite-batcher.cjs';

package/dist/cjs/lite-batcher.cjs

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class LiteBatcher {
+  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);
+      const shouldProcess = this.items.length >= this.options.maxSize || this.options.getShouldExecute(this.items, this);
+      if (shouldProcess) {
+        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;
+    this.options.getShouldExecute = this.options.getShouldExecute ?? (() => false);
+  }
+  /**
+   * Number of items currently in the batch
+   */
+  get size() {
+    return this.items.length;
+  }
+  /**
+   * Whether the batch has no items to process (items array is empty)
+   */
+  get isEmpty() {
+    return this.items.length === 0;
+  }
+  /**
+   * Whether the batcher is waiting for the timeout to trigger batch processing
+   */
+  get isPending() {
+    return this._isPending;
+  }
+  getWait() {
+    if (typeof this.options.wait === "function") {
+      return this.options.wait(this);
+    }
+    return this.options.wait;
+  }
+}
+function liteBatch(fn, options = {}) {
+  const batcher = new LiteBatcher(fn, options);
+  return batcher.addItem;
+}
+exports.LiteBatcher = LiteBatcher;
+exports.liteBatch = liteBatch;
+//# sourceMappingURL=lite-batcher.cjs.map

package/dist/cjs/lite-batcher.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lite-batcher.cjs","sources":["../../src/lite-batcher.ts"],"sourcesContent":["/**\n * Options for configuring a lite batcher instance\n */\nexport interface LiteBatcherOptions<TValue> {\n  /**\n   * Custom function to determine if a batch should be processed\n   * Return true to process the batch immediately\n   */\n  getShouldExecute?: (\n    items: Array<TValue>,\n    batcher: LiteBatcher<TValue>,\n  ) => boolean\n  /**\n   * Maximum number of items in a batch\n   * @default Infinity\n   */\n  maxSize?: number\n  /**\n   * Callback fired after a batch is processed\n   */\n  onExecute?: (batch: Array<TValue>, batcher: LiteBatcher<TValue>) => void\n  /**\n   * Callback fired after items are added to the batcher\n   */\n  onItemsChange?: (batcher: LiteBatcher<TValue>) => void\n  /**\n   * Whether the batcher should start processing immediately\n   * @default true\n   */\n  started?: boolean\n  /**\n   * Maximum time in milliseconds to wait before processing a batch.\n   * If the wait duration has elapsed, the batch will be processed.\n   * If not provided, the batch will not be triggered by a timeout.\n   * @default Infinity\n   */\n  wait?: number | ((batcher: LiteBatcher<TValue>) => number)\n}\n\n/**\n * A lightweight class that collects items and processes them in batches.\n *\n * This is an alternative to the Batcher in the core @tanstack/pacer package, but is more\n * suitable for libraries and npm packages that need minimal overhead. Unlike the core Batcher,\n * this version does not use TanStack Store for state management, has no devtools integration,\n * no callbacks, and provides only essential batching functionality.\n *\n * Batching is a technique for grouping multiple operations together to be processed as a single unit.\n * This synchronous version is lighter weight and often all you need.\n *\n * The Batcher provides a flexible way to implement batching with configurable:\n * - Maximum batch size (number of items per batch)\n * - Time-based batching (process after X milliseconds)\n * - Custom batch processing logic via getShouldExecute\n *\n * Features included:\n * - Core batching functionality (addItem, flush, clear, cancel)\n * - Size-based batching (maxSize)\n * - Time-based batching (wait timeout)\n * - Custom condition batching (getShouldExecute)\n * - Manual processing controls\n * - Public mutable options\n * - Callback support for monitoring batch execution and state changes\n *\n * Features NOT included (compared to core Batcher):\n * - No TanStack Store state management\n * - No devtools integration\n * - No complex state tracking (execution counts, etc.)\n * - No reactive state management\n *\n * @example\n * ```ts\n * // Basic batching\n * const batcher = new LiteBatcher<number>(\n *   (items) => console.log('Processing batch:', items),\n *   {\n *     maxSize: 5,\n *     wait: 2000,\n *     onExecute: (batch, batcher) => {\n *       console.log('Batch executed with', batch.length, 'items');\n *     },\n *     onItemsChange: (batcher) => {\n *       console.log('Batch size changed to:', batcher.size);\n *     }\n *   }\n * );\n *\n * batcher.addItem(1);\n * batcher.addItem(2);\n * // After 2 seconds or when 5 items are added, whichever comes first,\n * // the batch will be processed\n * ```\n *\n * @example\n * ```ts\n * // Custom condition batching\n * const batcher = new LiteBatcher<Task>(\n *   (items) => processTasks(items),\n *   {\n *     getShouldExecute: (items) => items.some(task => task.urgent),\n *     maxSize: 10,\n *   }\n * );\n *\n * batcher.addItem({ name: 'normal', urgent: false });\n * batcher.addItem({ name: 'urgent', urgent: true }); // Triggers immediate processing\n * ```\n */\nexport class LiteBatcher<TValue> {\n  private items: Array<TValue> = []\n  private timeoutId: NodeJS.Timeout | null = null\n  private _isPending = false\n\n  constructor(\n    public fn: (items: Array<TValue>) => void,\n    public options: LiteBatcherOptions<TValue> = {},\n  ) {\n    // Set defaults\n    this.options.maxSize = this.options.maxSize ?? Infinity\n    this.options.started = this.options.started ?? true\n    this.options.wait = this.options.wait ?? Infinity\n    this.options.getShouldExecute =\n      this.options.getShouldExecute ?? (() => false)\n  }\n\n  /**\n   * Number of items currently in the batch\n   */\n  get size(): number {\n    return this.items.length\n  }\n\n  /**\n   * Whether the batch has no items to process (items array is empty)\n   */\n  get isEmpty(): boolean {\n    return this.items.length === 0\n  }\n\n  /**\n   * Whether the batcher is waiting for the timeout to trigger batch processing\n   */\n  get isPending(): boolean {\n    return this._isPending\n  }\n\n  private getWait(): number {\n    if (typeof this.options.wait === 'function') {\n      return this.options.wait(this)\n    }\n    return this.options.wait!\n  }\n\n  /**\n   * Adds an item to the batcher\n   * If the batch size is reached, timeout occurs, or getShouldExecute returns true, the batch will be processed\n   */\n  addItem = (item: TValue): void => {\n    this.items.push(item)\n    this._isPending = this.options.wait !== Infinity\n    this.options.onItemsChange?.(this)\n\n    const shouldProcess =\n      this.items.length >= this.options.maxSize! ||\n      this.options.getShouldExecute!(this.items, this)\n\n    if (shouldProcess) {\n      this.execute()\n    } else if (this.options.wait !== Infinity) {\n      this.clearTimeout() // clear any pending timeout to replace it with a new one\n      this.timeoutId = setTimeout(() => this.execute(), this.getWait())\n    }\n  }\n\n  /**\n   * Processes the current batch of items.\n   * This method will automatically be triggered if the batcher is running and any of these conditions are met:\n   * - The number of items reaches maxSize\n   * - The wait duration has elapsed\n   * - The getShouldExecute function returns true upon adding an item\n   *\n   * You can also call this method manually to process the current batch at any time.\n   */\n  private execute = (): void => {\n    if (this.items.length === 0) {\n      return\n    }\n\n    const batch = this.peekAllItems() // copy of the items to be processed (to prevent race conditions)\n    this.clear() // Clear items before processing to prevent race conditions\n\n    this.fn(batch) // EXECUTE\n    this.options.onExecute?.(batch, this)\n  }\n\n  /**\n   * Processes the current batch of items immediately\n   */\n  flush = (): void => {\n    this.clearTimeout() // clear any pending timeout\n    this.execute() // execute immediately\n  }\n\n  /**\n   * Returns a copy of all items in the batcher\n   */\n  peekAllItems = (): Array<TValue> => {\n    return [...this.items]\n  }\n\n  private clearTimeout = (): void => {\n    if (this.timeoutId) {\n      clearTimeout(this.timeoutId)\n      this.timeoutId = null\n    }\n  }\n\n  /**\n   * Removes all items from the batcher\n   */\n  clear = (): void => {\n    const hadItems = this.items.length > 0\n    this.items = []\n    this._isPending = false\n    if (hadItems) {\n      this.options.onItemsChange?.(this)\n    }\n  }\n\n  /**\n   * Cancels any pending execution that was scheduled.\n   * Does NOT clear out the items.\n   */\n  cancel = (): void => {\n    this.clearTimeout()\n    this._isPending = false\n  }\n}\n\n/**\n * Creates a batcher that processes items in batches.\n *\n * This is an alternative to the batch function in the core @tanstack/pacer package, but is more\n * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,\n * this function creates a batcher with no external dependencies, devtools integration, or reactive state.\n *\n * @example\n * ```ts\n * const batchItems = liteBatch<number>(\n *   (items) => console.log('Processing:', items),\n *   {\n *     maxSize: 3,\n *   }\n * );\n *\n * batchItems(1);\n * batchItems(2);\n * batchItems(3); // Triggers batch processing\n * ```\n */\nexport function liteBatch<TValue>(\n  fn: (items: Array<TValue>) => void,\n  options: LiteBatcherOptions<TValue> = {},\n): (item: TValue) => void {\n  const batcher = new LiteBatcher<TValue>(fn, options)\n  return batcher.addItem\n}\n"],"names":[],"mappings":";;AA4GO,MAAM,YAAoB;AAAA,EAK/B,YACS,IACA,UAAsC,IAC7C;AAFO,SAAA,KAAA;AACA,SAAA,UAAA;AANT,SAAQ,QAAuB,CAAA;AAC/B,SAAQ,YAAmC;AAC3C,SAAQ,aAAa;AA8CrB,SAAA,UAAU,CAAC,SAAuB;AAChC,WAAK,MAAM,KAAK,IAAI;AACpB,WAAK,aAAa,KAAK,QAAQ,SAAS;AACxC,WAAK,QAAQ,gBAAgB,IAAI;AAEjC,YAAM,gBACJ,KAAK,MAAM,UAAU,KAAK,QAAQ,WAClC,KAAK,QAAQ,iBAAkB,KAAK,OAAO,IAAI;AAEjD,UAAI,eAAe;AACjB,aAAK,QAAA;AAAA,MACP,WAAW,KAAK,QAAQ,SAAS,UAAU;AACzC,aAAK,aAAA;AACL,aAAK,YAAY,WAAW,MAAM,KAAK,WAAW,KAAK,SAAS;AAAA,MAClE;AAAA,IACF;AAWA,SAAQ,UAAU,MAAY;AAC5B,UAAI,KAAK,MAAM,WAAW,GAAG;AAC3B;AAAA,MACF;AAEA,YAAM,QAAQ,KAAK,aAAA;AACnB,WAAK,MAAA;AAEL,WAAK,GAAG,KAAK;AACb,WAAK,QAAQ,YAAY,OAAO,IAAI;AAAA,IACtC;AAKA,SAAA,QAAQ,MAAY;AAClB,WAAK,aAAA;AACL,WAAK,QAAA;AAAA,IACP;AAKA,SAAA,eAAe,MAAqB;AAClC,aAAO,CAAC,GAAG,KAAK,KAAK;AAAA,IACvB;AAEA,SAAQ,eAAe,MAAY;AACjC,UAAI,KAAK,WAAW;AAClB,qBAAa,KAAK,SAAS;AAC3B,aAAK,YAAY;AAAA,MACnB;AAAA,IACF;AAKA,SAAA,QAAQ,MAAY;AAClB,YAAM,WAAW,KAAK,MAAM,SAAS;AACrC,WAAK,QAAQ,CAAA;AACb,WAAK,aAAa;AAClB,UAAI,UAAU;AACZ,aAAK,QAAQ,gBAAgB,IAAI;AAAA,MACnC;AAAA,IACF;AAMA,SAAA,SAAS,MAAY;AACnB,WAAK,aAAA;AACL,WAAK,aAAa;AAAA,IACpB;AAtHE,SAAK,QAAQ,UAAU,KAAK,QAAQ,WAAW;AAC/C,SAAK,QAAQ,UAAU,KAAK,QAAQ,WAAW;AAC/C,SAAK,QAAQ,OAAO,KAAK,QAAQ,QAAQ;AACzC,SAAK,QAAQ,mBACX,KAAK,QAAQ,qBAAqB,MAAM;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,OAAe;AACjB,WAAO,KAAK,MAAM;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,UAAmB;AACrB,WAAO,KAAK,MAAM,WAAW;AAAA,EAC/B;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,YAAqB;AACvB,WAAO,KAAK;AAAA,EACd;AAAA,EAEQ,UAAkB;AACxB,QAAI,OAAO,KAAK,QAAQ,SAAS,YAAY;AAC3C,aAAO,KAAK,QAAQ,KAAK,IAAI;AAAA,IAC/B;AACA,WAAO,KAAK,QAAQ;AAAA,EACtB;AAsFF;AAuBO,SAAS,UACd,IACA,UAAsC,IACd;AACxB,QAAM,UAAU,IAAI,YAAoB,IAAI,OAAO;AACnD,SAAO,QAAQ;AACjB;;;"}

package/dist/cjs/lite-batcher.d.cts

@@ -0,0 +1,180 @@
+/**
+ * Options for configuring a lite batcher instance
+ */
+export interface LiteBatcherOptions<TValue> {
+    /**
+     * Custom function to determine if a batch should be processed
+     * Return true to process the batch immediately
+     */
+    getShouldExecute?: (items: Array<TValue>, batcher: LiteBatcher<TValue>) => boolean;
+    /**
+     * Maximum number of items in a batch
+     * @default Infinity
+     */
+    maxSize?: number;
+    /**
+     * Callback fired after a batch is processed
+     */
+    onExecute?: (batch: Array<TValue>, batcher: LiteBatcher<TValue>) => void;
+    /**
+     * Callback fired after items are added to the batcher
+     */
+    onItemsChange?: (batcher: LiteBatcher<TValue>) => void;
+    /**
+     * Whether the batcher should start processing immediately
+     * @default true
+     */
+    started?: boolean;
+    /**
+     * Maximum time in milliseconds to wait before processing a batch.
+     * If the wait duration has elapsed, the batch will be processed.
+     * If not provided, the batch will not be triggered by a timeout.
+     * @default Infinity
+     */
+    wait?: number | ((batcher: LiteBatcher<TValue>) => number);
+}
+/**
+ * A lightweight class that collects items and processes them in batches.
+ *
+ * This is an alternative to the Batcher in the core @tanstack/pacer package, but is more
+ * suitable for libraries and npm packages that need minimal overhead. Unlike the core Batcher,
+ * this version does not use TanStack Store for state management, has no devtools integration,
+ * no callbacks, and provides only essential batching functionality.
+ *
+ * Batching is a technique for grouping multiple operations together to be processed as a single unit.
+ * This synchronous version is lighter weight and often all you need.
+ *
+ * The Batcher provides a flexible way to implement batching with configurable:
+ * - Maximum batch size (number of items per batch)
+ * - Time-based batching (process after X milliseconds)
+ * - Custom batch processing logic via getShouldExecute
+ *
+ * Features included:
+ * - Core batching functionality (addItem, flush, clear, cancel)
+ * - Size-based batching (maxSize)
+ * - Time-based batching (wait timeout)
+ * - Custom condition batching (getShouldExecute)
+ * - Manual processing controls
+ * - Public mutable options
+ * - Callback support for monitoring batch execution and state changes
+ *
+ * Features NOT included (compared to core Batcher):
+ * - No TanStack Store state management
+ * - No devtools integration
+ * - No complex state tracking (execution counts, etc.)
+ * - No reactive state management
+ *
+ * @example
+ * ```ts
+ * // Basic batching
+ * const batcher = new LiteBatcher<number>(
+ *   (items) => console.log('Processing batch:', items),
+ *   {
+ *     maxSize: 5,
+ *     wait: 2000,
+ *     onExecute: (batch, batcher) => {
+ *       console.log('Batch executed with', batch.length, 'items');
+ *     },
+ *     onItemsChange: (batcher) => {
+ *       console.log('Batch size changed to:', batcher.size);
+ *     }
+ *   }
+ * );
+ *
+ * batcher.addItem(1);
+ * batcher.addItem(2);
+ * // After 2 seconds or when 5 items are added, whichever comes first,
+ * // the batch will be processed
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Custom condition batching
+ * const batcher = new LiteBatcher<Task>(
+ *   (items) => processTasks(items),
+ *   {
+ *     getShouldExecute: (items) => items.some(task => task.urgent),
+ *     maxSize: 10,
+ *   }
+ * );
+ *
+ * batcher.addItem({ name: 'normal', urgent: false });
+ * batcher.addItem({ name: 'urgent', urgent: true }); // Triggers immediate processing
+ * ```
+ */
+export declare class LiteBatcher<TValue> {
+    fn: (items: Array<TValue>) => void;
+    options: LiteBatcherOptions<TValue>;
+    private items;
+    private timeoutId;
+    private _isPending;
+    constructor(fn: (items: Array<TValue>) => void, options?: LiteBatcherOptions<TValue>);
+    /**
+     * Number of items currently in the batch
+     */
+    get size(): number;
+    /**
+     * Whether the batch has no items to process (items array is empty)
+     */
+    get isEmpty(): boolean;
+    /**
+     * Whether the batcher is waiting for the timeout to trigger batch processing
+     */
+    get isPending(): boolean;
+    private getWait;
+    /**
+     * 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: TValue) => void;
+    /**
+     * 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.
+     */
+    private execute;
+    /**
+     * Processes the current batch of items immediately
+     */
+    flush: () => void;
+    /**
+     * Returns a copy of all items in the batcher
+     */
+    peekAllItems: () => Array<TValue>;
+    private clearTimeout;
+    /**
+     * Removes all items from the batcher
+     */
+    clear: () => void;
+    /**
+     * Cancels any pending execution that was scheduled.
+     * Does NOT clear out the items.
+     */
+    cancel: () => void;
+}
+/**
+ * Creates a batcher that processes items in batches.
+ *
+ * This is an alternative to the batch function in the core @tanstack/pacer package, but is more
+ * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,
+ * this function creates a batcher with no external dependencies, devtools integration, or reactive state.
+ *
+ * @example
+ * ```ts
+ * const batchItems = liteBatch<number>(
+ *   (items) => console.log('Processing:', items),
+ *   {
+ *     maxSize: 3,
+ *   }
+ * );
+ *
+ * batchItems(1);
+ * batchItems(2);
+ * batchItems(3); // Triggers batch processing
+ * ```
+ */
+export declare function liteBatch<TValue>(fn: (items: Array<TValue>) => void, options?: LiteBatcherOptions<TValue>): (item: TValue) => void;

package/dist/cjs/lite-debouncer.cjs

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class LiteDebouncer {
+  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;
+      }
+      this.lastArgs = void 0;
+      this.canLeadingExecute = true;
+    };
+    if (this.options.leading === void 0 && this.options.trailing === void 0) {
+      this.options.trailing = true;
+    }
+  }
+}
+function liteDebounce(fn, options) {
+  const debouncer = new LiteDebouncer(fn, options);
+  return debouncer.maybeExecute;
+}
+exports.LiteDebouncer = LiteDebouncer;
+exports.liteDebounce = liteDebounce;
+//# sourceMappingURL=lite-debouncer.cjs.map

package/dist/cjs/lite-debouncer.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lite-debouncer.cjs","sources":["../../src/lite-debouncer.ts"],"sourcesContent":["import type { AnyFunction } from '@tanstack/pacer/types'\n\n/**\n * Options for configuring a lite debounced function\n */\nexport interface LiteDebouncerOptions<TFn extends AnyFunction = AnyFunction> {\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * The first call will execute immediately and the rest will wait the delay.\n   * Defaults to false.\n   */\n  leading?: boolean\n  /**\n   * Callback function that is called after the function is executed\n   */\n  onExecute?: (args: Parameters<TFn>, debouncer: LiteDebouncer<TFn>) => void\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Delay in milliseconds before executing the function.\n   */\n  wait: number\n}\n\n/**\n * A lightweight class that creates a debounced function.\n *\n * This is an alternative to the Debouncer in the core @tanstack/pacer package, but is more\n * suitable for libraries and npm packages that need minimal overhead. Unlike the core Debouncer,\n * this version does not use TanStack Store for state management, has no devtools integration,\n * and provides only essential debouncing functionality.\n *\n * Debouncing ensures that a function is only executed after a certain amount of time has passed\n * since its last invocation. This is useful for handling frequent events like window resizing,\n * scroll events, or input changes where you want to limit the rate of execution.\n *\n * The debounced function can be configured to execute either at the start of the delay period\n * (leading edge) or at the end (trailing edge, default). Each new call during the wait period\n * will reset the timer.\n *\n * Features:\n * - Zero dependencies - no external libraries required\n * - Minimal API surface - only essential methods (maybeExecute, flush, cancel)\n * - Simple state management - uses basic private properties instead of reactive stores\n * - Callback support for monitoring execution events\n * - Lightweight - designed for use in npm packages where bundle size matters\n *\n * @example\n * ```ts\n * const debouncer = new LiteDebouncer((value: string) => {\n *   saveToDatabase(value);\n * }, {\n *   wait: 500,\n *   onExecute: (args, debouncer) => {\n *     console.log('Saved value:', args[0]);\n *   }\n * });\n *\n * // Will only save after 500ms of no new input\n * inputElement.addEventListener('input', () => {\n *   debouncer.maybeExecute(inputElement.value);\n * });\n * ```\n */\nexport class LiteDebouncer<TFn extends AnyFunction> {\n  private timeoutId: NodeJS.Timeout | undefined\n  private lastArgs: Parameters<TFn> | undefined\n  private canLeadingExecute = true\n\n  constructor(\n    public fn: TFn,\n    public options: LiteDebouncerOptions<TFn>,\n  ) {\n    // Default trailing to true if neither leading nor trailing is specified\n    if (\n      this.options.leading === undefined &&\n      this.options.trailing === undefined\n    ) {\n      this.options.trailing = true\n    }\n  }\n\n  /**\n   * Attempts to execute the debounced function.\n   * If leading is true and this is the first call, executes immediately.\n   * Otherwise, queues the execution for after the wait time.\n   * Each new call resets the timer.\n   */\n  maybeExecute = (...args: Parameters<TFn>): void => {\n    let didLeadingExecute = false\n\n    if (this.options.leading && this.canLeadingExecute) {\n      this.canLeadingExecute = false\n      didLeadingExecute = true\n      this.fn(...args)\n      this.options.onExecute?.(args, this)\n    }\n\n    this.lastArgs = args\n\n    if (this.timeoutId) {\n      clearTimeout(this.timeoutId)\n    }\n\n    this.timeoutId = setTimeout(() => {\n      this.canLeadingExecute = true\n      if (this.options.trailing && !didLeadingExecute && this.lastArgs) {\n        this.fn(...this.lastArgs)\n        this.options.onExecute?.(this.lastArgs, this)\n      }\n      this.lastArgs = undefined\n    }, this.options.wait)\n  }\n\n  /**\n   * Processes the current pending execution immediately.\n   * If there's a pending execution, it will be executed right away\n   * and the timeout will be cleared.\n   */\n  flush = (): void => {\n    if (this.timeoutId && this.lastArgs) {\n      clearTimeout(this.timeoutId)\n      this.timeoutId = undefined\n      const args = this.lastArgs\n      this.fn(...args)\n      this.options.onExecute?.(args, this)\n      this.lastArgs = undefined\n      this.canLeadingExecute = true\n    }\n  }\n\n  /**\n   * Cancels any pending execution.\n   * Clears the timeout and resets the internal state.\n   */\n  cancel = (): void => {\n    if (this.timeoutId) {\n      clearTimeout(this.timeoutId)\n      this.timeoutId = undefined\n    }\n    this.lastArgs = undefined\n    this.canLeadingExecute = true\n  }\n}\n\n/**\n * Creates a lightweight debounced function that delays invoking the provided function until after a specified wait time.\n * Multiple calls during the wait period will cancel previous pending invocations and reset the timer.\n *\n * This is an alternative to the debounce function in the core @tanstack/pacer package, but is more\n * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,\n * this function creates a debouncer with no external dependencies, devtools integration, or reactive state.\n *\n * If leading option is true, the function will execute immediately on the first call, then wait the delay\n * before allowing another execution.\n *\n * @example\n * ```ts\n * const debouncedSave = liteDebounce(() => {\n *   saveChanges();\n * }, { wait: 1000 });\n *\n * // Called repeatedly but executes at most once per second\n * inputElement.addEventListener('input', debouncedSave);\n * ```\n *\n * @example\n * ```ts\n * // Leading edge execution - fires immediately then waits\n * const debouncedSearch = liteDebounce((query: string) => {\n *   performSearch(query);\n * }, { wait: 300, leading: true });\n * ```\n */\nexport function liteDebounce<TFn extends AnyFunction>(\n  fn: TFn,\n  options: LiteDebouncerOptions<TFn>,\n): (...args: Parameters<TFn>) => void {\n  const debouncer = new LiteDebouncer(fn, options)\n  return debouncer.maybeExecute\n}\n"],"names":[],"mappings":";;AAmEO,MAAM,cAAuC;AAAA,EAKlD,YACS,IACA,SACP;AAFO,SAAA,KAAA;AACA,SAAA,UAAA;AAJT,SAAQ,oBAAoB;AAqB5B,SAAA,eAAe,IAAI,SAAgC;AACjD,UAAI,oBAAoB;AAExB,UAAI,KAAK,QAAQ,WAAW,KAAK,mBAAmB;AAClD,aAAK,oBAAoB;AACzB,4BAAoB;AACpB,aAAK,GAAG,GAAG,IAAI;AACf,aAAK,QAAQ,YAAY,MAAM,IAAI;AAAA,MACrC;AAEA,WAAK,WAAW;AAEhB,UAAI,KAAK,WAAW;AAClB,qBAAa,KAAK,SAAS;AAAA,MAC7B;AAEA,WAAK,YAAY,WAAW,MAAM;AAChC,aAAK,oBAAoB;AACzB,YAAI,KAAK,QAAQ,YAAY,CAAC,qBAAqB,KAAK,UAAU;AAChE,eAAK,GAAG,GAAG,KAAK,QAAQ;AACxB,eAAK,QAAQ,YAAY,KAAK,UAAU,IAAI;AAAA,QAC9C;AACA,aAAK,WAAW;AAAA,MAClB,GAAG,KAAK,QAAQ,IAAI;AAAA,IACtB;AAOA,SAAA,QAAQ,MAAY;AAClB,UAAI,KAAK,aAAa,KAAK,UAAU;AACnC,qBAAa,KAAK,SAAS;AAC3B,aAAK,YAAY;AACjB,cAAM,OAAO,KAAK;AAClB,aAAK,GAAG,GAAG,IAAI;AACf,aAAK,QAAQ,YAAY,MAAM,IAAI;AACnC,aAAK,WAAW;AAChB,aAAK,oBAAoB;AAAA,MAC3B;AAAA,IACF;AAMA,SAAA,SAAS,MAAY;AACnB,UAAI,KAAK,WAAW;AAClB,qBAAa,KAAK,SAAS;AAC3B,aAAK,YAAY;AAAA,MACnB;AACA,WAAK,WAAW;AAChB,WAAK,oBAAoB;AAAA,IAC3B;AApEE,QACE,KAAK,QAAQ,YAAY,UACzB,KAAK,QAAQ,aAAa,QAC1B;AACA,WAAK,QAAQ,WAAW;AAAA,IAC1B;AAAA,EACF;AA+DF;AA+BO,SAAS,aACd,IACA,SACoC;AACpC,QAAM,YAAY,IAAI,cAAc,IAAI,OAAO;AAC/C,SAAO,UAAU;AACnB;;;"}