diff --git a/docs/devtools.md b/docs/devtools.md index bc4bc9fd..f5c972d3 100644 --- a/docs/devtools.md +++ b/docs/devtools.md @@ -5,10 +5,10 @@ id: devtools What? My debouncer can have dedicated devtools? Yep! -TanStack Pacer provides devtools for debugging and monitoring all your utilities in real-time. The devtools integrate seamlessly within the new [TanStack Devtools](https://tanstack.com/devtools) multi-panel UI. +TanStack Pacer ships devtools for watching and debugging every registered utility in real time. They run as a plugin inside the [TanStack Devtools](https://tanstack.com/devtools) multi-panel UI. -> [!NOTE] -> By default, the TanStack Devtools and TanStack Pacer Devtools will only be included in development mode. This helps keep your production bundle size minimal. If you need to include devtools in production builds (e.g., for debugging production issues), you can use the alternative "production" imports. +> [!NOTE] +> The devtools are excluded from production builds by default, so they add nothing to your production bundle. See [Production builds](#production-builds) if you need them in production. ## Installation @@ -30,9 +30,9 @@ npm install @tanstack/solid-devtools @tanstack/solid-pacer-devtools Coming soon... -## Basic Setup +## Basic setup -### React Setup +### React setup ```tsx import { TanStackDevtools } from '@tanstack/react-devtools' @@ -54,7 +54,7 @@ function App() { } ``` -### Solid Setup +### Solid setup ```tsx import { TanStackDevtools } from '@tanstack/solid-devtools' @@ -76,25 +76,25 @@ function App() { } ``` -## Production Builds +## Production builds -By default, devtools are excluded from production builds to minimize bundle size. The default imports will return no-op implementations in production: +The default imports become no-ops in production builds: ```tsx -// This will be a no-op in production builds +// This is a no-op in production builds import { pacerDevtoolsPlugin } from '@tanstack/react-pacer-devtools' ``` -If you need to include devtools in production builds (e.g., for debugging production issues), use the production-specific imports: +To debug a production issue with full devtools, switch to the production-specific imports: ```tsx -// This will include full devtools even in production builds +// This includes full devtools even in production builds import { pacerDevtoolsPlugin } from '@tanstack/react-pacer-devtools/production' ``` -## Registering Utilities +## Registering utilities -Pacer utilities only register with the devtools when you pass a `key`. Keys are no longer generated automatically, so leave the option out if you do not want an instance to appear in the panels. +A utility only registers with the devtools when you give it a `key`. Leave the option out and the instance stays out of the panels. ```tsx const debouncer = new Debouncer(myDebounceFn, { diff --git a/docs/framework/angular/adapter.md b/docs/framework/angular/adapter.md index 154991c4..f595f4da 100644 --- a/docs/framework/angular/adapter.md +++ b/docs/framework/angular/adapter.md @@ -15,7 +15,7 @@ npm install @tanstack/angular-pacer See the [Angular inject API Reference](./reference/index.md) for the full list of inject functions (injectDebouncer, injectThrottler, injectRateLimiter, injectQueuer, injectBatcher, and their async and callback variants). -## Basic Usage +## Basic usage Inject a Pacer utility in your component or service. Each inject function returns an object that exposes methods and a reactive `state()` signal when you pass a selector. diff --git a/docs/framework/preact/adapter.md b/docs/framework/preact/adapter.md index 9bb43c48..7a705378 100644 --- a/docs/framework/preact/adapter.md +++ b/docs/framework/preact/adapter.md @@ -3,7 +3,7 @@ title: TanStack Pacer Preact Adapter id: adapter --- -If you are using TanStack Pacer in a Preact application, we recommend using the Preact Adapter. The Preact Adapter provides a set of easy-to-use hooks on top of the core Pacer utilities. If you find yourself wanting to use the core Pacer classes/functions directly, the Preact Adapter will also re-export everything from the core package. +In a Preact application, use the Preact Adapter. Its hooks wrap the core Pacer utilities with lifecycle cleanup and reactive state. The adapter also re-exports everything from the core package, so you can import the plain classes and functions from the same place. ## Installation @@ -11,13 +11,13 @@ If you are using TanStack Pacer in a Preact application, we recommend using the npm install @tanstack/preact-pacer ``` -## Preact Hooks +## Preact hooks -See the [Preact Functions Reference](./reference/index.md) to see the full list of hooks available in the Preact Adapter. +See the [Preact Functions Reference](./reference/index.md) for the full list of hooks in the Preact Adapter. -## Basic Usage +## Basic usage -Import a preact specific hook from the Preact Adapter. +Import a Preact-specific hook from the Preact Adapter. ```tsx import { useDebouncedValue } from '@tanstack/preact-pacer' @@ -35,11 +35,11 @@ Or import a core Pacer class/function that is re-exported from the Preact Adapte import { debounce, Debouncer } from '@tanstack/preact-pacer' // no need to install the core package separately ``` -## Option Helpers +## Option helpers -If you want a type-safe way to define common options for pacer utilities, TanStack Pacer provides option helpers for each utility. These helpers can be used with Preact hooks. +Option helpers define shared options with full type checking, so you can declare them once and reuse them across hooks. -### Debouncer Options +### Debouncer options ```tsx import { useDebouncer } from '@tanstack/preact-pacer' @@ -57,7 +57,7 @@ const debouncer = useDebouncer( ) ``` -### Async Queuer Options +### Async queuer options ```tsx import { useAsyncQueuer } from '@tanstack/preact-pacer' @@ -74,7 +74,7 @@ const queuer = useAsyncQueuer( ) ``` -### Rate Limiter Options +### Rate limiter options ```tsx import { useRateLimiter } from '@tanstack/preact-pacer' @@ -94,7 +94,7 @@ const rateLimiter = useRateLimiter( ## Provider -The Preact Adapter provides a `PacerProvider` component that you can use to provide default options to all instances of pacer utilities within your component tree. +The `PacerProvider` component sets default options for every Pacer utility instance in its component tree. ```tsx import { PacerProvider } from '@tanstack/preact-pacer' @@ -111,15 +111,15 @@ import { PacerProvider } from '@tanstack/preact-pacer' ``` -All hooks within the provider will automatically use these default options, which can be overridden on a per-hook basis. +Hooks inside the provider use these defaults. Options passed to an individual hook override them. -## Subscribing to State +## Subscribing to state The Preact Adapter supports subscribing to state changes in two ways: -### Using the Subscribe Component +### Using the Subscribe component -Use the `Subscribe` component to subscribe to state changes deep in your component tree without needing to pass a selector to the hook. This is ideal when you want to subscribe to state in child components. +Use the `Subscribe` component to read state deep in the component tree without passing a selector to the hook. ```tsx import { useRateLimiter } from '@tanstack/preact-pacer' @@ -151,11 +151,11 @@ function ApiComponent() { } ``` -### Using the Selector Parameter +### Using the selector parameter -The `selector` parameter allows you to specify which state changes will trigger reactive updates at the hook level, optimizing performance by preventing unnecessary updates when irrelevant state changes occur. +The `selector` parameter controls which state changes trigger reactive updates. State you do not select never causes an update. -**By default, `hook.state` is empty (`{}`) as the selector is empty by default.** You must opt-in to state tracking by providing a selector function. +Without a selector, `hook.state` is an empty object (`{}`). Pass a selector function to opt in to state tracking. ```tsx import { useDebouncer } from '@tanstack/preact-pacer' @@ -189,7 +189,7 @@ For more details on state management and available state properties, see the ind ## Examples -### Debouncer Example +### Debouncer example ```tsx import { useDebouncer } from '@tanstack/preact-pacer' @@ -212,7 +212,7 @@ function SearchComponent() { } ``` -### Async Queuer Example +### Async queuer example ```tsx import { useAsyncQueuer } from '@tanstack/preact-pacer' @@ -245,7 +245,7 @@ function UploadComponent() { } ``` -### Rate Limiter Example +### Rate limiter example ```tsx import { useRateLimiter } from '@tanstack/preact-pacer' diff --git a/docs/framework/react/adapter.md b/docs/framework/react/adapter.md index 0ce68b87..3bbce3ae 100644 --- a/docs/framework/react/adapter.md +++ b/docs/framework/react/adapter.md @@ -3,7 +3,7 @@ title: TanStack Pacer React Adapter id: adapter --- -If you are using TanStack Pacer in a React application, we recommend using the React Adapter. The React Adapter provides a set of easy-to-use hooks on top of the core Pacer utilities. If you find yourself wanting to use the core Pacer classes/functions directly, the React Adapter will also re-export everything from the core package. +In a React application, use the React Adapter. Its hooks wrap the core Pacer utilities with lifecycle cleanup and reactive state. The adapter also re-exports everything from the core package, so you can import the plain classes and functions from the same place. ## Installation @@ -11,13 +11,13 @@ If you are using TanStack Pacer in a React application, we recommend using the R npm install @tanstack/react-pacer ``` -## React Hooks +## React hooks -See the [React Functions Reference](./reference/index.md) to see the full list of hooks available in the React Adapter. +See the [React Functions Reference](./reference/index.md) for the full list of hooks in the React Adapter. -## Basic Usage +## Basic usage -Import a react specific hook from the React Adapter. +Import a React-specific hook from the React Adapter. ```tsx import { useDebouncedValue } from '@tanstack/react-pacer' @@ -34,11 +34,11 @@ Or import a core Pacer class/function that is re-exported from the React Adapter import { debounce, Debouncer } from '@tanstack/react-pacer' // no need to install the core package separately ``` -## Option Helpers +## Option helpers -If you want a type-safe way to define common options for pacer utilities, TanStack Pacer provides option helpers for each utility. These helpers can be used with React hooks. +Option helpers define shared options with full type checking, so you can declare them once and reuse them across hooks. -### Debouncer Options +### Debouncer options ```tsx import { useDebouncer } from '@tanstack/react-pacer' @@ -56,7 +56,7 @@ const debouncer = useDebouncer( ) ``` -### Async Queuer Options +### Async queuer options ```tsx import { useAsyncQueuer } from '@tanstack/react-pacer' @@ -73,7 +73,7 @@ const queuer = useAsyncQueuer( ) ``` -### Rate Limiter Options +### Rate limiter options ```tsx import { useRateLimiter } from '@tanstack/react-pacer' @@ -93,7 +93,7 @@ const rateLimiter = useRateLimiter( ## Provider -The React Adapter provides a `PacerProvider` component that you can use to provide default options to all instances of pacer utilities within your component tree. +The `PacerProvider` component sets default options for every Pacer utility instance in its component tree. ```tsx import { PacerProvider } from '@tanstack/react-pacer' @@ -110,15 +110,15 @@ import { PacerProvider } from '@tanstack/react-pacer' ``` -All hooks within the provider will automatically use these default options, which can be overridden on a per-hook basis. +Hooks inside the provider use these defaults. Options passed to an individual hook override them. -## Subscribing to State +## Subscribing to state The React adapter supports subscribing to state changes in two ways: -### Using the Subscribe Component +### Using the Subscribe component -Use the `Subscribe` component to subscribe to state changes deep in your component tree without needing to pass a selector to the hook. This is ideal when you want to subscribe to state in child components. +Use the `Subscribe` component to read state deep in the component tree without passing a selector to the hook. ```tsx import { useRateLimiter } from '@tanstack/react-pacer' @@ -150,11 +150,11 @@ function ApiComponent() { } ``` -### Using the Selector Parameter +### Using the selector parameter -The `selector` parameter allows you to specify which state changes will trigger reactive updates at the hook level, optimizing performance by preventing unnecessary updates when irrelevant state changes occur. +The `selector` parameter controls which state changes trigger reactive updates. State you do not select never causes an update. -**By default, `hook.state` is empty (`{}`) as the selector is empty by default.** You must opt-in to state tracking by providing a selector function. +Without a selector, `hook.state` is an empty object (`{}`). Pass a selector function to opt in to state tracking. ```tsx import { useDebouncer } from '@tanstack/react-pacer' @@ -188,7 +188,7 @@ For more details on state management and available state properties, see the ind ## Examples -### Debouncer Example +### Debouncer example ```tsx import { useDebouncer } from '@tanstack/react-pacer' @@ -211,7 +211,7 @@ function SearchComponent() { } ``` -### Async Queuer Example +### Async queuer example ```tsx import { useAsyncQueuer } from '@tanstack/react-pacer' @@ -244,7 +244,7 @@ function UploadComponent() { } ``` -### Rate Limiter Example +### Rate limiter example ```tsx import { useRateLimiter } from '@tanstack/react-pacer' diff --git a/docs/framework/solid/adapter.md b/docs/framework/solid/adapter.md index 71f7edbb..57f78ba8 100644 --- a/docs/framework/solid/adapter.md +++ b/docs/framework/solid/adapter.md @@ -3,7 +3,7 @@ title: TanStack Pacer Solid Adapter id: adapter --- -If you are using TanStack Pacer in a Solid application, we recommend using the Solid Adapter. The Solid Adapter provides a set of easy-to-use hooks on top of the core Pacer utilities. If you find yourself wanting to use the core Pacer classes/functions directly, the Solid Adapter will also re-export everything from the core package. +In a Solid application, use the Solid Adapter. Its hooks wrap the core Pacer utilities with lifecycle cleanup and reactive state. The adapter also re-exports everything from the core package, so you can import the plain classes and functions from the same place. ## Installation @@ -11,13 +11,13 @@ If you are using TanStack Pacer in a Solid application, we recommend using the S npm install @tanstack/solid-pacer ``` -## Solid Hooks +## Solid hooks -See the [Solid Functions Reference](./reference/index.md) to see the full list of hooks available in the Solid Adapter. +See the [Solid Functions Reference](./reference/index.md) for the full list of hooks in the Solid Adapter. -## Basic Usage +## Basic usage -Import a solid specific hook from the Solid Adapter. +Import a Solid-specific hook from the Solid Adapter. ```tsx import { createDebouncedValue } from '@tanstack/solid-pacer' @@ -35,11 +35,11 @@ Or import a core Pacer class/function that is re-exported from the Solid Adapter import { debounce, Debouncer } from '@tanstack/solid-pacer' // no need to install the core package separately ``` -## Option Helpers +## Option helpers -If you want a type-safe way to define common options for pacer utilities, TanStack Pacer provides option helpers for each utility. These helpers can be used with Solid hooks. +Option helpers define shared options with full type checking, so you can declare them once and reuse them across hooks. -### Debouncer Options +### Debouncer options ```tsx import { createDebouncer } from '@tanstack/solid-pacer' @@ -57,7 +57,7 @@ const debouncer = createDebouncer( ) ``` -### Async Queuer Options +### Async queuer options ```tsx import { createAsyncQueuer } from '@tanstack/solid-pacer' @@ -74,7 +74,7 @@ const queuer = createAsyncQueuer( ) ``` -### Rate Limiter Options +### Rate limiter options ```tsx import { createRateLimiter } from '@tanstack/solid-pacer' @@ -94,7 +94,7 @@ const rateLimiter = createRateLimiter( ## Provider -The Solid Adapter provides a `PacerProvider` component that you can use to provide default options to all instances of pacer utilities within your component tree. +The `PacerProvider` component sets default options for every Pacer utility instance in its component tree. ```tsx import { PacerProvider } from '@tanstack/solid-pacer' @@ -111,17 +111,17 @@ import { PacerProvider } from '@tanstack/solid-pacer' ``` -All hooks within the provider will automatically use these default options, which can be overridden on a per-hook basis. +Hooks inside the provider use these defaults. Options passed to an individual hook override them. -## Subscribing to State +## Subscribing to state The Solid Adapter supports subscribing to state changes in two ways: -### Using the Subscribe Component +### Using the Subscribe component -Use the `Subscribe` component to subscribe to state changes deep in your component tree without needing to pass a selector to the hook. This is ideal when you want to subscribe to state in child components. +Use the `Subscribe` component to read state deep in the component tree without passing a selector to the hook. -**Note:** In Solid, the `Subscribe` component provides an accessor (signal) to the selected state. You must call `state()` to access the value. +In Solid, the `Subscribe` component provides an accessor (signal) to the selected state, so call `state()` to read the value. ```tsx import { createRateLimiter } from '@tanstack/solid-pacer' @@ -153,13 +153,13 @@ function ApiComponent() { } ``` -### Using the Selector Parameter +### Using the selector parameter -The `selector` parameter allows you to specify which state changes will trigger reactive updates at the hook level, optimizing performance by preventing unnecessary updates when irrelevant state changes occur. +The `selector` parameter controls which state changes trigger reactive updates. State you do not select never causes an update. -**By default, `hook.state` is empty (`{}`) as the selector is empty by default.** You must opt-in to state tracking by providing a selector function. +Without a selector, `hook.state` is an empty object (`{}`). Pass a selector function to opt in to state tracking. -**Note:** In Solid, `hook.state` is an accessor (signal). You must call `hook.state()` to access the value. +In Solid, `hook.state` is an accessor (signal), so call `hook.state()` to read the value. ```tsx import { createDebouncer } from '@tanstack/solid-pacer' @@ -193,7 +193,7 @@ For more details on state management and available state properties, see the ind ## Examples -### Debouncer Example +### Debouncer example ```tsx import { createDebouncer } from '@tanstack/solid-pacer' @@ -216,7 +216,7 @@ function SearchComponent() { } ``` -### Async Queuer Example +### Async queuer example ```tsx import { createAsyncQueuer } from '@tanstack/solid-pacer' @@ -249,7 +249,7 @@ function UploadComponent() { } ``` -### Rate Limiter Example +### Rate limiter example ```tsx import { createRateLimiter } from '@tanstack/solid-pacer' diff --git a/docs/guides/which-pacer-utility-should-i-choose.md b/docs/guides/which-pacer-utility-should-i-choose.md index b6002dfd..4557bc9d 100644 --- a/docs/guides/which-pacer-utility-should-i-choose.md +++ b/docs/guides/which-pacer-utility-should-i-choose.md @@ -19,7 +19,7 @@ TanStack Pacer provides five strategies for controlling when operations run. The ### Only the final value matters -Use a [debouncer](./debouncing.md). Every call restarts a timer, and the most recent call runs after the activity becomes quiet. +Use a [debouncer](./debouncing.md). Every call restarts a timer, and the most recent call runs once the calls go quiet. ### Work should continue at a steady pace diff --git a/docs/installation.md b/docs/installation.md index 2c37f330..3680eb69 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -3,7 +3,7 @@ title: Installation id: installation --- -TanStack Pacer is compatible with various front-end frameworks. Install the corresponding adapter for your framework using your preferred package manager: +Install the adapter for your framework with your preferred package manager: @@ -13,10 +13,10 @@ angular: @tanstack/angular-pacer -Each framework package re-exports everything from the core `@tanstack/pacer` package, so there is no need to install the core package separately. +Each framework package re-exports everything from the core `@tanstack/pacer` package, so you do not need to install the core package separately. > [!NOTE] -> If you are not using a framework, you can install the core `@tanstack/pacer` package directly for use with vanilla JavaScript. +> Not using a framework? Install the core `@tanstack/pacer` package directly for vanilla JavaScript. @@ -24,13 +24,13 @@ Each framework package re-exports everything from the core `@tanstack/pacer` pac ## Devtools -Developer tools are available using [TanStack Devtools](https://tanstack.com/devtools/latest). Install the devtools adapter and the Pacer devtools plugin as dev dependencies to inspect and monitor your pacers. +Developer tools are available using [TanStack Devtools](https://tanstack.com/devtools/latest). Install the devtools adapter and the Pacer devtools plugin as dev dependencies to inspect your pacers at runtime. # Solid ## Devtools -Developer tools are available using [TanStack Devtools](https://tanstack.com/devtools/latest). Install the devtools adapter and the Pacer devtools plugin as dev dependencies to inspect and monitor your pacers. +Developer tools are available using [TanStack Devtools](https://tanstack.com/devtools/latest). Install the devtools adapter and the Pacer devtools plugin as dev dependencies to inspect your pacers at runtime. @@ -47,10 +47,10 @@ solid: @tanstack/solid-pacer-devtools # React -See the [devtools](./devtools) documentation for more information on how to set up and use the Pacer devtools. +See the [devtools](./devtools) page for setup and usage. # Solid -See the [devtools](./devtools) documentation for more information on how to set up and use the Pacer devtools. +See the [devtools](./devtools) page for setup and usage. \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md index 97c012a2..22f70b9d 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -3,7 +3,7 @@ title: Overview id: overview --- -TanStack Pacer is a library focused on providing high-quality utilities for controlling function execution timing in your applications. While similar utilities exist elsewhere, we aim to get all the important details right - including ***type-safety***, ***tree-shaking***, and a consistent and ***intuitive API***. By focusing on these fundamentals and making them available in a ***framework agnostic*** way, we hope to make these utilities and patterns more commonplace in your applications. Proper execution control is often an afterthought in application development, leading to performance issues, race conditions, and poor user experiences that could have been prevented. TanStack Pacer helps you implement these critical patterns correctly from the start! +TanStack Pacer is a library of utilities for controlling when functions run: debouncing, throttling, rate limiting, queuing, and batching. Plenty of libraries ship a `debounce` helper. We built Pacer because we kept needing the details those one-liners skip: full type safety, tree-shaking, cancellation, pending state you can render, and one consistent API across all five patterns and every framework adapter. Execution timing is usually an afterthought until a race condition or a hammered API forces the issue. Pacer's job is to make the correct pattern the easy one to reach for. > [!IMPORTANT] > TanStack Pacer is currently in **beta** and its API is still subject to change. @@ -17,57 +17,53 @@ Many of the ideas (and code) for TanStack Pacer are not new. In fact, many of th ## Features > [!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. +> TanStack Pacer is mostly a client-side library today, but we are designing the core so it can work on the server 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 + - Wait until calls stop, then run the latest one + - Sync and async variations with promise support and error handling + - 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. + - Limit how often a function fires, with evenly spaced executions + - Sync and async variations with promise support and error handling + - 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 + - Cap how many times a function fires within a time window + - Sync and async variations with promise support and error handling + - Fixed or sliding window behavior - **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 + - Run every call, in order, without losing any + - FIFO, LIFO, and priority ordering + - Configurable wait times and concurrency limits + - Start, stop, and item expiration controls - **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 + - Collect items and process them together in one call + - Trigger a batch by size, time, whichever comes first, or a custom condition +- **Async Support** + - Every utility has an async version that awaits results + - Optional error, success, and settled callbacks + - Retry and abort support - **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 + - TanStack Store under the hood, with fine-grained reactivity + - Works alongside whatever state management you already use + - Some utilities, like rate limiting and queuing, can persist state to local or session storage - **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. + - Pre-built hooks like `useDebouncedCallback`, `useThrottledValue`, and `useQueuedState` cut down on boilerplate + - Several layers of abstraction, from a bare callback to a full instance API - **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 + - Your functions are always called with the correct argument types + - Generic utilities that adapt to your own types - **Framework Adapters** - - React, Solid, and more + - React, Preact, Solid, and Angular - **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. + - Tree-shaking works by default, and each utility also has its own deep import, so a library can pull in one utility without inflating its bundle-phobia report -## Interactive Comparison Demo +## Interactive comparison demo -Each utility is designed to be used in a specific way, and each utility has its own unique behavior. - -See how each utility behaves with this interactive comparison. Move the range slider to observe the differences between debouncing, throttling, rate limiting, queuing, and batching: +The fastest way to understand the five utilities is to watch them handle the same input. Move the range slider and compare how debouncing, throttling, rate limiting, queuing, and batching each respond: ## Pacer Lite -Pacer Lite (`@tanstack/pacer-lite`) is a stripped down version of the core TanStack Pacer library. It is designed to be used in libraries and npm packages that need minimal overhead, and no reactivity features. The Lite version of each utility has the same core functionality of its core counterpart, but is stripped down to have a slightly smaller API surface and a smaller bundle size. Pacer Lite lacks reactivity features, framework adapters, devtools support, and some of the advanced options that the core utilities have. If that sounds interesting to you, you can feel free to try it out! \ No newline at end of file +Pacer Lite (`@tanstack/pacer-lite`) is a stripped-down version of the core library, meant for npm packages that want minimal overhead. Each Lite utility behaves the same as its full counterpart but drops reactivity, framework adapters, devtools support, and some advanced options in exchange for a smaller bundle. If you are building an application, use the regular packages. Reach for Lite when you are publishing a library and every kilobyte counts. \ No newline at end of file diff --git a/docs/quick-start.md b/docs/quick-start.md index d5264550..98508349 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -7,19 +7,19 @@ id: quick-start Don't have TanStack Pacer installed yet? See the [Installation](./installation.md) page for instructions. -## Understanding Which Pacer Utility to Use +## Which utility do you need? -Still learning what TanStack Pacer is and how it can help your application? See the [Which Pacer Utility Should I Choose?](./guides/which-pacer-utility-should-i-choose.md) guide for help choosing which Pacer utility to use. The TanStack Pacer libraries have 5 core utilities, but also quite a few flexible ways to use each utility. Famarilizing yourself with the above guide will help you choose the right utility for your use case. +Not sure whether you want a debouncer, throttler, rate limiter, queuer, or batcher? Start with [Which Pacer Utility Should I Choose?](./guides/which-pacer-utility-should-i-choose.md). It compares all five and explains the sync, async, and framework-specific variations of each. -## API References +## API references -See the [API References](./reference/index.md) page for the full list of API references for each Pacer utility. +See the [API References](./reference/index.md) page for the full API of each utility. -## Basic Usage +## Basic usage -If you are using vanilla JavaScript, there are core classes and functions that you can use from the core pacer package. +In vanilla JavaScript, use the classes and functions from the core pacer package directly. -### Class Usage +### Class usage ```ts import { Debouncer } from '@tanstack/pacer' // class @@ -31,7 +31,7 @@ debouncer.cancel() // cancel the debounced function debouncer.flush() // flush the debounced function ``` -### Function Usage +### Function usage ```ts import { debounce } from '@tanstack/pacer' // function @@ -41,9 +41,9 @@ const debouncedFn = debounce(fn, options) debouncedFn(args) // execute the debounced function ``` -### Framework Hook Usage (Recommended) +### Framework hook usage (recommended) -If you are using a framework adapter like React, you can use the `useDebouncer` hook to create a debounced function. +With a framework adapter like React, the `useDebouncer` hook creates a debounced function and cleans it up with the component lifecycle. ```tsx import { useDebouncer } from '@tanstack/react-pacer' @@ -55,9 +55,9 @@ debouncer.cancel() // cancel the debounced function debouncer.flush() // flush the debounced function ``` -### Option Helpers +### Option helpers -If want a type-safe way to define common options for pacer utilities, TanStack Pacer provides option helpers for each utility. +Each utility has an option helper for defining shared options with full type checking, so you can reuse them across instances. ```ts import { debouncerOptions } from '@tanstack/pacer' @@ -73,7 +73,7 @@ const debouncer = new Debouncer(fn, { ...commonDebouncerOptions, key: 'myDebounc ### Providers -In each framework adapter, there is a provider component that you can use to provide default options to all instances of a pacer utility. +Each framework adapter has a provider component for setting default options on every instance of a utility. ```tsx import { PacerProvider } from '@tanstack/react-pacer' @@ -86,4 +86,4 @@ import { PacerProvider } from '@tanstack/react-pacer' ### Devtools -TanStack Pacer provides an official TanStack Devtools integration for each framework adapter. See the [Devtools](./devtools.md) documentation for more information on how to set up and use the Pacer devtools. \ No newline at end of file +Each framework adapter has an official TanStack Devtools integration. See the [Devtools](./devtools.md) page for setup instructions. \ No newline at end of file diff --git a/packages/angular-pacer/README.md b/packages/angular-pacer/README.md index c9747ef3..03710e4e 100644 --- a/packages/angular-pacer/README.md +++ b/packages/angular-pacer/README.md @@ -103,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim > [!NOTE] > You may know **TanStack Pacer** by our adapter names, too! > -> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer) -> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer) -> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer) -> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer) +> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react) +> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact) +> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid) +> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular) > - Svelte Pacer - needs a contributor! > - Vue Pacer - needs a contributor! diff --git a/packages/pacer-devtools/README.md b/packages/pacer-devtools/README.md index c9747ef3..03710e4e 100644 --- a/packages/pacer-devtools/README.md +++ b/packages/pacer-devtools/README.md @@ -103,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim > [!NOTE] > You may know **TanStack Pacer** by our adapter names, too! > -> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer) -> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer) -> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer) -> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer) +> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react) +> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact) +> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid) +> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular) > - Svelte Pacer - needs a contributor! > - Vue Pacer - needs a contributor! diff --git a/packages/pacer-lite/README.md b/packages/pacer-lite/README.md index c9747ef3..03710e4e 100644 --- a/packages/pacer-lite/README.md +++ b/packages/pacer-lite/README.md @@ -103,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim > [!NOTE] > You may know **TanStack Pacer** by our adapter names, too! > -> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer) -> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer) -> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer) -> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer) +> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react) +> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact) +> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid) +> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular) > - Svelte Pacer - needs a contributor! > - Vue Pacer - needs a contributor! diff --git a/packages/pacer/README.md b/packages/pacer/README.md index c9747ef3..03710e4e 100644 --- a/packages/pacer/README.md +++ b/packages/pacer/README.md @@ -103,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim > [!NOTE] > You may know **TanStack Pacer** by our adapter names, too! > -> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer) -> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer) -> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer) -> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer) +> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react) +> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact) +> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid) +> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular) > - Svelte Pacer - needs a contributor! > - Vue Pacer - needs a contributor! diff --git a/packages/preact-pacer-devtools/README.md b/packages/preact-pacer-devtools/README.md index c9747ef3..03710e4e 100644 --- a/packages/preact-pacer-devtools/README.md +++ b/packages/preact-pacer-devtools/README.md @@ -103,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim > [!NOTE] > You may know **TanStack Pacer** by our adapter names, too! > -> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer) -> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer) -> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer) -> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer) +> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react) +> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact) +> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid) +> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular) > - Svelte Pacer - needs a contributor! > - Vue Pacer - needs a contributor! diff --git a/packages/react-pacer-devtools/README.md b/packages/react-pacer-devtools/README.md index c9747ef3..03710e4e 100644 --- a/packages/react-pacer-devtools/README.md +++ b/packages/react-pacer-devtools/README.md @@ -103,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim > [!NOTE] > You may know **TanStack Pacer** by our adapter names, too! > -> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer) -> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer) -> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer) -> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer) +> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react) +> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact) +> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid) +> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular) > - Svelte Pacer - needs a contributor! > - Vue Pacer - needs a contributor! diff --git a/packages/react-pacer/README.md b/packages/react-pacer/README.md index c9747ef3..03710e4e 100644 --- a/packages/react-pacer/README.md +++ b/packages/react-pacer/README.md @@ -103,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim > [!NOTE] > You may know **TanStack Pacer** by our adapter names, too! > -> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer) -> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer) -> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer) -> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer) +> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react) +> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact) +> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid) +> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular) > - Svelte Pacer - needs a contributor! > - Vue Pacer - needs a contributor! diff --git a/packages/solid-pacer-devtools/README.md b/packages/solid-pacer-devtools/README.md index c9747ef3..03710e4e 100644 --- a/packages/solid-pacer-devtools/README.md +++ b/packages/solid-pacer-devtools/README.md @@ -103,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim > [!NOTE] > You may know **TanStack Pacer** by our adapter names, too! > -> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer) -> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer) -> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer) -> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer) +> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react) +> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact) +> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid) +> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular) > - Svelte Pacer - needs a contributor! > - Vue Pacer - needs a contributor! diff --git a/packages/solid-pacer/README.md b/packages/solid-pacer/README.md index c9747ef3..03710e4e 100644 --- a/packages/solid-pacer/README.md +++ b/packages/solid-pacer/README.md @@ -103,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim > [!NOTE] > You may know **TanStack Pacer** by our adapter names, too! > -> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer) -> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer) -> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer) -> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer) +> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react) +> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact) +> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid) +> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular) > - Svelte Pacer - needs a contributor! > - Vue Pacer - needs a contributor!