qortex-core 0.1.4 → 0.1.6

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

@@ -3,8 +3,6 @@
  * Using readonly to prevent accidental mutations
  */
 type QueryKey = string | readonly (string | number)[];
-/** Valid query key values - only strings and numbers are allowed */
-type QueryKeyValue = string | number;
 /** Function that fetches data, can be async or sync */
 type Fetcher<T = any> = () => Promise<T> | T;
 /** Function that compares two values for equality */
@@ -82,12 +80,34 @@ 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;
     private defaultConfig;
     private throttleTime;
+    /**
+     * ⚠️ DANGER: Clear all cached data and subscriptions
+     *
+     * This method completely wipes all internal state including:
+     * - All cached query data
+     * - All active subscriptions
+     * - All state references
+     *
+     * @warning This should ONLY be used in testing environments or when you need to completely reset the query manager state. Using this in production will cause all active queries to lose their data and subscriptions to break.
+     *
+     * @example
+     * ```typescript
+     * // ✅ Safe usage in tests
+     * beforeEach(() => {
+     *   queryManager.dangerClearCache();
+     * });
+     *
+     * // ❌ Dangerous usage in production
+     * // queryManager.dangerClearCache(); // Don't do this!
+     * ```
+     */
+    dangerClearCache(): void;
     /**
      * Set default configuration for all queries
      */
@@ -160,7 +180,80 @@ declare class QueryManager {
      */
     private handleMountLogic;
 }
-declare const queryManager: QueryManager;
+
+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;
+declare const queryManager: {
+    registerFetcher: {
+        <T = any>(key: QueryKey, opts: QueryOptions<T>): void;
+        <F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+            fetcher: F;
+        }): void;
+    };
+    fetchQuery: {
+        <T = any>(key: QueryKey, opts?: QueryOptions<T>): Promise<T>;
+        <F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+            fetcher: F;
+        }): Promise<InferFetcherResult<F>>;
+    };
+    setQueryData: <T = any>(key: QueryKey, data: T) => void;
+    getQueryData: {
+        <T = any>(key: QueryKey, opts?: QueryOptions<T>): T | undefined;
+        <F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+            fetcher: F;
+        }): InferFetcherResult<F> | undefined;
+    };
+    getQueryState: {
+        <T = unknown>(key: QueryKey, opts?: QueryOptions<T>): QueryState<T>;
+        <F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+            fetcher: F;
+        }): QueryState<InferFetcherResult<F>>;
+    };
+    invalidateQuery: (key: QueryKey) => void;
+    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;
+    };
+    setDefaultConfig: ({ throttleTime, ...config }: DefaultConfig) => void;
+    dangerClearCache: () => void;
+    _queryManager: QueryManagerCore;
+};
 
 /**
  * Normalizes query keys to a consistent string format for internal storage
@@ -168,4 +261,4 @@ declare const queryManager: QueryManager;
  */
 declare function serializeKey(key: QueryKey): string;
 
-export { DefaultConfig, EqualityFn, Fetcher, InferFetcherResult, QueryKey, QueryKeyValue, QueryManager, QueryOptions, QueryState, QueryStatus, queryManager, serializeKey };
+export { DefaultConfig, EqualityFn, Fetcher, InferFetcherResult, QueryKey, QueryManagerCore, QueryOptions, QueryState, QueryStatus, dangerClearCache, fetchQuery, getQueryData, getQueryState, invalidateQuery, queryManager, 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,
+  QueryManagerCore: () => QueryManagerCore,
+  dangerClearCache: () => dangerClearCache,
+  fetchQuery: () => fetchQuery,
+  getQueryData: () => getQueryData,
+  getQueryState: () => getQueryState,
+  invalidateQuery: () => invalidateQuery,
   queryManager: () => queryManager,
-  serializeKey: () => serializeKey
+  registerFetcher: () => registerFetcher,
+  serializeKey: () => serializeKey,
+  setDefaultConfig: () => setDefaultConfig,
+  setQueryData: () => setQueryData,
+  subscribeQuery: () => subscribeQuery
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -114,9 +123,14 @@ function createPublicState(state) {
     refetch: state.refetch
   };
 }
+function warnNoFetcherOrData(key) {
+  console.warn(
+    `[qortex] No fetcher or data for key "${serializeKey(key)}". Register a fetcher or set initial data.`
+  );
+}
 
-// src/queryManager.ts
-var QueryManager = class {
+// src/queryManagerCore.ts
+var QueryManagerCore = class {
   constructor() {
     this.cache = /* @__PURE__ */ new Map();
     this.subs = /* @__PURE__ */ new Map();
@@ -124,6 +138,32 @@ var QueryManager = class {
     this.defaultConfig = {};
     this.throttleTime = THROTTLE_TIME;
   }
+  /**
+   * ⚠️ DANGER: Clear all cached data and subscriptions
+   * 
+   * This method completely wipes all internal state including:
+   * - All cached query data
+   * - All active subscriptions
+   * - All state references
+   * 
+   * @warning This should ONLY be used in testing environments or when you need to completely reset the query manager state. Using this in production will cause all active queries to lose their data and subscriptions to break.
+   * 
+   * @example
+   * ```typescript
+   * // ✅ Safe usage in tests
+   * beforeEach(() => {
+   *   queryManager.dangerClearCache();
+   * });
+   * 
+   * // ❌ Dangerous usage in production
+   * // queryManager.dangerClearCache(); // Don't do this!
+   * ```
+   */
+  dangerClearCache() {
+    this.cache.clear();
+    this.subs.clear();
+    this.lastReturnedState.clear();
+  }
   /**
    * Set default configuration for all queries
    */
@@ -165,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);
@@ -179,7 +214,9 @@ var QueryManager = class {
       return state.fetchPromise;
     const fetcher = state.fetcher;
     if (!fetcher) {
-      console.error("No fetcher found for key", key);
+      if (state.updatedAt === void 0) {
+        warnNoFetcherOrData(key);
+      }
       return Promise.resolve(state.data);
     }
     ;
@@ -285,10 +322,43 @@ 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);
+var queryManager = {
+  registerFetcher,
+  fetchQuery,
+  setQueryData,
+  getQueryData,
+  getQueryState,
+  invalidateQuery,
+  subscribeQuery,
+  setDefaultConfig,
+  dangerClearCache,
+  _queryManager
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  QueryManager,
+  QueryManagerCore,
+  dangerClearCache,
+  fetchQuery,
+  getQueryData,
+  getQueryState,
+  invalidateQuery,
   queryManager,
-  serializeKey
+  registerFetcher,
+  serializeKey,
+  setDefaultConfig,
+  setQueryData,
+  subscribeQuery
 });

package/index.mjs

@@ -86,9 +86,14 @@ function createPublicState(state) {
     refetch: state.refetch
   };
 }
+function warnNoFetcherOrData(key) {
+  console.warn(
+    `[qortex] No fetcher or data for key "${serializeKey(key)}". Register a fetcher or set initial data.`
+  );
+}
 
-// src/queryManager.ts
-var QueryManager = class {
+// src/queryManagerCore.ts
+var QueryManagerCore = class {
   constructor() {
     this.cache = /* @__PURE__ */ new Map();
     this.subs = /* @__PURE__ */ new Map();
@@ -96,6 +101,32 @@ var QueryManager = class {
     this.defaultConfig = {};
     this.throttleTime = THROTTLE_TIME;
   }
+  /**
+   * ⚠️ DANGER: Clear all cached data and subscriptions
+   * 
+   * This method completely wipes all internal state including:
+   * - All cached query data
+   * - All active subscriptions
+   * - All state references
+   * 
+   * @warning This should ONLY be used in testing environments or when you need to completely reset the query manager state. Using this in production will cause all active queries to lose their data and subscriptions to break.
+   * 
+   * @example
+   * ```typescript
+   * // ✅ Safe usage in tests
+   * beforeEach(() => {
+   *   queryManager.dangerClearCache();
+   * });
+   * 
+   * // ❌ Dangerous usage in production
+   * // queryManager.dangerClearCache(); // Don't do this!
+   * ```
+   */
+  dangerClearCache() {
+    this.cache.clear();
+    this.subs.clear();
+    this.lastReturnedState.clear();
+  }
   /**
    * Set default configuration for all queries
    */
@@ -137,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);
@@ -151,7 +177,9 @@ var QueryManager = class {
       return state.fetchPromise;
     const fetcher = state.fetcher;
     if (!fetcher) {
-      console.error("No fetcher found for key", key);
+      if (state.updatedAt === void 0) {
+        warnNoFetcherOrData(key);
+      }
       return Promise.resolve(state.data);
     }
     ;
@@ -257,9 +285,42 @@ 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);
+var queryManager = {
+  registerFetcher,
+  fetchQuery,
+  setQueryData,
+  getQueryData,
+  getQueryState,
+  invalidateQuery,
+  subscribeQuery,
+  setDefaultConfig,
+  dangerClearCache,
+  _queryManager
+};
 export {
-  QueryManager,
+  QueryManagerCore,
+  dangerClearCache,
+  fetchQuery,
+  getQueryData,
+  getQueryState,
+  invalidateQuery,
   queryManager,
-  serializeKey
+  registerFetcher,
+  serializeKey,
+  setDefaultConfig,
+  setQueryData,
+  subscribeQuery
 };

package/package.json

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