qortex-core 0.1.3 → 0.1.5

package/README.md

@@ -4,6 +4,7 @@
 
 [![npm version](https://badge.fury.io/js/qortex-core.svg)](https://badge.fury.io/js/qortex-core)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/qortex-core)](https://bundlephobia.com/package/qortex-core)
+[![Bundle Size](https://img.shields.io/badge/gzipped-2.1KB-brightgreen)](https://bundlephobia.com/package/qortex-core)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
 ## ✨ What makes this special?
@@ -92,6 +93,7 @@ function useAuth() {
   
   queryManager.subscribeQuery(["auth", "user"], (state) => {
     user.value = state.data;
+    console.log("Auth state:", state.isSuccess, state.isLoading);
   });
   
   return { user, isAuthenticated };
@@ -159,12 +161,23 @@ const { data, isLoading, error, refetch } = useQuery(["todos"]);
 const todos = useQueryData(["todos"]);
 ```
 
-### `queryManager.subscribeQuery(key, callback)`
+### `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)`

package/index.d.ts

@@ -3,22 +3,29 @@
  * 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 */
 type EqualityFn<T = any> = (a: T | undefined, b: T | undefined) => boolean;
 /**
- * Infers the resolved return type of a fetcher function
- * Falls back to any for user-friendly experience
+ * Infers the return type of a fetcher function
+ *
+ * This utility type extracts the return type from a fetcher function,
+ * handling both synchronous and asynchronous fetchers.
+ *
+ * @example
+ * ```typescript
+ * const fetchUser = async (id: string): Promise<User> => { ... };
+ * type UserType = InferFetcherResult<typeof fetchUser>; // Promise<User>
+ *
+ * const fetchConfig = (): Config => { ... };
+ * type ConfigType = InferFetcherResult<typeof fetchConfig>; // Config
+ * ```
+ *
+ * @template F - The fetcher function type
+ * @returns The inferred return type of the fetcher, or `any` if inference fails
  */
-type InferFetcherResult<F> = F extends (...args: any[]) => Promise<infer R> ? R : F extends (...args: any[]) => infer R ? R : any;
-/**
- * Infers the return type of a fetcher, handling both sync and async cases
- * Falls back to any for user-friendly experience
- */
-type InferFetcherReturnType<T> = T extends Fetcher<infer R> ? R : any;
+type InferFetcherResult<F> = F extends Fetcher<infer R> ? R : any;
 /**
  * Query status types for better type safety
  */
@@ -79,6 +86,28 @@ declare class QueryManager {
     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
      */
@@ -120,12 +149,18 @@ declare class QueryManager {
      * Handles mount logic to potentially start fetching
      */
     getQueryData<T = any>(key: QueryKey, opts?: QueryOptions<T>): T | undefined;
+    getQueryData<F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+        fetcher: F;
+    }): InferFetcherResult<F> | undefined;
     /**
      * Gets comprehensive query state including computed flags
      * Handles placeholder data and error states appropriately
      * Handles mount logic to potentially start fetching
      */
     getQueryState<T = unknown>(key: QueryKey, opts?: QueryOptions<T>): QueryState<T>;
+    getQueryState<F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
+        fetcher: F;
+    }): QueryState<InferFetcherResult<F>>;
     /**
      * Marks a query as invalidated, triggering refetch
      */
@@ -134,7 +169,11 @@ declare class QueryManager {
      * Subscribes to query state changes with automatic subscription management
      * Handles mount logic to potentially start fetching
      */
-    subscribeQuery<T = any>(key: QueryKey, cb: () => void, opts?: QueryOptions<T>): () => void;
+    subscribeQuery(key: QueryKey, cb: (state: QueryState<any>) => void): () => void;
+    subscribeQuery<F extends Fetcher>(key: QueryKey, cb: (state: QueryState<InferFetcherResult<F>>) => void, opts: QueryOptions<InferFetcherResult<F>> & {
+        fetcher: F;
+    }): () => void;
+    subscribeQuery<T = any>(key: QueryKey, cb: (state: QueryState<T>) => void, opts?: QueryOptions<T>): () => void;
     /**
      * Core mount logic that determines when to fetch
      * Implements robust throttling and race condition prevention
@@ -149,4 +188,4 @@ declare const queryManager: QueryManager;
  */
 declare function serializeKey(key: QueryKey): string;
 
-export { DefaultConfig, EqualityFn, Fetcher, InferFetcherResult, InferFetcherReturnType, QueryKey, QueryKeyValue, QueryManager, QueryOptions, QueryState, QueryStatus, queryManager, serializeKey };
+export { DefaultConfig, EqualityFn, Fetcher, InferFetcherResult, QueryKey, QueryManager, QueryOptions, QueryState, QueryStatus, queryManager, serializeKey };

package/index.js

@@ -71,9 +71,54 @@ function createDefaultState(opts, refetch) {
     usePlaceholderOnError: opts?.usePlaceholderOnError ?? false,
     refetchOnSubscribe: opts?.refetchOnSubscribe ?? "stale",
     enabled: opts?.enabled === false ? false : true,
-    refetch: refetch || (() => Promise.resolve(void 0))
+    refetch: refetch || (() => Promise.resolve(void 0)),
+    isSuccess: false,
+    isError: false
   };
 }
+function createPublicState(state) {
+  const now = Date.now();
+  const isStale = state.updatedAt == null || now - (state.updatedAt || 0) > state.staleTime || state.isInvalidated;
+  let returnedData = state.data;
+  let isPlaceholderData = false;
+  switch (state.status) {
+    case "error":
+      if (state.usePlaceholderOnError && state.placeholderData !== void 0) {
+        returnedData = state.placeholderData;
+        isPlaceholderData = true;
+      }
+      break;
+    case "fetching":
+      if (!state.data && state.placeholderData) {
+        returnedData = state.placeholderData;
+        isPlaceholderData = true;
+      }
+      break;
+    case "success":
+    case "idle":
+      returnedData = state.data ?? state.placeholderData;
+      isPlaceholderData = state.data ? false : Boolean(state.placeholderData);
+      break;
+  }
+  return {
+    data: returnedData,
+    error: state.error,
+    status: state.status,
+    updatedAt: state.updatedAt,
+    isStale,
+    isPlaceholderData,
+    isLoading: state.status === "fetching" && !state.updatedAt,
+    isFetching: state.status === "fetching",
+    isError: state.isError,
+    isSuccess: state.isSuccess,
+    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 {
@@ -84,6 +129,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
    */
@@ -115,12 +186,14 @@ var QueryManager = class {
    * Notifies all subscribers of a query state change
    */
   emit(key, state) {
-    this.cache.set(serializeKey(key), state);
-    const set = this.subs.get(serializeKey(key));
+    const stateKey = serializeKey(key);
+    this.cache.set(stateKey, state);
+    const set = this.subs.get(stateKey);
     if (!set)
       return;
+    const publicState = createPublicState(state);
     for (const cb of Array.from(set))
-      cb();
+      cb(publicState);
   }
   registerFetcher(key, opts) {
     this.ensureState(key, opts);
@@ -137,7 +210,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);
     }
     ;
@@ -151,9 +226,13 @@ var QueryManager = class {
       state.data = result2;
       state.status = "success";
       state.updatedAt = Date.now();
+      state.isError = false;
+      state.isSuccess = true;
     }).catch((error) => {
       state.error = error;
       state.status = "error";
+      state.isError = true;
+      state.isSuccess = false;
     }).finally(() => {
       state.fetchPromise = void 0;
       this.emit(key, state);
@@ -174,63 +253,19 @@ var QueryManager = class {
     state.error = void 0;
     state.status = "success";
     state.isInvalidated = false;
+    state.isError = false;
+    state.isSuccess = true;
     this.emit(key, state);
   }
-  /**
-   * Gets query data
-   * Handles mount logic to potentially start fetching
-   */
   getQueryData(key, opts) {
     const state = this.ensureState(key, opts);
     this.handleMountLogic(key, state);
     return state.data ?? state.placeholderData;
   }
-  /**
-   * Gets comprehensive query state including computed flags
-   * Handles placeholder data and error states appropriately
-   * Handles mount logic to potentially start fetching
-   */
   getQueryState(key, opts) {
     let state = this.ensureState(key, opts);
-    const now = Date.now();
-    const isStale = state.updatedAt == null || now - (state.updatedAt || 0) > state.staleTime || state.isInvalidated;
-    let returnedData = state.data;
-    let isPlaceholderData = false;
-    const status = state.status;
-    switch (status) {
-      case "error":
-        if (state.usePlaceholderOnError && state.placeholderData !== void 0) {
-          returnedData = state.placeholderData;
-          isPlaceholderData = true;
-        }
-        break;
-      case "fetching":
-        if (!state.data && state.placeholderData) {
-          returnedData = state.placeholderData;
-          isPlaceholderData = true;
-        }
-        break;
-      case "success":
-      case "idle":
-        returnedData = state.data ?? state.placeholderData;
-        isPlaceholderData = state.data ? false : Boolean(state.placeholderData);
-        break;
-    }
     this.handleMountLogic(key, state);
-    const currentState = {
-      data: returnedData,
-      error: state.error,
-      status: state.status,
-      updatedAt: state.updatedAt,
-      isStale,
-      isPlaceholderData,
-      isLoading: state.status === "fetching" && !state.updatedAt,
-      // true only for first fetch
-      isFetching: state.status === "fetching",
-      isError: state.status === "error",
-      isSuccess: state.status === "success",
-      refetch: state.refetch
-    };
+    const currentState = createPublicState(state);
     const stateKey = serializeKey(key);
     const lastState = this.lastReturnedState?.get(stateKey);
     if (!lastState || !shallowEqual(lastState, currentState)) {
@@ -250,10 +285,6 @@ var QueryManager = class {
     this.emit(key, state);
     this.fetchQuery(key);
   }
-  /**
-   * Subscribes to query state changes with automatic subscription management
-   * Handles mount logic to potentially start fetching
-   */
   subscribeQuery(key, cb, opts) {
     const sk = serializeKey(key);
     const state = this.ensureState(key, opts);

package/index.mjs

@@ -43,9 +43,54 @@ function createDefaultState(opts, refetch) {
     usePlaceholderOnError: opts?.usePlaceholderOnError ?? false,
     refetchOnSubscribe: opts?.refetchOnSubscribe ?? "stale",
     enabled: opts?.enabled === false ? false : true,
-    refetch: refetch || (() => Promise.resolve(void 0))
+    refetch: refetch || (() => Promise.resolve(void 0)),
+    isSuccess: false,
+    isError: false
   };
 }
+function createPublicState(state) {
+  const now = Date.now();
+  const isStale = state.updatedAt == null || now - (state.updatedAt || 0) > state.staleTime || state.isInvalidated;
+  let returnedData = state.data;
+  let isPlaceholderData = false;
+  switch (state.status) {
+    case "error":
+      if (state.usePlaceholderOnError && state.placeholderData !== void 0) {
+        returnedData = state.placeholderData;
+        isPlaceholderData = true;
+      }
+      break;
+    case "fetching":
+      if (!state.data && state.placeholderData) {
+        returnedData = state.placeholderData;
+        isPlaceholderData = true;
+      }
+      break;
+    case "success":
+    case "idle":
+      returnedData = state.data ?? state.placeholderData;
+      isPlaceholderData = state.data ? false : Boolean(state.placeholderData);
+      break;
+  }
+  return {
+    data: returnedData,
+    error: state.error,
+    status: state.status,
+    updatedAt: state.updatedAt,
+    isStale,
+    isPlaceholderData,
+    isLoading: state.status === "fetching" && !state.updatedAt,
+    isFetching: state.status === "fetching",
+    isError: state.isError,
+    isSuccess: state.isSuccess,
+    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 {
@@ -56,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
    */
@@ -87,12 +158,14 @@ var QueryManager = class {
    * Notifies all subscribers of a query state change
    */
   emit(key, state) {
-    this.cache.set(serializeKey(key), state);
-    const set = this.subs.get(serializeKey(key));
+    const stateKey = serializeKey(key);
+    this.cache.set(stateKey, state);
+    const set = this.subs.get(stateKey);
     if (!set)
       return;
+    const publicState = createPublicState(state);
     for (const cb of Array.from(set))
-      cb();
+      cb(publicState);
   }
   registerFetcher(key, opts) {
     this.ensureState(key, opts);
@@ -109,7 +182,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);
     }
     ;
@@ -123,9 +198,13 @@ var QueryManager = class {
       state.data = result2;
       state.status = "success";
       state.updatedAt = Date.now();
+      state.isError = false;
+      state.isSuccess = true;
     }).catch((error) => {
       state.error = error;
       state.status = "error";
+      state.isError = true;
+      state.isSuccess = false;
     }).finally(() => {
       state.fetchPromise = void 0;
       this.emit(key, state);
@@ -146,63 +225,19 @@ var QueryManager = class {
     state.error = void 0;
     state.status = "success";
     state.isInvalidated = false;
+    state.isError = false;
+    state.isSuccess = true;
     this.emit(key, state);
   }
-  /**
-   * Gets query data
-   * Handles mount logic to potentially start fetching
-   */
   getQueryData(key, opts) {
     const state = this.ensureState(key, opts);
     this.handleMountLogic(key, state);
     return state.data ?? state.placeholderData;
   }
-  /**
-   * Gets comprehensive query state including computed flags
-   * Handles placeholder data and error states appropriately
-   * Handles mount logic to potentially start fetching
-   */
   getQueryState(key, opts) {
     let state = this.ensureState(key, opts);
-    const now = Date.now();
-    const isStale = state.updatedAt == null || now - (state.updatedAt || 0) > state.staleTime || state.isInvalidated;
-    let returnedData = state.data;
-    let isPlaceholderData = false;
-    const status = state.status;
-    switch (status) {
-      case "error":
-        if (state.usePlaceholderOnError && state.placeholderData !== void 0) {
-          returnedData = state.placeholderData;
-          isPlaceholderData = true;
-        }
-        break;
-      case "fetching":
-        if (!state.data && state.placeholderData) {
-          returnedData = state.placeholderData;
-          isPlaceholderData = true;
-        }
-        break;
-      case "success":
-      case "idle":
-        returnedData = state.data ?? state.placeholderData;
-        isPlaceholderData = state.data ? false : Boolean(state.placeholderData);
-        break;
-    }
     this.handleMountLogic(key, state);
-    const currentState = {
-      data: returnedData,
-      error: state.error,
-      status: state.status,
-      updatedAt: state.updatedAt,
-      isStale,
-      isPlaceholderData,
-      isLoading: state.status === "fetching" && !state.updatedAt,
-      // true only for first fetch
-      isFetching: state.status === "fetching",
-      isError: state.status === "error",
-      isSuccess: state.status === "success",
-      refetch: state.refetch
-    };
+    const currentState = createPublicState(state);
     const stateKey = serializeKey(key);
     const lastState = this.lastReturnedState?.get(stateKey);
     if (!lastState || !shallowEqual(lastState, currentState)) {
@@ -222,10 +257,6 @@ var QueryManager = class {
     this.emit(key, state);
     this.fetchQuery(key);
   }
-  /**
-   * Subscribes to query state changes with automatic subscription management
-   * Handles mount logic to potentially start fetching
-   */
   subscribeQuery(key, cb, opts) {
     const sk = serializeKey(key);
     const state = this.ensureState(key, opts);

package/package.json

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