@octanejs/tanstack-pacer 0.0.5

package/src/index.ts

@@ -0,0 +1,63 @@
+// Octane port of @tanstack/react-pacer@0.22.1 — hook wrappers over the
+// framework-agnostic @tanstack/pacer core, mirroring the upstream module
+// layout (src/index.ts).
+
+// re-export everything from the core pacer package
+export * from '@tanstack/pacer';
+
+// provider
+export { PacerProvider } from './provider/PacerProvider.tsrx';
+export type { PacerProviderProps } from './provider/PacerProvider.tsrx';
+export { usePacerContext, useDefaultPacerOptions } from './provider/context';
+export type { PacerProviderOptions } from './provider/context';
+
+/**
+ * Export every hook individually - DON'T export from barrel files
+ */
+
+// async-batcher
+export * from './async-batcher/useAsyncBatcher';
+export * from './async-batcher/useAsyncBatchedCallback';
+
+// async-debouncer
+export * from './async-debouncer/useAsyncDebouncer';
+export * from './async-debouncer/useAsyncDebouncedCallback';
+
+// async-queuer
+export * from './async-queuer/useAsyncQueuer';
+export * from './async-queuer/useAsyncQueuedState';
+
+// async-rate-limiter
+export * from './async-rate-limiter/useAsyncRateLimiter';
+export * from './async-rate-limiter/useAsyncRateLimitedCallback';
+
+// async-throttler
+export * from './async-throttler/useAsyncThrottler';
+export * from './async-throttler/useAsyncThrottledCallback';
+
+// batcher
+export * from './batcher/useBatcher';
+export * from './batcher/useBatchedCallback';
+
+// debouncer
+export * from './debouncer/useDebouncedCallback';
+export * from './debouncer/useDebouncedState';
+export * from './debouncer/useDebouncedValue';
+export * from './debouncer/useDebouncer';
+
+// queuer
+export * from './queuer/useQueuer';
+export * from './queuer/useQueuedState';
+export * from './queuer/useQueuedValue';
+
+// rate-limiter
+export * from './rate-limiter/useRateLimitedCallback';
+export * from './rate-limiter/useRateLimiter';
+export * from './rate-limiter/useRateLimitedState';
+export * from './rate-limiter/useRateLimitedValue';
+
+// throttler
+export * from './throttler/useThrottledCallback';
+export * from './throttler/useThrottledState';
+export * from './throttler/useThrottledValue';
+export * from './throttler/useThrottler';

package/src/internal.ts

@@ -0,0 +1,45 @@
+import { useSelector } from '@octanejs/tanstack-store';
+
+// React type aliases used by upstream signatures (`React.Dispatch<React.SetStateAction<T>>`).
+// Octane's `useState` setter is structurally identical.
+export type SetStateAction<S> = S | ((prev: S) => S);
+export type Dispatch<A> = (value: A) => void;
+
+// Slot mechanics for the binding's plain-`.ts` hooks. The octane compiler
+// wraps custom-hook CALLS made from compiled `.tsrx`/`.tsx` modules in
+// `withSlot`, but calls made from plain `.ts` modules (this binding's hooks
+// composing `useSelector` from @octanejs/tanstack-store) are not wrapped —
+// so each `useSelector` call site here hands over its own slot symbol.
+// `useSelector` reads the slot off its last argument; the public overloads
+// don't declare it, hence the cast.
+
+type SelectionSource<T> = {
+	get: () => T;
+	subscribe: (listener: (value: T) => void) => {
+		unsubscribe: () => void;
+	};
+};
+
+// An omitted optional selector can be occupied by Octane's trailing hook slot.
+// Preserve Pacer's non-reactive empty selection without treating that slot as a selector.
+function selectEmpty<TSelected>(): TSelected {
+	return {} as TSelected;
+}
+
+export function useSelectorSlot<TSource, TSelected>(
+	source: SelectionSource<TSource>,
+	selector: ((snapshot: TSource) => TSelected) | symbol,
+	options: { compare?: (a: TSelected, b: TSelected) => boolean } | undefined,
+	slot: symbol,
+): TSelected {
+	const resolvedSelector = typeof selector === 'symbol' ? selectEmpty<TSelected> : selector;
+
+	return (
+		useSelector as (
+			source: SelectionSource<TSource>,
+			selector: (snapshot: TSource) => TSelected,
+			options: { compare?: (a: TSelected, b: TSelected) => boolean } | undefined,
+			slot: symbol,
+		) => TSelected
+	)(source, resolvedSelector, options, slot);
+}

package/src/provider/PacerProvider.tsrx

@@ -0,0 +1,25 @@
+import { useMemo } from 'octane';
+import type { OctaneNode } from 'octane';
+import { PacerContext } from './context.ts';
+import type { PacerContextValue, PacerProviderOptions } from './context.ts';
+
+export interface PacerProviderProps {
+	children: OctaneNode;
+	defaultOptions?: PacerProviderOptions;
+}
+
+const DEFAULT_OPTIONS: PacerProviderOptions = {};
+
+// PacerProvider — provides shared default options for every pacer hook family.
+// It's authored in .tsrx because it's a COMPONENT that renders a context
+// Provider with children (the binding's hooks stay plain TS).
+export function PacerProvider({ children, defaultOptions = DEFAULT_OPTIONS }: PacerProviderProps) @{
+	const contextValue: PacerContextValue = useMemo(
+		() => ({
+			defaultOptions,
+		}),
+		[defaultOptions],
+	);
+
+	<PacerContext.Provider value={contextValue}>{children}</PacerContext.Provider>
+}

package/src/provider/PacerProvider.tsrx.d.ts

@@ -0,0 +1,12 @@
+// Type declaration for the .tsrx provider component (PacerProvider.tsrx).
+// It's a SPECIFIC module declaration (resolved by relative path), not an ambient
+// `declare module '*.tsrx'` — so it types only this module and doesn't pollute a
+// consumer's own .tsrx imports. The runtime resolves the real compiled .tsrx.
+import type { PacerProviderOptions } from './context';
+
+export interface PacerProviderProps {
+	children: unknown;
+	defaultOptions?: PacerProviderOptions;
+}
+
+export declare function PacerProvider(props: PacerProviderProps): unknown;

package/src/provider/context.ts

@@ -0,0 +1,43 @@
+import { createContext, useContext } from 'octane';
+import type {
+	AnyAsyncFunction,
+	AnyFunction,
+	AsyncBatcherOptions,
+	AsyncDebouncerOptions,
+	AsyncQueuerOptions,
+	AsyncRateLimiterOptions,
+	AsyncThrottlerOptions,
+	BatcherOptions,
+	DebouncerOptions,
+	QueuerOptions,
+	RateLimiterOptions,
+	ThrottlerOptions,
+} from '@tanstack/pacer';
+
+export interface PacerProviderOptions {
+	asyncBatcher?: Partial<AsyncBatcherOptions<any>>;
+	asyncDebouncer?: Partial<AsyncDebouncerOptions<AnyAsyncFunction>>;
+	asyncQueuer?: Partial<AsyncQueuerOptions<any>>;
+	asyncRateLimiter?: Partial<AsyncRateLimiterOptions<AnyAsyncFunction>>;
+	asyncThrottler?: Partial<AsyncThrottlerOptions<AnyAsyncFunction>>;
+	batcher?: Partial<BatcherOptions<any>>;
+	debouncer?: Partial<DebouncerOptions<AnyFunction>>;
+	queuer?: Partial<QueuerOptions<any>>;
+	rateLimiter?: Partial<RateLimiterOptions<AnyFunction>>;
+	throttler?: Partial<ThrottlerOptions<AnyFunction>>;
+}
+
+export interface PacerContextValue {
+	defaultOptions: PacerProviderOptions;
+}
+
+export const PacerContext = createContext<PacerContextValue | null>(null);
+
+export function usePacerContext() {
+	return useContext(PacerContext);
+}
+
+export function useDefaultPacerOptions() {
+	const context = useContext(PacerContext);
+	return context?.defaultOptions ?? {};
+}

package/src/provider/index.ts

@@ -0,0 +1,4 @@
+export { PacerProvider } from './PacerProvider.tsrx';
+export type { PacerProviderProps } from './PacerProvider.tsrx';
+export { usePacerContext, useDefaultPacerOptions } from './context';
+export type { PacerProviderOptions } from './context';

package/src/queuer/index.ts

@@ -0,0 +1,6 @@
+// re-export everything from the core pacer package, BUT ONLY from the queuer module
+export * from '@tanstack/pacer/queuer';
+
+export * from './useQueuer';
+export * from './useQueuedState';
+export * from './useQueuedValue';

package/src/queuer/useQueuedState.ts

@@ -0,0 +1,27 @@
+import { useQueuer } from './useQueuer';
+import type { ReactQueuer, ReactQueuerOptions } from './useQueuer';
+import type { Queuer, QueuerState } from '@tanstack/pacer/queuer';
+
+/**
+ * An Octane hook that creates a queue with managed state. Returns a tuple of
+ * the current queue items, an addItem function, and the queuer instance.
+ *
+ * The selector defaults to tracking `items` (this hook is inherently
+ * reactive to the queue contents).
+ *
+ * @example
+ * ```tsx
+ * const [items, addItem, queuer] = useQueuedState(processItem, { wait: 1000 });
+ * ```
+ */
+export function useQueuedState<
+	TValue,
+	TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>,
+>(
+	fn: (item: TValue) => void,
+	options: ReactQueuerOptions<TValue, TSelected> = {},
+	selector?: (state: QueuerState<TValue>) => TSelected,
+): [Array<TValue>, Queuer<TValue>['addItem'], ReactQueuer<TValue, TSelected>] {
+	const queue = useQueuer(fn, options, selector);
+	return [queue.state.items, queue.addItem, queue];
+}

package/src/queuer/useQueuedValue.ts

@@ -0,0 +1,37 @@
+import { useEffect, useState } from 'octane';
+import { useQueuedState } from './useQueuedState';
+import type { ReactQueuer, ReactQueuerOptions } from './useQueuer';
+import type { QueuerState } from '@tanstack/pacer/queuer';
+
+/**
+ * An Octane hook that creates a queued value that processes changes through a
+ * queue, updating at the queue's pace.
+ *
+ * @example
+ * ```tsx
+ * const [queuedValue, queuer] = useQueuedValue(value, { wait: 500 });
+ * ```
+ */
+export function useQueuedValue<
+	TValue,
+	TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>,
+>(
+	initialValue: TValue,
+	options: ReactQueuerOptions<TValue, TSelected> = {},
+	selector?: (state: QueuerState<TValue>) => TSelected,
+): [TValue, ReactQueuer<TValue, TSelected>] {
+	const [value, setValue] = useState<TValue>(initialValue);
+	const [, addItem, queuer] = useQueuedState(
+		(item) => {
+			setValue(item);
+		},
+		options,
+		selector,
+	);
+
+	useEffect(() => {
+		addItem(initialValue);
+	}, [initialValue, addItem]);
+
+	return [value, queuer];
+}

package/src/queuer/useQueuer.ts

@@ -0,0 +1,110 @@
+import { useEffect, useMemo, useState } from 'octane';
+import { Queuer } from '@tanstack/pacer/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 { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer';
+
+const subscribeSlot = Symbol.for('@octanejs/tanstack-pacer:useQueuer:Subscribe');
+const stateSlot = Symbol.for('@octanejs/tanstack-pacer:useQueuer:state');
+
+export interface ReactQueuerOptions<TValue, TSelected = {}> extends QueuerOptions<TValue> {
+	/**
+	 * Custom unmount behavior. Defaults to stopping the queue.
+	 */
+	onUnmount?: (queuer: ReactQueuer<TValue, TSelected>) => void;
+}
+
+export interface ReactQueuer<TValue, TSelected = {}> extends Omit<Queuer<TValue>, 'store'> {
+	/**
+	 * Render-prop component subscribing to a slice of the queuer's state.
+	 */
+	Subscribe: <TSelected>(props: {
+		selector: (state: QueuerState<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<QueuerState<TValue>>>;
+}
+
+/**
+ * An Octane hook that creates and manages a Queuer instance — a FIFO/LIFO/
+ * priority queue processing items at a configurable interval.
+ *
+ * **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 = useQueuer(processItem, { wait: 1000 }, (state) => ({
+ *   items: state.items,
+ * }));
+ * ```
+ */
+export function useQueuer<TValue, TSelected = {}>(
+	fn: (item: TValue) => void,
+	options: ReactQueuerOptions<TValue, TSelected> = {},
+	selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,
+): ReactQueuer<TValue, TSelected> {
+	const mergedOptions = {
+		...useDefaultPacerOptions().queuer,
+		...options,
+	} as ReactQueuerOptions<TValue, TSelected>;
+	const [queuer] = useState(() => {
+		const queuerInstance = new Queuer<TValue>(fn, mergedOptions) as unknown as ReactQueuer<
+			TValue,
+			TSelected
+		>;
+
+		queuerInstance.Subscribe = function Subscribe<TSelected>(props: {
+			selector: (state: QueuerState<TValue>) => TSelected;
+			children: ((state: TSelected) => unknown) | unknown;
+		}) {
+			const selected = useSelectorSlot(
+				queuerInstance.store,
+				props.selector,
+				{ compare: shallow },
+				subscribeSlot,
+			);
+
+			return typeof props.children === 'function'
+				? (props.children as (state: TSelected) => unknown)(selected)
+				: props.children;
+		};
+
+		return queuerInstance;
+	});
+
+	queuer.fn = fn;
+	queuer.setOptions(mergedOptions);
+
+	// Unmount cleanup only; empty deps keep teardown stable (as upstream).
+	useEffect(() => {
+		return () => {
+			if (mergedOptions.onUnmount) {
+				mergedOptions.onUnmount(queuer);
+			} else {
+				queuer.stop();
+			}
+		};
+	}, []);
+
+	const state = useSelectorSlot(queuer.store, selector, { compare: shallow }, stateSlot);
+
+	return useMemo(
+		() =>
+			({
+				...queuer,
+				state,
+			}) as ReactQueuer<TValue, TSelected>, // omit `store` in favor of `state`
+		[queuer, state],
+	);
+}

package/src/rate-limiter/index.ts

@@ -0,0 +1,7 @@
+// re-export everything from the core pacer package, BUT ONLY from the rate-limiter module
+export * from '@tanstack/pacer/rate-limiter';
+
+export * from './useRateLimitedCallback';
+export * from './useRateLimiter';
+export * from './useRateLimitedState';
+export * from './useRateLimitedValue';

package/src/rate-limiter/useRateLimitedCallback.ts

@@ -0,0 +1,24 @@
+import { useCallback } from 'octane';
+import { useRateLimiter } from './useRateLimiter';
+import type { ReactRateLimiterOptions } from './useRateLimiter';
+import type { AnyFunction } from '@tanstack/pacer/types';
+
+/**
+ * An Octane hook that creates a rate-limited version of a callback function.
+ * The returned function reports whether the call was allowed to execute.
+ *
+ * @example
+ * ```tsx
+ * const rateLimitedCall = useRateLimitedCallback(makeApiCall, {
+ *   limit: 5,
+ *   window: 60000,
+ * });
+ * ```
+ */
+export function useRateLimitedCallback<TFn extends AnyFunction>(
+	fn: TFn,
+	options: ReactRateLimiterOptions<TFn, {}>,
+): (...args: Parameters<TFn>) => boolean {
+	const rateLimitedFn = useRateLimiter(fn, options).maybeExecute;
+	return useCallback((...args) => rateLimitedFn(...args), [rateLimitedFn]);
+}

package/src/rate-limiter/useRateLimitedState.ts

@@ -0,0 +1,34 @@
+import { useState } from 'octane';
+import { useRateLimiter } from './useRateLimiter';
+import type { ReactRateLimiter, ReactRateLimiterOptions } from './useRateLimiter';
+import type { Dispatch, SetStateAction } from '../internal';
+import type { RateLimiterState } from '@tanstack/pacer/rate-limiter';
+
+/**
+ * An Octane hook that creates a rate-limited state value. Returns a tuple of
+ * the current value, a rate-limited updater, and the rate limiter instance.
+ *
+ * **By default there are no reactive state subscriptions** — opt in by
+ * providing a `selector` (see {@link useRateLimiter}).
+ *
+ * @example
+ * ```tsx
+ * const [value, setValue, rateLimiter] = useRateLimitedState(0, {
+ *   limit: 5,
+ *   window: 60000,
+ * });
+ * ```
+ */
+export function useRateLimitedState<TValue, TSelected = RateLimiterState>(
+	value: TValue,
+	options: ReactRateLimiterOptions<Dispatch<SetStateAction<TValue>>, TSelected>,
+	selector?: (state: RateLimiterState) => TSelected,
+): [
+	TValue,
+	Dispatch<SetStateAction<TValue>>,
+	ReactRateLimiter<Dispatch<SetStateAction<TValue>>, TSelected>,
+] {
+	const [rateLimitedValue, setRateLimitedValue] = useState<TValue>(value);
+	const rateLimiter = useRateLimiter(setRateLimitedValue, options, selector);
+	return [rateLimitedValue, rateLimiter.maybeExecute, rateLimiter];
+}

package/src/rate-limiter/useRateLimitedValue.ts

@@ -0,0 +1,38 @@
+import { useEffect } from 'octane';
+import { useRateLimitedState } from './useRateLimitedState';
+import type { ReactRateLimiter, ReactRateLimiterOptions } from './useRateLimiter';
+import type { Dispatch, SetStateAction } from '../internal';
+import type { RateLimiterState } from '@tanstack/pacer/rate-limiter';
+
+/**
+ * An Octane hook that creates a rate-limited value that automatically tracks
+ * changes to the input value.
+ *
+ * **By default there are no reactive state subscriptions** — opt in by
+ * providing a `selector` (see {@link useRateLimiter}).
+ *
+ * @example
+ * ```tsx
+ * const [rateLimitedValue, rateLimiter] = useRateLimitedValue(value, {
+ *   limit: 5,
+ *   window: 60000,
+ * });
+ * ```
+ */
+export function useRateLimitedValue<TValue, TSelected = RateLimiterState>(
+	value: TValue,
+	options: ReactRateLimiterOptions<Dispatch<SetStateAction<TValue>>, TSelected>,
+	selector?: (state: RateLimiterState) => TSelected,
+): [TValue, ReactRateLimiter<Dispatch<SetStateAction<TValue>>, TSelected>] {
+	const [rateLimitedValue, setRateLimitedValue, rateLimiter] = useRateLimitedState(
+		value,
+		options,
+		selector,
+	);
+
+	useEffect(() => {
+		setRateLimitedValue(value);
+	}, [value, setRateLimitedValue]);
+
+	return [rateLimitedValue, rateLimiter];
+}

package/src/rate-limiter/useRateLimiter.ts

@@ -0,0 +1,119 @@
+import { useEffect, useMemo, useState } from 'octane';
+import { RateLimiter } from '@tanstack/pacer/rate-limiter';
+import { shallow } from '@octanejs/tanstack-store';
+import { useDefaultPacerOptions } from '../provider/context';
+import { useSelectorSlot } from '../internal';
+import type { Store } from '@octanejs/tanstack-store';
+import type { RateLimiterOptions, RateLimiterState } from '@tanstack/pacer/rate-limiter';
+import type { AnyFunction } from '@tanstack/pacer/types';
+
+const subscribeSlot = Symbol.for('@octanejs/tanstack-pacer:useRateLimiter:Subscribe');
+const stateSlot = Symbol.for('@octanejs/tanstack-pacer:useRateLimiter:state');
+
+export interface ReactRateLimiterOptions<
+	TFn extends AnyFunction,
+	TSelected = {},
+> extends RateLimiterOptions<TFn> {
+	/**
+	 * Custom unmount behavior (rate limiters have nothing to cancel by default).
+	 */
+	onUnmount?: (rateLimiter: ReactRateLimiter<TFn, TSelected>) => void;
+}
+
+export interface ReactRateLimiter<TFn extends AnyFunction, TSelected = {}> extends Omit<
+	RateLimiter<TFn>,
+	'store'
+> {
+	/**
+	 * Render-prop component subscribing to a slice of the rate limiter's state.
+	 */
+	Subscribe: <TSelected>(props: {
+		selector: (state: RateLimiterState) => 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<RateLimiterState>>;
+}
+
+/**
+ * An Octane hook that creates and manages a RateLimiter instance.
+ *
+ * The rate limiter allows a maximum number of executions within a time window
+ * (fixed or sliding).
+ *
+ * **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 rateLimiter = useRateLimiter(
+ *   makeApiCall,
+ *   { limit: 5, window: 60000 },
+ *   (state) => ({ rejectionCount: state.rejectionCount }),
+ * );
+ * ```
+ */
+export function useRateLimiter<TFn extends AnyFunction, TSelected = {}>(
+	fn: TFn,
+	options: ReactRateLimiterOptions<TFn, TSelected>,
+	selector: (state: RateLimiterState) => TSelected = () => ({}) as TSelected,
+): ReactRateLimiter<TFn, TSelected> {
+	const mergedOptions = {
+		...useDefaultPacerOptions().rateLimiter,
+		...options,
+	} as ReactRateLimiterOptions<TFn, TSelected>;
+	const [rateLimiter] = useState(() => {
+		const rateLimiterInstance = new RateLimiter<TFn>(
+			fn,
+			mergedOptions,
+		) as unknown as ReactRateLimiter<TFn, TSelected>;
+
+		rateLimiterInstance.Subscribe = function Subscribe<TSelected>(props: {
+			selector: (state: RateLimiterState) => TSelected;
+			children: ((state: TSelected) => unknown) | unknown;
+		}) {
+			const selected = useSelectorSlot(
+				rateLimiterInstance.store,
+				props.selector,
+				{ compare: shallow },
+				subscribeSlot,
+			);
+
+			return typeof props.children === 'function'
+				? (props.children as (state: TSelected) => unknown)(selected)
+				: props.children;
+		};
+
+		return rateLimiterInstance;
+	});
+
+	rateLimiter.fn = fn;
+	rateLimiter.setOptions(mergedOptions);
+
+	// Unmount cleanup only; empty deps keep teardown stable (as upstream).
+	useEffect(() => {
+		return () => {
+			if (mergedOptions.onUnmount) {
+				mergedOptions.onUnmount(rateLimiter);
+			}
+		};
+	}, []);
+
+	const state = useSelectorSlot(rateLimiter.store, selector, { compare: shallow }, stateSlot);
+
+	return useMemo(
+		() =>
+			({
+				...rateLimiter,
+				state,
+			}) as ReactRateLimiter<TFn, TSelected>, // omit `store` in favor of `state`
+		[rateLimiter, state],
+	);
+}

package/src/throttler/index.ts

@@ -0,0 +1,7 @@
+// re-export everything from the core pacer package, BUT ONLY from the throttler module
+export * from '@tanstack/pacer/throttler';
+
+export * from './useThrottledCallback';
+export * from './useThrottledState';
+export * from './useThrottledValue';
+export * from './useThrottler';

package/src/throttler/useThrottledCallback.ts

@@ -0,0 +1,20 @@
+import { useCallback } from 'octane';
+import { useThrottler } from './useThrottler';
+import type { ReactThrottlerOptions } from './useThrottler';
+import type { AnyFunction } from '@tanstack/pacer/types';
+
+/**
+ * An Octane hook that creates a throttled version of a callback function.
+ *
+ * @example
+ * ```tsx
+ * const throttledScroll = useThrottledCallback(onScroll, { wait: 200 });
+ * ```
+ */
+export function useThrottledCallback<TFn extends AnyFunction>(
+	fn: TFn,
+	options: ReactThrottlerOptions<TFn, {}>,
+): (...args: Parameters<TFn>) => void {
+	const throttledFn = useThrottler(fn, options).maybeExecute;
+	return useCallback((...args) => throttledFn(...args), [throttledFn]);
+}

package/src/throttler/useThrottledState.ts

@@ -0,0 +1,35 @@
+import { useState } from 'octane';
+import { useThrottler } from './useThrottler';
+import type { ReactThrottler, ReactThrottlerOptions } from './useThrottler';
+import type { Dispatch, SetStateAction } from '../internal';
+import type { ThrottlerState } from '@tanstack/pacer/throttler';
+
+/**
+ * An Octane hook that creates a throttled state value, combining `useState`
+ * with throttling functionality. Returns a tuple of the current throttled
+ * value, a throttled updater, and the throttler instance.
+ *
+ * **By default there are no reactive state subscriptions** — opt in by
+ * providing a `selector` (see {@link useThrottler}).
+ *
+ * @example
+ * ```tsx
+ * const [value, setValue, throttler] = useThrottledState(0, { wait: 1000 });
+ * ```
+ */
+export function useThrottledState<
+	TValue,
+	TSelected = ThrottlerState<Dispatch<SetStateAction<TValue>>>,
+>(
+	value: TValue,
+	options: ReactThrottlerOptions<Dispatch<SetStateAction<TValue>>, TSelected>,
+	selector?: (state: ThrottlerState<Dispatch<SetStateAction<TValue>>>) => TSelected,
+): [
+	TValue,
+	Dispatch<SetStateAction<TValue>>,
+	ReactThrottler<Dispatch<SetStateAction<TValue>>, TSelected>,
+] {
+	const [throttledValue, setThrottledValue] = useState<TValue>(value);
+	const throttler = useThrottler(setThrottledValue, options, selector);
+	return [throttledValue, throttler.maybeExecute, throttler];
+}