@spoosh/core 0.7.0 → 0.8.1

package/dist/index.d.mts

@@ -287,9 +287,10 @@ type PluginHandler<TData = unknown, TError = unknown> = (context: PluginContext<
 type PluginUpdateHandler<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>, previousContext: PluginContext<TData, TError>) => void | Promise<void>;
 /**
  * Handler called after every response, regardless of early returns from middleware.
- * Use this for post-response logic like scheduling polls or emitting events.
+ * Can return a new response to transform it, or void for side effects only.
+ * Returned responses are chained through plugins in order.
  */
-type PluginResponseHandler<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>, response: SpooshResponse<TData, TError>) => void | Promise<void>;
+type PluginResponseHandler<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>, response: SpooshResponse<TData, TError>) => SpooshResponse<TData, TError> | void | Promise<SpooshResponse<TData, TError> | void>;
 type PluginLifecycle<TData = unknown, TError = unknown> = {
     /** Called on component mount */
     onMount?: PluginHandler<TData, TError>;
@@ -333,7 +334,7 @@ type PluginTypeConfig = {
  *
  * Plugins can implement:
  * - `middleware`: Wraps the fetch flow for full control (intercept, retry, transform)
- * - `onResponse`: Called after every response, regardless of early returns
+ * - `afterResponse`: Called after every response, regardless of early returns
  * - `lifecycle`: Component lifecycle hooks (onMount, onUpdate, onUnmount)
  * - `exports`: Functions/variables accessible to other plugins
  *
@@ -353,7 +354,7 @@ type PluginTypeConfig = {
  *       const result = await next();
  *       return result;
  *     },
- *     onResponse(context, response) {
+ *     afterResponse(context, response) {
  *       // Always runs after response
  *     },
  *     lifecycle: {
@@ -370,8 +371,11 @@ interface SpooshPlugin<T extends PluginTypeConfig = PluginTypeConfig> {
     operations: OperationType[];
     /** Middleware for controlling the fetch flow. Called in plugin order, composing a chain. */
     middleware?: PluginMiddleware;
-    /** Called after every response, regardless of early returns from middleware. */
-    onResponse?: PluginResponseHandler;
+    /**
+     * Called after middleware chain completes, regardless of early returns.
+     * Return a new response to transform it, or void for side effects only.
+     */
+    afterResponse?: PluginResponseHandler;
     /** Component lifecycle hooks (setup, cleanup, option changes) */
     lifecycle?: PluginLifecycle;
     /** Expose functions/variables for other plugins to access via `context.plugins.get(name)` */
@@ -568,7 +572,7 @@ type PluginExecutor = {
     executeLifecycle: <TData, TError>(phase: "onMount" | "onUnmount", operationType: OperationType, context: PluginContext<TData, TError>) => Promise<void>;
     /** Execute onUpdate lifecycle with previous context */
     executeUpdateLifecycle: <TData, TError>(operationType: OperationType, context: PluginContext<TData, TError>, previousContext: PluginContext<TData, TError>) => Promise<void>;
-    /** Execute middleware chain with a core fetch function, then run onResponse handlers */
+    /** Execute middleware chain with a core fetch function, then run afterResponse handlers */
     executeMiddleware: <TData, TError>(operationType: OperationType, context: PluginContext<TData, TError>, coreFetch: () => Promise<SpooshResponse<TData, TError>>) => Promise<SpooshResponse<TData, TError>>;
     getPlugins: () => readonly SpooshPlugin[];
     /** Creates a full PluginContext with plugins accessor injected */

package/dist/index.d.ts

@@ -287,9 +287,10 @@ type PluginHandler<TData = unknown, TError = unknown> = (context: PluginContext<
 type PluginUpdateHandler<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>, previousContext: PluginContext<TData, TError>) => void | Promise<void>;
 /**
  * Handler called after every response, regardless of early returns from middleware.
- * Use this for post-response logic like scheduling polls or emitting events.
+ * Can return a new response to transform it, or void for side effects only.
+ * Returned responses are chained through plugins in order.
  */
-type PluginResponseHandler<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>, response: SpooshResponse<TData, TError>) => void | Promise<void>;
+type PluginResponseHandler<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>, response: SpooshResponse<TData, TError>) => SpooshResponse<TData, TError> | void | Promise<SpooshResponse<TData, TError> | void>;
 type PluginLifecycle<TData = unknown, TError = unknown> = {
     /** Called on component mount */
     onMount?: PluginHandler<TData, TError>;
@@ -333,7 +334,7 @@ type PluginTypeConfig = {
  *
  * Plugins can implement:
  * - `middleware`: Wraps the fetch flow for full control (intercept, retry, transform)
- * - `onResponse`: Called after every response, regardless of early returns
+ * - `afterResponse`: Called after every response, regardless of early returns
  * - `lifecycle`: Component lifecycle hooks (onMount, onUpdate, onUnmount)
  * - `exports`: Functions/variables accessible to other plugins
  *
@@ -353,7 +354,7 @@ type PluginTypeConfig = {
  *       const result = await next();
  *       return result;
  *     },
- *     onResponse(context, response) {
+ *     afterResponse(context, response) {
  *       // Always runs after response
  *     },
  *     lifecycle: {
@@ -370,8 +371,11 @@ interface SpooshPlugin<T extends PluginTypeConfig = PluginTypeConfig> {
     operations: OperationType[];
     /** Middleware for controlling the fetch flow. Called in plugin order, composing a chain. */
     middleware?: PluginMiddleware;
-    /** Called after every response, regardless of early returns from middleware. */
-    onResponse?: PluginResponseHandler;
+    /**
+     * Called after middleware chain completes, regardless of early returns.
+     * Return a new response to transform it, or void for side effects only.
+     */
+    afterResponse?: PluginResponseHandler;
     /** Component lifecycle hooks (setup, cleanup, option changes) */
     lifecycle?: PluginLifecycle;
     /** Expose functions/variables for other plugins to access via `context.plugins.get(name)` */
@@ -568,7 +572,7 @@ type PluginExecutor = {
     executeLifecycle: <TData, TError>(phase: "onMount" | "onUnmount", operationType: OperationType, context: PluginContext<TData, TError>) => Promise<void>;
     /** Execute onUpdate lifecycle with previous context */
     executeUpdateLifecycle: <TData, TError>(operationType: OperationType, context: PluginContext<TData, TError>, previousContext: PluginContext<TData, TError>) => Promise<void>;
-    /** Execute middleware chain with a core fetch function, then run onResponse handlers */
+    /** Execute middleware chain with a core fetch function, then run afterResponse handlers */
     executeMiddleware: <TData, TError>(operationType: OperationType, context: PluginContext<TData, TError>, coreFetch: () => Promise<SpooshResponse<TData, TError>>) => Promise<SpooshResponse<TData, TError>>;
     getPlugins: () => readonly SpooshPlugin[];
     /** Creates a full PluginContext with plugins accessor injected */

package/dist/index.js

@@ -836,11 +836,14 @@ function createPluginExecutor(initialPlugins = []) {
         response = await chain();
       }
       for (const plugin of applicablePlugins) {
-        if (plugin.onResponse) {
-          await plugin.onResponse(
+        if (plugin.afterResponse) {
+          const newResponse = await plugin.afterResponse(
             context,
             response
           );
+          if (newResponse) {
+            response = newResponse;
+          }
         }
       }
       return response;
@@ -1144,12 +1147,14 @@ function createOperationController(options) {
     const cached = stateManager.getCache(queryKey);
     if (cached) {
       stateManager.setCache(queryKey, {
-        state: { ...cached.state, ...updater }
+        state: { ...cached.state, ...updater },
+        stale: false
       });
     } else {
       stateManager.setCache(queryKey, {
         state: { ...createInitialState(), ...updater },
-        tags
+        tags,
+        stale: false
       });
     }
   };
@@ -1175,13 +1180,6 @@ function createOperationController(options) {
           try {
             const response = await fetchFn(context.requestOptions);
             context.response = response;
-            if (response.data !== void 0 && !response.error) {
-              updateState({
-                data: response.data,
-                error: void 0,
-                timestamp: Date.now()
-              });
-            }
             return response;
           } catch (err) {
             const errorResponse = {
@@ -1199,11 +1197,19 @@ function createOperationController(options) {
         });
         return fetchPromise;
       };
-      return pluginExecutor.executeMiddleware(
+      const finalResponse = await pluginExecutor.executeMiddleware(
         operationType,
         context,
         coreFetch
       );
+      if (finalResponse.data !== void 0 && !finalResponse.error) {
+        updateState({
+          data: finalResponse.data,
+          error: void 0,
+          timestamp: Date.now()
+        });
+      }
+      return finalResponse;
     },
     getState() {
       const cached = stateManager.getCache(queryKey);
@@ -1462,34 +1468,6 @@ function createInfiniteReadController(options) {
               aborted: true
             };
           }
-          if (response.data !== void 0 && !response.error) {
-            pageRequests.set(pageKey, mergedRequest);
-            if (direction === "next") {
-              if (!pageKeys.includes(pageKey)) {
-                pageKeys = [...pageKeys, pageKey];
-              }
-            } else {
-              if (!pageKeys.includes(pageKey)) {
-                pageKeys = [pageKey, ...pageKeys];
-              }
-            }
-            saveToTracker();
-            subscribeToPages();
-            stateManager.setCache(pageKey, {
-              state: {
-                data: response.data,
-                error: void 0,
-                timestamp: Date.now()
-              },
-              tags,
-              stale: false
-            });
-          }
-          if (response.data !== void 0 && !response.error) {
-            latestError = void 0;
-          } else if (response.error) {
-            latestError = response.error;
-          }
           return response;
         } catch (err) {
           if (signal.aborted) {
@@ -1517,7 +1495,37 @@ function createInfiniteReadController(options) {
       stateManager.setPendingPromise(pageKey, fetchPromise);
       return fetchPromise;
     };
-    await pluginExecutor.executeMiddleware("infiniteRead", context, coreFetch);
+    const finalResponse = await pluginExecutor.executeMiddleware(
+      "infiniteRead",
+      context,
+      coreFetch
+    );
+    if (finalResponse.data !== void 0 && !finalResponse.error) {
+      pageRequests.set(pageKey, mergedRequest);
+      if (direction === "next") {
+        if (!pageKeys.includes(pageKey)) {
+          pageKeys = [...pageKeys, pageKey];
+        }
+      } else {
+        if (!pageKeys.includes(pageKey)) {
+          pageKeys = [pageKey, ...pageKeys];
+        }
+      }
+      saveToTracker();
+      subscribeToPages();
+      stateManager.setCache(pageKey, {
+        state: {
+          data: finalResponse.data,
+          error: void 0,
+          timestamp: Date.now()
+        },
+        tags,
+        stale: false
+      });
+      latestError = void 0;
+    } else if (finalResponse.error) {
+      latestError = finalResponse.error;
+    }
   };
   const controller = {
     getState() {

package/dist/index.mjs

@@ -780,11 +780,14 @@ function createPluginExecutor(initialPlugins = []) {
         response = await chain();
       }
       for (const plugin of applicablePlugins) {
-        if (plugin.onResponse) {
-          await plugin.onResponse(
+        if (plugin.afterResponse) {
+          const newResponse = await plugin.afterResponse(
             context,
             response
           );
+          if (newResponse) {
+            response = newResponse;
+          }
         }
       }
       return response;
@@ -1088,12 +1091,14 @@ function createOperationController(options) {
     const cached = stateManager.getCache(queryKey);
     if (cached) {
       stateManager.setCache(queryKey, {
-        state: { ...cached.state, ...updater }
+        state: { ...cached.state, ...updater },
+        stale: false
       });
     } else {
       stateManager.setCache(queryKey, {
         state: { ...createInitialState(), ...updater },
-        tags
+        tags,
+        stale: false
       });
     }
   };
@@ -1119,13 +1124,6 @@ function createOperationController(options) {
           try {
             const response = await fetchFn(context.requestOptions);
             context.response = response;
-            if (response.data !== void 0 && !response.error) {
-              updateState({
-                data: response.data,
-                error: void 0,
-                timestamp: Date.now()
-              });
-            }
             return response;
           } catch (err) {
             const errorResponse = {
@@ -1143,11 +1141,19 @@ function createOperationController(options) {
         });
         return fetchPromise;
       };
-      return pluginExecutor.executeMiddleware(
+      const finalResponse = await pluginExecutor.executeMiddleware(
         operationType,
         context,
         coreFetch
       );
+      if (finalResponse.data !== void 0 && !finalResponse.error) {
+        updateState({
+          data: finalResponse.data,
+          error: void 0,
+          timestamp: Date.now()
+        });
+      }
+      return finalResponse;
     },
     getState() {
       const cached = stateManager.getCache(queryKey);
@@ -1406,34 +1412,6 @@ function createInfiniteReadController(options) {
               aborted: true
             };
           }
-          if (response.data !== void 0 && !response.error) {
-            pageRequests.set(pageKey, mergedRequest);
-            if (direction === "next") {
-              if (!pageKeys.includes(pageKey)) {
-                pageKeys = [...pageKeys, pageKey];
-              }
-            } else {
-              if (!pageKeys.includes(pageKey)) {
-                pageKeys = [pageKey, ...pageKeys];
-              }
-            }
-            saveToTracker();
-            subscribeToPages();
-            stateManager.setCache(pageKey, {
-              state: {
-                data: response.data,
-                error: void 0,
-                timestamp: Date.now()
-              },
-              tags,
-              stale: false
-            });
-          }
-          if (response.data !== void 0 && !response.error) {
-            latestError = void 0;
-          } else if (response.error) {
-            latestError = response.error;
-          }
           return response;
         } catch (err) {
           if (signal.aborted) {
@@ -1461,7 +1439,37 @@ function createInfiniteReadController(options) {
       stateManager.setPendingPromise(pageKey, fetchPromise);
       return fetchPromise;
     };
-    await pluginExecutor.executeMiddleware("infiniteRead", context, coreFetch);
+    const finalResponse = await pluginExecutor.executeMiddleware(
+      "infiniteRead",
+      context,
+      coreFetch
+    );
+    if (finalResponse.data !== void 0 && !finalResponse.error) {
+      pageRequests.set(pageKey, mergedRequest);
+      if (direction === "next") {
+        if (!pageKeys.includes(pageKey)) {
+          pageKeys = [...pageKeys, pageKey];
+        }
+      } else {
+        if (!pageKeys.includes(pageKey)) {
+          pageKeys = [pageKey, ...pageKeys];
+        }
+      }
+      saveToTracker();
+      subscribeToPages();
+      stateManager.setCache(pageKey, {
+        state: {
+          data: finalResponse.data,
+          error: void 0,
+          timestamp: Date.now()
+        },
+        tags,
+        stale: false
+      });
+      latestError = void 0;
+    } else if (finalResponse.error) {
+      latestError = finalResponse.error;
+    }
   };
   const controller = {
     getState() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/core",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "license": "MIT",
   "description": "Type-safe API client with plugin middleware system",
   "keywords": [