feat: new onUnmount option (#158)

* feat: new onUnmount option

* ci: apply automated fixes

* make onUnmount a framework specific option

* clean up code

* auto abort in async utils

* make angular unmount behavior consistent

* fix changeset

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: KevinVandy

.changeset/onunmount-and-lint-fix.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/pacer': minor
+'@tanstack/react-pacer': minor
+'@tanstack/preact-pacer': minor
+'@tanstack/solid-pacer': minor
+'@tanstack/angular-pacer': minor
+---
+
+feat: Add optional `onUnmount` callback to Debouncer, Throttler, Batcher, Queuer and async variants for custom cleanup.

docs/config.json

@@ -207,6 +207,14 @@
         {
           "label": "react",
           "children": [
+            {
+              "label": "ReactDebouncerOptions",
+              "to": "framework/react/reference/interfaces/ReactDebouncerOptions"
+            },
+            {
+              "label": "ReactAsyncDebouncerOptions",
+              "to": "framework/react/reference/interfaces/ReactAsyncDebouncerOptions"
+            },
             {
               "label": "ReactDebouncer",
               "to": "framework/react/reference/interfaces/ReactDebouncer"
@@ -244,6 +252,14 @@
         {
           "label": "solid",
           "children": [
+            {
+              "label": "SolidDebouncerOptions",
+              "to": "framework/solid/reference/interfaces/SolidDebouncerOptions"
+            },
+            {
+              "label": "SolidAsyncDebouncerOptions",
+              "to": "framework/solid/reference/interfaces/SolidAsyncDebouncerOptions"
+            },
             {
               "label": "SolidDebouncer",
               "to": "framework/solid/reference/interfaces/SolidDebouncer"
@@ -273,6 +289,14 @@
         {
           "label": "preact",
           "children": [
+            {
+              "label": "PreactDebouncerOptions",
+              "to": "framework/preact/reference/interfaces/PreactDebouncerOptions"
+            },
+            {
+              "label": "PreactAsyncDebouncerOptions",
+              "to": "framework/preact/reference/interfaces/PreactAsyncDebouncerOptions"
+            },
             {
               "label": "PreactDebouncer",
               "to": "framework/preact/reference/interfaces/PreactDebouncer"
@@ -310,6 +334,14 @@
         {
           "label": "angular",
           "children": [
+            {
+              "label": "AngularDebouncerOptions",
+              "to": "framework/angular/reference/interfaces/AngularDebouncerOptions"
+            },
+            {
+              "label": "AngularAsyncDebouncerOptions",
+              "to": "framework/angular/reference/interfaces/AngularAsyncDebouncerOptions"
+            },
             {
               "label": "AngularDebouncer",
               "to": "framework/angular/reference/interfaces/AngularDebouncer"
@@ -388,6 +420,14 @@
         {
           "label": "react",
           "children": [
+            {
+              "label": "ReactThrottlerOptions",
+              "to": "framework/react/reference/interfaces/ReactThrottlerOptions"
+            },
+            {
+              "label": "ReactAsyncThrottlerOptions",
+              "to": "framework/react/reference/interfaces/ReactAsyncThrottlerOptions"
+            },
             {
               "label": "ReactThrottler",
               "to": "framework/react/reference/interfaces/ReactThrottler"
@@ -425,6 +465,14 @@
         {
           "label": "solid",
           "children": [
+            {
+              "label": "SolidThrottlerOptions",
+              "to": "framework/solid/reference/interfaces/SolidThrottlerOptions"
+            },
+            {
+              "label": "SolidAsyncThrottlerOptions",
+              "to": "framework/solid/reference/interfaces/SolidAsyncThrottlerOptions"
+            },
             {
               "label": "SolidThrottler",
               "to": "framework/solid/reference/interfaces/SolidThrottler"
@@ -454,6 +502,14 @@
         {
           "label": "preact",
           "children": [
+            {
+              "label": "PreactThrottlerOptions",
+              "to": "framework/preact/reference/interfaces/PreactThrottlerOptions"
+            },
+            {
+              "label": "PreactAsyncThrottlerOptions",
+              "to": "framework/preact/reference/interfaces/PreactAsyncThrottlerOptions"
+            },
             {
               "label": "PreactThrottler",
               "to": "framework/preact/reference/interfaces/PreactThrottler"
@@ -491,6 +547,14 @@
         {
           "label": "angular",
           "children": [
+            {
+              "label": "AngularThrottlerOptions",
+              "to": "framework/angular/reference/interfaces/AngularThrottlerOptions"
+            },
+            {
+              "label": "AngularAsyncThrottlerOptions",
+              "to": "framework/angular/reference/interfaces/AngularAsyncThrottlerOptions"
+            },
             {
               "label": "AngularThrottler",
               "to": "framework/angular/reference/interfaces/AngularThrottler"
@@ -672,6 +736,14 @@
         {
           "label": "angular",
           "children": [
+            {
+              "label": "AngularRateLimiterOptions",
+              "to": "framework/angular/reference/interfaces/AngularRateLimiterOptions"
+            },
+            {
+              "label": "AngularAsyncRateLimiterOptions",
+              "to": "framework/angular/reference/interfaces/AngularAsyncRateLimiterOptions"
+            },
             {
               "label": "AngularRateLimiter",
               "to": "framework/angular/reference/interfaces/AngularRateLimiter"
@@ -750,6 +822,14 @@
         {
           "label": "react",
           "children": [
+            {
+              "label": "ReactQueuerOptions",
+              "to": "framework/react/reference/interfaces/ReactQueuerOptions"
+            },
+            {
+              "label": "ReactAsyncQueuerOptions",
+              "to": "framework/react/reference/interfaces/ReactAsyncQueuerOptions"
+            },
             {
               "label": "ReactQueuer",
               "to": "framework/react/reference/interfaces/ReactQueuer"
@@ -783,6 +863,14 @@
         {
           "label": "solid",
           "children": [
+            {
+              "label": "SolidQueuerOptions",
+              "to": "framework/solid/reference/interfaces/SolidQueuerOptions"
+            },
+            {
+              "label": "SolidAsyncQueuerOptions",
+              "to": "framework/solid/reference/interfaces/SolidAsyncQueuerOptions"
+            },
             {
               "label": "SolidQueuer",
               "to": "framework/solid/reference/interfaces/SolidQueuer"
@@ -808,6 +896,14 @@
         {
           "label": "preact",
           "children": [
+            {
+              "label": "PreactQueuerOptions",
+              "to": "framework/preact/reference/interfaces/PreactQueuerOptions"
+            },
+            {
+              "label": "PreactAsyncQueuerOptions",
+              "to": "framework/preact/reference/interfaces/PreactAsyncQueuerOptions"
+            },
             {
               "label": "PreactQueuer",
               "to": "framework/preact/reference/interfaces/PreactQueuer"
@@ -841,6 +937,14 @@
         {
           "label": "angular",
           "children": [
+            {
+              "label": "AngularQueuerOptions",
+              "to": "framework/angular/reference/interfaces/AngularQueuerOptions"
+            },
+            {
+              "label": "AngularAsyncQueuerOptions",
+              "to": "framework/angular/reference/interfaces/AngularAsyncQueuerOptions"
+            },
             {
               "label": "AngularQueuer",
               "to": "framework/angular/reference/interfaces/AngularQueuer"
@@ -915,6 +1019,14 @@
         {
           "label": "react",
           "children": [
+            {
+              "label": "ReactBatcherOptions",
+              "to": "framework/react/reference/interfaces/ReactBatcherOptions"
+            },
+            {
+              "label": "ReactAsyncBatcherOptions",
+              "to": "framework/react/reference/interfaces/ReactAsyncBatcherOptions"
+            },
             {
               "label": "ReactBatcher",
               "to": "framework/react/reference/interfaces/ReactBatcher"
@@ -944,6 +1056,14 @@
         {
           "label": "solid",
           "children": [
+            {
+              "label": "SolidBatcherOptions",
+              "to": "framework/solid/reference/interfaces/SolidBatcherOptions"
+            },
+            {
+              "label": "SolidAsyncBatcherOptions",
+              "to": "framework/solid/reference/interfaces/SolidAsyncBatcherOptions"
+            },
             {
               "label": "SolidBatcher",
               "to": "framework/solid/reference/interfaces/SolidBatcher"
@@ -965,6 +1085,14 @@
         {
           "label": "preact",
           "children": [
+            {
+              "label": "PreactBatcherOptions",
+              "to": "framework/preact/reference/interfaces/PreactBatcherOptions"
+            },
+            {
+              "label": "PreactAsyncBatcherOptions",
+              "to": "framework/preact/reference/interfaces/PreactAsyncBatcherOptions"
+            },
             {
               "label": "PreactBatcher",
               "to": "framework/preact/reference/interfaces/PreactBatcher"
@@ -994,6 +1122,14 @@
         {
           "label": "angular",
           "children": [
+            {
+              "label": "AngularBatcherOptions",
+              "to": "framework/angular/reference/interfaces/AngularBatcherOptions"
+            },
+            {
+              "label": "AngularAsyncBatcherOptions",
+              "to": "framework/angular/reference/interfaces/AngularAsyncBatcherOptions"
+            },
             {
               "label": "AngularBatcher",
               "to": "framework/angular/reference/interfaces/AngularBatcher"

docs/framework/angular/reference/functions/injectAsyncBatcher.md

@@ -12,7 +12,7 @@ function injectAsyncBatcher<TValue, TSelected>(
 selector): AngularAsyncBatcher<TValue, TSelected>;
 ```
 
-Defined in: [async-batcher/injectAsyncBatcher.ts:69](https://github.com/TanStack/pacer/blob/main/packages/angular-pacer/src/async-batcher/injectAsyncBatcher.ts#L69)
+Defined in: [async-batcher/injectAsyncBatcher.ts:96](https://github.com/TanStack/pacer/blob/main/packages/angular-pacer/src/async-batcher/injectAsyncBatcher.ts#L96)
 
 An Angular function that creates and manages an AsyncBatcher instance.
 
@@ -32,6 +32,20 @@ optimizing performance by preventing unnecessary updates when irrelevant state c
 tracking by providing a selector function. This prevents unnecessary updates and gives you
 full control over when your component tracks state changes.
 
+## Cleanup on Destroy
+
+By default, the function cancels any pending batch and aborts in-flight work when the component is destroyed.
+Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+
+```ts
+const batcher = injectAsyncBatcher(fn, {
+  maxSize: 10,
+  onUnmount: (b) => b.flush()
+});
+```
+
+When using onUnmount with flush, guard your callbacks since the component may already be destroyed.
+
 ## Type Parameters
 
 ### TValue
@@ -51,7 +65,7 @@ full control over when your component tracks state changes.
 
 ### options
 
-`AsyncBatcherOptions`\<`TValue`\> = `{}`
+[`AngularAsyncBatcherOptions`](../interfaces/AngularAsyncBatcherOptions.md)\<`TValue`, `TSelected`\> = `{}`
 
 ### selector
 

docs/framework/angular/reference/functions/injectAsyncDebouncer.md

@@ -12,7 +12,7 @@ function injectAsyncDebouncer<TFn, TSelected>(
 selector): AngularAsyncDebouncer<TFn, TSelected>;
 ```
 
-Defined in: [async-debouncer/injectAsyncDebouncer.ts:92](https://github.com/TanStack/pacer/blob/main/packages/angular-pacer/src/async-debouncer/injectAsyncDebouncer.ts#L92)
+Defined in: [async-debouncer/injectAsyncDebouncer.ts:119](https://github.com/TanStack/pacer/blob/main/packages/angular-pacer/src/async-debouncer/injectAsyncDebouncer.ts#L119)
 
 An Angular function that creates and manages an AsyncDebouncer instance.
 
@@ -47,6 +47,20 @@ Available state properties:
 - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing' | 'settled')
 - `successCount`: Number of function executions that have completed successfully
 
+## Cleanup on Destroy
+
+By default, the function cancels any pending execution and aborts in-flight work when the component is destroyed.
+Use the `onUnmount` option to customize this. For example, to flush pending work instead:
+
+```ts
+const debouncer = injectAsyncDebouncer(fn, {
+  wait: 500,
+  onUnmount: (d) => d.flush()
+});
+```
+
+When using onUnmount with flush, guard your callbacks since the component may already be destroyed.
+
 ## Type Parameters
 
 ### TFn
@@ -66,7 +80,7 @@ Available state properties:
 
 ### options
 
-`AsyncDebouncerOptions`\<`TFn`\>
+[`AngularAsyncDebouncerOptions`](../interfaces/AngularAsyncDebouncerOptions.md)\<`TFn`, `TSelected`\>
 
 ### selector
 

docs/framework/angular/reference/functions/injectAsyncQueuer.md

@@ -12,7 +12,7 @@ function injectAsyncQueuer<TValue, TSelected>(
 selector): AngularAsyncQueuer<TValue, TSelected>;
 ```
 
-Defined in: [async-queuer/injectAsyncQueuer.ts:69](https://github.com/TanStack/pacer/blob/main/packages/angular-pacer/src/async-queuer/injectAsyncQueuer.ts#L69)
+Defined in: [async-queuer/injectAsyncQueuer.ts:96](https://github.com/TanStack/pacer/blob/main/packages/angular-pacer/src/async-queuer/injectAsyncQueuer.ts#L96)
 
 An Angular function that creates and manages an AsyncQueuer instance.
 
@@ -32,6 +32,20 @@ optimizing performance by preventing unnecessary updates when irrelevant state c
 tracking by providing a selector function. This prevents unnecessary updates and gives you
 full control over when your component tracks state changes.
 
+## Cleanup on Destroy
+
+By default, the function stops the queuer and aborts in-flight work when the component is destroyed.
+Use the `onUnmount` option to customize this. For example, to flush pending items instead:
+
+```ts
+const queuer = injectAsyncQueuer(fn, {
+  concurrency: 2,
+  onUnmount: (q) => q.flush()
+});
+```
+
+When using onUnmount with flush, guard your callbacks since the component may already be destroyed.
+
 ## Type Parameters
 
 ### TValue
@@ -51,7 +65,7 @@ full control over when your component tracks state changes.
 
 ### options
 
-`AsyncQueuerOptions`\<`TValue`\> = `{}`
+[`AngularAsyncQueuerOptions`](../interfaces/AngularAsyncQueuerOptions.md)\<`TValue`, `TSelected`\> = `{}`
 
 ### selector