@modelence/react-query 1.0.1 → 1.2.0

package/.yalc/modelence/package.json

@@ -0,0 +1,80 @@
+{
+  "type": "module",
+  "name": "modelence",
+  "version": "0.8.0",
+  "description": "The Node.js Framework for Real-Time MongoDB Apps",
+  "main": "dist/index.js",
+  "types": "dist/global.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./client": "./dist/client.js",
+    "./server": "./dist/server.js",
+    "./telemetry": "./dist/telemetry.js",
+    "./mongodb": "./dist/mongo.js",
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    }
+  },
+  "files": [
+    "dist",
+    "dist/bin"
+  ],
+  "bin": {
+    "modelence": "./dist/bin/modelence.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,css,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,css,md}\"",
+    "lint": "eslint src --ext .ts,.tsx --fix",
+    "lint:check": "eslint src --ext .ts,.tsx",
+    "prepublishOnly": "npm run build",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
+    "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "postversion": "git push && git push --tags"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modelence/modelence.git"
+  },
+  "author": "Modelence",
+  "license": "SEE LICENSE IN LICENSE",
+  "bugs": {
+    "url": "https://github.com/modelence/modelence/issues"
+  },
+  "homepage": "https://modelence.com",
+  "dependencies": {
+    "@socket.io/mongo-adapter": "^0.4.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "archiver": "^7.0.1",
+    "bcrypt": "^5.1.1",
+    "commander": "^12.0.0",
+    "cookie-parser": "^1.4.7",
+    "dotenv": "^16.4.5",
+    "elastic-apm-node": "^4.8.0",
+    "express": "^4.21.0",
+    "fs-extra": "^11.2.0",
+    "jiti": "^2.4.2",
+    "mongodb": "^6.8.1",
+    "open": "^10.1.0",
+    "socket.io": "^4.8.1",
+    "socket.io-client": "^4.8.1",
+    "tsup": "^8.3.6",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.3",
+    "vite-plugin-eslint": "^1.8.1",
+    "winston": "^3.15.0",
+    "winston-elasticsearch": "^0.19.0",
+    "zod": "^3.23.8",
+    "zustand": "^5.0.2"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "yalcSig": "54beb281dea95e11540cf0bb45ff9771"
+}

package/.yalc/modelence/yalc.sig

@@ -0,0 +1 @@
+54beb281dea95e11540cf0bb45ff9771

package/dist/index.d.ts

@@ -1,4 +1,34 @@
+import { QueryClient } from '@tanstack/react-query';
+
 type Args = Record<string, unknown>;
+/**
+ * Client for managing Modelence live queries with TanStack Query.
+ * Create one instance and connect it to your QueryClient.
+ *
+ * @example
+ * ```tsx
+ * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+ * import { ModelenceQueryClient } from '@modelence/react-query';
+ *
+ * const queryClient = new QueryClient();
+ * new ModelenceQueryClient().connect(queryClient);
+ *
+ * function App() {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <YourApp />
+ *     </QueryClientProvider>
+ *   );
+ * }
+ * ```
+ */
+declare class ModelenceQueryClient {
+    /**
+     * Connects to a TanStack Query QueryClient.
+     * This enables live query subscriptions and cache updates.
+     */
+    connect(queryClient: QueryClient): void;
+}
 /**
  * Creates query options for use with TanStack Query's useQuery hook.
  *
@@ -32,6 +62,43 @@ declare function modelenceQuery<T = unknown>(methodName: string, args?: Args): {
     queryKey: (string | Args)[];
     queryFn: () => Promise<T>;
 };
+/**
+ * Creates query options for live queries with TanStack Query's useQuery hook.
+ * Data will be updated in real-time when underlying data changes.
+ *
+ * Requires ModelenceQueryClient to be connected to your QueryClient.
+ *
+ * @example
+ * ```tsx
+ * import { useQuery } from '@tanstack/react-query';
+ * import { modelenceLiveQuery } from '@modelence/react-query';
+ *
+ * function TodoList() {
+ *   // Subscribe to live updates - data refreshes automatically when todos change
+ *   const { data: todos } = useQuery(modelenceLiveQuery('todo.getAll', { userId }));
+ *
+ *   return (
+ *     <ul>
+ *       {todos?.map(todo => <li key={todo._id}>{todo.title}</li>)}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @typeParam T - The expected return type of the query
+ * @param methodName - The name of the method to query
+ * @param args - Optional arguments to pass to the method
+ * @returns Query options object for TanStack Query's useQuery
+ */
+declare function modelenceLiveQuery<T = unknown>(methodName: string, args?: Args): {
+    queryKey: readonly ["live", string, Args];
+    queryFn: () => Promise<T>;
+    staleTime: number;
+    refetchOnWindowFocus: boolean;
+    refetchOnMount: boolean;
+    refetchOnReconnect: boolean;
+    gcTime: number;
+};
 /**
  * Creates mutation options for use with TanStack Query's useMutation hook.
  *
@@ -95,4 +162,4 @@ type ModelenceQueryKey<T extends string, U extends Args = Args> = readonly [T, U
  */
 declare function createQueryKey<T extends string, U extends Args = Args>(methodName: T, args?: U): ModelenceQueryKey<T, U>;
 
-export { type ModelenceQueryKey, createQueryKey, modelenceMutation, modelenceQuery };
+export { ModelenceQueryClient, type ModelenceQueryKey, createQueryKey, modelenceLiveQuery, modelenceMutation, modelenceQuery };

package/dist/index.js

@@ -1,2 +1,2 @@
-import {callMethod}from'modelence/client';function s(e,n={}){return {queryKey:[e,n],queryFn:()=>callMethod(e,n)}}function u(e,n={}){return {mutationFn:(t={})=>callMethod(e,{...n,...t})}}function y(e,n={}){return [e,n]}export{y as createQueryKey,u as modelenceMutation,s as modelenceQuery};//# sourceMappingURL=index.js.map
+import {hashKey}from'@tanstack/react-query';import {startWebsockets,callMethod,subscribeLiveQuery}from'modelence/client';var c=null,b=null,s=new Map,d=class{connect(e){if(c)throw new Error("ModelenceQueryClient can only be connected to one QueryClient");b&&(b(),s.forEach(n=>n.unsubscribe()),s.clear()),startWebsockets(),c=e,b=e.getQueryCache().subscribe(n=>{if(n.type==="removed"){let o=hashKey(n.query.queryKey),u=s.get(o);u?.resolvers.size===0&&(u.unsubscribe(),s.delete(o));}});}};function h(r,e={}){return {queryKey:[r,e],queryFn:()=>callMethod(r,e)}}function x(r,e={}){let n=["live",r,e],o=hashKey(n);return {queryKey:n,queryFn:()=>new Promise((u,f)=>{if(!c){let y=new Error("ModelenceQueryClient must be connected before using modelenceLiveQuery()");console.error("[Modelence]",y.message),f(y);return}let i=s.get(o);i||(i={unsubscribe:subscribeLiveQuery(r,e,l=>{let t=s.get(o);t?.resolvers.size&&(t.resolvers.forEach(a=>a.resolve(l)),t.resolvers.clear()),c&&c.setQueryData(n,l);},l=>{let t=s.get(o);t?.resolvers.size&&(t.resolvers.forEach(a=>a.reject(new Error(l))),t.resolvers.clear());}),resolvers:new Set},s.set(o,i)),i.resolvers.add({resolve:u,reject:f});}),staleTime:1/0,refetchOnWindowFocus:false,refetchOnMount:false,refetchOnReconnect:false,gcTime:0}}function A(r,e={}){return {mutationFn:(n={})=>callMethod(r,{...e,...n})}}function K(r,e={}){return [r,e]}export{d as ModelenceQueryClient,K as createQueryKey,x as modelenceLiveQuery,A as modelenceMutation,h as modelenceQuery};//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["modelenceQuery","methodName","args","callMethod","modelenceMutation","defaultArgs","variables","createQueryKey"],"mappings":"0CAiCO,SAASA,CACdC,CAAAA,CAAAA,CACAC,CAAa,CAAA,EACb,CAAA,CACA,OAAO,CACL,QAAU,CAAA,CAACD,CAAYC,CAAAA,CAAI,CAC3B,CAAA,OAAA,CAAS,IAAMC,UAAAA,CAAcF,CAAYC,CAAAA,CAAI,CAC/C,CACF,CAiCO,SAASE,CACdH,CAAAA,CAAAA,CACAI,CAAoB,CAAA,EACpB,CAAA,CACA,OAAO,CACL,UAAY,CAAA,CAACC,CAAkB,CAAA,EAAOH,GAAAA,UAAAA,CAAcF,CAAY,CAAA,CAAE,GAAGI,CAAAA,CAAa,GAAGC,CAAU,CAAC,CAClG,CACF,CA8BO,SAASC,CAAAA,CACdN,CACAC,CAAAA,CAAAA,CAAU,EAAC,CACc,CACzB,OAAO,CAACD,CAAAA,CAAYC,CAAI,CAC1B","file":"index.js","sourcesContent":["import { callMethod } from 'modelence/client';\n\ntype Args = Record<string, unknown>;\n\n/**\n * Creates query options for use with TanStack Query's useQuery hook.\n * \n * @example\n * ```tsx\n * import { useQuery } from '@tanstack/react-query';\n * import { modelenceQuery } from '@modelence/react-query';\n * \n * function MyComponent() {\n *   // Basic usage\n *   const { data } = useQuery(modelenceQuery('todo.getAll'));\n * \n *   // With additional options\n *   const { data: todo } = useQuery({\n *     ...modelenceQuery('todo.getById', { id: '123' }),\n *     enabled: !!id,\n *     staleTime: 5 * 60 * 1000,\n *   });\n * \n *   return <div>{data?.name}</div>;\n * }\n * ```\n * \n * @typeParam T - The expected return type of the query\n * @param methodName - The name of the method to query\n * @param args - Optional arguments to pass to the method\n * @returns Query options object for TanStack Query's useQuery\n * \n */\nexport function modelenceQuery<T = unknown>(\n  methodName: string, \n  args: Args = {}\n) {\n  return {\n    queryKey: [methodName, args],\n    queryFn: () => callMethod<T>(methodName, args),\n  };\n}\n\n/**\n * Creates mutation options for use with TanStack Query's useMutation hook.\n * \n * @typeParam T - The expected return type of the mutation\n * @param methodName - The name of the method to mutate\n * @param defaultArgs - Optional default arguments to merge with mutation variables\n * @returns Mutation options object for TanStack Query's useMutation\n * \n * @example\n * ```tsx\n * import { useMutation, useQueryClient } from '@tanstack/react-query';\n * import { modelenceMutation } from '@modelence/react-query';\n * \n * function MyComponent() {\n *   const queryClient = useQueryClient();\n *   \n *   // Basic usage\n *   const { mutate } = useMutation(modelenceMutation('todos.create'));\n * \n *   // With additional options\n *   const { mutate: updateTodo } = useMutation({\n *     ...modelenceMutation('todos.update'),\n *     onSuccess: () => {\n *       queryClient.invalidateQueries({ queryKey: ['todos.getAll'] });\n *     },\n *   });\n * \n *   return <button onClick={() => mutate({ title: 'New Todo' })}>Create</button>;\n * }\n * ```\n */\nexport function modelenceMutation<T = unknown>(\n  methodName: string, \n  defaultArgs: Args = {}\n) {\n  return {\n    mutationFn: (variables: Args = {}) => callMethod<T>(methodName, { ...defaultArgs, ...variables }),\n  };\n}\n\n/**\n * Type helper for creating properly typed query keys\n */\nexport type ModelenceQueryKey<T extends string, U extends Args = Args> = readonly [T, U];\n\n/**\n * Utility function to create query keys for manual cache operations\n * \n * @param methodName - The method name\n * @param args - The arguments\n * @returns Typed query key\n * \n * @example\n * ```tsx\n * import { useQueryClient } from '@tanstack/react-query';\n * import { createQueryKey } from '@modelence/react-query';\n * \n * function TodoActions() {\n *   const queryClient = useQueryClient();\n *   \n *   const refreshTodos = () => {\n *     queryClient.invalidateQueries({ \n *       queryKey: createQueryKey('todo.getAll', { limit: 10 }) \n *     });\n *   };\n * }\n * ```\n */\nexport function createQueryKey<T extends string, U extends Args = Args>(\n  methodName: T,\n  args: U = {} as U\n): ModelenceQueryKey<T, U> {\n  return [methodName, args] as const;\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["queryClientRef","cacheUnsubscribe","subscriptions","ModelenceQueryClient","queryClient","sub","startWebsockets","event","subscriptionKey","hashKey","modelenceQuery","methodName","args","callMethod","modelenceLiveQuery","queryKey","resolve","reject","error","subscribeLiveQuery","data","currentSub","r","modelenceMutation","defaultArgs","variables","createQueryKey"],"mappings":"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","file":"index.js","sourcesContent":["import { QueryClient, hashKey } from '@tanstack/react-query';\nimport { callMethod, subscribeLiveQuery, startWebsockets } from 'modelence/client';\n\ntype Args = Record<string, unknown>;\n\ninterface Subscription {\n  unsubscribe: () => void;\n  resolvers: Set<{\n    resolve: (data: unknown) => void;\n    reject: (error: Error) => void;\n  }>;\n}\n\nlet queryClientRef: QueryClient | null = null;\nlet cacheUnsubscribe: (() => void) | null = null;\nconst subscriptions = new Map<string, Subscription>();\n\n/**\n * Client for managing Modelence live queries with TanStack Query.\n * Create one instance and connect it to your QueryClient.\n * \n * @example\n * ```tsx\n * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';\n * import { ModelenceQueryClient } from '@modelence/react-query';\n * \n * const queryClient = new QueryClient();\n * new ModelenceQueryClient().connect(queryClient);\n * \n * function App() {\n *   return (\n *     <QueryClientProvider client={queryClient}>\n *       <YourApp />\n *     </QueryClientProvider>\n *   );\n * }\n * ```\n */\nexport class ModelenceQueryClient {\n  /**\n   * Connects to a TanStack Query QueryClient.\n   * This enables live query subscriptions and cache updates.\n   */\n  connect(queryClient: QueryClient) {\n    // Only support one query client at a time\n    if (queryClientRef) {\n      throw new Error('ModelenceQueryClient can only be connected to one QueryClient');\n    }\n\n    if (cacheUnsubscribe) {\n      cacheUnsubscribe();\n      subscriptions.forEach((sub) => sub.unsubscribe());\n      subscriptions.clear();\n    }\n\n    startWebsockets();\n\n    queryClientRef = queryClient;\n\n    cacheUnsubscribe = queryClient.getQueryCache().subscribe((event) => {\n      if (event.type === 'removed') {\n        const subscriptionKey = hashKey(event.query.queryKey);\n        const sub = subscriptions.get(subscriptionKey);\n        if (sub?.resolvers.size === 0) {\n          sub.unsubscribe();\n          subscriptions.delete(subscriptionKey);\n        }\n      }\n    });\n  }\n}\n\n/**\n * Creates query options for use with TanStack Query's useQuery hook.\n * \n * @example\n * ```tsx\n * import { useQuery } from '@tanstack/react-query';\n * import { modelenceQuery } from '@modelence/react-query';\n * \n * function MyComponent() {\n *   // Basic usage\n *   const { data } = useQuery(modelenceQuery('todo.getAll'));\n * \n *   // With additional options\n *   const { data: todo } = useQuery({\n *     ...modelenceQuery('todo.getById', { id: '123' }),\n *     enabled: !!id,\n *     staleTime: 5 * 60 * 1000,\n *   });\n * \n *   return <div>{data?.name}</div>;\n * }\n * ```\n * \n * @typeParam T - The expected return type of the query\n * @param methodName - The name of the method to query\n * @param args - Optional arguments to pass to the method\n * @returns Query options object for TanStack Query's useQuery\n * \n */\nexport function modelenceQuery<T = unknown>(\n  methodName: string, \n  args: Args = {}\n) {\n  return {\n    queryKey: [methodName, args],\n    queryFn: () => callMethod<T>(methodName, args),\n  };\n}\n\n/**\n * Creates query options for live queries with TanStack Query's useQuery hook.\n * Data will be updated in real-time when underlying data changes.\n * \n * Requires ModelenceQueryClient to be connected to your QueryClient.\n * \n * @example\n * ```tsx\n * import { useQuery } from '@tanstack/react-query';\n * import { modelenceLiveQuery } from '@modelence/react-query';\n * \n * function TodoList() {\n *   // Subscribe to live updates - data refreshes automatically when todos change\n *   const { data: todos } = useQuery(modelenceLiveQuery('todo.getAll', { userId }));\n * \n *   return (\n *     <ul>\n *       {todos?.map(todo => <li key={todo._id}>{todo.title}</li>)}\n *     </ul>\n *   );\n * }\n * ```\n * \n * @typeParam T - The expected return type of the query\n * @param methodName - The name of the method to query\n * @param args - Optional arguments to pass to the method\n * @returns Query options object for TanStack Query's useQuery\n */\nexport function modelenceLiveQuery<T = unknown>(\n  methodName: string, \n  args: Args = {}\n) {\n  const queryKey = ['live', methodName, args] as const;\n  const subscriptionKey = hashKey(queryKey);\n\n  return {\n    queryKey,\n    queryFn: () => new Promise<T>((resolve, reject) => {\n      if (!queryClientRef) {\n        const error = new Error('ModelenceQueryClient must be connected before using modelenceLiveQuery()');\n        console.error('[Modelence]', error.message);\n        reject(error);\n        return;\n      }\n\n      let sub = subscriptions.get(subscriptionKey);\n\n      if (!sub) {\n        const unsubscribe = subscribeLiveQuery<T>(\n          methodName,\n          args,\n          (data) => {\n            const currentSub = subscriptions.get(subscriptionKey);\n            \n            if (currentSub?.resolvers.size) {\n              currentSub.resolvers.forEach((r) => r.resolve(data));\n              currentSub.resolvers.clear();\n            }\n\n            if (queryClientRef) {\n              queryClientRef.setQueryData(queryKey, data);\n            }\n          },\n          (error) => {\n            const currentSub = subscriptions.get(subscriptionKey);\n            if (currentSub?.resolvers.size) {\n              currentSub.resolvers.forEach((r) => r.reject(new Error(error)));\n              currentSub.resolvers.clear();\n            }\n          }\n        );\n\n        sub = { unsubscribe, resolvers: new Set() };\n        subscriptions.set(subscriptionKey, sub);\n      }\n\n      sub.resolvers.add({\n        resolve: resolve as (data: unknown) => void,\n        reject,\n      });\n    }),\n    staleTime: Infinity,\n    refetchOnWindowFocus: false,\n    refetchOnMount: false,\n    refetchOnReconnect: false,\n    gcTime: 0,\n  };\n}\n\n/**\n * Creates mutation options for use with TanStack Query's useMutation hook.\n * \n * @typeParam T - The expected return type of the mutation\n * @param methodName - The name of the method to mutate\n * @param defaultArgs - Optional default arguments to merge with mutation variables\n * @returns Mutation options object for TanStack Query's useMutation\n * \n * @example\n * ```tsx\n * import { useMutation, useQueryClient } from '@tanstack/react-query';\n * import { modelenceMutation } from '@modelence/react-query';\n * \n * function MyComponent() {\n *   const queryClient = useQueryClient();\n *   \n *   // Basic usage\n *   const { mutate } = useMutation(modelenceMutation('todos.create'));\n * \n *   // With additional options\n *   const { mutate: updateTodo } = useMutation({\n *     ...modelenceMutation('todos.update'),\n *     onSuccess: () => {\n *       queryClient.invalidateQueries({ queryKey: ['todos.getAll'] });\n *     },\n *   });\n * \n *   return <button onClick={() => mutate({ title: 'New Todo' })}>Create</button>;\n * }\n * ```\n */\nexport function modelenceMutation<T = unknown>(\n  methodName: string, \n  defaultArgs: Args = {}\n) {\n  return {\n    mutationFn: (variables: Args = {}) => callMethod<T>(methodName, { ...defaultArgs, ...variables }),\n  };\n}\n\n/**\n * Type helper for creating properly typed query keys\n */\nexport type ModelenceQueryKey<T extends string, U extends Args = Args> = readonly [T, U];\n\n/**\n * Utility function to create query keys for manual cache operations\n * \n * @param methodName - The method name\n * @param args - The arguments\n * @returns Typed query key\n * \n * @example\n * ```tsx\n * import { useQueryClient } from '@tanstack/react-query';\n * import { createQueryKey } from '@modelence/react-query';\n * \n * function TodoActions() {\n *   const queryClient = useQueryClient();\n *   \n *   const refreshTodos = () => {\n *     queryClient.invalidateQueries({ \n *       queryKey: createQueryKey('todo.getAll', { limit: 10 }) \n *     });\n *   };\n * }\n * ```\n */\nexport function createQueryKey<T extends string, U extends Args = Args>(\n  methodName: T,\n  args: U = {} as U\n): ModelenceQueryKey<T, U> {\n  return [methodName, args] as const;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@modelence/react-query",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "React Query utilities for Modelence",
   "exports": {
     ".": {
@@ -20,12 +20,13 @@
   "license": "SEE LICENSE IN LICENSE",
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",
+    "modelence": "*",
     "react": ">=18.0.0"
   },
   "devDependencies": {
-    "modelence": "^0.5.0",
     "@tanstack/react-query": "^5.76.2",
     "@types/react": "^19.0.0",
+    "modelence": "^0.10.0",
     "react": "^19.0.0",
     "tsup": "^8.3.6",
     "typescript": "^5.7.2"

package/src/index.ts

@@ -1,7 +1,75 @@
-import { callMethod } from 'modelence/client';
+import { QueryClient, hashKey } from '@tanstack/react-query';
+import { callMethod, subscribeLiveQuery, startWebsockets } from 'modelence/client';
 
 type Args = Record<string, unknown>;
 
+interface Subscription {
+  unsubscribe: () => void;
+  resolvers: Set<{
+    resolve: (data: unknown) => void;
+    reject: (error: Error) => void;
+  }>;
+}
+
+let queryClientRef: QueryClient | null = null;
+let cacheUnsubscribe: (() => void) | null = null;
+const subscriptions = new Map<string, Subscription>();
+
+/**
+ * Client for managing Modelence live queries with TanStack Query.
+ * Create one instance and connect it to your QueryClient.
+ * 
+ * @example
+ * ```tsx
+ * import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+ * import { ModelenceQueryClient } from '@modelence/react-query';
+ * 
+ * const queryClient = new QueryClient();
+ * new ModelenceQueryClient().connect(queryClient);
+ * 
+ * function App() {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <YourApp />
+ *     </QueryClientProvider>
+ *   );
+ * }
+ * ```
+ */
+export class ModelenceQueryClient {
+  /**
+   * Connects to a TanStack Query QueryClient.
+   * This enables live query subscriptions and cache updates.
+   */
+  connect(queryClient: QueryClient) {
+    // Only support one query client at a time
+    if (queryClientRef) {
+      throw new Error('ModelenceQueryClient can only be connected to one QueryClient');
+    }
+
+    if (cacheUnsubscribe) {
+      cacheUnsubscribe();
+      subscriptions.forEach((sub) => sub.unsubscribe());
+      subscriptions.clear();
+    }
+
+    startWebsockets();
+
+    queryClientRef = queryClient;
+
+    cacheUnsubscribe = queryClient.getQueryCache().subscribe((event) => {
+      if (event.type === 'removed') {
+        const subscriptionKey = hashKey(event.query.queryKey);
+        const sub = subscriptions.get(subscriptionKey);
+        if (sub?.resolvers.size === 0) {
+          sub.unsubscribe();
+          subscriptions.delete(subscriptionKey);
+        }
+      }
+    });
+  }
+}
+
 /**
  * Creates query options for use with TanStack Query's useQuery hook.
  * 
@@ -41,6 +109,95 @@ export function modelenceQuery<T = unknown>(
   };
 }
 
+/**
+ * Creates query options for live queries with TanStack Query's useQuery hook.
+ * Data will be updated in real-time when underlying data changes.
+ * 
+ * Requires ModelenceQueryClient to be connected to your QueryClient.
+ * 
+ * @example
+ * ```tsx
+ * import { useQuery } from '@tanstack/react-query';
+ * import { modelenceLiveQuery } from '@modelence/react-query';
+ * 
+ * function TodoList() {
+ *   // Subscribe to live updates - data refreshes automatically when todos change
+ *   const { data: todos } = useQuery(modelenceLiveQuery('todo.getAll', { userId }));
+ * 
+ *   return (
+ *     <ul>
+ *       {todos?.map(todo => <li key={todo._id}>{todo.title}</li>)}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ * 
+ * @typeParam T - The expected return type of the query
+ * @param methodName - The name of the method to query
+ * @param args - Optional arguments to pass to the method
+ * @returns Query options object for TanStack Query's useQuery
+ */
+export function modelenceLiveQuery<T = unknown>(
+  methodName: string, 
+  args: Args = {}
+) {
+  const queryKey = ['live', methodName, args] as const;
+  const subscriptionKey = hashKey(queryKey);
+
+  return {
+    queryKey,
+    queryFn: () => new Promise<T>((resolve, reject) => {
+      if (!queryClientRef) {
+        const error = new Error('ModelenceQueryClient must be connected before using modelenceLiveQuery()');
+        console.error('[Modelence]', error.message);
+        reject(error);
+        return;
+      }
+
+      let sub = subscriptions.get(subscriptionKey);
+
+      if (!sub) {
+        const unsubscribe = subscribeLiveQuery<T>(
+          methodName,
+          args,
+          (data) => {
+            const currentSub = subscriptions.get(subscriptionKey);
+            
+            if (currentSub?.resolvers.size) {
+              currentSub.resolvers.forEach((r) => r.resolve(data));
+              currentSub.resolvers.clear();
+            }
+
+            if (queryClientRef) {
+              queryClientRef.setQueryData(queryKey, data);
+            }
+          },
+          (error) => {
+            const currentSub = subscriptions.get(subscriptionKey);
+            if (currentSub?.resolvers.size) {
+              currentSub.resolvers.forEach((r) => r.reject(new Error(error)));
+              currentSub.resolvers.clear();
+            }
+          }
+        );
+
+        sub = { unsubscribe, resolvers: new Set() };
+        subscriptions.set(subscriptionKey, sub);
+      }
+
+      sub.resolvers.add({
+        resolve: resolve as (data: unknown) => void,
+        reject,
+      });
+    }),
+    staleTime: Infinity,
+    refetchOnWindowFocus: false,
+    refetchOnMount: false,
+    refetchOnReconnect: false,
+    gcTime: 0,
+  };
+}
+
 /**
  * Creates mutation options for use with TanStack Query's useMutation hook.
  * 

package/yalc.lock

@@ -0,0 +1,10 @@
+{
+  "version": "v1",
+  "packages": {
+    "modelence": {
+      "signature": "54beb281dea95e11540cf0bb45ff9771",
+      "file": true,
+      "replaced": "^0.6.2"
+    }
+  }
+}