@tanstack/preact-pacer 0.0.1 → 0.18.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

@@ -1,45 +1,165 @@
-# @tanstack/preact-pacer
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@tanstack/preact-pacer`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+<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/preact-pacer@latest" target="\_parent">
+  <img alt="" src="https://badgen.net/bundlephobia/minzip/@tanstack/preact-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/async-batcher/index.cjs

@@ -0,0 +1,12 @@
+const require_useAsyncBatcher = require('./useAsyncBatcher.cjs');
+const require_useAsyncBatchedCallback = require('./useAsyncBatchedCallback.cjs');
+
+exports.useAsyncBatchedCallback = require_useAsyncBatchedCallback.useAsyncBatchedCallback;
+exports.useAsyncBatcher = require_useAsyncBatcher.useAsyncBatcher;
+var __tanstack_pacer_async_batcher = require("@tanstack/pacer/async-batcher");
+Object.keys(__tanstack_pacer_async_batcher).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return __tanstack_pacer_async_batcher[k]; }
+  });
+});

package/dist/async-batcher/index.d.cts

@@ -0,0 +1,4 @@
+import { ReactAsyncBatcher, useAsyncBatcher } from "./useAsyncBatcher.cjs";
+import { useAsyncBatchedCallback } from "./useAsyncBatchedCallback.cjs";
+export * from "@tanstack/pacer/async-batcher";
+export { ReactAsyncBatcher, useAsyncBatchedCallback, useAsyncBatcher };

package/dist/async-batcher/index.d.ts

@@ -0,0 +1,4 @@
+import { ReactAsyncBatcher, useAsyncBatcher } from "./useAsyncBatcher.js";
+import { useAsyncBatchedCallback } from "./useAsyncBatchedCallback.js";
+export * from "@tanstack/pacer/async-batcher";
+export { ReactAsyncBatcher, useAsyncBatchedCallback, useAsyncBatcher };

package/dist/async-batcher/index.js

@@ -0,0 +1,6 @@
+import { useAsyncBatcher } from "./useAsyncBatcher.js";
+import { useAsyncBatchedCallback } from "./useAsyncBatchedCallback.js";
+
+export * from "@tanstack/pacer/async-batcher"
+
+export { useAsyncBatchedCallback, useAsyncBatcher };

package/dist/async-batcher/useAsyncBatchedCallback.cjs

@@ -0,0 +1,51 @@
+const require_useAsyncBatcher = require('./useAsyncBatcher.cjs');
+let preact_hooks = require("preact/hooks");
+
+//#region src/async-batcher/useAsyncBatchedCallback.ts
+/**
+* A Preact hook that creates a batched version of an async callback function.
+* This hook is a convenient wrapper around the `useAsyncBatcher` hook,
+* providing a stable, batched async function reference for use in Preact components.
+*
+* The batched async function will collect individual calls into batches and execute them
+* when batch conditions are met (max size reached, wait time elapsed, or custom logic).
+* The returned function always returns a promise that resolves with undefined (since the
+* batch function processes multiple items together).
+*
+* This hook provides a simpler API compared to `useAsyncBatcher`, making it ideal for basic
+* async batching needs. However, it does not expose the underlying AsyncBatcher instance.
+*
+* For advanced usage requiring features like:
+* - Manual batch execution
+* - Access to batch results and state
+* - Custom useCallback dependencies
+*
+* Consider using the `useAsyncBatcher` hook instead.
+*
+* @example
+* ```tsx
+* // Batch API requests
+* const batchApiCall = useAsyncBatchedCallback(async (requests: ApiRequest[]) => {
+*   const results = await Promise.all(requests.map(req => fetch(req.url)));
+*   return results.map(res => res.json());
+* }, {
+*   maxSize: 10,   // Process when 10 requests collected
+*   wait: 1000     // Or after 1 second
+* });
+*
+* // Use in event handlers
+* <button onClick={() => batchApiCall({ url: '/api/analytics', data: eventData })}>
+*   Track Event
+* </button>
+* ```
+*/
+function useAsyncBatchedCallback(fn, options) {
+	const asyncBatchedFn = require_useAsyncBatcher.useAsyncBatcher(fn, options).addItem;
+	return (0, preact_hooks.useCallback)(async (...args) => {
+		asyncBatchedFn(args[0]);
+	}, [asyncBatchedFn]);
+}
+
+//#endregion
+exports.useAsyncBatchedCallback = useAsyncBatchedCallback;
+//# sourceMappingURL=useAsyncBatchedCallback.cjs.map

package/dist/async-batcher/useAsyncBatchedCallback.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAsyncBatchedCallback.cjs","names":["useAsyncBatcher"],"sources":["../../src/async-batcher/useAsyncBatchedCallback.ts"],"sourcesContent":["import { useCallback } from 'preact/hooks'\nimport { useAsyncBatcher } from './useAsyncBatcher'\nimport type { AsyncBatcherOptions } from '@tanstack/pacer/async-batcher'\nimport type { AnyAsyncFunction } from '@tanstack/pacer/types'\n\n/**\n * A Preact hook that creates a batched version of an async callback function.\n * This hook is a convenient wrapper around the `useAsyncBatcher` hook,\n * providing a stable, batched async function reference for use in Preact components.\n *\n * The batched async function will collect individual calls into batches and execute them\n * when batch conditions are met (max size reached, wait time elapsed, or custom logic).\n * The returned function always returns a promise that resolves with undefined (since the\n * batch function processes multiple items together).\n *\n * This hook provides a simpler API compared to `useAsyncBatcher`, making it ideal for basic\n * async batching needs. However, it does not expose the underlying AsyncBatcher instance.\n *\n * For advanced usage requiring features like:\n * - Manual batch execution\n * - Access to batch results and state\n * - Custom useCallback dependencies\n *\n * Consider using the `useAsyncBatcher` hook instead.\n *\n * @example\n * ```tsx\n * // Batch API requests\n * const batchApiCall = useAsyncBatchedCallback(async (requests: ApiRequest[]) => {\n *   const results = await Promise.all(requests.map(req => fetch(req.url)));\n *   return results.map(res => res.json());\n * }, {\n *   maxSize: 10,   // Process when 10 requests collected\n *   wait: 1000     // Or after 1 second\n * });\n *\n * // Use in event handlers\n * <button onClick={() => batchApiCall({ url: '/api/analytics', data: eventData })}>\n *   Track Event\n * </button>\n * ```\n */\nexport function useAsyncBatchedCallback<TFn extends AnyAsyncFunction>(\n  fn: (items: Array<Parameters<TFn>[0]>) => Promise<any>,\n  options: AsyncBatcherOptions<Parameters<TFn>[0]>,\n): (...args: Parameters<TFn>) => Promise<void> {\n  const asyncBatchedFn = useAsyncBatcher(fn, options).addItem\n  return useCallback(\n    async (...args: Parameters<TFn>) => {\n      asyncBatchedFn(args[0])\n    },\n    [asyncBatchedFn],\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,wBACd,IACA,SAC6C;CAC7C,MAAM,iBAAiBA,wCAAgB,IAAI,QAAQ,CAAC;AACpD,sCACE,OAAO,GAAG,SAA0B;AAClC,iBAAe,KAAK,GAAG;IAEzB,CAAC,eAAe,CACjB"}

package/dist/async-batcher/useAsyncBatchedCallback.d.cts

@@ -0,0 +1,46 @@
+import { AsyncBatcherOptions } from "@tanstack/pacer/async-batcher";
+import { AnyAsyncFunction } from "@tanstack/pacer/types";
+
+//#region src/async-batcher/useAsyncBatchedCallback.d.ts
+
+/**
+ * A Preact hook that creates a batched version of an async callback function.
+ * This hook is a convenient wrapper around the `useAsyncBatcher` hook,
+ * providing a stable, batched async function reference for use in Preact components.
+ *
+ * The batched async function will collect individual calls into batches and execute them
+ * when batch conditions are met (max size reached, wait time elapsed, or custom logic).
+ * The returned function always returns a promise that resolves with undefined (since the
+ * batch function processes multiple items together).
+ *
+ * This hook provides a simpler API compared to `useAsyncBatcher`, making it ideal for basic
+ * async batching needs. However, it does not expose the underlying AsyncBatcher instance.
+ *
+ * For advanced usage requiring features like:
+ * - Manual batch execution
+ * - Access to batch results and state
+ * - Custom useCallback dependencies
+ *
+ * Consider using the `useAsyncBatcher` hook instead.
+ *
+ * @example
+ * ```tsx
+ * // Batch API requests
+ * const batchApiCall = useAsyncBatchedCallback(async (requests: ApiRequest[]) => {
+ *   const results = await Promise.all(requests.map(req => fetch(req.url)));
+ *   return results.map(res => res.json());
+ * }, {
+ *   maxSize: 10,   // Process when 10 requests collected
+ *   wait: 1000     // Or after 1 second
+ * });
+ *
+ * // Use in event handlers
+ * <button onClick={() => batchApiCall({ url: '/api/analytics', data: eventData })}>
+ *   Track Event
+ * </button>
+ * ```
+ */
+declare function useAsyncBatchedCallback<TFn extends AnyAsyncFunction>(fn: (items: Array<Parameters<TFn>[0]>) => Promise<any>, options: AsyncBatcherOptions<Parameters<TFn>[0]>): (...args: Parameters<TFn>) => Promise<void>;
+//#endregion
+export { useAsyncBatchedCallback };
+//# sourceMappingURL=useAsyncBatchedCallback.d.cts.map

package/dist/async-batcher/useAsyncBatchedCallback.d.ts

@@ -0,0 +1,46 @@
+import { AsyncBatcherOptions } from "@tanstack/pacer/async-batcher";
+import { AnyAsyncFunction } from "@tanstack/pacer/types";
+
+//#region src/async-batcher/useAsyncBatchedCallback.d.ts
+
+/**
+ * A Preact hook that creates a batched version of an async callback function.
+ * This hook is a convenient wrapper around the `useAsyncBatcher` hook,
+ * providing a stable, batched async function reference for use in Preact components.
+ *
+ * The batched async function will collect individual calls into batches and execute them
+ * when batch conditions are met (max size reached, wait time elapsed, or custom logic).
+ * The returned function always returns a promise that resolves with undefined (since the
+ * batch function processes multiple items together).
+ *
+ * This hook provides a simpler API compared to `useAsyncBatcher`, making it ideal for basic
+ * async batching needs. However, it does not expose the underlying AsyncBatcher instance.
+ *
+ * For advanced usage requiring features like:
+ * - Manual batch execution
+ * - Access to batch results and state
+ * - Custom useCallback dependencies
+ *
+ * Consider using the `useAsyncBatcher` hook instead.
+ *
+ * @example
+ * ```tsx
+ * // Batch API requests
+ * const batchApiCall = useAsyncBatchedCallback(async (requests: ApiRequest[]) => {
+ *   const results = await Promise.all(requests.map(req => fetch(req.url)));
+ *   return results.map(res => res.json());
+ * }, {
+ *   maxSize: 10,   // Process when 10 requests collected
+ *   wait: 1000     // Or after 1 second
+ * });
+ *
+ * // Use in event handlers
+ * <button onClick={() => batchApiCall({ url: '/api/analytics', data: eventData })}>
+ *   Track Event
+ * </button>
+ * ```
+ */
+declare function useAsyncBatchedCallback<TFn extends AnyAsyncFunction>(fn: (items: Array<Parameters<TFn>[0]>) => Promise<any>, options: AsyncBatcherOptions<Parameters<TFn>[0]>): (...args: Parameters<TFn>) => Promise<void>;
+//#endregion
+export { useAsyncBatchedCallback };
+//# sourceMappingURL=useAsyncBatchedCallback.d.ts.map

package/dist/async-batcher/useAsyncBatchedCallback.js

@@ -0,0 +1,51 @@
+import { useAsyncBatcher } from "./useAsyncBatcher.js";
+import { useCallback } from "preact/hooks";
+
+//#region src/async-batcher/useAsyncBatchedCallback.ts
+/**
+* A Preact hook that creates a batched version of an async callback function.
+* This hook is a convenient wrapper around the `useAsyncBatcher` hook,
+* providing a stable, batched async function reference for use in Preact components.
+*
+* The batched async function will collect individual calls into batches and execute them
+* when batch conditions are met (max size reached, wait time elapsed, or custom logic).
+* The returned function always returns a promise that resolves with undefined (since the
+* batch function processes multiple items together).
+*
+* This hook provides a simpler API compared to `useAsyncBatcher`, making it ideal for basic
+* async batching needs. However, it does not expose the underlying AsyncBatcher instance.
+*
+* For advanced usage requiring features like:
+* - Manual batch execution
+* - Access to batch results and state
+* - Custom useCallback dependencies
+*
+* Consider using the `useAsyncBatcher` hook instead.
+*
+* @example
+* ```tsx
+* // Batch API requests
+* const batchApiCall = useAsyncBatchedCallback(async (requests: ApiRequest[]) => {
+*   const results = await Promise.all(requests.map(req => fetch(req.url)));
+*   return results.map(res => res.json());
+* }, {
+*   maxSize: 10,   // Process when 10 requests collected
+*   wait: 1000     // Or after 1 second
+* });
+*
+* // Use in event handlers
+* <button onClick={() => batchApiCall({ url: '/api/analytics', data: eventData })}>
+*   Track Event
+* </button>
+* ```
+*/
+function useAsyncBatchedCallback(fn, options) {
+	const asyncBatchedFn = useAsyncBatcher(fn, options).addItem;
+	return useCallback(async (...args) => {
+		asyncBatchedFn(args[0]);
+	}, [asyncBatchedFn]);
+}
+
+//#endregion
+export { useAsyncBatchedCallback };
+//# sourceMappingURL=useAsyncBatchedCallback.js.map

package/dist/async-batcher/useAsyncBatchedCallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAsyncBatchedCallback.js","names":[],"sources":["../../src/async-batcher/useAsyncBatchedCallback.ts"],"sourcesContent":["import { useCallback } from 'preact/hooks'\nimport { useAsyncBatcher } from './useAsyncBatcher'\nimport type { AsyncBatcherOptions } from '@tanstack/pacer/async-batcher'\nimport type { AnyAsyncFunction } from '@tanstack/pacer/types'\n\n/**\n * A Preact hook that creates a batched version of an async callback function.\n * This hook is a convenient wrapper around the `useAsyncBatcher` hook,\n * providing a stable, batched async function reference for use in Preact components.\n *\n * The batched async function will collect individual calls into batches and execute them\n * when batch conditions are met (max size reached, wait time elapsed, or custom logic).\n * The returned function always returns a promise that resolves with undefined (since the\n * batch function processes multiple items together).\n *\n * This hook provides a simpler API compared to `useAsyncBatcher`, making it ideal for basic\n * async batching needs. However, it does not expose the underlying AsyncBatcher instance.\n *\n * For advanced usage requiring features like:\n * - Manual batch execution\n * - Access to batch results and state\n * - Custom useCallback dependencies\n *\n * Consider using the `useAsyncBatcher` hook instead.\n *\n * @example\n * ```tsx\n * // Batch API requests\n * const batchApiCall = useAsyncBatchedCallback(async (requests: ApiRequest[]) => {\n *   const results = await Promise.all(requests.map(req => fetch(req.url)));\n *   return results.map(res => res.json());\n * }, {\n *   maxSize: 10,   // Process when 10 requests collected\n *   wait: 1000     // Or after 1 second\n * });\n *\n * // Use in event handlers\n * <button onClick={() => batchApiCall({ url: '/api/analytics', data: eventData })}>\n *   Track Event\n * </button>\n * ```\n */\nexport function useAsyncBatchedCallback<TFn extends AnyAsyncFunction>(\n  fn: (items: Array<Parameters<TFn>[0]>) => Promise<any>,\n  options: AsyncBatcherOptions<Parameters<TFn>[0]>,\n): (...args: Parameters<TFn>) => Promise<void> {\n  const asyncBatchedFn = useAsyncBatcher(fn, options).addItem\n  return useCallback(\n    async (...args: Parameters<TFn>) => {\n      asyncBatchedFn(args[0])\n    },\n    [asyncBatchedFn],\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,wBACd,IACA,SAC6C;CAC7C,MAAM,iBAAiB,gBAAgB,IAAI,QAAQ,CAAC;AACpD,QAAO,YACL,OAAO,GAAG,SAA0B;AAClC,iBAAe,KAAK,GAAG;IAEzB,CAAC,eAAe,CACjB"}

package/dist/async-batcher/useAsyncBatcher.cjs

@@ -0,0 +1,165 @@
+const require_PacerProvider = require('../provider/PacerProvider.cjs');
+let preact_hooks = require("preact/hooks");
+let __tanstack_pacer_async_batcher = require("@tanstack/pacer/async-batcher");
+let __tanstack_preact_store = require("@tanstack/preact-store");
+
+//#region src/async-batcher/useAsyncBatcher.ts
+/**
+* A Preact hook that creates an `AsyncBatcher` instance for managing asynchronous batches of items.
+*
+* This is the async version of the useBatcher hook. Unlike the sync version, this async batcher:
+* - Handles promises and returns results from batch executions
+* - Provides error handling with configurable error behavior
+* - Tracks success, error, and settle counts separately
+* - Has state tracking for when batches are executing
+* - Returns the result of the batch function execution
+*
+* Features:
+* - Configurable batch size and wait time
+* - Custom batch processing logic via getShouldExecute
+* - Event callbacks for monitoring batch operations
+* - Error handling for failed batch operations
+* - Automatic or manual batch processing
+*
+* The batcher collects items and processes them in batches based on:
+* - Maximum batch size (number of items per batch)
+* - Time-based batching (process after X milliseconds)
+* - Custom batch processing logic via getShouldExecute
+*
+* Error Handling:
+* - If an `onError` handler is provided, it will be called with the error and batcher instance
+* - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+* - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+* - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+* - The error state can be checked using the underlying AsyncBatcher instance
+*
+* ## State Management and Selector
+*
+* The hook uses TanStack Store for reactive state management. The `selector` parameter allows you
+* to specify which state changes will trigger a re-render, optimizing performance by preventing
+* unnecessary re-renders when irrelevant state changes occur.
+*
+* **By default, there will be no reactive state subscriptions** and you must opt-in to state
+* tracking by providing a selector function. This prevents unnecessary re-renders and gives you
+* full control over when your component updates. Only when you provide a selector will the
+* component re-render when the selected state values change.
+*
+* Available state properties:
+* - `errorCount`: Number of batch executions that have resulted in errors
+* - `failedItems`: Array of items that failed during batch processing
+* - `isEmpty`: Whether the batcher has no items to process
+* - `isExecuting`: Whether a batch is currently being processed asynchronously
+* - `isPending`: Whether the batcher is waiting for the timeout to trigger batch processing
+* - `isRunning`: Whether the batcher is active and will process items automatically
+* - `items`: Array of items currently queued for batch processing
+* - `lastResult`: The result from the most recent batch execution
+* - `settleCount`: Number of batch executions that have completed (success or error)
+* - `size`: Number of items currently in the batch queue
+* - `status`: Current processing status ('idle' | 'pending' | 'executing' | 'populated')
+* - `successCount`: Number of batch executions that have completed successfully
+* - `totalItemsProcessed`: Total number of items processed across all batches
+* - `totalItemsFailed`: Total number of items that have failed processing
+*
+* @example
+* ```tsx
+* // Basic async batcher for API requests - no reactive state subscriptions
+* const asyncBatcher = useAsyncBatcher(
+*   async (items) => {
+*     const results = await Promise.all(items.map(item => processItem(item)));
+*     return results;
+*   },
+*   { maxSize: 10, wait: 2000 }
+* );
+*
+* // Opt-in to re-render when execution state changes (optimized for loading indicators)
+* const asyncBatcher = useAsyncBatcher(
+*   async (items) => {
+*     const results = await Promise.all(items.map(item => processItem(item)));
+*     return results;
+*   },
+*   { maxSize: 10, wait: 2000 },
+*   (state) => ({
+*     isExecuting: state.isExecuting,
+*     isPending: state.isPending,
+*     status: state.status
+*   })
+* );
+*
+* // Opt-in to re-render when results are available (optimized for data display)
+* const asyncBatcher = useAsyncBatcher(
+*   async (items) => {
+*     const results = await Promise.all(items.map(item => processItem(item)));
+*     return results;
+*   },
+*   { maxSize: 10, wait: 2000 },
+*   (state) => ({
+*     lastResult: state.lastResult,
+*     successCount: state.successCount,
+*     totalItemsProcessed: state.totalItemsProcessed
+*   })
+* );
+*
+* // Opt-in to re-render when error state changes (optimized for error handling)
+* const asyncBatcher = useAsyncBatcher(
+*   async (items) => {
+*     const results = await Promise.all(items.map(item => processItem(item)));
+*     return results;
+*   },
+*   {
+*     maxSize: 10,
+*     wait: 2000,
+*     onError: (error) => console.error('Batch processing failed:', error)
+*   },
+*   (state) => ({
+*     errorCount: state.errorCount,
+*     failedItems: state.failedItems,
+*     totalItemsFailed: state.totalItemsFailed
+*   })
+* );
+*
+* // Complete example with all callbacks
+* const asyncBatcher = useAsyncBatcher(
+*   async (items) => {
+*     const results = await Promise.all(items.map(item => processItem(item)));
+*     return results;
+*   },
+*   {
+*     maxSize: 10,
+*     wait: 2000,
+*     onSuccess: (result) => {
+*       console.log('Batch processed successfully:', result);
+*     },
+*     onError: (error) => {
+*       console.error('Batch processing failed:', error);
+*     }
+*   }
+* );
+*
+* // Add items to batch
+* asyncBatcher.addItem(newItem);
+*
+* // Manually execute batch
+* const result = await asyncBatcher.execute();
+*
+* // Access the selected state (will be empty object {} unless selector provided)
+* const { isExecuting, lastResult, size } = asyncBatcher.state;
+* ```
+*/
+function useAsyncBatcher(fn, options = {}, selector = () => ({})) {
+	const mergedOptions = {
+		...require_PacerProvider.useDefaultPacerOptions().asyncBatcher,
+		...options
+	};
+	const [asyncBatcher] = (0, preact_hooks.useState)(() => new __tanstack_pacer_async_batcher.AsyncBatcher(fn, mergedOptions));
+	asyncBatcher.fn = fn;
+	asyncBatcher.setOptions(mergedOptions);
+	const state = (0, __tanstack_preact_store.useStore)(asyncBatcher.store, selector);
+	return (0, preact_hooks.useMemo)(() => ({
+		...asyncBatcher,
+		state
+	}), [asyncBatcher, state]);
+}
+
+//#endregion
+exports.useAsyncBatcher = useAsyncBatcher;
+//# sourceMappingURL=useAsyncBatcher.cjs.map