@plyaz/api 1.0.1 → 1.1.0

package/dist/api/polling/strategies.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Polling Strategy Presets
+ * Pre-configured polling strategies for common use cases
+ */
+import type { PollingConfig } from '@plyaz/types/api';
+import type { FetchResponse } from 'fetchff';
+/**
+ * Polling strategy names for type-safe access
+ */
+export type PollingStrategyName = 'jobStatus' | 'healthCheck' | 'liveData' | 'notifications' | 'longProcess' | 'resourceWait' | 'dataSync';
+/**
+ * Pre-configured polling strategies for common use cases
+ * These work with any response type - the actual types come from your endpoint definitions
+ */
+export declare const pollingStrategies: {
+    /**
+     * Job Status Monitoring
+     * Use Case: Checking job completion, task progress, async operations
+     * Pattern: Frequent checks with timeout and completion detection
+     * Expected fields: data.status (completed/failed/cancelled), data.progress
+     */
+    readonly jobStatus: {
+        interval: number;
+        delay: number;
+        maxAttempts: number;
+        shouldStop: <T>(response: FetchResponse<T>, attempt: number) => boolean;
+    };
+    /**
+     * Health Monitoring
+     * Use Case: Server health checks, service availability monitoring
+     * Pattern: Regular intervals, continuous monitoring
+     */
+    readonly healthCheck: {
+        interval: number;
+        delay: number;
+        maxAttempts: number;
+        shouldStop: () => false;
+    };
+    /**
+     * Live Data Feed
+     * Use Case: Real-time dashboards, stock prices, metrics
+     * Pattern: Rapid updates with smart stopping
+     * Expected fields: data.noUpdates
+     */
+    readonly liveData: {
+        interval: number;
+        delay: number;
+        maxAttempts: number;
+        shouldStop: <T>(response: FetchResponse<T>) => boolean;
+    };
+    /**
+     * Notification Check
+     * Use Case: New messages, alerts, updates
+     * Pattern: Moderate frequency with backoff
+     */
+    readonly notifications: {
+        interval: number;
+        delay: number;
+        maxAttempts: number;
+        shouldStop: <T>(_response: FetchResponse<T>, attempt: number) => boolean;
+    };
+    /**
+     * Long-Running Process
+     * Use Case: File uploads, data processing, migrations
+     * Pattern: Adaptive intervals based on expected duration
+     * Expected fields: data.progress, data.status
+     */
+    readonly longProcess: {
+        interval: number;
+        delay: number;
+        maxAttempts: number;
+        shouldStop: <T>(response: FetchResponse<T>, attempt: number) => boolean;
+    };
+    /**
+     * Resource Availability
+     * Use Case: Waiting for resource to become available
+     * Pattern: Exponential backoff-like behavior
+     * Expected fields: data.available
+     */
+    readonly resourceWait: {
+        interval: number;
+        delay: number;
+        maxAttempts: number;
+        shouldStop: <T>(response: FetchResponse<T>, attempt: number) => boolean;
+    };
+    /**
+     * Data Sync
+     * Use Case: Syncing with external systems, data reconciliation
+     * Pattern: Periodic checks with conflict detection
+     * Expected fields: data.syncComplete, data.hasConflicts
+     */
+    readonly dataSync: {
+        interval: number;
+        delay: number;
+        maxAttempts: number;
+        shouldStop: <T>(response: FetchResponse<T>, attempt: number) => boolean;
+    };
+};
+/**
+ * Create custom polling strategy with defaults
+ *
+ * @param options - Partial polling configuration
+ * @returns Complete polling configuration with defaults
+ *
+ * @example
+ * ```typescript
+ * const customPolling = createPollingStrategy({
+ *   interval: 3000,
+ *   maxAttempts: 10
+ * });
+ * ```
+ */
+export declare function createPollingStrategy<T = unknown>(options: Partial<PollingConfig<T>>): PollingConfig<T>;
+/**
+ * Apply polling strategy by name or config
+ *
+ * @param strategy - Strategy name or config object
+ * @returns Polling configuration
+ *
+ * @example
+ * ```typescript
+ * const config = applyPollingStrategy('jobStatus');
+ * // or
+ * const config = applyPollingStrategy({ interval: 2000 });
+ * ```
+ */
+export declare function applyPollingStrategy<T = unknown>(strategy: PollingStrategyName | PollingConfig<T>): PollingConfig<T>;
+//# sourceMappingURL=strategies.d.ts.map

package/dist/api/polling/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../src/api/polling/strategies.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAuB7C;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,aAAa,GACb,UAAU,GACV,eAAe,GACf,aAAa,GACb,cAAc,GACd,UAAU,CAAC;AAEf;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;;;;OAKG;;;;;qBAKY,CAAC,YAAY,aAAa,CAAC,CAAC,CAAC,WAAW,MAAM;;IAU7D;;;;OAIG;;;;;;;IAQH;;;;;OAKG;;;;;qBAKY,CAAC,YAAY,aAAa,CAAC,CAAC,CAAC;;IAM5C;;;;OAIG;;;;;qBAKY,CAAC,aAAa,aAAa,CAAC,CAAC,CAAC,WAAW,MAAM;;IAQ9D;;;;;OAKG;;;;;qBAKY,CAAC,YAAY,aAAa,CAAC,CAAC,CAAC,WAAW,MAAM;;IAW7D;;;;;OAKG;;;;;qBAKY,CAAC,YAAY,aAAa,CAAC,CAAC,CAAC,WAAW,MAAM;;IAM7D;;;;;OAKG;;;;;qBAKY,CAAC,YAAY,aAAa,CAAC,CAAC,CAAC,WAAW,MAAM;;CASrD,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EAC/C,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GACjC,aAAa,CAAC,CAAC,CAAC,CAQlB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAC9C,QAAQ,EAAE,mBAAmB,GAAG,aAAa,CAAC,CAAC,CAAC,GAC/C,aAAa,CAAC,CAAC,CAAC,CAKlB"}

package/dist/api/polling/utils.d.ts

@@ -0,0 +1,133 @@
+import type { PollingConfig, ProgressivePollingOptions, ConditionalPollingOptions } from '@plyaz/types/api';
+/**
+ * Check if polling is active based on configuration
+ *
+ * @param config - Polling configuration to check
+ * @returns True if polling is enabled
+ *
+ * @example
+ * ```typescript
+ * if (isPollingActive(config)) {
+ *   console.log('Polling is enabled');
+ * }
+ * ```
+ */
+export declare function isPollingActive<T>(config: PollingConfig<T>): boolean;
+/**
+ * Calculate total polling duration based on configuration
+ *
+ * @param config - Polling configuration
+ * @returns Total duration in milliseconds, or null if infinite
+ *
+ * @example
+ * ```typescript
+ * const duration = calculatePollingDuration({
+ *   interval: 2000,
+ *   delay: 500,
+ *   maxAttempts: 10
+ * });
+ * // Returns: 25000 (20s intervals + 5s delays)
+ * ```
+ */
+export declare function calculatePollingDuration<T>(config: PollingConfig<T>): number | null;
+/**
+ * Create SSR-safe polling configuration
+ * Disables polling on server-side rendering
+ *
+ * @param config - Original polling configuration
+ * @returns SSR-safe configuration
+ *
+ * @example
+ * ```typescript
+ * const safeConfig = getSSRSafePollingConfig({
+ *   interval: 5000,
+ *   maxAttempts: 10
+ * });
+ * // On server: { interval: 0, maxAttempts: 1 }
+ * // On client: unchanged
+ * ```
+ */
+export declare function getSSRSafePollingConfig<T>(config: PollingConfig<T>): PollingConfig<T>;
+/**
+ * Create progressive polling with increasing intervals
+ *
+ * @param options - Progressive polling options
+ * @returns Polling configuration with progressive intervals
+ *
+ * @example
+ * ```typescript
+ * const config = createProgressivePolling<MyResponse>({
+ *   baseInterval: 1000,
+ *   maxInterval: 30000,
+ *   multiplier: 1.5
+ * });
+ * // Intervals: 1s, 1.5s, 2.25s, ... up to 30s
+ * ```
+ */
+export declare function createProgressivePolling<T = unknown>(options?: ProgressivePollingOptions): PollingConfig<T>;
+/**
+ * Create condition-based polling configuration
+ *
+ * @param options - Conditional polling options
+ * @returns Polling configuration with condition checking
+ *
+ * @example
+ * ```typescript
+ * const config = createConditionalPolling<MyResponse>({
+ *   successCondition: (response) => response?.data?.ready === true,
+ *   errorCondition: (response) => response?.data?.failed === true,
+ *   timeoutMs: 60000
+ * });
+ * ```
+ */
+export declare function createConditionalPolling<T = unknown>(options: ConditionalPollingOptions<T>): PollingConfig<T>;
+/**
+ * Create visibility-aware polling configuration
+ * Stops polling when document is hidden (browser tab inactive)
+ *
+ * @param baseConfig - Base polling configuration
+ * @returns Polling configuration with visibility checking
+ *
+ * @example
+ * ```typescript
+ * const config = createVisibilityAwarePolling<MyResponse>({
+ *   interval: 5000,
+ *   maxAttempts: 100
+ * });
+ * // Stops polling when tab is hidden
+ * ```
+ */
+export declare function createVisibilityAwarePolling<T>(baseConfig: PollingConfig<T>): PollingConfig<T>;
+/**
+ * Merge polling configurations with priority
+ * Later configs override earlier ones
+ *
+ * @param configs - Polling configurations to merge
+ * @returns Merged polling configuration
+ *
+ * @example
+ * ```typescript
+ * const merged = mergePollingConfigs(
+ *   { interval: 1000 },
+ *   { maxAttempts: 10 },
+ *   { delay: 500 }
+ * );
+ * // Result: { interval: 1000, maxAttempts: 10, delay: 500 }
+ * ```
+ */
+export declare function mergePollingConfigs<T>(...configs: Array<PollingConfig<T> | undefined>): PollingConfig<T>;
+/**
+ * Validate polling configuration
+ *
+ * @param config - Polling configuration to validate
+ * @returns True if configuration is valid
+ *
+ * @example
+ * ```typescript
+ * if (isValidPollingConfig(config)) {
+ *   // Use config safely
+ * }
+ * ```
+ */
+export declare function isValidPollingConfig<T = unknown>(config: unknown): config is PollingConfig<T>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/api/polling/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/api/polling/utils.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,aAAa,EACb,yBAAyB,EACzB,yBAAyB,EAC1B,MAAM,kBAAkB,CAAC;AAO1B;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAEpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAQnF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAUrF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EAClD,OAAO,GAAE,yBAA8B,GACtC,aAAa,CAAC,CAAC,CAAC,CAqBlB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EAClD,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACpC,aAAa,CAAC,CAAC,CAAC,CA4DlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAmB9F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,GAAG,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAC9C,aAAa,CAAC,CAAC,CAAC,CAqBlB;AA+BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,aAAa,CAAC,CAAC,CAAC,CAa7F"}

package/dist/api/pubsub/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Pub/Sub System - Lightweight wrapper for fetchff's subscribe functionality
+ *
+ * @module pubsub
+ */
+import { subscribe as fetchffSubscribe, mutate, revalidate, type FetchResponse } from 'fetchff';
+import type { DefaultResponse, EventEmitter, SubscriptionCallback } from '@plyaz/types/api';
+import { PUB_SUB_EVENT } from '@plyaz/types/api';
+export type { EventEmitter, SubscriptionCallback, DefaultResponse, PubSubEvent, Serializable, } from '@plyaz/types/api';
+export { PUB_SUB_EVENT };
+/**
+ * Subscribe to cache updates for a specific key or pattern
+ * Direct export from fetchff for vendor abstraction
+ *
+ * @param key - Cache key or URL pattern to subscribe to
+ * @param callback - Function called when cache updates
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = subscribe('/api/users', (response) => {
+ *   console.log('Cache updated:', response.data);
+ * });
+ *
+ * // Cleanup when done
+ * unsubscribe();
+ * ```
+ */
+export declare const subscribe: typeof fetchffSubscribe;
+/**
+ * Trigger cache update and notify subscribers
+ * Direct export from fetchff
+ *
+ * @param key - Cache key to update
+ * @param data - New data or updater function
+ * @param options - Optional configuration
+ *
+ * @example
+ * ```typescript
+ * // Update cache and notify subscribers
+ * mutate('/api/user', newUserData);
+ *
+ * // Optimistic update with rollback
+ * mutate('/api/user', updatedData, {
+ *   optimistic: true,
+ *   rollbackOnError: true
+ * });
+ * ```
+ */
+export { mutate };
+/**
+ * Revalidate cache and notify subscribers
+ * Direct export from fetchff
+ *
+ * @param key - Cache key(s) to revalidate
+ * @returns Promise that resolves when revalidation completes
+ *
+ * @example
+ * ```typescript
+ * // Revalidate specific endpoint
+ * await revalidate('/api/user');
+ *
+ * // Revalidate multiple endpoints
+ * await revalidate(['/api/user', '/api/posts']);
+ * ```
+ */
+export { revalidate };
+/**
+ * Create a typed subscription for better type safety
+ *
+ * @param key - Cache key to subscribe to
+ * @param callback - Typed callback function
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * const unsubscribe = createTypedSubscription<User>(
+ *   '/api/user',
+ *   (response) => {
+ *     if (response.data) {
+ *       console.log(response.data.name); // TypeScript knows this is a User
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare function createTypedSubscription<T = DefaultResponse>(key: string, callback: SubscriptionCallback<T>): () => void;
+/**
+ * Subscribe to multiple cache keys with a single handler
+ *
+ * @param keys - Array of cache keys to subscribe to
+ * @param callback - Function called when any cache updates
+ * @returns Function to unsubscribe from all
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = subscribeMultiple(
+ *   ['/api/users', '/api/posts', '/api/comments'],
+ *   (key, response) => {
+ *     console.log(`${key} updated:`, response.data);
+ *   }
+ * );
+ * ```
+ */
+export declare function subscribeMultiple<T = DefaultResponse>(keys: string[], callback: (key: string, response: FetchResponse<T>) => void): () => void;
+/**
+ * Subscribe with automatic cleanup after timeout
+ *
+ * @param key - Cache key to subscribe to
+ * @param callback - Subscription callback
+ * @param timeout - Timeout in milliseconds
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * // Subscribe for 30 seconds only
+ * const unsubscribe = subscribeWithTimeout(
+ *   '/api/live-data',
+ *   (response) => console.log('Update:', response),
+ *   30000
+ * );
+ * ```
+ */
+export declare function subscribeWithTimeout<T = DefaultResponse>(key: string, callback: SubscriptionCallback<T>, timeout: number): () => void;
+/**
+ * Subscribe once - automatically unsubscribes after first update
+ *
+ * @param key - Cache key to subscribe to
+ * @param callback - Subscription callback
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * subscribeOnce('/api/user', (response) => {
+ *   console.log('User updated once:', response.data);
+ *   // Automatically unsubscribed after this
+ * });
+ * ```
+ */
+export declare function subscribeOnce<T = DefaultResponse>(key: string, callback: SubscriptionCallback<T>): () => void;
+export declare function createEventEmitter<T = DefaultResponse>(): EventEmitter<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/pubsub/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/pubsub/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,IAAI,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAEhG,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EAGZ,oBAAoB,EAErB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAKjD,YAAY,EACV,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,YAAY,GACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,CAAC;AAYzB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS,yBAAmB,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,eAAe,EACzD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAChC,MAAM,IAAI,CAEZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,eAAe,EACnD,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,GAC1D,MAAM,IAAI,CAQZ;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,eAAe,EACtD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,EACjC,OAAO,EAAE,MAAM,GACd,MAAM,IAAI,CAWZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,eAAe,EAC/C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAChC,MAAM,IAAI,CAWZ;AA+PD,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,eAAe,KAAK,YAAY,CAAC,CAAC,CAAC,CAqHzE"}

package/dist/api/pubsub/react.d.ts

@@ -0,0 +1,214 @@
+/**
+ * React hooks for Pub/Sub system
+ *
+ * @module pubsub/react
+ */
+import type { FetchResponse, ResponseError } from 'fetchff';
+import type { SubscriptionCallback, DefaultResponse } from './index';
+/**
+ * Union type for API errors - can be ResponseError from fetchff or standard Error
+ */
+type ApiError = ResponseError | Error;
+/**
+ * Hook to subscribe to cache updates
+ * Handles cleanup automatically
+ *
+ * @param key - Cache key to subscribe to
+ * @param callback - Function called on cache updates
+ * @param enabled - Enable/disable subscription
+ *
+ * @example
+ * ```typescript
+ * function LiveData() {
+ *   const [data, setData] = useState(null);
+ *
+ *   useSubscription('/api/live-data', (response) => {
+ *     if (response.data) {
+ *       setData(response.data);
+ *     }
+ *   });
+ *
+ *   return <Display data={data} />;
+ * }
+ * ```
+ */
+export declare function useSubscription<T = DefaultResponse>(key: string | null, callback: SubscriptionCallback<T>, enabled?: boolean): void;
+/**
+ * Subscribe to multiple cache keys at once
+ * Useful for dashboards or components that need multiple data sources
+ *
+ * @param keys - Array of cache keys to subscribe to
+ * @param callback - Function called on any cache update
+ * @param enabled - Enable/disable all subscriptions
+ *
+ * @example
+ * ```typescript
+ * function Dashboard() {
+ *   const [metrics, setMetrics] = useState({});
+ *
+ *   useMultipleSubscriptions(
+ *     ['/api/metrics', '/api/alerts', '/api/status'],
+ *     (key, response) => {
+ *       const dataKey = key.split('/').pop();
+ *       setMetrics(prev => ({
+ *         ...prev,
+ *         [dataKey]: response.data
+ *       }));
+ *     }
+ *   );
+ *
+ *   return <MetricsDisplay data={metrics} />;
+ * }
+ * ```
+ */
+export declare function useMultipleSubscriptions<T = DefaultResponse>(keys: string[], callback: (key: string, response: FetchResponse<T>) => void, enabled?: boolean): void;
+/**
+ * Hook for optimistic updates with subscription
+ * Provides mutate function and subscribes to updates
+ *
+ * @param key - Cache key
+ * @param initialData - Initial data value
+ *
+ * @example
+ * ```typescript
+ * function EditableUser({ userId }) {
+ *   const { data, mutate, isValidating } = useOptimisticUpdate(
+ *     `/api/user/${userId}`,
+ *     null
+ *   );
+ *
+ *   const updateName = async (newName) => {
+ *     // Optimistic update
+ *     mutate({ ...data, name: newName });
+ *
+ *     // Send to server
+ *     await api.updateUser(userId, { name: newName });
+ *   };
+ *
+ *   return (
+ *     <input
+ *       value={data?.name || ''}
+ *       onChange={(e) => updateName(e.target.value)}
+ *       disabled={isValidating}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function useOptimisticUpdate<T = DefaultResponse>(key: string, initialData?: T): {
+    data: T | undefined;
+    mutate: (data: T | ((current: T | undefined) => T)) => void;
+    isValidating: boolean;
+    error: ApiError | undefined;
+};
+/**
+ * Hook for real-time data with automatic refresh
+ *
+ * @param key - Cache key
+ * @param refreshInterval - Refresh interval in milliseconds
+ * @param enabled - Enable/disable real-time updates
+ *
+ * @example
+ * ```typescript
+ * function LiveMetrics() {
+ *   const { data, isLoading, error } = useRealTimeData(
+ *     '/api/metrics/live',
+ *     5000 // Refresh every 5 seconds
+ *   );
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <Error error={error} />;
+ *
+ *   return <MetricsChart data={data} />;
+ * }
+ * ```
+ */
+export declare function useRealTimeData<T = DefaultResponse>(key: string, refreshInterval?: number, enabled?: boolean): {
+    data: T | undefined;
+    isLoading: boolean;
+    error: ApiError | undefined;
+    refresh: () => void;
+};
+/**
+ * Hook for subscription with debounced callback
+ * Useful for reducing update frequency
+ *
+ * @param key - Cache key
+ * @param callback - Debounced callback
+ * @param delay - Debounce delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * function SearchResults() {
+ *   const [results, setResults] = useState([]);
+ *
+ *   // Only update UI after 300ms of no changes
+ *   useDebouncedSubscription(
+ *     '/api/search/results',
+ *     (response) => {
+ *       setResults(response.data || []);
+ *     },
+ *     300
+ *   );
+ *
+ *   return <ResultsList results={results} />;
+ * }
+ * ```
+ */
+export declare function useDebouncedSubscription<T = DefaultResponse>(key: string | null, callback: SubscriptionCallback<T>, delay?: number): void;
+/**
+ * Hook for conditional subscription based on a condition
+ *
+ * @param key - Cache key
+ * @param callback - Subscription callback
+ * @param condition - Condition function or boolean
+ *
+ * @example
+ * ```typescript
+ * function ConditionalData({ shouldFetch }) {
+ *   const [data, setData] = useState(null);
+ *
+ *   useConditionalSubscription(
+ *     '/api/conditional-data',
+ *     (response) => setData(response.data),
+ *     shouldFetch // Only subscribe when true
+ *   );
+ *
+ *   return data ? <DataView data={data} /> : <Empty />;
+ * }
+ * ```
+ */
+export declare function useConditionalSubscription<T = DefaultResponse>(key: string | null, callback: SubscriptionCallback<T>, condition?: boolean | (() => boolean)): void;
+/**
+ * Hook to track subscription state
+ *
+ * @param key - Cache key
+ * @returns Subscription state
+ *
+ * @example
+ * ```typescript
+ * function DataComponent() {
+ *   const { data, error, isValidating, isSubscribed } = useSubscriptionState(
+ *     '/api/data'
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       {isSubscribed && <Badge>Live</Badge>}
+ *       {isValidating && <Spinner />}
+ *       {error && <Error error={error} />}
+ *       {data && <DataView data={data} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSubscriptionState<T = DefaultResponse>(key: string | null): {
+    data: T | undefined;
+    error: ApiError | undefined;
+    isValidating: boolean;
+    isLoading: boolean;
+    isSubscribed: boolean;
+};
+export {};
+//# sourceMappingURL=react.d.ts.map

package/dist/api/pubsub/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../../src/api/pubsub/react.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAErE;;GAEG;AACH,KAAK,QAAQ,GAAG,aAAa,GAAG,KAAK,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,eAAe,EACjD,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,EACjC,OAAO,UAAO,GACb,IAAI,CAaN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,eAAe,EAC1D,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,EAC3D,OAAO,UAAO,GACb,IAAI,CAeN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,eAAe,EACrD,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,CAAC,GACd;IACD,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC7B,CAuCA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,eAAe,EACjD,GAAG,EAAE,MAAM,EACX,eAAe,CAAC,EAAE,MAAM,EACxB,OAAO,UAAO,GACb;IACD,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CA4CA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,eAAe,EAC1D,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,EACjC,KAAK,SAAM,GACV,IAAI,CAsBN;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,GAAG,eAAe,EAC5D,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,EACjC,SAAS,GAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAQ,GAC1C,IAAI,CAGN;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,eAAe,EACtD,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB;IACD,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;CACvB,CA2CA"}