qortex-core 0.1.5 → 0.1.7

package/README.md

@@ -20,255 +20,11 @@
 pnpm add qortex-core
 ```
 
-```ts
-import { queryManager } from "qortex-core";
+## 📚 Documentation
 
-// Set global defaults for all queries
-queryManager.setDefaultConfig({
-  staleTime: 5 * 60 * 1000, // 5 minutes default
-  throttleTime: 100, // 100ms throttle
-  usePreviousDataOnError: true
-});
+**Complete documentation, examples, and API reference available at:**
 
-// Register a fetcher
-queryManager.registerFetcher(["todos"], {
-  fetcher: async () => {
-    const response = await fetch("/api/todos");
-    return response.json();
-  },
-  placeholderData: [] // Uses global staleTime: 5 minutes
-});
-
-// Fetch data
-const todos = await queryManager.fetchQuery(["todos"]);
-console.log("Todos loaded:", todos);
-```
-
-## 🔐 Perfect for Authentication
-
-```ts
-// Auth service - update from anywhere
-class AuthService {
-  async login(email: string, password: string) {
-    const { user, token } = await fetch("/api/auth/login", {
-      method: "POST",
-      body: JSON.stringify({ email, password })
-    }).then(r => r.json());
-    
-    // 🎯 Update auth state - accessible everywhere!
-    queryManager.setQueryData(["auth", "user"], user);
-    queryManager.setQueryData(["auth", "isAuthenticated"], true);
-  }
-  
-  logout() {
-    // 🎯 Clear auth state from anywhere
-    queryManager.setQueryData(["auth", "user"], null);
-    queryManager.setQueryData(["auth", "isAuthenticated"], false);
-  }
-}
-
-// Access from any environment
-// React
-function useAuth() {
-  const user = queryManager.getQueryData(["auth", "user"]);
-  const isAuthenticated = queryManager.getQueryData(["auth", "isAuthenticated"]);
-  return { user, isAuthenticated };
-}
-
-// React with hooks (qortex-react package)
-import { useQuery, useQueryData } from "qortex-react";
-
-function AuthComponent() {
-  const { data: user, isLoading } = useQuery(["auth", "user"]);
-  const isAuthenticated = useQueryData(["auth", "isAuthenticated"]);
-  
-  if (isLoading) return <div>Loading...</div>;
-  return <div>Welcome {user?.name}</div>;
-}
-
-// Vue
-function useAuth() {
-  const user = ref(queryManager.getQueryData(["auth", "user"]));
-  const isAuthenticated = ref(queryManager.getQueryData(["auth", "isAuthenticated"]));
-  
-  queryManager.subscribeQuery(["auth", "user"], (state) => {
-    user.value = state.data;
-    console.log("Auth state:", state.isSuccess, state.isLoading);
-  });
-  
-  return { user, isAuthenticated };
-}
-
-// Vanilla JS
-function checkAuth() {
-  const user = queryManager.getQueryData(["auth", "user"]);
-  const isAuthenticated = queryManager.getQueryData(["auth", "isAuthenticated"]);
-  return { user, isAuthenticated };
-}
-```
-
-## 🎨 API Reference
-
-### `queryManager.registerFetcher(key, options)`
-
-```ts
-queryManager.registerFetcher(key, {
-  fetcher: async () => Promise<T>,
-  staleTime?: number, // Default: 0
-  placeholderData?: T,
-  enabled?: boolean // Default: true
-});
-```
-
-### `queryManager.fetchQuery(key, options?)`
-
-```ts
-const data = await queryManager.fetchQuery(key, {
-  fetcher?: Fetcher<T>,
-  staleTime?: number
-});
-```
-
-### `queryManager.setQueryData(key, data)`
-
-```ts
-// Direct update
-queryManager.setQueryData(["todos"], newTodos);
-
-// Functional update
-queryManager.setQueryData(["todos"], (oldData) => [
-  ...(oldData || []),
-  newTodo
-]);
-```
-
-### `queryManager.getQueryData(key)`
-
-```ts
-const user = queryManager.getQueryData(["auth", "user"]);
-const isAuthenticated = queryManager.getQueryData(["auth", "isAuthenticated"]);
-```
-
-### React Hooks (qortex-react package)
-
-```tsx
-import { useQuery, useQueryData } from "qortex-react";
-
-// Full query state with loading, error, refetch
-const { data, isLoading, error, refetch } = useQuery(["todos"]);
-
-// Just the data - simpler API
-const todos = useQueryData(["todos"]);
-```
-
-### `queryManager.subscribeQuery(key, callback, options?)`
-
-Subscribe to query state changes with flexible callback signatures.
-
-```ts
-// Callback receives the current state
-const unsubscribe = queryManager.subscribeQuery(["todos"], (state) => {
-  console.log("State changed:", state);
-  console.log("Data:", state.data);
-  console.log("Loading:", state.isLoading);
-  console.log("Success:", state.isSuccess);
-});
-
-// With fetcher for automatic type inference
-const unsubscribe = queryManager.subscribeQuery(["todos"], (state) => {
-  console.log("Todos:", state.data); // Automatically typed
-}, { fetcher: fetchTodos });
-```
-
-### `queryManager.setDefaultConfig(config)`
-
-Set global default configuration for all queries.
-
-```ts
-queryManager.setDefaultConfig({
-  staleTime: 5 * 60 * 1000, // 5 minutes
-  refetchOnSubscribe: "stale",
-  throttleTime: 100, // 100ms throttle
-  usePreviousDataOnError: true,
-  equalityFn: shallowEqual
-});
-```
-
-**Available options:**
-- `enabled?: boolean` - Whether queries are enabled by default
-- `refetchOnSubscribe?: "stale" | "always" | false` - Default refetch behavior
-- `staleTime?: number` - Default time before data is considered stale
-- `usePreviousDataOnError?: boolean` - Keep previous data on error
-- `usePlaceholderOnError?: boolean` - Use placeholder data on error
-- `equalityFn?: EqualityFn<any>` - Default equality function
-- `throttleTime?: number` - Default throttle time for duplicate request prevention
-
-## 🎯 More Examples
-
-### WebSocket Updates
-
-```ts
-// Update data from WebSocket
-const ws = new WebSocket("ws://localhost:8080");
-ws.onmessage = (event) => {
-  const data = JSON.parse(event.data);
-  queryManager.setQueryData(["live-stats"], data);
-};
-
-// Access from any environment
-const stats = queryManager.getQueryData(["live-stats"]);
-console.log("Users online:", stats?.users);
-```
-
-### Cross-Framework Data Sharing
-
-```ts
-// React component updates data
-function ReactComponent() {
-  const updateTheme = () => {
-    queryManager.setQueryData(["user", "preferences"], { theme: "dark" });
-  };
-  return <button onClick={updateTheme}>Update Theme</button>;
-}
-
-// Vue component automatically reflects changes
-function VueComponent() {
-  const preferences = ref(queryManager.getQueryData(["user", "preferences"]));
-  
-  queryManager.subscribeQuery(["user", "preferences"], (state) => {
-    preferences.value = state.data;
-  });
-  
-  return { preferences };
-}
-
-// Vanilla JS also gets updates
-function vanillaJSFunction() {
-  const preferences = queryManager.getQueryData(["user", "preferences"]);
-  console.log("Current theme:", preferences?.theme);
-}
-```
-
-## 🎭 TypeScript Support
-
-```ts
-interface User {
-  id: string;
-  name: string;
-  email: string;
-}
-
-// Type-safe usage
-queryManager.registerFetcher<User[]>(["users"], {
-  fetcher: async (): Promise<User[]> => {
-    const response = await fetch("/api/users");
-    return response.json();
-  }
-});
-
-const users = await queryManager.fetchQuery<User[]>(["users"]);
-// users is typed as User[] | undefined
-```
+### 🌐 [qortex.darshannaik.com](https://qortex.darshannaik.com)
 
 ## 📄 License
 
@@ -276,10 +32,12 @@ MIT License - feel free to use this in your projects! 🎉
 
 ## 🎯 Support
 
-Need help? Have questions?
+Need help? Have questions? Want to chat about data fetching strategies?
 
+- 📚 **Documentation**: [qortex.darshannaik.com](https://qortex.darshannaik.com)
 - 📧 **Email**: [darshannaik.com](https://darshannaik.com)
 - 🐛 **Issues**: [GitHub Issues](https://github.com/Darshan-Naik/qortex/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/Darshan-Naik/qortex/discussions)
 - 🌟 **Repository**: [https://github.com/Darshan-Naik/qortex](https://github.com/Darshan-Naik/qortex)
 
 ---
@@ -287,4 +45,4 @@ Need help? Have questions?
 <div align="center">
   <p>Made with ❤️ by <a href="https://darshannaik.com">Darshan</a></p>
   <p>⭐ Star this repo if you found it helpful!</p>
-</div>
+</div>

package/index.d.ts

@@ -80,7 +80,7 @@ type QueryState<T = any, E = Error> = {
  * Core query manager that handles caching, fetching, and state management
  * Implements robust throttling and race condition prevention
  */
-declare class QueryManager {
+declare class QueryManagerCore {
     private cache;
     private subs;
     private lastReturnedState;
@@ -180,7 +180,43 @@ declare class QueryManager {
      */
     private handleMountLogic;
 }
-declare const queryManager: QueryManager;
+
+declare const _queryManager: QueryManagerCore;
+declare const registerFetcher: {
+    <T = any>(key: QueryKey, opts: QueryOptions<T>): void;
+    <F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+        fetcher: F;
+    }): void;
+};
+declare const fetchQuery: {
+    <T = any>(key: QueryKey, opts?: QueryOptions<T>): Promise<T>;
+    <F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+        fetcher: F;
+    }): Promise<InferFetcherResult<F>>;
+};
+declare const setQueryData: <T = any>(key: QueryKey, data: T) => void;
+declare const getQueryData: {
+    <T = any>(key: QueryKey, opts?: QueryOptions<T>): T | undefined;
+    <F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+        fetcher: F;
+    }): InferFetcherResult<F> | undefined;
+};
+declare const getQueryState: {
+    <T = unknown>(key: QueryKey, opts?: QueryOptions<T>): QueryState<T>;
+    <F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+        fetcher: F;
+    }): QueryState<InferFetcherResult<F>>;
+};
+declare const invalidateQuery: (key: QueryKey) => void;
+declare const subscribeQuery: {
+    (key: QueryKey, cb: (state: QueryState<any>) => void): () => void;
+    <F extends Fetcher>(key: QueryKey, cb: (state: QueryState<InferFetcherResult<F>>) => void, opts: QueryOptions<InferFetcherResult<F>> & {
+        fetcher: F;
+    }): () => void;
+    <T = any>(key: QueryKey, cb: (state: QueryState<T>) => void, opts?: QueryOptions<T>): () => void;
+};
+declare const setDefaultConfig: ({ throttleTime, ...config }: DefaultConfig) => void;
+declare const dangerClearCache: () => void;
 
 /**
  * Normalizes query keys to a consistent string format for internal storage
@@ -188,4 +224,4 @@ declare const queryManager: QueryManager;
  */
 declare function serializeKey(key: QueryKey): string;
 
-export { DefaultConfig, EqualityFn, Fetcher, InferFetcherResult, QueryKey, QueryManager, QueryOptions, QueryState, QueryStatus, queryManager, serializeKey };
+export { DefaultConfig, EqualityFn, Fetcher, InferFetcherResult, QueryKey, QueryManagerCore, QueryOptions, QueryState, QueryStatus, _queryManager, dangerClearCache, fetchQuery, getQueryData, getQueryState, invalidateQuery, registerFetcher, serializeKey, setDefaultConfig, setQueryData, subscribeQuery };

package/index.js

@@ -20,9 +20,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  QueryManager: () => QueryManager,
-  queryManager: () => queryManager,
-  serializeKey: () => serializeKey
+  QueryManagerCore: () => QueryManagerCore,
+  _queryManager: () => _queryManager,
+  dangerClearCache: () => dangerClearCache,
+  fetchQuery: () => fetchQuery,
+  getQueryData: () => getQueryData,
+  getQueryState: () => getQueryState,
+  invalidateQuery: () => invalidateQuery,
+  registerFetcher: () => registerFetcher,
+  serializeKey: () => serializeKey,
+  setDefaultConfig: () => setDefaultConfig,
+  setQueryData: () => setQueryData,
+  subscribeQuery: () => subscribeQuery
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -120,8 +129,8 @@ function warnNoFetcherOrData(key) {
   );
 }
 
-// src/queryManager.ts
-var QueryManager = class {
+// src/queryManagerCore.ts
+var QueryManagerCore = class {
   constructor() {
     this.cache = /* @__PURE__ */ new Map();
     this.subs = /* @__PURE__ */ new Map();
@@ -196,13 +205,8 @@ var QueryManager = class {
       cb(publicState);
   }
   registerFetcher(key, opts) {
-    this.ensureState(key, opts);
-    if (opts.enabled !== false) {
-      try {
-        void this.fetchQuery(key);
-      } catch {
-      }
-    }
+    const state = this.ensureState(key, opts);
+    this.handleMountLogic(key, state);
   }
   fetchQuery(key, opts) {
     const state = this.ensureState(key, opts);
@@ -318,10 +322,31 @@ var QueryManager = class {
     }
   }
 };
-var queryManager = new QueryManager();
+var queryManagerCore_default = QueryManagerCore;
+
+// src/queryManager.ts
+var _queryManager = new queryManagerCore_default();
+var registerFetcher = _queryManager.registerFetcher.bind(_queryManager);
+var fetchQuery = _queryManager.fetchQuery.bind(_queryManager);
+var setQueryData = _queryManager.setQueryData.bind(_queryManager);
+var getQueryData = _queryManager.getQueryData.bind(_queryManager);
+var getQueryState = _queryManager.getQueryState.bind(_queryManager);
+var invalidateQuery = _queryManager.invalidateQuery.bind(_queryManager);
+var subscribeQuery = _queryManager.subscribeQuery.bind(_queryManager);
+var setDefaultConfig = _queryManager.setDefaultConfig.bind(_queryManager);
+var dangerClearCache = _queryManager.dangerClearCache.bind(_queryManager);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  QueryManager,
-  queryManager,
-  serializeKey
+  QueryManagerCore,
+  _queryManager,
+  dangerClearCache,
+  fetchQuery,
+  getQueryData,
+  getQueryState,
+  invalidateQuery,
+  registerFetcher,
+  serializeKey,
+  setDefaultConfig,
+  setQueryData,
+  subscribeQuery
 });

package/index.mjs

@@ -92,8 +92,8 @@ function warnNoFetcherOrData(key) {
   );
 }
 
-// src/queryManager.ts
-var QueryManager = class {
+// src/queryManagerCore.ts
+var QueryManagerCore = class {
   constructor() {
     this.cache = /* @__PURE__ */ new Map();
     this.subs = /* @__PURE__ */ new Map();
@@ -168,13 +168,8 @@ var QueryManager = class {
       cb(publicState);
   }
   registerFetcher(key, opts) {
-    this.ensureState(key, opts);
-    if (opts.enabled !== false) {
-      try {
-        void this.fetchQuery(key);
-      } catch {
-      }
-    }
+    const state = this.ensureState(key, opts);
+    this.handleMountLogic(key, state);
   }
   fetchQuery(key, opts) {
     const state = this.ensureState(key, opts);
@@ -290,9 +285,30 @@ var QueryManager = class {
     }
   }
 };
-var queryManager = new QueryManager();
+var queryManagerCore_default = QueryManagerCore;
+
+// src/queryManager.ts
+var _queryManager = new queryManagerCore_default();
+var registerFetcher = _queryManager.registerFetcher.bind(_queryManager);
+var fetchQuery = _queryManager.fetchQuery.bind(_queryManager);
+var setQueryData = _queryManager.setQueryData.bind(_queryManager);
+var getQueryData = _queryManager.getQueryData.bind(_queryManager);
+var getQueryState = _queryManager.getQueryState.bind(_queryManager);
+var invalidateQuery = _queryManager.invalidateQuery.bind(_queryManager);
+var subscribeQuery = _queryManager.subscribeQuery.bind(_queryManager);
+var setDefaultConfig = _queryManager.setDefaultConfig.bind(_queryManager);
+var dangerClearCache = _queryManager.dangerClearCache.bind(_queryManager);
 export {
-  QueryManager,
-  queryManager,
-  serializeKey
+  QueryManagerCore,
+  _queryManager,
+  dangerClearCache,
+  fetchQuery,
+  getQueryData,
+  getQueryState,
+  invalidateQuery,
+  registerFetcher,
+  serializeKey,
+  setDefaultConfig,
+  setQueryData,
+  subscribeQuery
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qortex-core",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Framework-agnostic query cache & fetch registry (MFE friendly).",
   "main": "index.js",
   "module": "index.mjs",