@tanstack/react-db 0.1.36 → 0.1.38

package/dist/cjs/index.cjs

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const useLiveQuery = require("./useLiveQuery.cjs");
+const usePacedMutations = require("./usePacedMutations.cjs");
 const useLiveInfiniteQuery = require("./useLiveInfiniteQuery.cjs");
 const db = require("@tanstack/db");
 exports.useLiveQuery = useLiveQuery.useLiveQuery;
+exports.usePacedMutations = usePacedMutations.usePacedMutations;
 exports.useLiveInfiniteQuery = useLiveInfiniteQuery.useLiveInfiniteQuery;
 Object.defineProperty(exports, "createTransaction", {
   enumerable: true,

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -1,4 +1,5 @@
 export * from './useLiveQuery.cjs';
+export * from './usePacedMutations.cjs';
 export * from './useLiveInfiniteQuery.cjs';
 export * from '@tanstack/db';
 export type { Collection } from '@tanstack/db';

package/dist/cjs/usePacedMutations.cjs

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const db = require("@tanstack/db");
+function usePacedMutations(config) {
+  const onMutateRef = react.useRef(config.onMutate);
+  onMutateRef.current = config.onMutate;
+  const mutationFnRef = react.useRef(config.mutationFn);
+  mutationFnRef.current = config.mutationFn;
+  const stableOnMutate = react.useCallback((variables) => {
+    return onMutateRef.current(variables);
+  }, []);
+  const stableMutationFn = react.useCallback((params) => {
+    return mutationFnRef.current(params);
+  }, []);
+  const mutate = react.useMemo(() => {
+    return db.createPacedMutations({
+      ...config,
+      onMutate: stableOnMutate,
+      mutationFn: stableMutationFn
+    });
+  }, [
+    stableOnMutate,
+    stableMutationFn,
+    config.metadata,
+    // Serialize strategy to avoid recreating when object reference changes but values are same
+    JSON.stringify({
+      type: config.strategy._type,
+      options: config.strategy.options
+    })
+  ]);
+  const stableMutate = react.useCallback(mutate, [mutate]);
+  return stableMutate;
+}
+exports.usePacedMutations = usePacedMutations;
+//# sourceMappingURL=usePacedMutations.cjs.map

package/dist/cjs/usePacedMutations.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePacedMutations.cjs","sources":["../../src/usePacedMutations.ts"],"sourcesContent":["import { useCallback, useMemo, useRef } from \"react\"\nimport { createPacedMutations } from \"@tanstack/db\"\nimport type { PacedMutationsConfig, Transaction } from \"@tanstack/db\"\n\n/**\n * React hook for managing paced mutations with timing strategies.\n *\n * Provides optimistic mutations with pluggable strategies like debouncing,\n * queuing, or throttling. The optimistic updates are applied immediately via\n * `onMutate`, and the actual persistence is controlled by the strategy.\n *\n * @param config - Configuration including onMutate, mutationFn and strategy\n * @returns A mutate function that accepts variables and returns Transaction objects\n *\n * @example\n * ```tsx\n * // Debounced auto-save\n * function AutoSaveForm({ formId }: { formId: string }) {\n *   const mutate = usePacedMutations<string>({\n *     onMutate: (value) => {\n *       // Apply optimistic update immediately\n *       formCollection.update(formId, draft => {\n *         draft.content = value\n *       })\n *     },\n *     mutationFn: async ({ transaction }) => {\n *       await api.save(transaction.mutations)\n *     },\n *     strategy: debounceStrategy({ wait: 500 })\n *   })\n *\n *   const handleChange = async (value: string) => {\n *     const tx = mutate(value)\n *\n *     // Optional: await persistence or handle errors\n *     try {\n *       await tx.isPersisted.promise\n *       console.log('Saved!')\n *     } catch (error) {\n *       console.error('Save failed:', error)\n *     }\n *   }\n *\n *   return <textarea onChange={e => handleChange(e.target.value)} />\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Throttled slider updates\n * function VolumeSlider() {\n *   const mutate = usePacedMutations<number>({\n *     onMutate: (volume) => {\n *       settingsCollection.update('volume', draft => {\n *         draft.value = volume\n *       })\n *     },\n *     mutationFn: async ({ transaction }) => {\n *       await api.updateVolume(transaction.mutations)\n *     },\n *     strategy: throttleStrategy({ wait: 200 })\n *   })\n *\n *   return <input type=\"range\" onChange={e => mutate(+e.target.value)} />\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Debounce with leading/trailing for color picker (persist first + final only)\n * function ColorPicker() {\n *   const mutate = usePacedMutations<string>({\n *     onMutate: (color) => {\n *       themeCollection.update('primary', draft => {\n *         draft.color = color\n *       })\n *     },\n *     mutationFn: async ({ transaction }) => {\n *       await api.updateTheme(transaction.mutations)\n *     },\n *     strategy: debounceStrategy({ wait: 0, leading: true, trailing: true })\n *   })\n *\n *   return (\n *     <input\n *       type=\"color\"\n *       onChange={e => mutate(e.target.value)}\n *     />\n *   )\n * }\n * ```\n */\nexport function usePacedMutations<\n  TVariables = unknown,\n  T extends object = Record<string, unknown>,\n>(\n  config: PacedMutationsConfig<TVariables, T>\n): (variables: TVariables) => Transaction<T> {\n  // Keep refs to the latest callbacks so we can call them without recreating the instance\n  const onMutateRef = useRef(config.onMutate)\n  onMutateRef.current = config.onMutate\n\n  const mutationFnRef = useRef(config.mutationFn)\n  mutationFnRef.current = config.mutationFn\n\n  // Create stable wrappers that always call the latest version\n  const stableOnMutate = useCallback<typeof config.onMutate>((variables) => {\n    return onMutateRef.current(variables)\n  }, [])\n\n  const stableMutationFn = useCallback<typeof config.mutationFn>((params) => {\n    return mutationFnRef.current(params)\n  }, [])\n\n  // Create paced mutations instance with proper dependency tracking\n  // Serialize strategy for stable comparison since strategy objects are recreated on each render\n  const mutate = useMemo(() => {\n    return createPacedMutations<TVariables, T>({\n      ...config,\n      onMutate: stableOnMutate,\n      mutationFn: stableMutationFn,\n    })\n  }, [\n    stableOnMutate,\n    stableMutationFn,\n    config.metadata,\n    // Serialize strategy to avoid recreating when object reference changes but values are same\n    JSON.stringify({\n      type: config.strategy._type,\n      options: config.strategy.options,\n    }),\n  ])\n\n  // Return stable mutate callback\n  const stableMutate = useCallback(mutate, [mutate])\n\n  return stableMutate\n}\n"],"names":["useRef","useCallback","useMemo","createPacedMutations"],"mappings":";;;;AA4FO,SAAS,kBAId,QAC2C;AAE3C,QAAM,cAAcA,MAAAA,OAAO,OAAO,QAAQ;AAC1C,cAAY,UAAU,OAAO;AAE7B,QAAM,gBAAgBA,MAAAA,OAAO,OAAO,UAAU;AAC9C,gBAAc,UAAU,OAAO;AAG/B,QAAM,iBAAiBC,kBAAoC,CAAC,cAAc;AACxE,WAAO,YAAY,QAAQ,SAAS;AAAA,EACtC,GAAG,CAAA,CAAE;AAEL,QAAM,mBAAmBA,kBAAsC,CAAC,WAAW;AACzE,WAAO,cAAc,QAAQ,MAAM;AAAA,EACrC,GAAG,CAAA,CAAE;AAIL,QAAM,SAASC,MAAAA,QAAQ,MAAM;AAC3B,WAAOC,wBAAoC;AAAA,MACzC,GAAG;AAAA,MACH,UAAU;AAAA,MACV,YAAY;AAAA,IAAA,CACb;AAAA,EACH,GAAG;AAAA,IACD;AAAA,IACA;AAAA,IACA,OAAO;AAAA;AAAA,IAEP,KAAK,UAAU;AAAA,MACb,MAAM,OAAO,SAAS;AAAA,MACtB,SAAS,OAAO,SAAS;AAAA,IAAA,CAC1B;AAAA,EAAA,CACF;AAGD,QAAM,eAAeF,MAAAA,YAAY,QAAQ,CAAC,MAAM,CAAC;AAEjD,SAAO;AACT;;"}

package/dist/cjs/usePacedMutations.d.cts

@@ -0,0 +1,90 @@
+import { PacedMutationsConfig, Transaction } from '@tanstack/db';
+/**
+ * React hook for managing paced mutations with timing strategies.
+ *
+ * Provides optimistic mutations with pluggable strategies like debouncing,
+ * queuing, or throttling. The optimistic updates are applied immediately via
+ * `onMutate`, and the actual persistence is controlled by the strategy.
+ *
+ * @param config - Configuration including onMutate, mutationFn and strategy
+ * @returns A mutate function that accepts variables and returns Transaction objects
+ *
+ * @example
+ * ```tsx
+ * // Debounced auto-save
+ * function AutoSaveForm({ formId }: { formId: string }) {
+ *   const mutate = usePacedMutations<string>({
+ *     onMutate: (value) => {
+ *       // Apply optimistic update immediately
+ *       formCollection.update(formId, draft => {
+ *         draft.content = value
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.save(transaction.mutations)
+ *     },
+ *     strategy: debounceStrategy({ wait: 500 })
+ *   })
+ *
+ *   const handleChange = async (value: string) => {
+ *     const tx = mutate(value)
+ *
+ *     // Optional: await persistence or handle errors
+ *     try {
+ *       await tx.isPersisted.promise
+ *       console.log('Saved!')
+ *     } catch (error) {
+ *       console.error('Save failed:', error)
+ *     }
+ *   }
+ *
+ *   return <textarea onChange={e => handleChange(e.target.value)} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Throttled slider updates
+ * function VolumeSlider() {
+ *   const mutate = usePacedMutations<number>({
+ *     onMutate: (volume) => {
+ *       settingsCollection.update('volume', draft => {
+ *         draft.value = volume
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.updateVolume(transaction.mutations)
+ *     },
+ *     strategy: throttleStrategy({ wait: 200 })
+ *   })
+ *
+ *   return <input type="range" onChange={e => mutate(+e.target.value)} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Debounce with leading/trailing for color picker (persist first + final only)
+ * function ColorPicker() {
+ *   const mutate = usePacedMutations<string>({
+ *     onMutate: (color) => {
+ *       themeCollection.update('primary', draft => {
+ *         draft.color = color
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.updateTheme(transaction.mutations)
+ *     },
+ *     strategy: debounceStrategy({ wait: 0, leading: true, trailing: true })
+ *   })
+ *
+ *   return (
+ *     <input
+ *       type="color"
+ *       onChange={e => mutate(e.target.value)}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export declare function usePacedMutations<TVariables = unknown, T extends object = Record<string, unknown>>(config: PacedMutationsConfig<TVariables, T>): (variables: TVariables) => Transaction<T>;

package/dist/esm/index.d.ts

@@ -1,4 +1,5 @@
 export * from './useLiveQuery.js';
+export * from './usePacedMutations.js';
 export * from './useLiveInfiniteQuery.js';
 export * from '@tanstack/db';
 export type { Collection } from '@tanstack/db';

package/dist/esm/index.js

@@ -1,10 +1,12 @@
 import { useLiveQuery } from "./useLiveQuery.js";
+import { usePacedMutations } from "./usePacedMutations.js";
 import { useLiveInfiniteQuery } from "./useLiveInfiniteQuery.js";
 export * from "@tanstack/db";
 import { createTransaction } from "@tanstack/db";
 export {
   createTransaction,
   useLiveInfiniteQuery,
-  useLiveQuery
+  useLiveQuery,
+  usePacedMutations
 };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}

package/dist/esm/usePacedMutations.d.ts

@@ -0,0 +1,90 @@
+import { PacedMutationsConfig, Transaction } from '@tanstack/db';
+/**
+ * React hook for managing paced mutations with timing strategies.
+ *
+ * Provides optimistic mutations with pluggable strategies like debouncing,
+ * queuing, or throttling. The optimistic updates are applied immediately via
+ * `onMutate`, and the actual persistence is controlled by the strategy.
+ *
+ * @param config - Configuration including onMutate, mutationFn and strategy
+ * @returns A mutate function that accepts variables and returns Transaction objects
+ *
+ * @example
+ * ```tsx
+ * // Debounced auto-save
+ * function AutoSaveForm({ formId }: { formId: string }) {
+ *   const mutate = usePacedMutations<string>({
+ *     onMutate: (value) => {
+ *       // Apply optimistic update immediately
+ *       formCollection.update(formId, draft => {
+ *         draft.content = value
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.save(transaction.mutations)
+ *     },
+ *     strategy: debounceStrategy({ wait: 500 })
+ *   })
+ *
+ *   const handleChange = async (value: string) => {
+ *     const tx = mutate(value)
+ *
+ *     // Optional: await persistence or handle errors
+ *     try {
+ *       await tx.isPersisted.promise
+ *       console.log('Saved!')
+ *     } catch (error) {
+ *       console.error('Save failed:', error)
+ *     }
+ *   }
+ *
+ *   return <textarea onChange={e => handleChange(e.target.value)} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Throttled slider updates
+ * function VolumeSlider() {
+ *   const mutate = usePacedMutations<number>({
+ *     onMutate: (volume) => {
+ *       settingsCollection.update('volume', draft => {
+ *         draft.value = volume
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.updateVolume(transaction.mutations)
+ *     },
+ *     strategy: throttleStrategy({ wait: 200 })
+ *   })
+ *
+ *   return <input type="range" onChange={e => mutate(+e.target.value)} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Debounce with leading/trailing for color picker (persist first + final only)
+ * function ColorPicker() {
+ *   const mutate = usePacedMutations<string>({
+ *     onMutate: (color) => {
+ *       themeCollection.update('primary', draft => {
+ *         draft.color = color
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.updateTheme(transaction.mutations)
+ *     },
+ *     strategy: debounceStrategy({ wait: 0, leading: true, trailing: true })
+ *   })
+ *
+ *   return (
+ *     <input
+ *       type="color"
+ *       onChange={e => mutate(e.target.value)}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export declare function usePacedMutations<TVariables = unknown, T extends object = Record<string, unknown>>(config: PacedMutationsConfig<TVariables, T>): (variables: TVariables) => Transaction<T>;

package/dist/esm/usePacedMutations.js

@@ -0,0 +1,36 @@
+import { useRef, useCallback, useMemo } from "react";
+import { createPacedMutations } from "@tanstack/db";
+function usePacedMutations(config) {
+  const onMutateRef = useRef(config.onMutate);
+  onMutateRef.current = config.onMutate;
+  const mutationFnRef = useRef(config.mutationFn);
+  mutationFnRef.current = config.mutationFn;
+  const stableOnMutate = useCallback((variables) => {
+    return onMutateRef.current(variables);
+  }, []);
+  const stableMutationFn = useCallback((params) => {
+    return mutationFnRef.current(params);
+  }, []);
+  const mutate = useMemo(() => {
+    return createPacedMutations({
+      ...config,
+      onMutate: stableOnMutate,
+      mutationFn: stableMutationFn
+    });
+  }, [
+    stableOnMutate,
+    stableMutationFn,
+    config.metadata,
+    // Serialize strategy to avoid recreating when object reference changes but values are same
+    JSON.stringify({
+      type: config.strategy._type,
+      options: config.strategy.options
+    })
+  ]);
+  const stableMutate = useCallback(mutate, [mutate]);
+  return stableMutate;
+}
+export {
+  usePacedMutations
+};
+//# sourceMappingURL=usePacedMutations.js.map

package/dist/esm/usePacedMutations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePacedMutations.js","sources":["../../src/usePacedMutations.ts"],"sourcesContent":["import { useCallback, useMemo, useRef } from \"react\"\nimport { createPacedMutations } from \"@tanstack/db\"\nimport type { PacedMutationsConfig, Transaction } from \"@tanstack/db\"\n\n/**\n * React hook for managing paced mutations with timing strategies.\n *\n * Provides optimistic mutations with pluggable strategies like debouncing,\n * queuing, or throttling. The optimistic updates are applied immediately via\n * `onMutate`, and the actual persistence is controlled by the strategy.\n *\n * @param config - Configuration including onMutate, mutationFn and strategy\n * @returns A mutate function that accepts variables and returns Transaction objects\n *\n * @example\n * ```tsx\n * // Debounced auto-save\n * function AutoSaveForm({ formId }: { formId: string }) {\n *   const mutate = usePacedMutations<string>({\n *     onMutate: (value) => {\n *       // Apply optimistic update immediately\n *       formCollection.update(formId, draft => {\n *         draft.content = value\n *       })\n *     },\n *     mutationFn: async ({ transaction }) => {\n *       await api.save(transaction.mutations)\n *     },\n *     strategy: debounceStrategy({ wait: 500 })\n *   })\n *\n *   const handleChange = async (value: string) => {\n *     const tx = mutate(value)\n *\n *     // Optional: await persistence or handle errors\n *     try {\n *       await tx.isPersisted.promise\n *       console.log('Saved!')\n *     } catch (error) {\n *       console.error('Save failed:', error)\n *     }\n *   }\n *\n *   return <textarea onChange={e => handleChange(e.target.value)} />\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Throttled slider updates\n * function VolumeSlider() {\n *   const mutate = usePacedMutations<number>({\n *     onMutate: (volume) => {\n *       settingsCollection.update('volume', draft => {\n *         draft.value = volume\n *       })\n *     },\n *     mutationFn: async ({ transaction }) => {\n *       await api.updateVolume(transaction.mutations)\n *     },\n *     strategy: throttleStrategy({ wait: 200 })\n *   })\n *\n *   return <input type=\"range\" onChange={e => mutate(+e.target.value)} />\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Debounce with leading/trailing for color picker (persist first + final only)\n * function ColorPicker() {\n *   const mutate = usePacedMutations<string>({\n *     onMutate: (color) => {\n *       themeCollection.update('primary', draft => {\n *         draft.color = color\n *       })\n *     },\n *     mutationFn: async ({ transaction }) => {\n *       await api.updateTheme(transaction.mutations)\n *     },\n *     strategy: debounceStrategy({ wait: 0, leading: true, trailing: true })\n *   })\n *\n *   return (\n *     <input\n *       type=\"color\"\n *       onChange={e => mutate(e.target.value)}\n *     />\n *   )\n * }\n * ```\n */\nexport function usePacedMutations<\n  TVariables = unknown,\n  T extends object = Record<string, unknown>,\n>(\n  config: PacedMutationsConfig<TVariables, T>\n): (variables: TVariables) => Transaction<T> {\n  // Keep refs to the latest callbacks so we can call them without recreating the instance\n  const onMutateRef = useRef(config.onMutate)\n  onMutateRef.current = config.onMutate\n\n  const mutationFnRef = useRef(config.mutationFn)\n  mutationFnRef.current = config.mutationFn\n\n  // Create stable wrappers that always call the latest version\n  const stableOnMutate = useCallback<typeof config.onMutate>((variables) => {\n    return onMutateRef.current(variables)\n  }, [])\n\n  const stableMutationFn = useCallback<typeof config.mutationFn>((params) => {\n    return mutationFnRef.current(params)\n  }, [])\n\n  // Create paced mutations instance with proper dependency tracking\n  // Serialize strategy for stable comparison since strategy objects are recreated on each render\n  const mutate = useMemo(() => {\n    return createPacedMutations<TVariables, T>({\n      ...config,\n      onMutate: stableOnMutate,\n      mutationFn: stableMutationFn,\n    })\n  }, [\n    stableOnMutate,\n    stableMutationFn,\n    config.metadata,\n    // Serialize strategy to avoid recreating when object reference changes but values are same\n    JSON.stringify({\n      type: config.strategy._type,\n      options: config.strategy.options,\n    }),\n  ])\n\n  // Return stable mutate callback\n  const stableMutate = useCallback(mutate, [mutate])\n\n  return stableMutate\n}\n"],"names":[],"mappings":";;AA4FO,SAAS,kBAId,QAC2C;AAE3C,QAAM,cAAc,OAAO,OAAO,QAAQ;AAC1C,cAAY,UAAU,OAAO;AAE7B,QAAM,gBAAgB,OAAO,OAAO,UAAU;AAC9C,gBAAc,UAAU,OAAO;AAG/B,QAAM,iBAAiB,YAAoC,CAAC,cAAc;AACxE,WAAO,YAAY,QAAQ,SAAS;AAAA,EACtC,GAAG,CAAA,CAAE;AAEL,QAAM,mBAAmB,YAAsC,CAAC,WAAW;AACzE,WAAO,cAAc,QAAQ,MAAM;AAAA,EACrC,GAAG,CAAA,CAAE;AAIL,QAAM,SAAS,QAAQ,MAAM;AAC3B,WAAO,qBAAoC;AAAA,MACzC,GAAG;AAAA,MACH,UAAU;AAAA,MACV,YAAY;AAAA,IAAA,CACb;AAAA,EACH,GAAG;AAAA,IACD;AAAA,IACA;AAAA,IACA,OAAO;AAAA;AAAA,IAEP,KAAK,UAAU;AAAA,MACb,MAAM,OAAO,SAAS;AAAA,MACtB,SAAS,OAAO,SAAS;AAAA,IAAA,CAC1B;AAAA,EAAA,CACF;AAGD,QAAM,eAAe,YAAY,QAAQ,CAAC,MAAM,CAAC;AAEjD,SAAO;AACT;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/react-db",
   "description": "React integration for @tanstack/db",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "author": "Kyle Mathews",
   "license": "MIT",
   "repository": {
@@ -17,10 +17,10 @@
   ],
   "dependencies": {
     "use-sync-external-store": "^1.6.0",
-    "@tanstack/db": "0.4.14"
+    "@tanstack/db": "0.4.16"
   },
   "devDependencies": {
-    "@electric-sql/client": "1.0.14",
+    "@electric-sql/client": "1.1.0",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
@@ -56,6 +56,7 @@
   "types": "dist/esm/index.d.ts",
   "scripts": {
     "build": "vite build",
+    "build:minified": "vite build --minify",
     "dev": "vite build --watch",
     "test": "npx vitest --run",
     "lint": "eslint . --fix"

package/src/index.ts

@@ -1,5 +1,6 @@
 // Re-export all public APIs
 export * from "./useLiveQuery"
+export * from "./usePacedMutations"
 export * from "./useLiveInfiniteQuery"
 
 // Re-export everything from @tanstack/db

package/src/usePacedMutations.ts

@@ -0,0 +1,138 @@
+import { useCallback, useMemo, useRef } from "react"
+import { createPacedMutations } from "@tanstack/db"
+import type { PacedMutationsConfig, Transaction } from "@tanstack/db"
+
+/**
+ * React hook for managing paced mutations with timing strategies.
+ *
+ * Provides optimistic mutations with pluggable strategies like debouncing,
+ * queuing, or throttling. The optimistic updates are applied immediately via
+ * `onMutate`, and the actual persistence is controlled by the strategy.
+ *
+ * @param config - Configuration including onMutate, mutationFn and strategy
+ * @returns A mutate function that accepts variables and returns Transaction objects
+ *
+ * @example
+ * ```tsx
+ * // Debounced auto-save
+ * function AutoSaveForm({ formId }: { formId: string }) {
+ *   const mutate = usePacedMutations<string>({
+ *     onMutate: (value) => {
+ *       // Apply optimistic update immediately
+ *       formCollection.update(formId, draft => {
+ *         draft.content = value
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.save(transaction.mutations)
+ *     },
+ *     strategy: debounceStrategy({ wait: 500 })
+ *   })
+ *
+ *   const handleChange = async (value: string) => {
+ *     const tx = mutate(value)
+ *
+ *     // Optional: await persistence or handle errors
+ *     try {
+ *       await tx.isPersisted.promise
+ *       console.log('Saved!')
+ *     } catch (error) {
+ *       console.error('Save failed:', error)
+ *     }
+ *   }
+ *
+ *   return <textarea onChange={e => handleChange(e.target.value)} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Throttled slider updates
+ * function VolumeSlider() {
+ *   const mutate = usePacedMutations<number>({
+ *     onMutate: (volume) => {
+ *       settingsCollection.update('volume', draft => {
+ *         draft.value = volume
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.updateVolume(transaction.mutations)
+ *     },
+ *     strategy: throttleStrategy({ wait: 200 })
+ *   })
+ *
+ *   return <input type="range" onChange={e => mutate(+e.target.value)} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Debounce with leading/trailing for color picker (persist first + final only)
+ * function ColorPicker() {
+ *   const mutate = usePacedMutations<string>({
+ *     onMutate: (color) => {
+ *       themeCollection.update('primary', draft => {
+ *         draft.color = color
+ *       })
+ *     },
+ *     mutationFn: async ({ transaction }) => {
+ *       await api.updateTheme(transaction.mutations)
+ *     },
+ *     strategy: debounceStrategy({ wait: 0, leading: true, trailing: true })
+ *   })
+ *
+ *   return (
+ *     <input
+ *       type="color"
+ *       onChange={e => mutate(e.target.value)}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function usePacedMutations<
+  TVariables = unknown,
+  T extends object = Record<string, unknown>,
+>(
+  config: PacedMutationsConfig<TVariables, T>
+): (variables: TVariables) => Transaction<T> {
+  // Keep refs to the latest callbacks so we can call them without recreating the instance
+  const onMutateRef = useRef(config.onMutate)
+  onMutateRef.current = config.onMutate
+
+  const mutationFnRef = useRef(config.mutationFn)
+  mutationFnRef.current = config.mutationFn
+
+  // Create stable wrappers that always call the latest version
+  const stableOnMutate = useCallback<typeof config.onMutate>((variables) => {
+    return onMutateRef.current(variables)
+  }, [])
+
+  const stableMutationFn = useCallback<typeof config.mutationFn>((params) => {
+    return mutationFnRef.current(params)
+  }, [])
+
+  // Create paced mutations instance with proper dependency tracking
+  // Serialize strategy for stable comparison since strategy objects are recreated on each render
+  const mutate = useMemo(() => {
+    return createPacedMutations<TVariables, T>({
+      ...config,
+      onMutate: stableOnMutate,
+      mutationFn: stableMutationFn,
+    })
+  }, [
+    stableOnMutate,
+    stableMutationFn,
+    config.metadata,
+    // Serialize strategy to avoid recreating when object reference changes but values are same
+    JSON.stringify({
+      type: config.strategy._type,
+      options: config.strategy.options,
+    }),
+  ])
+
+  // Return stable mutate callback
+  const stableMutate = useCallback(mutate, [mutate])
+
+  return stableMutate
+}