@spoosh/plugin-invalidation 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spoosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @spoosh/plugin-invalidation
+
+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`
+
+## Installation
+
+```bash
+npm install @spoosh/plugin-invalidation
+```
+
+## How It Works
+
+Tags are automatically generated from the API path hierarchy:
+
+```typescript
+// Query tags are generated from the path:
+useRead((api) => api.users.$get());
+// → tags: ["users"]
+
+useRead((api) => api.users[123].$get());
+// → tags: ["users", "users/123"]
+
+useRead((api) => api.users[123].posts.$get());
+// → tags: ["users", "users/123", "users/123/posts"]
+```
+
+When a mutation succeeds, related queries are automatically invalidated:
+
+```typescript
+// Creating a post at users/123/posts invalidates:
+const { trigger } = useWrite((api) => api.users[123].posts.$post);
+await trigger({ body: { title: "New Post" } });
+
+// ✓ Invalidates: "users", "users/123", "users/123/posts"
+// All queries matching these tags will refetch automatically
+```
+
+## Usage
+
+```typescript
+import { invalidationPlugin } from "@spoosh/plugin-invalidation";
+
+const plugins = [invalidationPlugin()];
+
+// Auto-invalidates all related queries after mutation (default)
+const { trigger } = useWrite((api) => api.posts.$post);
+await trigger({ body: { title: "New Post" } });
+```
+
+## Default Configuration
+
+```typescript
+// Default: invalidate all related tags (full hierarchy)
+invalidationPlugin(); // same as { autoInvalidate: "all" }
+
+// Only invalidate the exact endpoint by default
+invalidationPlugin({ autoInvalidate: "self" });
+
+// Disable auto-invalidation by default (manual only)
+invalidationPlugin({ autoInvalidate: "none" });
+```
+
+## Per-Request Override
+
+```typescript
+// Override to invalidate all related tags
+await trigger({
+  body: { title: "New Post" },
+  autoInvalidate: "all",
+});
+
+// Override to only invalidate the exact endpoint
+await trigger({
+  body: { title: "New Post" },
+  autoInvalidate: "self",
+});
+
+// Disable auto-invalidation and specify custom targets
+await trigger({
+  body: { title: "New Post" },
+  autoInvalidate: "none",
+  invalidate: (api) => [api.posts.$get, api.stats.$get, "dashboard-data"],
+});
+
+// Add specific tags (works alongside autoInvalidate)
+await trigger({
+  body: { title: "New Post" },
+  invalidate: ["posts", "user-posts"],
+});
+```
+
+## Options
+
+### Plugin Config
+
+| Option           | Type                        | Default | Description                        |
+| ---------------- | --------------------------- | ------- | ---------------------------------- |
+| `autoInvalidate` | `"all" \| "self" \| "none"` | `"all"` | Default auto-invalidation behavior |
+
+### Per-Request Options
+
+| Option           | Type                           | Description                              |
+| ---------------- | ------------------------------ | ---------------------------------------- |
+| `autoInvalidate` | `"all" \| "self" \| "none"`    | Override auto-invalidation behavior      |
+| `invalidate`     | `string[] \| ((api) => [...])` | Specific tags or endpoints to invalidate |
+
+### Auto-Invalidate Modes
+
+| Mode     | Description                             | Example                                                     |
+| -------- | --------------------------------------- | ----------------------------------------------------------- |
+| `"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                                   |

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+import { QuerySchemaHelper, SpooshResponse, SpooshPlugin } from '@spoosh/core';
+
+type AutoInvalidate = "all" | "self" | "none";
+type InvalidateCallbackFn<TSchema> = (api: QuerySchemaHelper<TSchema>) => (((...args: never[]) => Promise<SpooshResponse<unknown, unknown>>) | string)[];
+type InvalidateOption<TSchema> = string[] | InvalidateCallbackFn<TSchema>;
+interface InvalidationPluginConfig {
+    /** Default auto-invalidation behavior. Defaults to `"all"`. */
+    autoInvalidate?: AutoInvalidate;
+}
+interface InvalidationWriteOptions<TSchema = unknown> {
+    /** Auto-invalidation behavior. Overrides plugin default. */
+    autoInvalidate?: AutoInvalidate;
+    /** Specific tags or endpoints to invalidate after mutation. */
+    invalidate?: InvalidateOption<TSchema>;
+}
+type InvalidationReadOptions = object;
+type InvalidationInfiniteReadOptions = object;
+type InvalidationReadResult = object;
+type InvalidationWriteResult = object;
+interface InvalidationPluginExports {
+    /** Set the default autoInvalidate behavior for this mutation */
+    setAutoInvalidateDefault: (value: AutoInvalidate) => void;
+}
+declare module "@spoosh/core" {
+    interface PluginExportsRegistry {
+        "spoosh:invalidation": InvalidationPluginExports;
+    }
+    interface PluginResolvers<TContext> {
+        invalidate: InvalidateOption<TContext["schema"]> | undefined;
+    }
+}
+
+/**
+ * Enables automatic cache invalidation after mutations.
+ *
+ * Marks related cache entries as stale and triggers refetches
+ * based on tags or explicit invalidation targets.
+ *
+ * @param config - Plugin configuration
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/invalidation | Invalidation Plugin Documentation}
+ *
+ * @example
+ * ```ts
+ * const plugins = [invalidationPlugin({ autoInvalidate: "all" })];
+ *
+ * // Per-mutation override
+ * trigger({
+ *   autoInvalidate: "self", // Only invalidate the same endpoint
+ *   invalidate: ["posts"], // Or explicit tags
+ * });
+ * ```
+ */
+declare function invalidationPlugin(config?: InvalidationPluginConfig): SpooshPlugin<{
+    readOptions: InvalidationReadOptions;
+    writeOptions: InvalidationWriteOptions;
+    infiniteReadOptions: InvalidationInfiniteReadOptions;
+    readResult: InvalidationReadResult;
+    writeResult: InvalidationWriteResult;
+}>;
+
+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

@@ -0,0 +1,62 @@
+import { QuerySchemaHelper, SpooshResponse, SpooshPlugin } from '@spoosh/core';
+
+type AutoInvalidate = "all" | "self" | "none";
+type InvalidateCallbackFn<TSchema> = (api: QuerySchemaHelper<TSchema>) => (((...args: never[]) => Promise<SpooshResponse<unknown, unknown>>) | string)[];
+type InvalidateOption<TSchema> = string[] | InvalidateCallbackFn<TSchema>;
+interface InvalidationPluginConfig {
+    /** Default auto-invalidation behavior. Defaults to `"all"`. */
+    autoInvalidate?: AutoInvalidate;
+}
+interface InvalidationWriteOptions<TSchema = unknown> {
+    /** Auto-invalidation behavior. Overrides plugin default. */
+    autoInvalidate?: AutoInvalidate;
+    /** Specific tags or endpoints to invalidate after mutation. */
+    invalidate?: InvalidateOption<TSchema>;
+}
+type InvalidationReadOptions = object;
+type InvalidationInfiniteReadOptions = object;
+type InvalidationReadResult = object;
+type InvalidationWriteResult = object;
+interface InvalidationPluginExports {
+    /** Set the default autoInvalidate behavior for this mutation */
+    setAutoInvalidateDefault: (value: AutoInvalidate) => void;
+}
+declare module "@spoosh/core" {
+    interface PluginExportsRegistry {
+        "spoosh:invalidation": InvalidationPluginExports;
+    }
+    interface PluginResolvers<TContext> {
+        invalidate: InvalidateOption<TContext["schema"]> | undefined;
+    }
+}
+
+/**
+ * Enables automatic cache invalidation after mutations.
+ *
+ * Marks related cache entries as stale and triggers refetches
+ * based on tags or explicit invalidation targets.
+ *
+ * @param config - Plugin configuration
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/invalidation | Invalidation Plugin Documentation}
+ *
+ * @example
+ * ```ts
+ * const plugins = [invalidationPlugin({ autoInvalidate: "all" })];
+ *
+ * // Per-mutation override
+ * trigger({
+ *   autoInvalidate: "self", // Only invalidate the same endpoint
+ *   invalidate: ["posts"], // Or explicit tags
+ * });
+ * ```
+ */
+declare function invalidationPlugin(config?: InvalidationPluginConfig): SpooshPlugin<{
+    readOptions: InvalidationReadOptions;
+    writeOptions: InvalidationWriteOptions;
+    infiniteReadOptions: InvalidationInfiniteReadOptions;
+    readResult: InvalidationReadResult;
+    writeResult: InvalidationWriteResult;
+}>;
+
+export { type AutoInvalidate, type InvalidateOption, type InvalidationInfiniteReadOptions, type InvalidationPluginConfig, type InvalidationPluginExports, type InvalidationReadOptions, type InvalidationReadResult, type InvalidationWriteOptions, type InvalidationWriteResult, invalidationPlugin };

package/dist/index.js

@@ -0,0 +1,86 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  invalidationPlugin: () => invalidationPlugin
+});
+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;
+  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);
+          }
+        }
+      }
+    }
+  }
+  const overrideDefault = context.metadata.get(INVALIDATION_DEFAULT_KEY);
+  const effectiveDefault = overrideDefault ?? defaultAutoInvalidate;
+  const autoInvalidate = pluginOptions?.autoInvalidate ?? effectiveDefault;
+  if (autoInvalidate === "all") {
+    tags.push(...context.tags);
+  } else if (autoInvalidate === "self") {
+    const selfTag = context.path.join("/");
+    tags.push(selfTag);
+  }
+  return [...new Set(tags)];
+}
+function invalidationPlugin(config = {}) {
+  const { autoInvalidate: defaultAutoInvalidate = "all" } = config;
+  return {
+    name: "spoosh:invalidation",
+    operations: ["write"],
+    exports(context) {
+      return {
+        setAutoInvalidateDefault(value) {
+          context.metadata.set(INVALIDATION_DEFAULT_KEY, value);
+        }
+      };
+    },
+    onResponse(context, response) {
+      if (!response.error) {
+        const tags = resolveInvalidateTags(context, defaultAutoInvalidate);
+        if (tags.length > 0) {
+          context.stateManager.markStale(tags);
+          context.eventEmitter.emit("invalidate", tags);
+        }
+      }
+    }
+  };
+}

package/dist/index.mjs

@@ -0,0 +1,67 @@
+// src/plugin.ts
+import {
+  createSelectorProxy,
+  extractPathFromSelector,
+  generateTags
+} from "@spoosh/core";
+var INVALIDATION_DEFAULT_KEY = "invalidation:autoInvalidateDefault";
+function resolveInvalidateTags(context, defaultAutoInvalidate) {
+  const pluginOptions = context.pluginOptions;
+  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);
+          }
+        }
+      }
+    }
+  }
+  const overrideDefault = context.metadata.get(INVALIDATION_DEFAULT_KEY);
+  const effectiveDefault = overrideDefault ?? defaultAutoInvalidate;
+  const autoInvalidate = pluginOptions?.autoInvalidate ?? effectiveDefault;
+  if (autoInvalidate === "all") {
+    tags.push(...context.tags);
+  } else if (autoInvalidate === "self") {
+    const selfTag = context.path.join("/");
+    tags.push(selfTag);
+  }
+  return [...new Set(tags)];
+}
+function invalidationPlugin(config = {}) {
+  const { autoInvalidate: defaultAutoInvalidate = "all" } = config;
+  return {
+    name: "spoosh:invalidation",
+    operations: ["write"],
+    exports(context) {
+      return {
+        setAutoInvalidateDefault(value) {
+          context.metadata.set(INVALIDATION_DEFAULT_KEY, value);
+        }
+      };
+    },
+    onResponse(context, response) {
+      if (!response.error) {
+        const tags = resolveInvalidateTags(context, defaultAutoInvalidate);
+        if (tags.length > 0) {
+          context.stateManager.markStale(tags);
+          context.eventEmitter.emit("invalidate", tags);
+        }
+      }
+    }
+  };
+}
+export {
+  invalidationPlugin
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@spoosh/plugin-invalidation",
+  "version": "0.1.0-beta.0",
+  "description": "Cache invalidation plugin for Spoosh - auto-invalidates after mutations",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxnom/spoosh.git",
+    "directory": "packages/plugin-invalidation"
+  },
+  "bugs": {
+    "url": "https://github.com/nxnom/spoosh/issues"
+  },
+  "homepage": "https://spoosh.dev/docs/plugins/invalidation",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spoosh",
+    "plugin",
+    "invalidation",
+    "cache",
+    "api-client"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@spoosh/core": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@spoosh/core": "0.1.0-beta.0",
+    "@spoosh/test-utils": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --max-warnings 0",
+    "format": "prettier --write 'src/**/*.ts'"
+  }
+}