qortex-core 0.1.3 → 0.1.4

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

@@ -10,15 +10,24 @@ 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
  */
@@ -120,12 +129,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 +149,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 +168,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, QueryKeyValue, QueryManager, QueryOptions, QueryState, QueryStatus, queryManager, serializeKey };

package/index.js

@@ -71,7 +71,47 @@ 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
   };
 }
 
@@ -115,12 +155,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);
@@ -151,9 +193,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 +220,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 +252,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,7 +43,47 @@ 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
   };
 }
 
@@ -87,12 +127,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);
@@ -123,9 +165,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 +192,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 +224,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.4",
   "description": "Framework-agnostic query cache & fetch registry (MFE friendly).",
   "main": "index.js",
   "module": "index.mjs",