@spoosh/plugin-invalidation 0.5.2 → 0.5.3

package/README.md

@@ -2,7 +2,7 @@
 
 Cache invalidation plugin for Spoosh - auto-invalidates related queries after mutations.
 
-**[Documentation](https://spoosh.dev/docs/plugins/invalidation)** · **Requirements:** TypeScript >= 5.0 · **Peer Dependencies:** `@spoosh/core`
+**[Documentation](https://spoosh.dev/react/docs/plugins/invalidation)** · **Requirements:** TypeScript >= 5.0 · **Peer Dependencies:** `@spoosh/core`
 
 ## Installation
 
@@ -81,7 +81,13 @@ await trigger({
   invalidate: "none", // No invalidation
 });
 
-// Tags only (array without mode keyword)
+// Single tag (string)
+await trigger({
+  body: { title: "New Post" },
+  invalidate: "posts", // Invalidate only "posts" tag
+});
+
+// Multiple tags (array without mode keyword)
 await trigger({
   body: { title: "New Post" },
   invalidate: ["posts", "users", "custom-tag"],
@@ -106,6 +112,18 @@ await trigger({
   invalidate: ["dashboard", "stats", "all"],
   // → 'all' mode + explicit tags (mode can be anywhere)
 });
+
+// Wildcard - global refetch
+await trigger({
+  body: { title: "New Post" },
+  invalidate: "*", // Triggers ALL queries to refetch
+});
+
+// Combined with clearCache (from @spoosh/plugin-cache)
+await trigger({
+  clearCache: true,     // Clear all cached data
+  invalidate: "*",      // Then refetch all queries
+});
 ```
 
 ## Options
@@ -118,9 +136,9 @@ await trigger({
 
 ### Per-Request Options
 
-| Option       | Type                                    | Description                                                                                             |
-| ------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `invalidate` | `"all" \| "self" \| "none" \| string[]` | Mode only (string), tags only (array), or mode + tags (array with 'all'/'self' keyword at any position) |
+| Option       | Type                                                     | Description                                                                                                                      |
+| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `invalidate` | `"all" \| "self" \| "none" \| "*" \| string \| string[]` | Mode (`"all"`, `"self"`, `"none"`), wildcard (`"*"` for global refetch), single tag, or array of tags with optional mode keyword |
 
 ### Invalidation Modes
 
@@ -129,6 +147,25 @@ await trigger({
 | `"all"`  | Invalidate all tags from path hierarchy | `users/123/posts` → `users`, `users/123`, `users/123/posts` |
 | `"self"` | Only invalidate the exact endpoint tag  | `users/123/posts` → `users/123/posts`                       |
 | `"none"` | Disable auto-invalidation (manual only) | No automatic invalidation                                   |
+| `"*"`    | Global refetch - triggers all queries   | All active queries refetch                                  |
+
+### Understanding `"all"` vs `"*"`
+
+These two options serve different purposes:
+
+- **`"all"`** - Invalidates all tags **from the current endpoint's path hierarchy**. If you're mutating `users/123/posts`, it invalidates `["users", "users/123", "users/123/posts"]`. It's scoped to the mutation's path.
+
+- **`"*"`** - Triggers a **global refetch of every active query** in your app, regardless of tags. Use this sparingly for scenarios like "user logged out" or "full data sync from server".
+
+```typescript
+// "all" - scoped to this mutation's path hierarchy
+await trigger({ invalidate: "all" });
+// If path is users/123/posts → invalidates: users, users/123, users/123/posts
+
+// "*" - refetches ALL queries in the entire app
+await trigger({ invalidate: "*" });
+// Every active useRead/injectRead will refetch
+```
 
 ## Instance API
 
@@ -145,12 +182,38 @@ invalidate(["users", "posts"]);
 // Invalidate with single string
 invalidate("users");
 
+// Global refetch - triggers ALL queries to refetch
+invalidate("*");
+
 // Useful for external events like WebSocket messages
 socket.on("data-changed", (tags) => {
   invalidate(tags);
 });
+
+// WebSocket: trigger global refetch
+socket.on("full-sync", () => {
+  invalidate("*");
+});
+```
+
+| Method       | Description                                                            |
+| ------------ | ---------------------------------------------------------------------- |
+| `invalidate` | Manually invalidate cache entries by tags, or use `"*"` to refetch all |
+
+## Combining with Cache Plugin
+
+For scenarios like logout or user switching, combine `invalidate: "*"` with `clearCache` from `@spoosh/plugin-cache`:
+
+```typescript
+const { trigger } = useWrite((api) => api("auth/logout").POST);
+
+// Clear cache + trigger all queries to refetch
+await trigger({
+  clearCache: true,    // From cache plugin: clear all cached data
+  invalidate: "*",     // From invalidation plugin: trigger all queries to refetch
+});
 ```
 
-| Method       | Description                               |
-| ------------ | ----------------------------------------- |
-| `invalidate` | Manually invalidate cache entries by tags |
+This ensures both:
+1. All cached data is cleared (no stale data from previous session)
+2. All active queries refetch with fresh data

package/dist/index.d.mts

@@ -15,7 +15,7 @@ type ReadPaths<TSchema> = {
  *   - Otherwise, it's tags only with mode defaulting to 'none'
  *   - 'none' keyword should NOT be used in arrays (use string 'none' instead)
  */
-type InvalidateOption<TSchema = unknown> = InvalidationMode | (ReadPaths<TSchema> | "all" | "self" | (string & {}))[];
+type InvalidateOption<TSchema = unknown> = InvalidationMode | "*" | ReadPaths<TSchema> | (ReadPaths<TSchema> | "all" | "self" | (string & {}))[];
 interface InvalidationPluginConfig {
     /**
      * Default invalidation mode when invalidate option is not specified
@@ -32,13 +32,12 @@ type InvalidationInfiniteReadOptions = object;
 type InvalidationReadResult = object;
 type InvalidationWriteResult = object;
 /**
- * Manual invalidation - tags only
+ * Manual invalidation - tags only, or "*" for global refetch
  */
 type InvalidateFn<TSchema> = {
-    (tag: ReadPaths<TSchema>): void;
-    (tags: ReadPaths<TSchema>[]): void;
-    (tag: string): void;
-    (tags: string[]): void;
+    (tag: "*"): void;
+    (tag: ReadPaths<TSchema> | (string & {})): void;
+    (tags: (ReadPaths<TSchema> | (string & {}))[]): void;
 };
 interface InvalidationInstanceApi {
     /** Manually invalidate cache entries by tags. Useful for external events like WebSocket messages. */
@@ -85,12 +84,20 @@ declare module "@spoosh/core" {
  * });
  *
  * trigger({
- *   invalidate: ["posts", "users"], // Tags only
+ *   invalidate: "posts", // Single tag
+ * });
+ *
+ * trigger({
+ *   invalidate: ["posts", "users"], // Multiple tags
  * });
  *
  * trigger({
  *   invalidate: ["all", "posts", "custom-tag"], // Mode + tags
  * });
+ *
+ * trigger({
+ *   invalidate: "*", // Global refetch - triggers all queries to refetch
+ * });
  * ```
  */
 declare function invalidationPlugin(config?: InvalidationPluginConfig): SpooshPlugin<{

package/dist/index.d.ts

@@ -15,7 +15,7 @@ type ReadPaths<TSchema> = {
  *   - Otherwise, it's tags only with mode defaulting to 'none'
  *   - 'none' keyword should NOT be used in arrays (use string 'none' instead)
  */
-type InvalidateOption<TSchema = unknown> = InvalidationMode | (ReadPaths<TSchema> | "all" | "self" | (string & {}))[];
+type InvalidateOption<TSchema = unknown> = InvalidationMode | "*" | ReadPaths<TSchema> | (ReadPaths<TSchema> | "all" | "self" | (string & {}))[];
 interface InvalidationPluginConfig {
     /**
      * Default invalidation mode when invalidate option is not specified
@@ -32,13 +32,12 @@ type InvalidationInfiniteReadOptions = object;
 type InvalidationReadResult = object;
 type InvalidationWriteResult = object;
 /**
- * Manual invalidation - tags only
+ * Manual invalidation - tags only, or "*" for global refetch
  */
 type InvalidateFn<TSchema> = {
-    (tag: ReadPaths<TSchema>): void;
-    (tags: ReadPaths<TSchema>[]): void;
-    (tag: string): void;
-    (tags: string[]): void;
+    (tag: "*"): void;
+    (tag: ReadPaths<TSchema> | (string & {})): void;
+    (tags: (ReadPaths<TSchema> | (string & {}))[]): void;
 };
 interface InvalidationInstanceApi {
     /** Manually invalidate cache entries by tags. Useful for external events like WebSocket messages. */
@@ -85,12 +84,20 @@ declare module "@spoosh/core" {
  * });
  *
  * trigger({
- *   invalidate: ["posts", "users"], // Tags only
+ *   invalidate: "posts", // Single tag
+ * });
+ *
+ * trigger({
+ *   invalidate: ["posts", "users"], // Multiple tags
  * });
  *
  * trigger({
  *   invalidate: ["all", "posts", "custom-tag"], // Mode + tags
  * });
+ *
+ * trigger({
+ *   invalidate: "*", // Global refetch - triggers all queries to refetch
+ * });
  * ```
  */
 declare function invalidationPlugin(config?: InvalidationPluginConfig): SpooshPlugin<{

package/dist/index.js

@@ -45,7 +45,10 @@ function resolveInvalidateTags(context, defaultMode) {
     return resolveModeTags(context, effectiveDefault);
   }
   if (typeof invalidateOption === "string") {
-    return resolveModeTags(context, invalidateOption);
+    if (invalidateOption === "all" || invalidateOption === "self" || invalidateOption === "none") {
+      return resolveModeTags(context, invalidateOption);
+    }
+    return [invalidateOption];
   }
   if (Array.isArray(invalidateOption)) {
     const tags = [];
@@ -77,6 +80,10 @@ function invalidationPlugin(config = {}) {
     afterResponse(context, response) {
       if (!response.error) {
         const tags = resolveInvalidateTags(context, defaultMode);
+        if (tags.includes("*")) {
+          context.eventEmitter.emit("refetchAll", void 0);
+          return;
+        }
         if (tags.length > 0) {
           context.stateManager.markStale(tags);
           context.eventEmitter.emit("invalidate", tags);
@@ -87,6 +94,10 @@ function invalidationPlugin(config = {}) {
       const { stateManager, eventEmitter } = context;
       const invalidate = (input) => {
         const tags = Array.isArray(input) ? input : [input];
+        if (tags.includes("*")) {
+          eventEmitter.emit("refetchAll", void 0);
+          return;
+        }
         if (tags.length > 0) {
           stateManager.markStale(tags);
           eventEmitter.emit("invalidate", tags);

package/dist/index.mjs

@@ -19,7 +19,10 @@ function resolveInvalidateTags(context, defaultMode) {
     return resolveModeTags(context, effectiveDefault);
   }
   if (typeof invalidateOption === "string") {
-    return resolveModeTags(context, invalidateOption);
+    if (invalidateOption === "all" || invalidateOption === "self" || invalidateOption === "none") {
+      return resolveModeTags(context, invalidateOption);
+    }
+    return [invalidateOption];
   }
   if (Array.isArray(invalidateOption)) {
     const tags = [];
@@ -51,6 +54,10 @@ function invalidationPlugin(config = {}) {
     afterResponse(context, response) {
       if (!response.error) {
         const tags = resolveInvalidateTags(context, defaultMode);
+        if (tags.includes("*")) {
+          context.eventEmitter.emit("refetchAll", void 0);
+          return;
+        }
         if (tags.length > 0) {
           context.stateManager.markStale(tags);
           context.eventEmitter.emit("invalidate", tags);
@@ -61,6 +68,10 @@ function invalidationPlugin(config = {}) {
       const { stateManager, eventEmitter } = context;
       const invalidate = (input) => {
         const tags = Array.isArray(input) ? input : [input];
+        if (tags.includes("*")) {
+          eventEmitter.emit("refetchAll", void 0);
+          return;
+        }
         if (tags.length > 0) {
           stateManager.markStale(tags);
           eventEmitter.emit("invalidate", tags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/plugin-invalidation",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Cache invalidation plugin for Spoosh - auto-invalidates after mutations",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "@spoosh/core": ">=0.8.0"
   },
   "devDependencies": {
-    "@spoosh/core": "0.9.2",
+    "@spoosh/core": "0.9.3",
     "@spoosh/test-utils": "0.1.5"
   },
   "scripts": {