@tanstack/preact-pacer 0.0.1 → 0.18.0

package/dist/queuer/useQueuedState.d.cts

@@ -0,0 +1,123 @@
+import { PreactQueuer } from "./useQueuer.cjs";
+import { Queuer, QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
+
+//#region src/queuer/useQueuedState.d.ts
+
+/**
+ * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.
+ * This hook provides both the current queue state and queue control methods.
+ *
+ * The queue state is automatically updated whenever items are added, removed, or reordered in the queue.
+ * All queue operations are reflected in the state array returned by the hook.
+ *
+ * The queue can be started and stopped to automatically process items at a specified interval,
+ * making it useful as a scheduler. When started, it will process one item per tick, with an
+ * optional wait time between ticks.
+ *
+ * The hook returns a tuple containing:
+ * - The current queue state as an array
+ * - The queue instance with methods for queue manipulation
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying queuer instance.
+ * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,
+ * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
+ *
+ * **By default, there will be no reactive state subscriptions** and you must opt-in to state
+ * tracking by providing a selector function. This prevents unnecessary re-renders and gives you
+ * full control over when your component updates. Only when you provide a selector will the
+ * component re-render when the selected state values change.
+ *
+ * Available queuer state properties:
+ * - `executionCount`: Number of items that have been processed by the queuer
+ * - `expirationCount`: Number of items that have been removed due to expiration
+ * - `isEmpty`: Whether the queuer has no items to process
+ * - `isFull`: Whether the queuer has reached its maximum capacity
+ * - `isIdle`: Whether the queuer is not currently processing any items
+ * - `isRunning`: Whether the queuer is active and will process items automatically
+ * - `items`: Array of items currently waiting to be processed
+ * - `itemTimestamps`: Timestamps when items were added for expiration tracking
+ * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+ * - `rejectionCount`: Number of items that have been rejected from being added
+ * - `size`: Number of items currently in the queue
+ * - `status`: Current processing status ('idle' | 'running' | 'stopped')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   {
+ *     initialItems: ['item1', 'item2'],
+ *     started: true,
+ *     wait: 1000,
+ *     getPriority: (item) => item.priority
+ *   }
+ * );
+ *
+ * // Opt-in to re-render when queue contents change (optimized for displaying queue items)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     items: state.items,
+ *     size: state.size,
+ *     isEmpty: state.isEmpty
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when processing state changes (optimized for loading indicators)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     isRunning: state.isRunning,
+ *     isIdle: state.isIdle,
+ *     status: state.status,
+ *     pendingTick: state.pendingTick
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when execution metrics change (optimized for stats display)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     executionCount: state.executionCount,
+ *     expirationCount: state.expirationCount,
+ *     rejectionCount: state.rejectionCount
+ *   })
+ * );
+ *
+ * // Add items to queue
+ * const handleAdd = (item) => {
+ *   addItem(item);
+ * };
+ *
+ * // Start automatic processing
+ * const startProcessing = () => {
+ *   queue.start();
+ * };
+ *
+ * // Stop automatic processing
+ * const stopProcessing = () => {
+ *   queue.stop();
+ * };
+ *
+ * // Manual processing still available
+ * const handleProcess = () => {
+ *   const nextItem = queue.getNextItem();
+ *   if (nextItem) {
+ *     processItem(nextItem);
+ *   }
+ * };
+ *
+ * // Access the selected queuer state (will be empty object {} unless selector provided)
+ * const { size, isRunning, executionCount } = queue.state;
+ * ```
+ */
+declare function useQueuedState<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(fn: (item: TValue) => void, options?: QueuerOptions<TValue>, selector?: (state: QueuerState<TValue>) => TSelected): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>];
+//#endregion
+export { useQueuedState };
+//# sourceMappingURL=useQueuedState.d.cts.map

package/dist/queuer/useQueuedState.d.ts

@@ -0,0 +1,123 @@
+import { PreactQueuer } from "./useQueuer.js";
+import { Queuer, QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
+
+//#region src/queuer/useQueuedState.d.ts
+
+/**
+ * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.
+ * This hook provides both the current queue state and queue control methods.
+ *
+ * The queue state is automatically updated whenever items are added, removed, or reordered in the queue.
+ * All queue operations are reflected in the state array returned by the hook.
+ *
+ * The queue can be started and stopped to automatically process items at a specified interval,
+ * making it useful as a scheduler. When started, it will process one item per tick, with an
+ * optional wait time between ticks.
+ *
+ * The hook returns a tuple containing:
+ * - The current queue state as an array
+ * - The queue instance with methods for queue manipulation
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying queuer instance.
+ * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,
+ * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
+ *
+ * **By default, there will be no reactive state subscriptions** and you must opt-in to state
+ * tracking by providing a selector function. This prevents unnecessary re-renders and gives you
+ * full control over when your component updates. Only when you provide a selector will the
+ * component re-render when the selected state values change.
+ *
+ * Available queuer state properties:
+ * - `executionCount`: Number of items that have been processed by the queuer
+ * - `expirationCount`: Number of items that have been removed due to expiration
+ * - `isEmpty`: Whether the queuer has no items to process
+ * - `isFull`: Whether the queuer has reached its maximum capacity
+ * - `isIdle`: Whether the queuer is not currently processing any items
+ * - `isRunning`: Whether the queuer is active and will process items automatically
+ * - `items`: Array of items currently waiting to be processed
+ * - `itemTimestamps`: Timestamps when items were added for expiration tracking
+ * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+ * - `rejectionCount`: Number of items that have been rejected from being added
+ * - `size`: Number of items currently in the queue
+ * - `status`: Current processing status ('idle' | 'running' | 'stopped')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   {
+ *     initialItems: ['item1', 'item2'],
+ *     started: true,
+ *     wait: 1000,
+ *     getPriority: (item) => item.priority
+ *   }
+ * );
+ *
+ * // Opt-in to re-render when queue contents change (optimized for displaying queue items)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     items: state.items,
+ *     size: state.size,
+ *     isEmpty: state.isEmpty
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when processing state changes (optimized for loading indicators)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     isRunning: state.isRunning,
+ *     isIdle: state.isIdle,
+ *     status: state.status,
+ *     pendingTick: state.pendingTick
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when execution metrics change (optimized for stats display)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     executionCount: state.executionCount,
+ *     expirationCount: state.expirationCount,
+ *     rejectionCount: state.rejectionCount
+ *   })
+ * );
+ *
+ * // Add items to queue
+ * const handleAdd = (item) => {
+ *   addItem(item);
+ * };
+ *
+ * // Start automatic processing
+ * const startProcessing = () => {
+ *   queue.start();
+ * };
+ *
+ * // Stop automatic processing
+ * const stopProcessing = () => {
+ *   queue.stop();
+ * };
+ *
+ * // Manual processing still available
+ * const handleProcess = () => {
+ *   const nextItem = queue.getNextItem();
+ *   if (nextItem) {
+ *     processItem(nextItem);
+ *   }
+ * };
+ *
+ * // Access the selected queuer state (will be empty object {} unless selector provided)
+ * const { size, isRunning, executionCount } = queue.state;
+ * ```
+ */
+declare function useQueuedState<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(fn: (item: TValue) => void, options?: QueuerOptions<TValue>, selector?: (state: QueuerState<TValue>) => TSelected): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>];
+//#endregion
+export { useQueuedState };
+//# sourceMappingURL=useQueuedState.d.ts.map

package/dist/queuer/useQueuedState.js

@@ -0,0 +1,129 @@
+import { useQueuer } from "./useQueuer.js";
+
+//#region src/queuer/useQueuedState.ts
+/**
+* A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.
+* This hook provides both the current queue state and queue control methods.
+*
+* The queue state is automatically updated whenever items are added, removed, or reordered in the queue.
+* All queue operations are reflected in the state array returned by the hook.
+*
+* The queue can be started and stopped to automatically process items at a specified interval,
+* making it useful as a scheduler. When started, it will process one item per tick, with an
+* optional wait time between ticks.
+*
+* The hook returns a tuple containing:
+* - The current queue state as an array
+* - The queue instance with methods for queue manipulation
+*
+* ## State Management and Selector
+*
+* The hook uses TanStack Store for reactive state management via the underlying queuer instance.
+* The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,
+* optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
+*
+* **By default, there will be no reactive state subscriptions** and you must opt-in to state
+* tracking by providing a selector function. This prevents unnecessary re-renders and gives you
+* full control over when your component updates. Only when you provide a selector will the
+* component re-render when the selected state values change.
+*
+* Available queuer state properties:
+* - `executionCount`: Number of items that have been processed by the queuer
+* - `expirationCount`: Number of items that have been removed due to expiration
+* - `isEmpty`: Whether the queuer has no items to process
+* - `isFull`: Whether the queuer has reached its maximum capacity
+* - `isIdle`: Whether the queuer is not currently processing any items
+* - `isRunning`: Whether the queuer is active and will process items automatically
+* - `items`: Array of items currently waiting to be processed
+* - `itemTimestamps`: Timestamps when items were added for expiration tracking
+* - `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+* - `rejectionCount`: Number of items that have been rejected from being added
+* - `size`: Number of items currently in the queue
+* - `status`: Current processing status ('idle' | 'running' | 'stopped')
+*
+* @example
+* ```tsx
+* // Default behavior - no reactive state subscriptions
+* const [items, addItem, queue] = useQueuedState(
+*   (item) => console.log('Processing:', item),
+*   {
+*     initialItems: ['item1', 'item2'],
+*     started: true,
+*     wait: 1000,
+*     getPriority: (item) => item.priority
+*   }
+* );
+*
+* // Opt-in to re-render when queue contents change (optimized for displaying queue items)
+* const [items, addItem, queue] = useQueuedState(
+*   (item) => console.log('Processing:', item),
+*   { started: true, wait: 1000 },
+*   (state) => ({
+*     items: state.items,
+*     size: state.size,
+*     isEmpty: state.isEmpty
+*   })
+* );
+*
+* // Opt-in to re-render when processing state changes (optimized for loading indicators)
+* const [items, addItem, queue] = useQueuedState(
+*   (item) => console.log('Processing:', item),
+*   { started: true, wait: 1000 },
+*   (state) => ({
+*     isRunning: state.isRunning,
+*     isIdle: state.isIdle,
+*     status: state.status,
+*     pendingTick: state.pendingTick
+*   })
+* );
+*
+* // Opt-in to re-render when execution metrics change (optimized for stats display)
+* const [items, addItem, queue] = useQueuedState(
+*   (item) => console.log('Processing:', item),
+*   { started: true, wait: 1000 },
+*   (state) => ({
+*     executionCount: state.executionCount,
+*     expirationCount: state.expirationCount,
+*     rejectionCount: state.rejectionCount
+*   })
+* );
+*
+* // Add items to queue
+* const handleAdd = (item) => {
+*   addItem(item);
+* };
+*
+* // Start automatic processing
+* const startProcessing = () => {
+*   queue.start();
+* };
+*
+* // Stop automatic processing
+* const stopProcessing = () => {
+*   queue.stop();
+* };
+*
+* // Manual processing still available
+* const handleProcess = () => {
+*   const nextItem = queue.getNextItem();
+*   if (nextItem) {
+*     processItem(nextItem);
+*   }
+* };
+*
+* // Access the selected queuer state (will be empty object {} unless selector provided)
+* const { size, isRunning, executionCount } = queue.state;
+* ```
+*/
+function useQueuedState(fn, options = {}, selector) {
+	const queue = useQueuer(fn, options, selector);
+	return [
+		queue.state.items,
+		queue.addItem,
+		queue
+	];
+}
+
+//#endregion
+export { useQueuedState };
+//# sourceMappingURL=useQueuedState.js.map

package/dist/queuer/useQueuedState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQueuedState.js","names":[],"sources":["../../src/queuer/useQueuedState.ts"],"sourcesContent":["import { useQueuer } from './useQueuer'\nimport type { PreactQueuer } from './useQueuer'\nimport type { Queuer, QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.\n * This hook provides both the current queue state and queue control methods.\n *\n * The queue state is automatically updated whenever items are added, removed, or reordered in the queue.\n * All queue operations are reflected in the state array returned by the hook.\n *\n * The queue can be started and stopped to automatically process items at a specified interval,\n * making it useful as a scheduler. When started, it will process one item per tick, with an\n * optional wait time between ticks.\n *\n * The hook returns a tuple containing:\n * - The current queue state as an array\n * - The queue instance with methods for queue manipulation\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [items, addItem, queue] = useQueuedState(\n *   (item) => console.log('Processing:', item),\n *   {\n *     initialItems: ['item1', 'item2'],\n *     started: true,\n *     wait: 1000,\n *     getPriority: (item) => item.priority\n *   }\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue items)\n * const [items, addItem, queue] = useQueuedState(\n *   (item) => console.log('Processing:', item),\n *   { started: true, wait: 1000 },\n *   (state) => ({\n *     items: state.items,\n *     size: state.size,\n *     isEmpty: state.isEmpty\n *   })\n * );\n *\n * // Opt-in to re-render when processing state changes (optimized for loading indicators)\n * const [items, addItem, queue] = useQueuedState(\n *   (item) => console.log('Processing:', item),\n *   { started: true, wait: 1000 },\n *   (state) => ({\n *     isRunning: state.isRunning,\n *     isIdle: state.isIdle,\n *     status: state.status,\n *     pendingTick: state.pendingTick\n *   })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [items, addItem, queue] = useQueuedState(\n *   (item) => console.log('Processing:', item),\n *   { started: true, wait: 1000 },\n *   (state) => ({\n *     executionCount: state.executionCount,\n *     expirationCount: state.expirationCount,\n *     rejectionCount: state.rejectionCount\n *   })\n * );\n *\n * // Add items to queue\n * const handleAdd = (item) => {\n *   addItem(item);\n * };\n *\n * // Start automatic processing\n * const startProcessing = () => {\n *   queue.start();\n * };\n *\n * // Stop automatic processing\n * const stopProcessing = () => {\n *   queue.stop();\n * };\n *\n * // Manual processing still available\n * const handleProcess = () => {\n *   const nextItem = queue.getNextItem();\n *   if (nextItem) {\n *     processItem(nextItem);\n *   }\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queue.state;\n * ```\n */\nexport function useQueuedState<\n  TValue,\n  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n    QueuerState<TValue>,\n    'items'\n  >,\n>(\n  fn: (item: TValue) => void,\n  options: QueuerOptions<TValue> = {},\n  selector?: (state: QueuerState<TValue>) => TSelected,\n): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>] {\n  const queue = useQueuer(fn, options, selector)\n\n  return [queue.state.items, queue.addItem, queue]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsHA,SAAgB,eAOd,IACA,UAAiC,EAAE,EACnC,UAC6E;CAC7E,MAAM,QAAQ,UAAU,IAAI,SAAS,SAAS;AAE9C,QAAO;EAAC,MAAM,MAAM;EAAO,MAAM;EAAS;EAAM"}

package/dist/queuer/useQueuedValue.cjs

@@ -0,0 +1,115 @@
+const require_useQueuedState = require('./useQueuedState.cjs');
+let preact_hooks = require("preact/hooks");
+
+//#region src/queuer/useQueuedValue.ts
+/**
+* A Preact hook that creates a queued value that processes state changes in order with an optional delay.
+* This hook uses useQueuer internally to manage a queue of state changes and apply them sequentially.
+*
+* The queued value will process changes in the order they are received, with optional delays between
+* processing each change. This is useful for handling state updates that need to be processed
+* in a specific order, like animations or sequential UI updates.
+*
+* The hook returns a tuple containing:
+* - The current queued value
+* - The queuer instance with control methods
+*
+* ## State Management and Selector
+*
+* The hook uses TanStack Store for reactive state management via the underlying queuer instance.
+* The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,
+* optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
+*
+* **By default, there will be no reactive state subscriptions** and you must opt-in to state
+* tracking by providing a selector function. This prevents unnecessary re-renders and gives you
+* full control over when your component updates. Only when you provide a selector will the
+* component re-render when the selected state values change.
+*
+* Available queuer state properties:
+* - `executionCount`: Number of items that have been processed by the queuer
+* - `expirationCount`: Number of items that have been removed due to expiration
+* - `isEmpty`: Whether the queuer has no items to process
+* - `isFull`: Whether the queuer has reached its maximum capacity
+* - `isIdle`: Whether the queuer is not currently processing any items
+* - `isRunning`: Whether the queuer is active and will process items automatically
+* - `items`: Array of items currently waiting to be processed
+* - `itemTimestamps`: Timestamps when items were added for expiration tracking
+* - `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+* - `rejectionCount`: Number of items that have been rejected from being added
+* - `size`: Number of items currently in the queue
+* - `status`: Current processing status ('idle' | 'running' | 'stopped')
+*
+* @example
+* ```tsx
+* // Default behavior - no reactive state subscriptions
+* const [value, queuer] = useQueuedValue(initialValue, {
+*   wait: 500, // Wait 500ms between processing each change
+*   started: true // Start processing immediately
+* });
+*
+* // Opt-in to re-render when queue processing state changes (optimized for loading indicators)
+* const [value, queuer] = useQueuedValue(
+*   initialValue,
+*   { wait: 500, started: true },
+*   (state) => ({
+*     isRunning: state.isRunning,
+*     isIdle: state.isIdle,
+*     status: state.status,
+*     pendingTick: state.pendingTick
+*   })
+* );
+*
+* // Opt-in to re-render when queue contents change (optimized for displaying queue status)
+* const [value, queuer] = useQueuedValue(
+*   initialValue,
+*   { wait: 500, started: true },
+*   (state) => ({
+*     size: state.size,
+*     isEmpty: state.isEmpty,
+*     isFull: state.isFull
+*   })
+* );
+*
+* // Opt-in to re-render when execution metrics change (optimized for stats display)
+* const [value, queuer] = useQueuedValue(
+*   initialValue,
+*   { wait: 500, started: true },
+*   (state) => ({
+*     executionCount: state.executionCount,
+*     expirationCount: state.expirationCount,
+*     rejectionCount: state.rejectionCount
+*   })
+* );
+*
+* // Add changes to the queue
+* const handleChange = (newValue) => {
+*   queuer.addItem(newValue);
+* };
+*
+* // Control the queue
+* const pauseProcessing = () => {
+*   queuer.stop();
+* };
+*
+* const resumeProcessing = () => {
+*   queuer.start();
+* };
+*
+* // Access the selected queuer state (will be empty object {} unless selector provided)
+* const { size, isRunning, executionCount } = queuer.state;
+* ```
+*/
+function useQueuedValue(initialValue, options = {}, selector) {
+	const [value, setValue] = (0, preact_hooks.useState)(initialValue);
+	const [, addItem, queuer] = require_useQueuedState.useQueuedState((item) => {
+		setValue(item);
+	}, options, selector);
+	(0, preact_hooks.useEffect)(() => {
+		addItem(initialValue);
+	}, [initialValue, addItem]);
+	return [value, queuer];
+}
+
+//#endregion
+exports.useQueuedValue = useQueuedValue;
+//# sourceMappingURL=useQueuedValue.cjs.map

package/dist/queuer/useQueuedValue.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQueuedValue.cjs","names":["useQueuedState"],"sources":["../../src/queuer/useQueuedValue.ts"],"sourcesContent":["import { useEffect, useState } from 'preact/hooks'\nimport { useQueuedState } from './useQueuedState'\nimport type { PreactQueuer } from './useQueuer'\nimport type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'\n\n/**\n * A Preact hook that creates a queued value that processes state changes in order with an optional delay.\n * This hook uses useQueuer internally to manage a queue of state changes and apply them sequentially.\n *\n * The queued value will process changes in the order they are received, with optional delays between\n * processing each change. This is useful for handling state updates that need to be processed\n * in a specific order, like animations or sequential UI updates.\n *\n * The hook returns a tuple containing:\n * - The current queued value\n * - The queuer instance with control methods\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying queuer instance.\n * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available queuer state properties:\n * - `executionCount`: Number of items that have been processed by the queuer\n * - `expirationCount`: Number of items that have been removed due to expiration\n * - `isEmpty`: Whether the queuer has no items to process\n * - `isFull`: Whether the queuer has reached its maximum capacity\n * - `isIdle`: Whether the queuer is not currently processing any items\n * - `isRunning`: Whether the queuer is active and will process items automatically\n * - `items`: Array of items currently waiting to be processed\n * - `itemTimestamps`: Timestamps when items were added for expiration tracking\n * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item\n * - `rejectionCount`: Number of items that have been rejected from being added\n * - `size`: Number of items currently in the queue\n * - `status`: Current processing status ('idle' | 'running' | 'stopped')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [value, queuer] = useQueuedValue(initialValue, {\n *   wait: 500, // Wait 500ms between processing each change\n *   started: true // Start processing immediately\n * });\n *\n * // Opt-in to re-render when queue processing state changes (optimized for loading indicators)\n * const [value, queuer] = useQueuedValue(\n *   initialValue,\n *   { wait: 500, started: true },\n *   (state) => ({\n *     isRunning: state.isRunning,\n *     isIdle: state.isIdle,\n *     status: state.status,\n *     pendingTick: state.pendingTick\n *   })\n * );\n *\n * // Opt-in to re-render when queue contents change (optimized for displaying queue status)\n * const [value, queuer] = useQueuedValue(\n *   initialValue,\n *   { wait: 500, started: true },\n *   (state) => ({\n *     size: state.size,\n *     isEmpty: state.isEmpty,\n *     isFull: state.isFull\n *   })\n * );\n *\n * // Opt-in to re-render when execution metrics change (optimized for stats display)\n * const [value, queuer] = useQueuedValue(\n *   initialValue,\n *   { wait: 500, started: true },\n *   (state) => ({\n *     executionCount: state.executionCount,\n *     expirationCount: state.expirationCount,\n *     rejectionCount: state.rejectionCount\n *   })\n * );\n *\n * // Add changes to the queue\n * const handleChange = (newValue) => {\n *   queuer.addItem(newValue);\n * };\n *\n * // Control the queue\n * const pauseProcessing = () => {\n *   queuer.stop();\n * };\n *\n * const resumeProcessing = () => {\n *   queuer.start();\n * };\n *\n * // Access the selected queuer state (will be empty object {} unless selector provided)\n * const { size, isRunning, executionCount } = queuer.state;\n * ```\n */\nexport function useQueuedValue<\n  TValue,\n  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<\n    QueuerState<TValue>,\n    'items'\n  >,\n>(\n  initialValue: TValue,\n  options: QueuerOptions<TValue> = {},\n  selector?: (state: QueuerState<TValue>) => TSelected,\n): [TValue, PreactQueuer<TValue, TSelected>] {\n  const [value, setValue] = useState<TValue>(initialValue)\n\n  const [, addItem, queuer] = useQueuedState(\n    (item) => {\n      setValue(item)\n    },\n    options,\n    selector,\n  )\n\n  useEffect(() => {\n    addItem(initialValue)\n  }, [initialValue, addItem])\n\n  return [value, queuer]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA,SAAgB,eAOd,cACA,UAAiC,EAAE,EACnC,UAC2C;CAC3C,MAAM,CAAC,OAAO,uCAA6B,aAAa;CAExD,MAAM,GAAG,SAAS,UAAUA,uCACzB,SAAS;AACR,WAAS,KAAK;IAEhB,SACA,SACD;AAED,mCAAgB;AACd,UAAQ,aAAa;IACpB,CAAC,cAAc,QAAQ,CAAC;AAE3B,QAAO,CAAC,OAAO,OAAO"}

package/dist/queuer/useQueuedValue.d.cts

@@ -0,0 +1,106 @@
+import { PreactQueuer } from "./useQueuer.cjs";
+import { QueuerOptions, QueuerState } from "@tanstack/pacer/queuer";
+
+//#region src/queuer/useQueuedValue.d.ts
+
+/**
+ * A Preact hook that creates a queued value that processes state changes in order with an optional delay.
+ * This hook uses useQueuer internally to manage a queue of state changes and apply them sequentially.
+ *
+ * The queued value will process changes in the order they are received, with optional delays between
+ * processing each change. This is useful for handling state updates that need to be processed
+ * in a specific order, like animations or sequential UI updates.
+ *
+ * The hook returns a tuple containing:
+ * - The current queued value
+ * - The queuer instance with control methods
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying queuer instance.
+ * The `selector` parameter allows you to specify which queuer state changes will trigger a re-render,
+ * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
+ *
+ * **By default, there will be no reactive state subscriptions** and you must opt-in to state
+ * tracking by providing a selector function. This prevents unnecessary re-renders and gives you
+ * full control over when your component updates. Only when you provide a selector will the
+ * component re-render when the selected state values change.
+ *
+ * Available queuer state properties:
+ * - `executionCount`: Number of items that have been processed by the queuer
+ * - `expirationCount`: Number of items that have been removed due to expiration
+ * - `isEmpty`: Whether the queuer has no items to process
+ * - `isFull`: Whether the queuer has reached its maximum capacity
+ * - `isIdle`: Whether the queuer is not currently processing any items
+ * - `isRunning`: Whether the queuer is active and will process items automatically
+ * - `items`: Array of items currently waiting to be processed
+ * - `itemTimestamps`: Timestamps when items were added for expiration tracking
+ * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+ * - `rejectionCount`: Number of items that have been rejected from being added
+ * - `size`: Number of items currently in the queue
+ * - `status`: Current processing status ('idle' | 'running' | 'stopped')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const [value, queuer] = useQueuedValue(initialValue, {
+ *   wait: 500, // Wait 500ms between processing each change
+ *   started: true // Start processing immediately
+ * });
+ *
+ * // Opt-in to re-render when queue processing state changes (optimized for loading indicators)
+ * const [value, queuer] = useQueuedValue(
+ *   initialValue,
+ *   { wait: 500, started: true },
+ *   (state) => ({
+ *     isRunning: state.isRunning,
+ *     isIdle: state.isIdle,
+ *     status: state.status,
+ *     pendingTick: state.pendingTick
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when queue contents change (optimized for displaying queue status)
+ * const [value, queuer] = useQueuedValue(
+ *   initialValue,
+ *   { wait: 500, started: true },
+ *   (state) => ({
+ *     size: state.size,
+ *     isEmpty: state.isEmpty,
+ *     isFull: state.isFull
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when execution metrics change (optimized for stats display)
+ * const [value, queuer] = useQueuedValue(
+ *   initialValue,
+ *   { wait: 500, started: true },
+ *   (state) => ({
+ *     executionCount: state.executionCount,
+ *     expirationCount: state.expirationCount,
+ *     rejectionCount: state.rejectionCount
+ *   })
+ * );
+ *
+ * // Add changes to the queue
+ * const handleChange = (newValue) => {
+ *   queuer.addItem(newValue);
+ * };
+ *
+ * // Control the queue
+ * const pauseProcessing = () => {
+ *   queuer.stop();
+ * };
+ *
+ * const resumeProcessing = () => {
+ *   queuer.start();
+ * };
+ *
+ * // Access the selected queuer state (will be empty object {} unless selector provided)
+ * const { size, isRunning, executionCount } = queuer.state;
+ * ```
+ */
+declare function useQueuedValue<TValue, TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<QueuerState<TValue>, 'items'>>(initialValue: TValue, options?: QueuerOptions<TValue>, selector?: (state: QueuerState<TValue>) => TSelected): [TValue, PreactQueuer<TValue, TSelected>];
+//#endregion
+export { useQueuedValue };
+//# sourceMappingURL=useQueuedValue.d.cts.map