update quick start guide

Author: KevinVandy

docs/framework/react/adapter.md

@@ -34,3 +34,173 @@ 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
+
+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.
+
+### Debouncer Options
+
+```tsx
+import { useDebouncer } from '@tanstack/react-pacer'
+import { debouncerOptions } from '@tanstack/pacer'
+
+const commonDebouncerOptions = debouncerOptions({
+  wait: 1000,
+  leading: false,
+  trailing: true,
+})
+
+const debouncer = useDebouncer(
+  (query: string) => fetchSearchResults(query),
+  { ...commonDebouncerOptions, key: 'searchDebouncer' }
+)
+```
+
+### Queuer Options
+
+```tsx
+import { useQueuer } from '@tanstack/react-pacer'
+import { queuerOptions } from '@tanstack/pacer'
+
+const commonQueuerOptions = queuerOptions({
+  concurrency: 3,
+  addItemsTo: 'back',
+})
+
+const queuer = useQueuer(
+  (item: string) => processItem(item),
+  { ...commonQueuerOptions, key: 'itemQueuer' }
+)
+```
+
+### Rate Limiter Options
+
+```tsx
+import { useRateLimiter } from '@tanstack/react-pacer'
+import { rateLimiterOptions } from '@tanstack/pacer'
+
+const commonRateLimiterOptions = rateLimiterOptions({
+  limit: 5,
+  window: 60000,
+  windowType: 'sliding',
+})
+
+const rateLimiter = useRateLimiter(
+  (data: string) => sendApiRequest(data),
+  { ...commonRateLimiterOptions, key: 'apiRateLimiter' }
+)
+```
+
+## 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.
+
+```tsx
+import { PacerProvider } from '@tanstack/react-pacer'
+
+// Set default options for react-pacer instances
+<PacerProvider
+  defaultOptions={{
+    debouncer: { wait: 1000 },
+    queuer: { concurrency: 3 },
+    rateLimiter: { limit: 5, window: 60000 },
+  }}
+>
+  <App />
+</PacerProvider>
+```
+
+All hooks within the provider will automatically use these default options, which can be overridden on a per-hook basis.
+
+## Examples
+
+### Debouncer Example
+
+```tsx
+import { useDebouncer } from '@tanstack/react-pacer'
+
+function SearchComponent() {
+  const debouncer = useDebouncer(
+    (query: string) => {
+      console.log('Searching for:', query)
+      // Perform search
+    },
+    { wait: 500 }
+  )
+
+  return (
+    <input
+      onChange={(e) => debouncer.maybeExecute(e.target.value)}
+      placeholder="Search..."
+    />
+  )
+}
+```
+
+### Queuer Example
+
+```tsx
+import { useQueuer } from '@tanstack/react-pacer'
+
+function UploadComponent() {
+  const queuer = useQueuer(
+    async (file: File) => {
+      await uploadFile(file)
+    },
+    { concurrency: 3 }
+  )
+
+  const handleFileSelect = (files: FileList) => {
+    Array.from(files).forEach((file) => {
+      queuer.add(file)
+    })
+  }
+
+  return (
+    <input
+      type="file"
+      multiple
+      onChange={(e) => {
+        if (e.target.files) {
+          handleFileSelect(e.target.files)
+        }
+      }}
+    />
+  )
+}
+```
+
+### Rate Limiter Example
+
+```tsx
+import { useRateLimiter } from '@tanstack/react-pacer'
+
+function ApiComponent() {
+  const rateLimiter = useRateLimiter(
+    (data: string) => {
+      return fetch('/api/endpoint', {
+        method: 'POST',
+        body: JSON.stringify({ data }),
+      })
+    },
+    {
+      limit: 5,
+      window: 60000,
+      windowType: 'sliding',
+      onReject: () => {
+        alert('Rate limit reached. Please try again later.')
+      },
+    }
+  )
+
+  const handleSubmit = () => {
+    const remaining = rateLimiter.getRemainingInWindow()
+    if (remaining > 0) {
+      rateLimiter.maybeExecute('some data')
+    }
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+

docs/quick-start.md

@@ -3,11 +3,87 @@ title: Quick Start
 id: quick-start
 ---
 
-This page contains links to the the highest-level example for each of Tanstack Pacer's 4 core concepts:
+## Installation
 
- * [Debouncing](./guides/debouncing.md): [`useDebouncedValue`](../examples/react/useDebouncedValue/)
- * [Throttling](./guides/throttling.md): [`useThrottledValue`](../examples/react/useThrottledValue/)
- * [Rate-limiting](./guides/rate-limiting.md): [`useRateLimitedValue`](../examples/react/useRateLimitedValue/)
- * [Queueing](./guides/queueing.md): [`useQueuerState`](../examples/react/useQueuerState/)
+Don't have TanStack Pacer installed yet? See the [Installation](../installation.md) page for instructions.
 
-If you're looking lower-level examples or `async` examples, take a look at our catalog of examples.
+## Understanding Which Pacer Utility to Use
+
+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.
+
+## API References
+
+See the [API References](../reference/index.md) page for the full list of API references for each Pacer utility.
+
+## Basic Usage
+
+If you are using vanilla JavaScript, there are core classes and functions that you can use from the core pacer package.
+
+### Class Usage
+
+```ts
+import { Debouncer } from '@tanstack/pacer' // class
+
+const debouncer = new Debouncer(fn, options)
+
+debouncer.maybeExecute(args) // execute the debounced function
+debouncer.cancel() // cancel the debounced function
+debouncer.flush() // flush the debounced function
+```
+
+### Function Usage
+
+```ts
+import { debounce } from '@tanstack/pacer' // function
+
+const debouncedFn = debounce(fn, options)
+
+debouncedFn(args) // execute the debounced function
+```
+
+### Framework Hook Usage (Recommended)
+
+If you are using a framework adapter like React, you can use the `useDebouncer` hook to create a debounced function.
+
+```tsx
+import { useDebouncer } from '@tanstack/react-pacer'
+
+const debouncer = useDebouncer(fn, options) // recommended
+
+debouncer.maybeExecute(args) // execute the debounced function
+debouncer.cancel() // cancel the debounced function
+debouncer.flush() // flush the debounced function
+```
+
+### Option Helpers
+
+If want a type-safe way to define common options for pacer utilities, TanStack Pacer provides option helpers for each utility.
+
+```ts
+import { debouncerOptions } from '@tanstack/pacer'
+
+const commonDebouncerOptions = debouncerOptions({
+  wait: 1000,
+  leading: false,
+  trailing: true,
+})
+
+const debouncer = new Debouncer(fn, { ...commonDebouncerOptions, key: 'myDebouncer' })
+```
+
+### 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.
+
+```tsx
+import { PacerProvider } from '@tanstack/react-pacer'
+
+// set default options for react-pacer instances
+<PacerProvider defaultOptions={{ debouncer: { wait: 1000 } }}>
+  <App />
+</PacerProvider>
+```
+
+### 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.