@spoosh/plugin-invalidation 0.1.4 → 0.2.0

package/README.md

@@ -113,3 +113,28 @@ 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                                   |
+
+## Instance API
+
+The plugin exposes `invalidate` for manually triggering cache invalidation outside of mutations:
+
+```typescript
+import { createReactSpoosh } from "@spoosh/react";
+
+const { useRead, invalidate } = createReactSpoosh(client);
+
+// Invalidate with string array
+invalidate(["users", "posts"]);
+
+// Invalidate with callback (type-safe API selector)
+invalidate((api) => [api.users.$get, api.posts.$get, "custom-tag"]);
+
+// Useful for external events like WebSocket messages
+socket.on("data-changed", (tags) => {
+  invalidate(tags);
+});
+```
+
+| Method           | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `invalidate` | Manually invalidate cache entries by tags or API selector callback |

package/dist/index.d.mts

@@ -17,6 +17,11 @@ type InvalidationReadOptions = object;
 type InvalidationInfiniteReadOptions = object;
 type InvalidationReadResult = object;
 type InvalidationWriteResult = object;
+type InvalidateFn<TSchema> = (tags: InvalidateOption<TSchema>) => void;
+interface InvalidationInstanceApi {
+    /** Manually invalidate cache entries by tags. Useful for external events like WebSocket messages. */
+    invalidate: InvalidateFn<unknown>;
+}
 interface InvalidationPluginExports {
     /** Set the default autoInvalidate behavior for this mutation */
     setAutoInvalidateDefault: (value: AutoInvalidate) => void;
@@ -28,6 +33,9 @@ declare module "@spoosh/core" {
     interface PluginResolvers<TContext> {
         invalidate: InvalidateOption<TContext["schema"]> | undefined;
     }
+    interface InstanceApiResolvers<TSchema> {
+        invalidate: InvalidateFn<TSchema>;
+    }
 }
 
 /**
@@ -62,6 +70,7 @@ declare function invalidationPlugin(config?: InvalidationPluginConfig): SpooshPl
     infiniteReadOptions: InvalidationInfiniteReadOptions;
     readResult: InvalidationReadResult;
     writeResult: InvalidationWriteResult;
+    instanceApi: InvalidationInstanceApi;
 }>;
 
 export { type AutoInvalidate, type InvalidateOption, type InvalidationInfiniteReadOptions, type InvalidationPluginConfig, type InvalidationPluginExports, type InvalidationReadOptions, type InvalidationReadResult, type InvalidationWriteOptions, type InvalidationWriteResult, invalidationPlugin };

package/dist/index.d.ts

@@ -17,6 +17,11 @@ type InvalidationReadOptions = object;
 type InvalidationInfiniteReadOptions = object;
 type InvalidationReadResult = object;
 type InvalidationWriteResult = object;
+type InvalidateFn<TSchema> = (tags: InvalidateOption<TSchema>) => void;
+interface InvalidationInstanceApi {
+    /** Manually invalidate cache entries by tags. Useful for external events like WebSocket messages. */
+    invalidate: InvalidateFn<unknown>;
+}
 interface InvalidationPluginExports {
     /** Set the default autoInvalidate behavior for this mutation */
     setAutoInvalidateDefault: (value: AutoInvalidate) => void;
@@ -28,6 +33,9 @@ declare module "@spoosh/core" {
     interface PluginResolvers<TContext> {
         invalidate: InvalidateOption<TContext["schema"]> | undefined;
     }
+    interface InstanceApiResolvers<TSchema> {
+        invalidate: InvalidateFn<TSchema>;
+    }
 }
 
 /**
@@ -62,6 +70,7 @@ declare function invalidationPlugin(config?: InvalidationPluginConfig): SpooshPl
     infiniteReadOptions: InvalidationInfiniteReadOptions;
     readResult: InvalidationReadResult;
     writeResult: InvalidationWriteResult;
+    instanceApi: InvalidationInstanceApi;
 }>;
 
 export { type AutoInvalidate, type InvalidateOption, type InvalidationInfiniteReadOptions, type InvalidationPluginConfig, type InvalidationPluginExports, type InvalidationReadOptions, type InvalidationReadResult, type InvalidationWriteOptions, type InvalidationWriteResult, invalidationPlugin };

package/dist/index.js

@@ -27,29 +27,34 @@ module.exports = __toCommonJS(src_exports);
 // src/plugin.ts
 var import_core = require("@spoosh/core");
 var INVALIDATION_DEFAULT_KEY = "invalidation:autoInvalidateDefault";
-function resolveInvalidateTags(context, defaultAutoInvalidate) {
-  const pluginOptions = context.pluginOptions;
+function resolveTagsFromOption(invalidate) {
   const tags = [];
-  if (pluginOptions?.invalidate) {
-    if (Array.isArray(pluginOptions.invalidate)) {
-      tags.push(...pluginOptions.invalidate);
-    } else {
-      const proxy = (0, import_core.createSelectorProxy)();
-      const invalidationTargets = pluginOptions.invalidate(proxy);
-      for (const target of invalidationTargets) {
-        if (typeof target === "string") {
-          tags.push(target);
-        } else {
-          const path = (0, import_core.extractPathFromSelector)(target);
-          const derivedTags = (0, import_core.generateTags)(path);
-          const exactTag = derivedTags[derivedTags.length - 1];
-          if (exactTag) {
-            tags.push(exactTag);
-          }
+  if (Array.isArray(invalidate)) {
+    tags.push(...invalidate);
+  } else {
+    const proxy = (0, import_core.createSelectorProxy)();
+    const invalidationTargets = invalidate(proxy);
+    for (const target of invalidationTargets) {
+      if (typeof target === "string") {
+        tags.push(target);
+      } else {
+        const path = (0, import_core.extractPathFromSelector)(target);
+        const derivedTags = (0, import_core.generateTags)(path);
+        const exactTag = derivedTags[derivedTags.length - 1];
+        if (exactTag) {
+          tags.push(exactTag);
         }
       }
     }
   }
+  return tags;
+}
+function resolveInvalidateTags(context, defaultAutoInvalidate) {
+  const pluginOptions = context.pluginOptions;
+  const tags = [];
+  if (pluginOptions?.invalidate) {
+    tags.push(...resolveTagsFromOption(pluginOptions.invalidate));
+  }
   const overrideDefault = context.metadata.get(INVALIDATION_DEFAULT_KEY);
   const effectiveDefault = overrideDefault ?? defaultAutoInvalidate;
   const autoInvalidate = pluginOptions?.autoInvalidate ?? effectiveDefault;
@@ -81,6 +86,17 @@ function invalidationPlugin(config = {}) {
           context.eventEmitter.emit("invalidate", tags);
         }
       }
+    },
+    instanceApi(context) {
+      const { stateManager, eventEmitter } = context;
+      const invalidate = (input) => {
+        const tags = resolveTagsFromOption(input);
+        if (tags.length > 0) {
+          stateManager.markStale(tags);
+          eventEmitter.emit("invalidate", tags);
+        }
+      };
+      return { invalidate };
     }
   };
 }

package/dist/index.mjs

@@ -5,29 +5,34 @@ import {
   generateTags
 } from "@spoosh/core";
 var INVALIDATION_DEFAULT_KEY = "invalidation:autoInvalidateDefault";
-function resolveInvalidateTags(context, defaultAutoInvalidate) {
-  const pluginOptions = context.pluginOptions;
+function resolveTagsFromOption(invalidate) {
   const tags = [];
-  if (pluginOptions?.invalidate) {
-    if (Array.isArray(pluginOptions.invalidate)) {
-      tags.push(...pluginOptions.invalidate);
-    } else {
-      const proxy = createSelectorProxy();
-      const invalidationTargets = pluginOptions.invalidate(proxy);
-      for (const target of invalidationTargets) {
-        if (typeof target === "string") {
-          tags.push(target);
-        } else {
-          const path = extractPathFromSelector(target);
-          const derivedTags = generateTags(path);
-          const exactTag = derivedTags[derivedTags.length - 1];
-          if (exactTag) {
-            tags.push(exactTag);
-          }
+  if (Array.isArray(invalidate)) {
+    tags.push(...invalidate);
+  } else {
+    const proxy = createSelectorProxy();
+    const invalidationTargets = invalidate(proxy);
+    for (const target of invalidationTargets) {
+      if (typeof target === "string") {
+        tags.push(target);
+      } else {
+        const path = extractPathFromSelector(target);
+        const derivedTags = generateTags(path);
+        const exactTag = derivedTags[derivedTags.length - 1];
+        if (exactTag) {
+          tags.push(exactTag);
         }
       }
     }
   }
+  return tags;
+}
+function resolveInvalidateTags(context, defaultAutoInvalidate) {
+  const pluginOptions = context.pluginOptions;
+  const tags = [];
+  if (pluginOptions?.invalidate) {
+    tags.push(...resolveTagsFromOption(pluginOptions.invalidate));
+  }
   const overrideDefault = context.metadata.get(INVALIDATION_DEFAULT_KEY);
   const effectiveDefault = overrideDefault ?? defaultAutoInvalidate;
   const autoInvalidate = pluginOptions?.autoInvalidate ?? effectiveDefault;
@@ -59,6 +64,17 @@ function invalidationPlugin(config = {}) {
           context.eventEmitter.emit("invalidate", tags);
         }
       }
+    },
+    instanceApi(context) {
+      const { stateManager, eventEmitter } = context;
+      const invalidate = (input) => {
+        const tags = resolveTagsFromOption(input);
+        if (tags.length > 0) {
+          stateManager.markStale(tags);
+          eventEmitter.emit("invalidate", tags);
+        }
+      };
+      return { invalidate };
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/plugin-invalidation",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Cache invalidation plugin for Spoosh - auto-invalidates after mutations",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "@spoosh/core": ">=0.4.0"
   },
   "devDependencies": {
-    "@spoosh/core": "0.4.2",
+    "@spoosh/core": "0.5.0",
     "@spoosh/test-utils": "0.1.5"
   },
   "scripts": {