jquery-pro-query 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# jquery-pro-query 🌐 v1.1.0
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Smart Async Data Fetching, Automatic Caching, Request Deduplication, SWR, Optimistic UI, & Infinite Queries for jQuery.**
+
+Bring modern server-state management (like TanStack/React Query v5 and SWR) to your legacy jQuery applications. Stop writing repetitive `$.ajax()` boilerplate and start building fast, cached, auto-updating web applications with zero backend changes.
+
+---
+
+## Features in v1.1.0 🚀
+
+1. **⚡ Optimistic UI Updates & Cache Rollback:** Instantly update the UI before the network request finishes, with automatic rollback if the server fails.
+2. **♾️ Infinite Scrolling & Paginated Queries (`$.infiniteQuery`):** Handle paginated feeds and "Load More" lists with `fetchNextPage()`, `hasNextPage`, and `isFetchingNextPage`.
+3. **💾 Offline Cache Persistence (`$.queryClient.setPersistence`):** Persist query cache to `localStorage` or `sessionStorage` so pages load instantly offline.
+4. **🔗 Conditional & Dependent Queries (`enabled` flag):** Execute queries conditionally (e.g. wait for a user ID signal before fetching user details).
+5. **🔌 Native `jquery-signals` Integration:** Reactive Signals for `data`, `isLoading`, `isFetching`, `isError`, `isFetchingNextPage`.
+
+---
+
+## Quick Example
+
+```javascript
+// Enable Offline Cache Persistence
+$.queryClient.setPersistence({ key: 'app_query_cache', storage: 'local' });
+
+// 1. Conditional Query (only runs when userId has a value)
+const userDetails = $.query(['user', userIdSignal], () => $.get(`/api/user/${userIdSignal.value}`), {
+    enabled: () => Boolean(userIdSignal.value)
+});
+
+// 2. Infinite Query for Paginated Lists
+const auditLogs = $.infiniteQuery('audit-logs', ({ pageParam = 1 }) => $.get(`/api/logs?page=${pageParam}`), {
+    initialPageParam: 1,
+    getNextPageParam: (lastPage, allPages) => lastPage.hasMore ? allPages.length + 1 : undefined
+});
+
+// 3. Optimistic UI Mutation with Rollback
+const updateName = $.mutation((newName) => $.post('/api/user', { name: newName }), {
+    onMutate: async (newName) => {
+        const previousData = $.queryClient.getQueryData('user');
+        $.queryClient.setQueryData('user', { ...previousData, name: newName }); // 0ms UI Update!
+        return { previousData }; // Return rollback context
+    },
+    onError: (err, variables, context) => {
+        if (context?.previousData) {
+            $.queryClient.setQueryData('user', context.previousData); // Automatic Rollback!
+        }
+    }
+});
+```
+
+---
+
+## Core API Reference
+
+### `$.query(queryKey, fetcherFn, [options])`
+Creates a managed async query instance.
+
+**Options:**
+* `enabled` *(boolean|function)*: Conditional execution. If false or evaluates to false, query will not run.
+* `staleTime` *(number)*: Time in ms before data is considered stale.
+* `cacheTime` *(number)*: Time in ms data stays in memory cache (default: 5 mins).
+* `refetchOnWindowFocus` *(boolean)*: Re-runs query when browser tab regains focus.
+* `retry` *(number)*: Retry attempts on failure.
+
+---
+
+### `$.infiniteQuery(queryKey, fetcherFn, [options])`
+Creates a managed paginated / infinite scrolling query instance.
+
+**Options:**
+* `initialPageParam`: Initial page parameter (default: `1`).
+* `getNextPageParam(lastPage, allPages)`: Function determining the next page parameter or returning `undefined` if no more pages exist.
+
+**Methods:**
+* `fetchNextPage()`: Fetches the next page and appends it to `data.pages`.
+* `hasNextPage`: Reactive signal/boolean indicating if more pages are available.
+* `isFetchingNextPage`: Reactive signal/boolean indicating if a next page request is running.
+
+---
+
+### `$.mutation(mutationFn, [options])`
+Creates a managed async mutation instance.
+
+**Options:**
+* `onMutate(variables)`: Fired before mutation starts (ideal for Optimistic UI updates). Returns rollback context.
+* `onSuccess(data, variables, context)`: Fired when mutation succeeds.
+* `onError(error, variables, context)`: Fired when mutation fails (ideal for cache rollbacks).
+* `onSettled(data, error, variables, context)`: Fired on success or failure.
+
+---
+
+### `$.queryClient`
+Global cache and query controller.
+
+* `$.queryClient.setPersistence({ key, storage, maxAge })`: Enables persistent caching to `localStorage` / `sessionStorage`.
+* `$.queryClient.setQueryData(key, updaterOrValue)`: Manually updates or populates cached query data.
+* `$.queryClient.getQueryData(key)`: Retrieves cached data for a query key.
+* `$.queryClient.invalidateQueries(keyPattern)`: Marks matching queries stale and triggers background refetch.
+* `$.queryClient.prefetchQuery(key, fetcherFn)`: Fetches data ahead of time.
+
+---
+
+## License
+MIT

package/example.html

@@ -0,0 +1,164 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>jquery-pro-query v1.1.0 Showcase</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; padding: 2rem; max-width: 700px; margin: 0 auto; line-height: 1.5; background: #f8fafc; color: #1e293b; }
+    .card { border: 1px solid #e2e8f0; padding: 1.5rem; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.04); margin-bottom: 1.5rem; background: #fff; }
+    button { background: #3b82f6; color: white; border: none; padding: 0.5rem 1rem; border-radius: 4px; cursor: pointer; font-size: 0.95rem; font-weight: 500; }
+    button:hover { background: #2563eb; }
+    button:disabled { background: #cbd5e1; cursor: not-allowed; }
+    button.btn-danger { background: #ef4444; }
+    button.btn-danger:hover { background: #dc2626; }
+    .status-tag { display: inline-block; padding: 0.2rem 0.5rem; border-radius: 4px; font-size: 0.8rem; font-weight: 600; }
+    .bg-green { background: #dcfce7; color: #166534; }
+    .bg-blue { background: #dbeafe; color: #1e40af; }
+    .bg-amber { background: #fef3c7; color: #92400e; }
+    .hidden { display: none !important; }
+    ul { list-style: none; padding: 0; margin: 0.5rem 0 0 0; }
+    li { padding: 0.5rem; border-bottom: 1px solid #f1f5f9; }
+  </style>
+</head>
+<body>
+
+  <h1>🌐 jquery-pro-query v1.1.0 Showcase</h1>
+  <p style="color: #64748b; margin-top: -0.5rem; margin-bottom: 2rem;">Optimistic UI, Infinite Queries, Conditional Execution, & Offline Cache Persistence.</p>
+
+  <!-- Demo 1: Optimistic UI Updates & Automatic Rollback -->
+  <div class="card">
+    <h2>1. Optimistic UI Updates & Rollback</h2>
+    <p>Likes Count: <strong id="likes-count">0</strong> <span id="likes-status" class="status-tag bg-green">Synced</span></p>
+    
+    <div style="display: flex; gap: 0.5rem; margin-top: 1rem;">
+      <button id="btn-like-success">Like (Optimistic 0ms - Server Succeeds)</button>
+      <button id="btn-like-fail" class="btn-danger">Like (Optimistic 0ms - Server Fails & Rolls back)</button>
+    </div>
+  </div>
+
+  <!-- Demo 2: Infinite Scrolling / Pagination Query -->
+  <div class="card">
+    <h2>2. Infinite Query (<code>$.infiniteQuery</code>)</h2>
+    <p>Loaded Logs:</p>
+    <ul id="logs-list"></ul>
+    
+    <div style="margin-top: 1rem;">
+      <button id="btn-load-more">Load Next Page</button>
+    </div>
+  </div>
+
+  <!-- Demo 3: Conditional / Dependent Queries -->
+  <div class="card">
+    <h2>3. Conditional Query (<code>enabled</code>)</h2>
+    <p>Selected User ID: <strong id="selected-user-id">None</strong></p>
+    <p>Dependent User Data: <span id="user-details" style="font-weight: bold;">(Waiting for selection...)</span></p>
+    
+    <div style="margin-top: 1rem; display: flex; gap: 0.5rem;">
+      <button id="btn-select-user-1">Select User #101</button>
+      <button id="btn-clear-user">Clear Selection</button>
+    </div>
+  </div>
+
+  <!-- Load Dependencies -->
+  <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+  <script src="../jquery-signals/src/jquery-signals.js"></script>
+  <script src="./src/jquery-pro-query.js"></script>
+
+  <script>
+    $(function() {
+      // Enable Offline Cache Persistence
+      $.queryClient.setPersistence({ key: 'demo_query_cache', storage: 'local' });
+
+      // --- Demo 1: Optimistic UI Setup ---
+      $.queryClient.setQueryData('post-likes', 42);
+
+      const likesQuery = $.query('post-likes', () => Promise.resolve($.queryClient.getQueryData('post-likes')));
+      $('#likes-count').bindSignal(likesQuery.dataSignal);
+
+      const likeMutation = $.mutation((shouldFail) => {
+        return new Promise((resolve, reject) => {
+          setTimeout(() => {
+            if (shouldFail) reject(new Error('Server Error: Network Disconnected'));
+            else resolve($.queryClient.getQueryData('post-likes'));
+          }, 1500);
+        });
+      }, {
+        onMutate: async (shouldFail) => {
+          // Snapshot previous data before optimistic update
+          const previousLikes = $.queryClient.getQueryData('post-likes');
+          // Optimistically increment UI to 0ms latency!
+          $.queryClient.setQueryData('post-likes', previousLikes + 1);
+          $('#likes-status').text('Optimistic Update (Server pending...)').removeClass('bg-green').addClass('bg-amber');
+
+          return { previousLikes }; // Return context for rollback
+        },
+        onSuccess: () => {
+          $('#likes-status').text('Synced with Server!').removeClass('bg-amber').addClass('bg-green');
+        },
+        onError: (err, variables, context) => {
+          // Automatic Rollback to snapshot!
+          if (context && context.previousLikes !== undefined) {
+            $.queryClient.setQueryData('post-likes', context.previousLikes);
+          }
+          alert(err.message + ' -> Rolled back to ' + context.previousLikes);
+          $('#likes-status').text('Rolled Back!').removeClass('bg-amber').addClass('bg-green');
+        }
+      });
+
+      $('#btn-like-success').on('click', () => likeMutation.mutate(false));
+      $('#btn-like-fail').on('click', () => likeMutation.mutate(true));
+
+      // --- Demo 2: Infinite Query Setup ---
+      const infiniteLogs = $.infiniteQuery('audit-logs', ({ pageParam = 1 }) => {
+        return new Promise((resolve) => {
+          setTimeout(() => {
+            resolve([
+              `Log Entry #${pageParam}-A: System boot`,
+              `Log Entry #${pageParam}-B: User login`,
+              `Log Entry #${pageParam}-C: Database backup`
+            ]);
+          }, 500);
+        });
+      }, {
+        initialPageParam: 1,
+        getNextPageParam: (lastPage, allPages) => allPages.length < 4 ? allPages.length + 1 : undefined
+      });
+
+      // Bind infinite pages array to list
+      $.effect(() => {
+        const pages = infiniteLogs.dataSignal.value?.pages || [];
+        const allItems = pages.flat();
+        $('#logs-list').empty();
+        allItems.forEach(item => $('#logs-list').append(`<li>${item}</li>`));
+      });
+
+      $('#btn-load-more').bindSignalProp('disabled', infiniteLogs.isFetchingNextPageSignal);
+      $('#btn-load-more').bindSignal(infiniteLogs.isFetchingNextPageSignal, fetching => fetching ? 'Loading Page...' : 'Load Next Page');
+      $('#btn-load-more').on('click', () => infiniteLogs.fetchNextPage());
+
+      // --- Demo 3: Conditional Query Setup ---
+      const selectedUserId = $.signal(null);
+      $('#selected-user-id').bindSignal(selectedUserId, id => id || 'None');
+
+      const dependentQuery = $.query(['user-detail', selectedUserId], () => {
+        return new Promise(resolve => {
+          setTimeout(() => {
+            resolve(`Details for User #${selectedUserId.value}: Role = Admin, Access = Granted`);
+          }, 800);
+        });
+      }, {
+        enabled: () => Boolean(selectedUserId.value) // Only runs when user ID is selected!
+      });
+
+      $('#user-details').bindSignal(dependentQuery.dataSignal, data => data || '(Waiting for selection...)');
+
+      $('#btn-select-user-1').on('click', () => selectedUserId.value = 101);
+      $('#btn-clear-user').on('click', () => {
+        selectedUserId.value = null;
+        $.queryClient.setQueryData(['user-detail', null], undefined);
+      });
+    });
+  </script>
+</body>
+</html>

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "jquery-pro-query",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Smart async data fetching, automatic caching, request deduplication, and SWR for jQuery.",
+  "main": "src/jquery-pro-query.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "jquery",
+    "jquery-plugin",
+    "query",
+    "cache",
+    "data-fetching",
+    "swr",
+    "stale-while-revalidate",
+    "mutation",
+    "ajax",
+    "optimistic-ui"
+  ],
+  "author": "prabhnoorsingh12",
+  "license": "MIT",
+  "peerDependencies": {
+    "jquery": ">=1.12.0"
+  }
+}

package/src/jquery-pro-query.js

@@ -0,0 +1,587 @@
+/**
+ * jquery-pro-query v1.1.1
+ * Smart async data fetching, automatic caching, request deduplication, SWR, Optimistic UI, & Infinite Queries for jQuery.
+ * https://github.com/prabhnoorsingh12/jquery-pro-query
+ *
+ * (c) 2026 prabhnoorsingh12
+ * Released under the MIT License.
+ */
+
+(function (factory) {
+  if (typeof define === 'function' && define.amd) {
+    // AMD
+    define(['jquery'], factory);
+  } else if (typeof exports === 'object') {
+    // Node/CommonJS
+    module.exports = factory(require('jquery'));
+  } else {
+    // Browser globals
+    if (typeof jQuery === 'undefined') {
+      throw new Error('jquery-pro-query requires jQuery');
+    }
+    factory(jQuery);
+  }
+}(function ($) {
+  'use strict';
+
+  // Helper to recursively unwrap Signals, getters, or functions inside Query Keys
+  function unwrapKey(key) {
+    if (key === null || key === undefined) return key;
+    if (typeof key === 'function') return unwrapKey(key());
+    if (typeof key === 'object' && typeof key.peek === 'function') return unwrapKey(key.peek());
+    if (typeof key === 'object' && key.value !== undefined && key.subscribers !== undefined) return unwrapKey(key.value);
+    if (Array.isArray(key)) return key.map(unwrapKey);
+    return key;
+  }
+
+  // Helper to normalize query keys (string or array) into a deterministic string identifier
+  function hashQueryKey(key) {
+    const unwrapped = unwrapKey(key);
+    if (typeof unwrapped === 'string') return unwrapped;
+    if (Array.isArray(unwrapped)) return JSON.stringify(unwrapped);
+    return String(unwrapped);
+  }
+
+  // Helper to create a reactive state property (uses $.signal if available, else standard getter/setter)
+  function createReactiveVal(initialVal) {
+    if (typeof $.signal === 'function') {
+      return $.signal(initialVal);
+    }
+    let _val = initialVal;
+    return {
+      get value() { return _val; },
+      set value(v) { _val = v; },
+      peek() { return _val; }
+    };
+  }
+
+  // Helper to convert jQuery $.Deferred / jqXHR or standard thenables safely to native Promise
+  function toNativePromise(thenableOrVal) {
+    if (thenableOrVal && typeof thenableOrVal.then === 'function') {
+      return new Promise((resolve, reject) => {
+        thenableOrVal.then(resolve, reject);
+      });
+    }
+    return Promise.resolve(thenableOrVal);
+  }
+
+  /**
+   * Query Class
+   */
+  class Query {
+    constructor(key, fetcherFn, options = {}) {
+      this.key = hashQueryKey(key);
+      this.rawKey = key;
+      this.fetcherFn = fetcherFn;
+
+      this.options = Object.assign({
+        enabled: true,             // Conditional query execution
+        staleTime: 0,              // Data is stale immediately by default
+        cacheTime: 300000,         // 5 minutes in memory cache
+        refetchOnWindowFocus: true,
+        refetchOnReconnect: true,
+        retry: 3,                  // Retry attempts
+        retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000), // Exponential backoff
+        refetchInterval: false     // Polling interval
+      }, options);
+
+      // Reactive state signals
+      this._data = createReactiveVal(undefined);
+      this._isLoading = createReactiveVal(false);
+      this._isFetching = createReactiveVal(false);
+      this._isError = createReactiveVal(false);
+      this._error = createReactiveVal(null);
+      this._status = createReactiveVal('idle'); // 'idle' | 'loading' | 'success' | 'error'
+
+      this.updatedAt = 0;
+      this.inFlightPromise = null;
+      this.subscribers = new Set();
+      this.intervalId = null;
+      this.enabledDisposer = null;
+
+      // Auto-watch enabled flag if it's a function or signal
+      this.setupEnabledWatcher();
+
+      if (this.options.refetchInterval && typeof this.options.refetchInterval === 'number') {
+        this.startPolling();
+      }
+    }
+
+    get data() { return this._data.value !== undefined ? this._data.value : this._data; }
+    get isLoading() { return this._isLoading.value !== undefined ? this._isLoading.value : this._isLoading; }
+    get isFetching() { return this._isFetching.value !== undefined ? this._isFetching.value : this._isFetching; }
+    get isError() { return this._isError.value !== undefined ? this._isError.value : this._isError; }
+    get error() { return this._error.value !== undefined ? this._error.value : this._error; }
+
+    get dataSignal() { return this._data; }
+    get isLoadingSignal() { return this._isLoading; }
+    get isFetchingSignal() { return this._isFetching; }
+    get isErrorSignal() { return this._isError; }
+    get errorSignal() { return this._error; }
+
+    setupEnabledWatcher() {
+      if (typeof $.effect === 'function' && typeof this.options.enabled === 'function') {
+        this.enabledDisposer = $.effect(() => {
+          const isEnabled = this.isEnabled();
+          if (isEnabled && this.subscribers.size > 0 && this.isStale()) {
+            this.fetch();
+          }
+        });
+      }
+    }
+
+    subscribe(callback) {
+      const subId = Symbol();
+      this.subscribers.add(subId);
+      if (typeof callback === 'function') {
+        callback(this.data);
+      }
+      return () => {
+        this.subscribers.delete(subId);
+        if (this.subscribers.size === 0) {
+          this.stopPolling();
+        }
+      };
+    }
+
+    isEnabled() {
+      if (typeof this.options.enabled === 'function') {
+        return Boolean(this.options.enabled());
+      }
+      return this.options.enabled !== false;
+    }
+
+    isStale() {
+      if (this.updatedAt === 0) return true;
+      return (Date.now() - this.updatedAt) >= this.options.staleTime;
+    }
+
+    startPolling() {
+      this.stopPolling();
+      this.intervalId = setInterval(() => {
+        if (this.isEnabled() && this.subscribers.size > 0) {
+          this.fetch({ isBackground: true });
+        }
+      }, this.options.refetchInterval);
+    }
+
+    stopPolling() {
+      if (this.intervalId) {
+        clearInterval(this.intervalId);
+        this.intervalId = null;
+      }
+    }
+
+    setData(updaterOrValue) {
+      const current = this._data.value !== undefined ? this._data.value : (typeof this._data.peek === 'function' ? this._data.peek() : undefined);
+      const nextData = typeof updaterOrValue === 'function' ? updaterOrValue(current) : updaterOrValue;
+      this._data.value = nextData;
+      this._isError.value = false;
+      this._error.value = null;
+      this._status.value = 'success';
+      this.updatedAt = Date.now();
+      return nextData;
+    }
+
+    fetch(fetchOptions = {}) {
+      if (!this.isEnabled()) {
+        return Promise.resolve(this._data.value);
+      }
+
+      // 1. Request Deduplication
+      if (this.inFlightPromise) {
+        return this.inFlightPromise;
+      }
+
+      // 2. Cache Freshness Check
+      const hasCachedData = this._data.value !== undefined || (typeof this._data.peek === 'function' && this._data.peek() !== undefined);
+      if (hasCachedData && !this.isStale() && !fetchOptions.force) {
+        return Promise.resolve(this._data.value !== undefined ? this._data.value : this._data.peek());
+      }
+
+      if (!hasCachedData) {
+        this._isLoading.value = true;
+        this._status.value = 'loading';
+      }
+      this._isFetching.value = true;
+
+      let attempt = 0;
+
+      const executeFetchWithRetry = () => {
+        return toNativePromise(this.fetcherFn(unwrapKey(this.rawKey)))
+          .catch((err) => {
+            if (attempt < this.options.retry) {
+              attempt++;
+              const delay = typeof this.options.retryDelay === 'function'
+                ? this.options.retryDelay(attempt)
+                : this.options.retryDelay;
+              return new Promise((resolve) => setTimeout(resolve, delay)).then(executeFetchWithRetry);
+            }
+            throw err;
+          });
+      };
+
+      this.inFlightPromise = executeFetchWithRetry()
+        .then((result) => {
+          this.setData(result);
+          return result;
+        })
+        .catch((err) => {
+          this._isError.value = true;
+          this._error.value = err;
+          this._status.value = 'error';
+          throw err;
+        })
+        .finally(() => {
+          this._isLoading.value = false;
+          this._isFetching.value = false;
+          this.inFlightPromise = null;
+        });
+
+      return this.inFlightPromise;
+    }
+  }
+
+  /**
+   * InfiniteQuery Class
+   */
+  class InfiniteQuery extends Query {
+    constructor(key, fetcherFn, options = {}) {
+      super(key, fetcherFn, Object.assign({
+        initialPageParam: 1,
+        getNextPageParam: () => undefined
+      }, options));
+
+      this._isFetchingNextPage = createReactiveVal(false);
+      this._hasNextPage = createReactiveVal(true);
+      this._data.value = { pages: [], pageParams: [] };
+    }
+
+    get isFetchingNextPage() { return this._isFetchingNextPage.value !== undefined ? this._isFetchingNextPage.value : this._isFetchingNextPage; }
+    get hasNextPage() { return this._hasNextPage.value !== undefined ? this._hasNextPage.value : this._hasNextPage; }
+    get isFetchingNextPageSignal() { return this._isFetchingNextPage; }
+    get hasNextPageSignal() { return this._hasNextPage; }
+
+    fetchNextPage() {
+      if (this.inFlightPromise || !this._hasNextPage.value) {
+        return Promise.resolve(this._data.value);
+      }
+
+      const currentData = this._data.value || { pages: [], pageParams: [] };
+      const lastPage = currentData.pages[currentData.pages.length - 1];
+      const nextPageParam = currentData.pages.length === 0
+        ? this.options.initialPageParam
+        : this.options.getNextPageParam(lastPage, currentData.pages);
+
+      if (nextPageParam === undefined) {
+        this._hasNextPage.value = false;
+        return Promise.resolve(currentData);
+      }
+
+      this._isFetchingNextPage.value = true;
+      this._isFetching.value = true;
+
+      this.inFlightPromise = toNativePromise(this.fetcherFn({ pageParam: nextPageParam, queryKey: unwrapKey(this.rawKey) }))
+        .then((pageData) => {
+          const newPages = [...currentData.pages, pageData];
+          const newPageParams = [...currentData.pageParams, nextPageParam];
+          
+          this._data.value = { pages: newPages, pageParams: newPageParams };
+          this.updatedAt = Date.now();
+
+          const checkNext = this.options.getNextPageParam(pageData, newPages);
+          this._hasNextPage.value = checkNext !== undefined;
+
+          return this._data.value;
+        })
+        .catch((err) => {
+          this._isError.value = true;
+          this._error.value = err;
+          throw err;
+        })
+        .finally(() => {
+          this._isFetchingNextPage.value = false;
+          this._isFetching.value = false;
+          this.inFlightPromise = null;
+        });
+
+      return this.inFlightPromise;
+    }
+  }
+
+  /**
+   * QueryClient Class
+   */
+  class QueryClient {
+    constructor() {
+      this.queries = new Map();
+      this.persistenceOptions = null;
+      this.setupGlobalListeners();
+    }
+
+    setupGlobalListeners() {
+      if (typeof window !== 'undefined') {
+        window.addEventListener('focus', () => {
+          this.queries.forEach((query) => {
+            if (query.options.refetchOnWindowFocus && query.subscribers.size > 0 && query.isStale() && query.isEnabled()) {
+              query.fetch({ isBackground: true });
+            }
+          });
+        });
+
+        window.addEventListener('online', () => {
+          this.queries.forEach((query) => {
+            if (query.options.refetchOnReconnect && query.subscribers.size > 0 && query.isEnabled()) {
+              query.fetch({ isBackground: true });
+            }
+          });
+        });
+      }
+    }
+
+    getQuery(key, fetcherFn, options) {
+      const hashedKey = hashQueryKey(key);
+      let query = this.queries.get(hashedKey);
+      if (!query) {
+        query = new Query(key, fetcherFn, options);
+        this.queries.set(hashedKey, query);
+      } else if (options) {
+        Object.assign(query.options, options);
+      }
+      return query;
+    }
+
+    getInfiniteQuery(key, fetcherFn, options) {
+      const hashedKey = hashQueryKey(key);
+      let query = this.queries.get(hashedKey);
+      if (!query) {
+        query = new InfiniteQuery(key, fetcherFn, options);
+        this.queries.set(hashedKey, query);
+      } else if (options) {
+        Object.assign(query.options, options);
+      }
+      return query;
+    }
+
+    getQueryData(key) {
+      const hashedKey = hashQueryKey(key);
+      const query = this.queries.get(hashedKey);
+      if (!query) return undefined;
+      return query.data;
+    }
+
+    setQueryData(key, updaterOrValue) {
+      const hashedKey = hashQueryKey(key);
+      let query = this.queries.get(hashedKey);
+      if (!query) {
+        query = new Query(key, () => Promise.resolve(updaterOrValue));
+        this.queries.set(hashedKey, query);
+      }
+      const newNext = query.setData(updaterOrValue);
+      this.saveToPersistence();
+      return newNext;
+    }
+
+    invalidateQueries(keyPattern) {
+      const hashedPattern = hashQueryKey(keyPattern);
+      this.queries.forEach((query, key) => {
+        if (key === hashedPattern || key.startsWith(hashedPattern)) {
+          query.updatedAt = 0; // Mark stale
+          if (query.subscribers.size > 0 && query.isEnabled()) {
+            query.fetch({ force: true });
+          }
+        }
+      });
+    }
+
+    prefetchQuery(key, fetcherFn, options) {
+      const query = this.getQuery(key, fetcherFn, options);
+      return query.fetch();
+    }
+
+    clear() {
+      this.queries.forEach((query) => query.stopPolling());
+      this.queries.clear();
+      if (this.persistenceOptions) {
+        try {
+          const storage = this.persistenceOptions.storage === 'session' ? window.sessionStorage : window.localStorage;
+          storage.removeItem(this.persistenceOptions.key || 'jquery_pro_query_cache');
+        } catch (e) {}
+      }
+    }
+
+    setPersistence(options = {}) {
+      this.persistenceOptions = Object.assign({
+        key: 'jquery_pro_query_cache',
+        storage: 'local',
+        maxAge: 86400000 // 24 hours
+      }, options);
+
+      this.restoreFromPersistence();
+    }
+
+    saveToPersistence() {
+      if (!this.persistenceOptions) return;
+      try {
+        const storage = this.persistenceOptions.storage === 'session' ? window.sessionStorage : window.localStorage;
+        const serialized = {};
+
+        this.queries.forEach((query, key) => {
+          const dataVal = query._data.value !== undefined ? query._data.value : (typeof query._data.peek === 'function' ? query._data.peek() : undefined);
+          if (dataVal !== undefined) {
+            try {
+              // Test serializability before saving
+              JSON.stringify(dataVal);
+              serialized[key] = {
+                data: dataVal,
+                updatedAt: query.updatedAt,
+                rawKey: query.rawKey
+              };
+            } catch (err) {
+              // Ignore non-serializable DOM / Circular objects
+            }
+          }
+        });
+
+        storage.setItem(this.persistenceOptions.key, JSON.stringify(serialized));
+      } catch (e) {
+        console.warn('[jquery-pro-query] Failed to save cache persistence:', e);
+      }
+    }
+
+    restoreFromPersistence() {
+      if (!this.persistenceOptions) return;
+      try {
+        const storage = this.persistenceOptions.storage === 'session' ? window.sessionStorage : window.localStorage;
+        const raw = storage.getItem(this.persistenceOptions.key);
+        if (!raw) return;
+
+        const parsed = JSON.parse(raw);
+        const now = Date.now();
+
+        Object.keys(parsed).forEach((key) => {
+          const entry = parsed[key];
+          if ((now - entry.updatedAt) < this.persistenceOptions.maxAge) {
+            const query = this.getQuery(entry.rawKey || key);
+            query._data.value = entry.data;
+            query.updatedAt = entry.updatedAt;
+            query._isLoading.value = false;
+            query._status.value = 'success';
+          }
+        });
+      } catch (e) {
+        console.warn('[jquery-pro-query] Failed to restore cache persistence:', e);
+      }
+    }
+  }
+
+  const defaultClient = new QueryClient();
+
+  /**
+   * Mutation Class
+   */
+  class Mutation {
+    constructor(mutationFn, options = {}) {
+      this.mutationFn = mutationFn;
+      this.options = options;
+
+      this._data = createReactiveVal(undefined);
+      this._isLoading = createReactiveVal(false);
+      this._isError = createReactiveVal(false);
+      this._error = createReactiveVal(null);
+    }
+
+    get data() { return this._data.value !== undefined ? this._data.value : this._data; }
+    get isLoading() { return this._isLoading.value !== undefined ? this._isLoading.value : this._isLoading; }
+    get isError() { return this._isError.value !== undefined ? this._isError.value : this._isError; }
+    get error() { return this._error.value !== undefined ? this._error.value : this._error; }
+
+    async mutate(variables) {
+      this._isLoading.value = true;
+      this._isError.value = false;
+      this._error.value = null;
+
+      let context;
+
+      if (typeof this.options.onMutate === 'function') {
+        try {
+          context = await this.options.onMutate(variables);
+        } catch (e) {
+          console.error('[jquery-pro-query] Error in onMutate callback:', e);
+        }
+      }
+
+      try {
+        const result = await toNativePromise(this.mutationFn(variables));
+        this._data.value = result;
+
+        if (typeof this.options.onSuccess === 'function') {
+          await this.options.onSuccess(result, variables, context);
+        }
+
+        defaultClient.saveToPersistence();
+        return result;
+      } catch (err) {
+        this._isError.value = true;
+        this._error.value = err;
+
+        if (typeof this.options.onError === 'function') {
+          await this.options.onError(err, variables, context);
+        }
+
+        throw err;
+      } finally {
+        this._isLoading.value = false;
+        if (typeof this.options.onSettled === 'function') {
+          this.options.onSettled(this._data.value, this._error.value, variables, context);
+        }
+      }
+    }
+  }
+
+  // --- Attach Core API to jQuery Namespace ($) ---
+
+  $.queryClient = defaultClient;
+
+  /**
+   * $.query(key, fetcherFn, [options])
+   */
+  $.query = function (key, fetcherFn, options) {
+    const query = defaultClient.getQuery(key, fetcherFn, options);
+    
+    // Subscribe and return un-subscribe disposer via query.unsubscribe
+    const unsubscribe = query.subscribe();
+    query.unsubscribe = unsubscribe;
+
+    if (query.isEnabled()) {
+      query.fetch();
+    }
+
+    return query;
+  };
+
+  /**
+   * $.infiniteQuery(key, fetcherFn, [options])
+   */
+  $.infiniteQuery = function (key, fetcherFn, options) {
+    const query = defaultClient.getInfiniteQuery(key, fetcherFn, options);
+
+    const unsubscribe = query.subscribe();
+    query.unsubscribe = unsubscribe;
+
+    if (query.isEnabled() && query._data.value.pages.length === 0) {
+      query.fetchNextPage();
+    }
+
+    return query;
+  };
+
+  /**
+   * $.mutation(mutationFn, [options])
+   */
+  $.mutation = function (mutationFn, options) {
+    return new Mutation(mutationFn, options);
+  };
+
+  return $;
+}));