@octanejs/tanstack-pacer 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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,9 @@
+# @octanejs/tanstack-pacer
+
+Octane port of `@tanstack/react-pacer` — debouncing, throttling, rate
+limiting, queuing, batching, and their async variants. Re-exports the
+framework-agnostic `@tanstack/pacer` core unchanged and implements every
+upstream hook family (`useDebouncer`/`useDebouncedState`/`useDebouncedValue`/
+`useDebouncedCallback`, throttler, rate-limiter, queuer, batcher, and the
+async families) plus `PacerProvider` on Octane hooks, with store
+subscriptions via `@octanejs/tanstack-store`.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@octanejs/tanstack-pacer",
+  "version": "0.0.5",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "TanStack Pacer bindings for Octane — debouncing, throttling, rate limiting, queuing, and batching hooks over the framework-agnostic @tanstack/pacer core.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tanstack-pacer"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./async-batcher": "./src/async-batcher/index.ts",
+    "./async-debouncer": "./src/async-debouncer/index.ts",
+    "./async-queuer": "./src/async-queuer/index.ts",
+    "./async-rate-limiter": "./src/async-rate-limiter/index.ts",
+    "./async-retryer": "./src/async-retryer/index.ts",
+    "./async-throttler": "./src/async-throttler/index.ts",
+    "./batcher": "./src/batcher/index.ts",
+    "./debouncer": "./src/debouncer/index.ts",
+    "./provider": "./src/provider/index.ts",
+    "./queuer": "./src/queuer/index.ts",
+    "./rate-limiter": "./src/rate-limiter/index.ts",
+    "./throttler": "./src/throttler/index.ts",
+    "./types": "./src/types/index.ts",
+    "./utils": "./src/utils/index.ts"
+  },
+  "dependencies": {
+    "@tanstack/pacer": "0.21.1"
+  },
+  "peerDependencies": {
+    "@octanejs/tanstack-store": "0.0.10",
+    "octane": "0.1.16"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "octane": "0.1.16",
+    "@octanejs/tanstack-store": "0.0.10"
+  },
+  "scripts": {
+    "test": "vitest run --project tanstack-pacer",
+    "typecheck": "tsrx-tsc --noEmit"
+  }
+}

package/src/async-batcher/index.ts

@@ -0,0 +1,5 @@
+// re-export everything from the core pacer package, BUT ONLY from the async-batcher module
+export * from '@tanstack/pacer/async-batcher';
+
+export * from './useAsyncBatcher';
+export * from './useAsyncBatchedCallback';

package/src/async-batcher/useAsyncBatchedCallback.ts

@@ -0,0 +1,20 @@
+import { useCallback } from 'octane';
+import { useAsyncBatcher } from './useAsyncBatcher';
+import type { ReactAsyncBatcherOptions } from './useAsyncBatcher';
+
+/**
+ * An Octane hook that creates a batched version of an async callback
+ * function. Calling the returned function adds the item to the batch.
+ *
+ * @example
+ * ```tsx
+ * const addToBatch = useAsyncBatchedCallback(processBatch, { maxSize: 10 });
+ * ```
+ */
+export function useAsyncBatchedCallback<TValue>(
+	fn: (items: Array<TValue>) => Promise<unknown>,
+	options: ReactAsyncBatcherOptions<TValue, {}>,
+): (item: TValue) => Promise<void> {
+	const asyncBatchedFn = useAsyncBatcher(fn, options).addItem;
+	return useCallback((item: TValue) => asyncBatchedFn(item), [asyncBatchedFn]);
+}

package/src/async-batcher/useAsyncBatcher.ts

@@ -0,0 +1,116 @@
+import { useEffect, useMemo, useState } from 'octane';
+import { AsyncBatcher } from '@tanstack/pacer/async-batcher';
+import { shallow } from '@octanejs/tanstack-store';
+import { useDefaultPacerOptions } from '../provider/context';
+import { useSelectorSlot } from '../internal';
+import type { Store } from '@octanejs/tanstack-store';
+import type { AsyncBatcherOptions, AsyncBatcherState } from '@tanstack/pacer/async-batcher';
+
+const subscribeSlot = Symbol.for('@octanejs/tanstack-pacer:useAsyncBatcher:Subscribe');
+const stateSlot = Symbol.for('@octanejs/tanstack-pacer:useAsyncBatcher:state');
+
+export interface ReactAsyncBatcherOptions<
+	TValue,
+	TSelected = {},
+> extends AsyncBatcherOptions<TValue> {
+	/**
+	 * Custom unmount behavior. Defaults to cancelling any pending batch and
+	 * aborting in-flight executions.
+	 */
+	onUnmount?: (batcher: ReactAsyncBatcher<TValue, TSelected>) => void;
+}
+
+export interface ReactAsyncBatcher<TValue, TSelected = {}> extends Omit<
+	AsyncBatcher<TValue>,
+	'store'
+> {
+	/**
+	 * Render-prop component subscribing to a slice of the batcher's state.
+	 */
+	Subscribe: <TSelected>(props: {
+		selector: (state: AsyncBatcherState<TValue>) => TSelected;
+		children: ((state: TSelected) => unknown) | unknown;
+	}) => unknown;
+	/**
+	 * Reactive state selected by the hook's `selector` (empty object without one).
+	 */
+	readonly state: Readonly<TSelected>;
+	/**
+	 * The underlying TanStack Store instance.
+	 */
+	readonly store: Store<Readonly<AsyncBatcherState<TValue>>>;
+}
+
+/**
+ * An Octane hook that creates and manages an AsyncBatcher instance — collects
+ * items and processes them together through an async function.
+ *
+ * **By default there are no reactive state subscriptions** — opt in by
+ * providing a `selector`; only then does the component re-render when the
+ * selected state values change.
+ *
+ * @example
+ * ```tsx
+ * const batcher = useAsyncBatcher(processBatch, { maxSize: 10, wait: 2000 });
+ * ```
+ */
+export function useAsyncBatcher<TValue, TSelected = {}>(
+	fn: (items: Array<TValue>) => Promise<any>,
+	options: ReactAsyncBatcherOptions<TValue, TSelected> = {},
+	selector: (state: AsyncBatcherState<TValue>) => TSelected = () => ({}) as TSelected,
+): ReactAsyncBatcher<TValue, TSelected> {
+	const mergedOptions = {
+		...useDefaultPacerOptions().asyncBatcher,
+		...options,
+	} as ReactAsyncBatcherOptions<TValue, TSelected>;
+	const [asyncBatcher] = useState(() => {
+		const asyncBatcherInstance = new AsyncBatcher<TValue>(
+			fn,
+			mergedOptions,
+		) as unknown as ReactAsyncBatcher<TValue, TSelected>;
+
+		asyncBatcherInstance.Subscribe = function Subscribe<TSelected>(props: {
+			selector: (state: AsyncBatcherState<TValue>) => TSelected;
+			children: ((state: TSelected) => unknown) | unknown;
+		}) {
+			const selected = useSelectorSlot(
+				asyncBatcherInstance.store,
+				props.selector,
+				{ compare: shallow },
+				subscribeSlot,
+			);
+
+			return typeof props.children === 'function'
+				? (props.children as (state: TSelected) => unknown)(selected)
+				: props.children;
+		};
+
+		return asyncBatcherInstance;
+	});
+
+	asyncBatcher.fn = fn;
+	asyncBatcher.setOptions(mergedOptions);
+
+	// Unmount cleanup only; empty deps keep teardown stable (as upstream).
+	useEffect(() => {
+		return () => {
+			if (mergedOptions.onUnmount) {
+				mergedOptions.onUnmount(asyncBatcher);
+			} else {
+				asyncBatcher.cancel();
+				asyncBatcher.abort();
+			}
+		};
+	}, []);
+
+	const state = useSelectorSlot(asyncBatcher.store, selector, { compare: shallow }, stateSlot);
+
+	return useMemo(
+		() =>
+			({
+				...asyncBatcher,
+				state,
+			}) as ReactAsyncBatcher<TValue, TSelected>, // omit `store` in favor of `state`
+		[asyncBatcher, state],
+	);
+}

package/src/async-debouncer/index.ts

@@ -0,0 +1,5 @@
+// re-export everything from the core pacer package, BUT ONLY from the async-debouncer module
+export * from '@tanstack/pacer/async-debouncer';
+
+export * from './useAsyncDebouncer';
+export * from './useAsyncDebouncedCallback';

package/src/async-debouncer/useAsyncDebouncedCallback.ts

@@ -0,0 +1,25 @@
+import { useCallback } from 'octane';
+import { useAsyncDebouncer } from './useAsyncDebouncer';
+import type { ReactAsyncDebouncerOptions } from './useAsyncDebouncer';
+import type { AnyAsyncFunction } from '@tanstack/pacer/types';
+
+/**
+ * An Octane hook that creates a debounced version of an async callback
+ * function. The returned function resolves with the callback's result once
+ * the debounced execution runs.
+ *
+ * @example
+ * ```tsx
+ * const debouncedSearch = useAsyncDebouncedCallback(searchApi, { wait: 500 });
+ * ```
+ */
+export function useAsyncDebouncedCallback<TFn extends AnyAsyncFunction>(
+	fn: TFn,
+	options: ReactAsyncDebouncerOptions<TFn, {}>,
+): (...args: Parameters<TFn>) => Promise<ReturnType<TFn>> {
+	const asyncDebouncedFn = useAsyncDebouncer(fn, options).maybeExecute;
+	return useCallback(
+		(...args) => asyncDebouncedFn(...args) as Promise<ReturnType<TFn>>,
+		[asyncDebouncedFn],
+	);
+}

package/src/async-debouncer/useAsyncDebouncer.ts

@@ -0,0 +1,123 @@
+import { useEffect, useMemo, useState } from 'octane';
+import { AsyncDebouncer } from '@tanstack/pacer/async-debouncer';
+import { shallow } from '@octanejs/tanstack-store';
+import { useDefaultPacerOptions } from '../provider/context';
+import { useSelectorSlot } from '../internal';
+import type { Store } from '@octanejs/tanstack-store';
+import type { AsyncDebouncerOptions, AsyncDebouncerState } from '@tanstack/pacer/async-debouncer';
+import type { AnyAsyncFunction } from '@tanstack/pacer/types';
+
+const subscribeSlot = Symbol.for('@octanejs/tanstack-pacer:useAsyncDebouncer:Subscribe');
+const stateSlot = Symbol.for('@octanejs/tanstack-pacer:useAsyncDebouncer:state');
+
+export interface ReactAsyncDebouncerOptions<
+	TFn extends AnyAsyncFunction,
+	TSelected = {},
+> extends AsyncDebouncerOptions<TFn> {
+	/**
+	 * Custom unmount behavior. Defaults to cancelling pending executions and
+	 * aborting in-flight ones.
+	 */
+	onUnmount?: (debouncer: ReactAsyncDebouncer<TFn, TSelected>) => void;
+}
+
+export interface ReactAsyncDebouncer<TFn extends AnyAsyncFunction, TSelected = {}> extends Omit<
+	AsyncDebouncer<TFn>,
+	'store'
+> {
+	/**
+	 * Render-prop component subscribing to a slice of the debouncer's state.
+	 */
+	Subscribe: <TSelected>(props: {
+		selector: (state: AsyncDebouncerState<TFn>) => TSelected;
+		children: ((state: TSelected) => unknown) | unknown;
+	}) => unknown;
+	/**
+	 * Reactive state selected by the hook's `selector` (empty object without one).
+	 */
+	readonly state: Readonly<TSelected>;
+	/**
+	 * The underlying TanStack Store instance.
+	 */
+	readonly store: Store<Readonly<AsyncDebouncerState<TFn>>>;
+}
+
+/**
+ * An Octane hook that creates and manages an AsyncDebouncer instance.
+ *
+ * Like the sync debouncer but for async functions: adds success/error/settled
+ * lifecycle callbacks, abort support, and execution tracking.
+ *
+ * **By default there are no reactive state subscriptions** — opt in by
+ * providing a `selector`; only then does the component re-render when the
+ * selected state values change.
+ *
+ * @example
+ * ```tsx
+ * const debouncer = useAsyncDebouncer(
+ *   async (query: string) => fetchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({ isExecuting: state.isExecuting }),
+ * );
+ * ```
+ */
+export function useAsyncDebouncer<TFn extends AnyAsyncFunction, TSelected = {}>(
+	fn: TFn,
+	options: ReactAsyncDebouncerOptions<TFn, TSelected>,
+	selector: (state: AsyncDebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
+): ReactAsyncDebouncer<TFn, TSelected> {
+	const mergedOptions = {
+		...useDefaultPacerOptions().asyncDebouncer,
+		...options,
+	} as ReactAsyncDebouncerOptions<TFn, TSelected>;
+	const [asyncDebouncer] = useState(() => {
+		const asyncDebouncerInstance = new AsyncDebouncer<TFn>(
+			fn,
+			mergedOptions,
+		) as unknown as ReactAsyncDebouncer<TFn, TSelected>;
+
+		asyncDebouncerInstance.Subscribe = function Subscribe<TSelected>(props: {
+			selector: (state: AsyncDebouncerState<TFn>) => TSelected;
+			children: ((state: TSelected) => unknown) | unknown;
+		}) {
+			const selected = useSelectorSlot(
+				asyncDebouncerInstance.store,
+				props.selector,
+				{ compare: shallow },
+				subscribeSlot,
+			);
+
+			return typeof props.children === 'function'
+				? (props.children as (state: TSelected) => unknown)(selected)
+				: props.children;
+		};
+
+		return asyncDebouncerInstance;
+	});
+
+	asyncDebouncer.fn = fn;
+	asyncDebouncer.setOptions(mergedOptions);
+
+	const state = useSelectorSlot(asyncDebouncer.store, selector, { compare: shallow }, stateSlot);
+
+	// Unmount cleanup only; empty deps keep teardown stable (as upstream).
+	useEffect(() => {
+		return () => {
+			if (mergedOptions.onUnmount) {
+				mergedOptions.onUnmount(asyncDebouncer);
+			} else {
+				asyncDebouncer.cancel();
+				asyncDebouncer.abort();
+			}
+		};
+	}, []);
+
+	return useMemo(
+		() =>
+			({
+				...asyncDebouncer,
+				state,
+			}) as ReactAsyncDebouncer<TFn, TSelected>, // omit `store` in favor of `state`
+		[asyncDebouncer, state],
+	);
+}

package/src/async-queuer/index.ts

@@ -0,0 +1,5 @@
+// re-export everything from the core pacer package, BUT ONLY from the async-queuer module
+export * from '@tanstack/pacer/async-queuer';
+
+export * from './useAsyncQueuer';
+export * from './useAsyncQueuedState';

package/src/async-queuer/useAsyncQueuedState.ts

@@ -0,0 +1,30 @@
+import { useAsyncQueuer } from './useAsyncQueuer';
+import type { ReactAsyncQueuer, ReactAsyncQueuerOptions } from './useAsyncQueuer';
+import type { AsyncQueuerState } from '@tanstack/pacer/async-queuer';
+
+/**
+ * An Octane hook that creates an async queue with managed state. Returns a
+ * tuple of the current queue items and the queuer instance.
+ *
+ * The selector defaults to tracking `items` (this hook is inherently
+ * reactive to the queue contents).
+ *
+ * @example
+ * ```tsx
+ * const [items, queuer] = useAsyncQueuedState(processItem, { concurrency: 2 });
+ * ```
+ */
+export function useAsyncQueuedState<
+	TValue,
+	TSelected extends Pick<AsyncQueuerState<TValue>, 'items'> = Pick<
+		AsyncQueuerState<TValue>,
+		'items'
+	>,
+>(
+	fn: (value: TValue) => Promise<any>,
+	options: ReactAsyncQueuerOptions<TValue, TSelected> = {},
+	selector?: (state: AsyncQueuerState<TValue>) => TSelected,
+): [Array<TValue>, ReactAsyncQueuer<TValue, TSelected>] {
+	const asyncQueuer = useAsyncQueuer(fn, options, selector);
+	return [asyncQueuer.state.items, asyncQueuer];
+}

package/src/async-queuer/useAsyncQueuer.ts

@@ -0,0 +1,116 @@
+import { useEffect, useMemo, useState } from 'octane';
+import { AsyncQueuer } from '@tanstack/pacer/async-queuer';
+import { shallow } from '@octanejs/tanstack-store';
+import { useDefaultPacerOptions } from '../provider/context';
+import { useSelectorSlot } from '../internal';
+import type { Store } from '@octanejs/tanstack-store';
+import type { AsyncQueuerOptions, AsyncQueuerState } from '@tanstack/pacer/async-queuer';
+
+const subscribeSlot = Symbol.for('@octanejs/tanstack-pacer:useAsyncQueuer:Subscribe');
+const stateSlot = Symbol.for('@octanejs/tanstack-pacer:useAsyncQueuer:state');
+
+export interface ReactAsyncQueuerOptions<
+	TValue,
+	TSelected = {},
+> extends AsyncQueuerOptions<TValue> {
+	/**
+	 * Custom unmount behavior. Defaults to stopping the queue and aborting
+	 * in-flight executions.
+	 */
+	onUnmount?: (queuer: ReactAsyncQueuer<TValue, TSelected>) => void;
+}
+
+export interface ReactAsyncQueuer<TValue, TSelected = {}> extends Omit<
+	AsyncQueuer<TValue>,
+	'store'
+> {
+	/**
+	 * Render-prop component subscribing to a slice of the queuer's state.
+	 */
+	Subscribe: <TSelected>(props: {
+		selector: (state: AsyncQueuerState<TValue>) => TSelected;
+		children: ((state: TSelected) => unknown) | unknown;
+	}) => unknown;
+	/**
+	 * Reactive state selected by the hook's `selector` (empty object without one).
+	 */
+	readonly state: Readonly<TSelected>;
+	/**
+	 * The underlying TanStack Store instance.
+	 */
+	readonly store: Store<Readonly<AsyncQueuerState<TValue>>>;
+}
+
+/**
+ * An Octane hook that creates and manages an AsyncQueuer instance — processes
+ * queued items through an async function with configurable concurrency.
+ *
+ * **By default there are no reactive state subscriptions** — opt in by
+ * providing a `selector`; only then does the component re-render when the
+ * selected state values change.
+ *
+ * @example
+ * ```tsx
+ * const queuer = useAsyncQueuer(processItem, { concurrency: 2 });
+ * ```
+ */
+export function useAsyncQueuer<TValue, TSelected = {}>(
+	fn: (value: TValue) => Promise<any>,
+	options: ReactAsyncQueuerOptions<TValue, TSelected> = {},
+	selector: (state: AsyncQueuerState<TValue>) => TSelected = () => ({}) as TSelected,
+): ReactAsyncQueuer<TValue, TSelected> {
+	const mergedOptions = {
+		...useDefaultPacerOptions().asyncQueuer,
+		...options,
+	} as ReactAsyncQueuerOptions<TValue, TSelected>;
+	const [asyncQueuer] = useState(() => {
+		const asyncQueuerInstance = new AsyncQueuer<TValue>(
+			fn,
+			mergedOptions,
+		) as unknown as ReactAsyncQueuer<TValue, TSelected>;
+
+		asyncQueuerInstance.Subscribe = function Subscribe<TSelected>(props: {
+			selector: (state: AsyncQueuerState<TValue>) => TSelected;
+			children: ((state: TSelected) => unknown) | unknown;
+		}) {
+			const selected = useSelectorSlot(
+				asyncQueuerInstance.store,
+				props.selector,
+				{ compare: shallow },
+				subscribeSlot,
+			);
+
+			return typeof props.children === 'function'
+				? (props.children as (state: TSelected) => unknown)(selected)
+				: props.children;
+		};
+
+		return asyncQueuerInstance;
+	});
+
+	asyncQueuer.fn = fn;
+	asyncQueuer.setOptions(mergedOptions);
+
+	// Unmount cleanup only; empty deps keep teardown stable (as upstream).
+	useEffect(() => {
+		return () => {
+			if (mergedOptions.onUnmount) {
+				mergedOptions.onUnmount(asyncQueuer);
+			} else {
+				asyncQueuer.stop();
+				asyncQueuer.abort();
+			}
+		};
+	}, []);
+
+	const state = useSelectorSlot(asyncQueuer.store, selector, { compare: shallow }, stateSlot);
+
+	return useMemo(
+		() =>
+			({
+				...asyncQueuer,
+				state,
+			}) as ReactAsyncQueuer<TValue, TSelected>, // omit `store` in favor of `state`
+		[asyncQueuer, state],
+	);
+}

package/src/async-rate-limiter/index.ts

@@ -0,0 +1,5 @@
+// re-export everything from the core pacer package, BUT ONLY from the async-rate-limiter module
+export * from '@tanstack/pacer/async-rate-limiter';
+
+export * from './useAsyncRateLimiter';
+export * from './useAsyncRateLimitedCallback';

package/src/async-rate-limiter/useAsyncRateLimitedCallback.ts

@@ -0,0 +1,27 @@
+import { useCallback } from 'octane';
+import { useAsyncRateLimiter } from './useAsyncRateLimiter';
+import type { ReactAsyncRateLimiterOptions } from './useAsyncRateLimiter';
+import type { AnyAsyncFunction } from '@tanstack/pacer/types';
+
+/**
+ * An Octane hook that creates a rate-limited version of an async callback
+ * function.
+ *
+ * @example
+ * ```tsx
+ * const rateLimitedFetch = useAsyncRateLimitedCallback(fetchData, {
+ *   limit: 5,
+ *   window: 60000,
+ * });
+ * ```
+ */
+export function useAsyncRateLimitedCallback<TFn extends AnyAsyncFunction>(
+	fn: TFn,
+	options: ReactAsyncRateLimiterOptions<TFn, {}>,
+): (...args: Parameters<TFn>) => Promise<ReturnType<TFn>> {
+	const asyncRateLimitedFn = useAsyncRateLimiter(fn, options).maybeExecute;
+	return useCallback(
+		(...args) => asyncRateLimitedFn(...args) as Promise<ReturnType<TFn>>,
+		[asyncRateLimitedFn],
+	);
+}