@spoosh/plugin-invalidation 0.9.1 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @spoosh/plugin-invalidation
 
-Cache invalidation plugin for Spoosh - auto-invalidates related queries after mutations.
+Cache invalidation plugin for Spoosh - auto-invalidates related queries after mutations using wildcard patterns.
 
 **[Documentation](https://spoosh.dev/docs/react/plugins/invalidation)** · **Requirements:** TypeScript >= 5.0 · **Peer Dependencies:** `@spoosh/core`
 
@@ -12,29 +12,28 @@ npm install @spoosh/plugin-invalidation
 
 ## How It Works
 
-Tags are automatically generated from the API path hierarchy:
+Tags are automatically generated from the API path:
 
 ```typescript
-// Query tags are generated from the path:
-useRead((api) => api("users").GET());
-// → tags: ["users"]
+useRead((api) => api("posts").GET());
+// → tag: "posts"
 
-useRead((api) => api("users/:id").GET({ params: { id: 123 } }));
-// → tags: ["users", "users/123"]
+useRead((api) => api("posts/:id").GET({ params: { id: 123 } }));
+// → tag: "posts/123"
 
-useRead((api) => api("users/:id/posts").GET({ params: { id: 123 } }));
-// → tags: ["users", "users/123", "users/123/posts"]
+useRead((api) => api("posts/:id/comments").GET({ params: { id: 123 } }));
+// → tag: "posts/123/comments"
 ```
 
-When a mutation succeeds, related queries are automatically invalidated:
+When a mutation succeeds, related queries are automatically invalidated using wildcard patterns:
 
 ```typescript
-// Creating a post at users/123/posts invalidates:
-const { trigger } = useWrite((api) => api("users/:id/posts").POST());
-await trigger({ params: { id: 123 }, body: { title: "New Post" } });
+const { trigger } = useWrite((api) => api("posts/:id/comments").POST());
+await trigger({ params: { id: 123 }, body: { text: "Hello" } });
 
-// ✓ Invalidates: "users", "users/123", "users/123/posts"
-// All queries matching these tags will refetch automatically
+// Default behavior (autoInvalidate: true):
+// Invalidates: ["posts", "posts/*"]
+// ✓ Matches: "posts", "posts/123", "posts/123/comments", etc.
 ```
 
 ## Usage
@@ -49,172 +48,153 @@ const { trigger } = useWrite((api) => api("posts").POST());
 await trigger({ body: { title: "New Post" } });
 ```
 
-## Default Configuration
+## Pattern Matching
 
-```typescript
-// Default: invalidate all related tags (full hierarchy)
-invalidationPlugin(); // same as { defaultMode: "all" }
-
-// Only invalidate the exact endpoint by default
-invalidationPlugin({ defaultMode: "self" });
-
-// Disable auto-invalidation by default (manual only)
-invalidationPlugin({ defaultMode: "none" });
-```
+| Pattern                | Matches                           | Does NOT Match         |
+| ---------------------- | --------------------------------- | ---------------------- |
+| `"posts"`              | `"posts"` (exact)                 | `"posts/1"`, `"users"` |
+| `"posts/*"`            | `"posts/1"`, `"posts/1/comments"` | `"posts"` (parent)     |
+| `["posts", "posts/*"]` | `"posts"` AND all children        | -                      |
 
 ## Per-Request Invalidation
 
 ```typescript
-// Mode only (string)
+// Exact match only
 await trigger({
   body: { title: "New Post" },
-  invalidate: "all", // Invalidate entire path hierarchy
+  invalidate: "posts",
 });
 
+// Children only (not the parent)
 await trigger({
   body: { title: "New Post" },
-  invalidate: "self", // Only invalidate the exact endpoint
+  invalidate: "posts/*",
 });
 
+// Parent AND all children
 await trigger({
   body: { title: "New Post" },
-  invalidate: "none", // No invalidation
+  invalidate: ["posts", "posts/*"],
 });
 
-// Single tag (string)
+// Multiple patterns
 await trigger({
   body: { title: "New Post" },
-  invalidate: "posts", // Invalidate only "posts" tag
+  invalidate: ["posts", "users/*", "dashboard"],
 });
 
-// Multiple tags (array without mode keyword)
+// Disable invalidation for this mutation
 await trigger({
   body: { title: "New Post" },
-  invalidate: ["posts", "users", "custom-tag"],
-  // → Default mode: 'none' (only explicit tags are invalidated)
+  invalidate: false,
 });
 
-// Mode + Tags (array with mode keyword at any position)
+// Global refetch - triggers ALL queries to refetch
 await trigger({
   body: { title: "New Post" },
-  invalidate: ["all", "dashboard", "stats"],
-  // → 'all' mode + explicit tags
+  invalidate: "*",
 });
+```
 
-await trigger({
-  body: { title: "New Post" },
-  invalidate: ["posts", "self", "users"],
-  // → 'self' mode + explicit tags
-});
+## Options
 
-await trigger({
-  body: { title: "New Post" },
-  invalidate: ["dashboard", "stats", "all"],
-  // → 'all' mode + explicit tags (mode can be anywhere)
-});
+### Plugin Config
 
-// Wildcard - global refetch
-await trigger({
-  body: { title: "New Post" },
-  invalidate: "*", // Triggers ALL queries to refetch
-});
+| Option           | Type       | Default | Description                                    |
+| ---------------- | ---------- | ------- | ---------------------------------------------- |
+| `autoInvalidate` | `boolean`  | `true`  | Auto-generate invalidation patterns from path  |
+| `groups`         | `string[]` | `[]`    | Path prefixes that use deeper segment matching |
 
-// Combined with clearCache (from @spoosh/plugin-cache)
-await trigger({
-  clearCache: true, // Clear all cached data
-  invalidate: "*", // Then refetch all queries
+```typescript
+// Default: auto-invalidate using [firstSegment, firstSegment/*]
+invalidationPlugin(); // same as { autoInvalidate: true }
+
+// Disable auto-invalidation (manual only)
+invalidationPlugin({ autoInvalidate: false });
+
+// Groups: use deeper segment matching for grouped endpoints
+invalidationPlugin({
+  groups: ["admin", "api/v1"],
 });
 ```
 
-## Options
+### Groups Configuration
 
-### Plugin Config
-
-| Option        | Type                        | Default | Description                                         |
-| ------------- | --------------------------- | ------- | --------------------------------------------------- |
-| `defaultMode` | `"all" \| "self" \| "none"` | `"all"` | Default invalidation mode when option not specified |
+Use `groups` when you have path prefixes that should be treated as a namespace:
 
-### Per-Request Options
+```typescript
+invalidationPlugin({
+  groups: ["admin", "api/v1"],
+});
 
-| 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 |
+// Without groups:
+// POST admin/posts → invalidates ["admin", "admin/*"]
 
-### Invalidation Modes
+// With groups: ["admin"]:
+// POST admin/posts → invalidates ["admin/posts", "admin/posts/*"]
+// POST admin/users → invalidates ["admin/users", "admin/users/*"]
+// POST admin → invalidates ["admin", "admin/*"]
 
-| 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                                   |
-| `"*"`    | Global refetch - triggers all queries   | All active queries refetch                                  |
+// With groups: ["api/v1"]:
+// POST api/v1/users → invalidates ["api/v1/users", "api/v1/users/*"]
+```
 
-### Understanding `"all"` vs `"*"`
+### Per-Request Options
 
-These two options serve different purposes:
+| Option       | Type                                 | Description                                                               |
+| ------------ | ------------------------------------ | ------------------------------------------------------------------------- |
+| `invalidate` | `string \| string[] \| false \| "*"` | Pattern(s) to invalidate, `false` to disable, or `"*"` for global refetch |
 
-- **`"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.
+## Default Behavior
 
-- **`"*"`** - 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".
+When `autoInvalidate: true` (default) and no `invalidate` option is provided:
 
 ```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
+// POST /posts/123/comments
+// → Invalidates: ["posts", "posts/*"]
 
-// "*" - refetches ALL queries in the entire app
-await trigger({ invalidate: "*" });
-// Every active useRead/injectRead will refetch
+// The first path segment is used to generate patterns:
+// - "posts" - exact match for the root
+// - "posts/*" - all children under posts
 ```
 
 ## Instance API
 
-The plugin exposes `invalidate` for manually triggering cache invalidation outside of mutations:
+The plugin exposes `invalidate` for manual cache invalidation:
 
 ```typescript
 import { create } from "@spoosh/react";
 
 const { useRead, invalidate } = create(spoosh);
 
-// Invalidate with string array
-invalidate(["users", "posts"]);
+// Single pattern
+invalidate("posts");
 
-// Invalidate with single string
-invalidate("users");
+// Multiple patterns
+invalidate(["posts", "users/*"]);
 
-// Global refetch - triggers ALL queries to refetch
+// Global refetch
 invalidate("*");
 
-// Useful for external events like WebSocket messages
-socket.on("data-changed", (tags) => {
-  invalidate(tags);
+// Useful for external events
+socket.on("posts-updated", () => {
+  invalidate(["posts", "posts/*"]);
 });
 
-// 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`:
+For scenarios like logout, combine 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
+  clearCache: true, // Clear all cached data
+  invalidate: "*", // Trigger all queries to refetch
 });
 ```
-
-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

@@ -1,31 +1,57 @@
 import * as _spoosh_core from '@spoosh/core';
 
-type InvalidationMode = "all" | "self" | "none";
 /**
  * Extract paths that have GET methods (eligible for invalidation)
+ * Excludes "/" root path to avoid "//*" pattern in autocomplete
  */
 type ReadPaths<TSchema> = {
-    [K in keyof TSchema & string]: "GET" extends keyof TSchema[K] ? K : never;
+    [K in keyof TSchema & string]: "GET" extends keyof TSchema[K] ? K extends "/" | "" ? never : K : never;
 }[keyof TSchema & string];
 /**
- * Unified invalidate option
- * - String: mode only ('all' | 'self' | 'none')
- * - Array: tags only OR [mode keyword mixed with tags]
- *   - If array contains 'all' or 'self' at ANY position, it's treated as mode + tags
- *   - Otherwise, it's tags only with mode defaulting to 'none'
- *   - 'none' keyword should NOT be used in arrays (use string 'none' instead)
+ * Support both exact paths and wildcard patterns in autocomplete
  */
-type InvalidateOption<TSchema = unknown> = InvalidationMode | "*" | ReadPaths<TSchema> | (ReadPaths<TSchema> | "all" | "self" | (string & {}))[];
+type InvalidatePattern<TSchema> = ReadPaths<TSchema> | `${ReadPaths<TSchema>}/*`;
+/**
+ * Unified invalidate option with wildcard pattern support
+ * - `"posts"` - Exact match only
+ * - `"posts/*"` - Children only (posts/1, posts/1/comments) - NOT posts itself
+ * - `["posts", "posts/*"]` - posts AND all children
+ * - `"*"` - Global refetch
+ * - `false` - Disable invalidation
+ * - Any custom string is also allowed for custom tags
+ */
+type InvalidateOption<TSchema = unknown> = "*" | false | InvalidatePattern<TSchema> | (string & {}) | (InvalidatePattern<TSchema> | (string & {}))[];
 interface InvalidationPluginConfig {
     /**
-     * Default invalidation mode when invalidate option is not specified
-     * @default "all"
+     * Enable automatic invalidation for mutations.
+     * When true, mutations automatically invalidate `[firstSegment, firstSegment/*]`.
+     * @default true
+     */
+    autoInvalidate?: boolean;
+    /**
+     * Path groups that should use deeper segment matching for invalidation.
+     * Useful for grouped endpoints like `admin/posts`, `api/v1/users`.
+     *
+     * @example
+     * ```ts
+     * invalidationPlugin({
+     *   groups: ["admin", "api/v1"]
+     * })
+     *
+     * // Without groups:
+     * // POST admin/posts → invalidates ["admin", "admin/*"]
+     *
+     * // With groups: ["admin"]:
+     * // POST admin/posts → invalidates ["admin/posts", "admin/posts/*"]
+     * // POST admin/users → invalidates ["admin/users", "admin/users/*"]
+     * // POST admin → invalidates ["admin", "admin/*"]
+     * ```
      */
-    defaultMode?: InvalidationMode;
+    groups?: string[];
 }
 type InvalidationWriteOptions = object;
 interface InvalidationWriteTriggerOptions<TSchema = unknown> {
-    /** Unified invalidation configuration */
+    /** Unified invalidation configuration with wildcard pattern support */
     invalidate?: InvalidateOption<TSchema>;
 }
 type InvalidationReadOptions = object;
@@ -33,43 +59,43 @@ type InvalidationPagesOptions = object;
 type InvalidationReadResult = object;
 type InvalidationWriteResult = object;
 interface InvalidationQueueTriggerOptions<TSchema = unknown> {
-    /** Unified invalidation configuration */
+    /** Unified invalidation configuration with wildcard pattern support */
     invalidate?: InvalidateOption<TSchema>;
 }
 type InvalidationQueueResult = object;
 /**
- * Manual invalidation - tags only, or "*" for global refetch
+ * Manual invalidation with pattern support
  */
 type InvalidateFn<TSchema> = {
     (tag: "*"): void;
-    (tag: ReadPaths<TSchema> | (string & {})): void;
-    (tags: (ReadPaths<TSchema> | (string & {}))[]): void;
+    (pattern: InvalidatePattern<TSchema> | (string & {})): void;
+    (patterns: (InvalidatePattern<TSchema> | (string & {}))[]): void;
 };
 interface InvalidationInstanceApi {
-    /** Manually invalidate cache entries by tags. Useful for external events like WebSocket messages. */
+    /** Manually invalidate cache entries by patterns. Useful for external events like WebSocket messages. */
     invalidate: InvalidateFn<unknown>;
 }
-interface InvalidationPluginExports {
-    /** Set the default invalidation mode for this mutation */
-    setDefaultMode: (value: InvalidationMode) => void;
+interface InvalidationPluginInternal {
+    /** Disable auto-invalidation for this request. Used by optimistic plugin. */
+    disableAutoInvalidate: () => void;
 }
 declare module "@spoosh/core" {
-    interface PluginExportsRegistry {
-        "spoosh:invalidation": InvalidationPluginExports;
-    }
     interface PluginResolvers<TContext> {
         invalidate: InvalidateOption<TContext["schema"]> | undefined;
     }
-    interface InstanceApiResolvers<TSchema> {
+    interface ApiResolvers<TSchema> {
         invalidate: InvalidateFn<TSchema>;
     }
+    interface PluginInternalRegistry {
+        "spoosh:invalidation": InvalidationPluginInternal;
+    }
 }
 
 /**
  * Enables automatic cache invalidation after mutations.
  *
  * Marks related cache entries as stale and triggers refetches
- * based on tags or explicit invalidation targets.
+ * based on wildcard patterns or explicit invalidation targets.
  *
  * @param config - Plugin configuration
  *
@@ -81,24 +107,24 @@ declare module "@spoosh/core" {
  *
  * const spoosh = new Spoosh<ApiSchema, Error>("/api")
  *   .use([
- *     invalidationPlugin({ defaultMode: "all" }),
+ *     invalidationPlugin({ autoInvalidate: true }),
  *   ]);
  *
  * // Per-mutation invalidation
  * trigger({
- *   invalidate: "self", // Mode only
+ *   invalidate: "posts", // Exact match only
  * });
  *
  * trigger({
- *   invalidate: "posts", // Single tag
+ *   invalidate: "posts/*", // Children only (posts/1, posts/1/comments)
  * });
  *
  * trigger({
- *   invalidate: ["posts", "users"], // Multiple tags
+ *   invalidate: ["posts", "posts/*"], // posts AND all children
  * });
  *
  * trigger({
- *   invalidate: ["all", "posts", "custom-tag"], // Mode + tags
+ *   invalidate: false, // Disable invalidation
  * });
  *
  * trigger({
@@ -115,7 +141,8 @@ declare function invalidationPlugin(config?: InvalidationPluginConfig): _spoosh_
     readResult: InvalidationReadResult;
     writeResult: InvalidationWriteResult;
     queueResult: InvalidationQueueResult;
-    instanceApi: InvalidationInstanceApi;
+    api: InvalidationInstanceApi;
+    internal: InvalidationPluginInternal;
 }>;
 
-export { type InvalidateOption, type InvalidationMode, type InvalidationPagesOptions, type InvalidationPluginConfig, type InvalidationPluginExports, type InvalidationQueueResult, type InvalidationQueueTriggerOptions, type InvalidationReadOptions, type InvalidationReadResult, type InvalidationWriteOptions, type InvalidationWriteResult, type InvalidationWriteTriggerOptions, invalidationPlugin };
+export { type InvalidateFn, type InvalidateOption, type InvalidationInstanceApi, type InvalidationPagesOptions, type InvalidationPluginConfig, type InvalidationPluginInternal, type InvalidationQueueResult, type InvalidationQueueTriggerOptions, type InvalidationReadOptions, type InvalidationReadResult, type InvalidationWriteOptions, type InvalidationWriteResult, type InvalidationWriteTriggerOptions, invalidationPlugin };

package/dist/index.d.ts

@@ -1,31 +1,57 @@
 import * as _spoosh_core from '@spoosh/core';
 
-type InvalidationMode = "all" | "self" | "none";
 /**
  * Extract paths that have GET methods (eligible for invalidation)
+ * Excludes "/" root path to avoid "//*" pattern in autocomplete
  */
 type ReadPaths<TSchema> = {
-    [K in keyof TSchema & string]: "GET" extends keyof TSchema[K] ? K : never;
+    [K in keyof TSchema & string]: "GET" extends keyof TSchema[K] ? K extends "/" | "" ? never : K : never;
 }[keyof TSchema & string];
 /**
- * Unified invalidate option
- * - String: mode only ('all' | 'self' | 'none')
- * - Array: tags only OR [mode keyword mixed with tags]
- *   - If array contains 'all' or 'self' at ANY position, it's treated as mode + tags
- *   - Otherwise, it's tags only with mode defaulting to 'none'
- *   - 'none' keyword should NOT be used in arrays (use string 'none' instead)
+ * Support both exact paths and wildcard patterns in autocomplete
  */
-type InvalidateOption<TSchema = unknown> = InvalidationMode | "*" | ReadPaths<TSchema> | (ReadPaths<TSchema> | "all" | "self" | (string & {}))[];
+type InvalidatePattern<TSchema> = ReadPaths<TSchema> | `${ReadPaths<TSchema>}/*`;
+/**
+ * Unified invalidate option with wildcard pattern support
+ * - `"posts"` - Exact match only
+ * - `"posts/*"` - Children only (posts/1, posts/1/comments) - NOT posts itself
+ * - `["posts", "posts/*"]` - posts AND all children
+ * - `"*"` - Global refetch
+ * - `false` - Disable invalidation
+ * - Any custom string is also allowed for custom tags
+ */
+type InvalidateOption<TSchema = unknown> = "*" | false | InvalidatePattern<TSchema> | (string & {}) | (InvalidatePattern<TSchema> | (string & {}))[];
 interface InvalidationPluginConfig {
     /**
-     * Default invalidation mode when invalidate option is not specified
-     * @default "all"
+     * Enable automatic invalidation for mutations.
+     * When true, mutations automatically invalidate `[firstSegment, firstSegment/*]`.
+     * @default true
+     */
+    autoInvalidate?: boolean;
+    /**
+     * Path groups that should use deeper segment matching for invalidation.
+     * Useful for grouped endpoints like `admin/posts`, `api/v1/users`.
+     *
+     * @example
+     * ```ts
+     * invalidationPlugin({
+     *   groups: ["admin", "api/v1"]
+     * })
+     *
+     * // Without groups:
+     * // POST admin/posts → invalidates ["admin", "admin/*"]
+     *
+     * // With groups: ["admin"]:
+     * // POST admin/posts → invalidates ["admin/posts", "admin/posts/*"]
+     * // POST admin/users → invalidates ["admin/users", "admin/users/*"]
+     * // POST admin → invalidates ["admin", "admin/*"]
+     * ```
      */
-    defaultMode?: InvalidationMode;
+    groups?: string[];
 }
 type InvalidationWriteOptions = object;
 interface InvalidationWriteTriggerOptions<TSchema = unknown> {
-    /** Unified invalidation configuration */
+    /** Unified invalidation configuration with wildcard pattern support */
     invalidate?: InvalidateOption<TSchema>;
 }
 type InvalidationReadOptions = object;
@@ -33,43 +59,43 @@ type InvalidationPagesOptions = object;
 type InvalidationReadResult = object;
 type InvalidationWriteResult = object;
 interface InvalidationQueueTriggerOptions<TSchema = unknown> {
-    /** Unified invalidation configuration */
+    /** Unified invalidation configuration with wildcard pattern support */
     invalidate?: InvalidateOption<TSchema>;
 }
 type InvalidationQueueResult = object;
 /**
- * Manual invalidation - tags only, or "*" for global refetch
+ * Manual invalidation with pattern support
  */
 type InvalidateFn<TSchema> = {
     (tag: "*"): void;
-    (tag: ReadPaths<TSchema> | (string & {})): void;
-    (tags: (ReadPaths<TSchema> | (string & {}))[]): void;
+    (pattern: InvalidatePattern<TSchema> | (string & {})): void;
+    (patterns: (InvalidatePattern<TSchema> | (string & {}))[]): void;
 };
 interface InvalidationInstanceApi {
-    /** Manually invalidate cache entries by tags. Useful for external events like WebSocket messages. */
+    /** Manually invalidate cache entries by patterns. Useful for external events like WebSocket messages. */
     invalidate: InvalidateFn<unknown>;
 }
-interface InvalidationPluginExports {
-    /** Set the default invalidation mode for this mutation */
-    setDefaultMode: (value: InvalidationMode) => void;
+interface InvalidationPluginInternal {
+    /** Disable auto-invalidation for this request. Used by optimistic plugin. */
+    disableAutoInvalidate: () => void;
 }
 declare module "@spoosh/core" {
-    interface PluginExportsRegistry {
-        "spoosh:invalidation": InvalidationPluginExports;
-    }
     interface PluginResolvers<TContext> {
         invalidate: InvalidateOption<TContext["schema"]> | undefined;
     }
-    interface InstanceApiResolvers<TSchema> {
+    interface ApiResolvers<TSchema> {
         invalidate: InvalidateFn<TSchema>;
     }
+    interface PluginInternalRegistry {
+        "spoosh:invalidation": InvalidationPluginInternal;
+    }
 }
 
 /**
  * Enables automatic cache invalidation after mutations.
  *
  * Marks related cache entries as stale and triggers refetches
- * based on tags or explicit invalidation targets.
+ * based on wildcard patterns or explicit invalidation targets.
  *
  * @param config - Plugin configuration
  *
@@ -81,24 +107,24 @@ declare module "@spoosh/core" {
  *
  * const spoosh = new Spoosh<ApiSchema, Error>("/api")
  *   .use([
- *     invalidationPlugin({ defaultMode: "all" }),
+ *     invalidationPlugin({ autoInvalidate: true }),
  *   ]);
  *
  * // Per-mutation invalidation
  * trigger({
- *   invalidate: "self", // Mode only
+ *   invalidate: "posts", // Exact match only
  * });
  *
  * trigger({
- *   invalidate: "posts", // Single tag
+ *   invalidate: "posts/*", // Children only (posts/1, posts/1/comments)
  * });
  *
  * trigger({
- *   invalidate: ["posts", "users"], // Multiple tags
+ *   invalidate: ["posts", "posts/*"], // posts AND all children
  * });
  *
  * trigger({
- *   invalidate: ["all", "posts", "custom-tag"], // Mode + tags
+ *   invalidate: false, // Disable invalidation
  * });
  *
  * trigger({
@@ -115,7 +141,8 @@ declare function invalidationPlugin(config?: InvalidationPluginConfig): _spoosh_
     readResult: InvalidationReadResult;
     writeResult: InvalidationWriteResult;
     queueResult: InvalidationQueueResult;
-    instanceApi: InvalidationInstanceApi;
+    api: InvalidationInstanceApi;
+    internal: InvalidationPluginInternal;
 }>;
 
-export { type InvalidateOption, type InvalidationMode, type InvalidationPagesOptions, type InvalidationPluginConfig, type InvalidationPluginExports, type InvalidationQueueResult, type InvalidationQueueTriggerOptions, type InvalidationReadOptions, type InvalidationReadResult, type InvalidationWriteOptions, type InvalidationWriteResult, type InvalidationWriteTriggerOptions, invalidationPlugin };
+export { type InvalidateFn, type InvalidateOption, type InvalidationInstanceApi, type InvalidationPagesOptions, type InvalidationPluginConfig, type InvalidationPluginInternal, type InvalidationQueueResult, type InvalidationQueueTriggerOptions, type InvalidationReadOptions, type InvalidationReadResult, type InvalidationWriteOptions, type InvalidationWriteResult, type InvalidationWriteTriggerOptions, invalidationPlugin };

package/dist/index.js

@@ -27,96 +27,118 @@ module.exports = __toCommonJS(src_exports);
 // src/plugin.ts
 var import_core = require("@spoosh/core");
 var PLUGIN_NAME = "spoosh:invalidation";
-var INVALIDATION_DEFAULT_KEY = "invalidation:defaultMode";
-function resolveModeTags(context, mode) {
-  const params = context.request.params;
-  switch (mode) {
-    case "all":
-      return context.tags.map((tag) => (0, import_core.resolvePathString)(tag, params));
-    case "self":
-      return [(0, import_core.resolvePathString)(context.path, params)];
-    case "none":
-      return [];
+var AUTO_INVALIDATE_DISABLED_KEY = "invalidation:autoDisabled";
+function calculateSegmentDepth(path, groups) {
+  if (groups.length === 0) return 1;
+  const sortedGroups = [...groups].sort((a, b) => b.length - a.length);
+  for (const group of sortedGroups) {
+    const normalizedGroup = group.replace(/^\/+|\/+$/g, "");
+    if (path === normalizedGroup || path.startsWith(normalizedGroup + "/")) {
+      return normalizedGroup.split("/").length + 1;
+    }
   }
+  return 1;
 }
-function resolveInvalidateTags(context, defaultMode) {
-  const invalidateOption = context.pluginOptions?.invalidate;
-  if (!invalidateOption) {
-    const overrideDefault = context.temp.get(INVALIDATION_DEFAULT_KEY);
-    const effectiveDefault = overrideDefault ?? defaultMode;
-    return resolveModeTags(context, effectiveDefault);
+function resolveInvalidateTags(path, params, invalidateOption, autoInvalidate, groups) {
+  if (invalidateOption === false) {
+    return false;
+  }
+  if (invalidateOption === "*" || invalidateOption === "/*") {
+    return ["*"];
   }
   if (typeof invalidateOption === "string") {
-    if (invalidateOption === "all" || invalidateOption === "self" || invalidateOption === "none") {
-      return resolveModeTags(context, invalidateOption);
+    const normalized = (0, import_core.normalizeTag)(invalidateOption);
+    if (normalized === "*") {
+      return ["*"];
     }
-    return [invalidateOption];
+    return [normalized];
   }
   if (Array.isArray(invalidateOption)) {
-    const tags = [];
-    let mode = "none";
-    for (const item of invalidateOption) {
-      if (item === "all" || item === "self") {
-        mode = item;
-      } else if (typeof item === "string") {
-        tags.push(item);
-      }
-    }
-    tags.push(...resolveModeTags(context, mode));
-    return [...new Set(tags)];
+    return [...new Set(invalidateOption.map(import_core.normalizeTag))];
+  }
+  if (!autoInvalidate) {
+    return false;
+  }
+  const resolvedPath = (0, import_core.normalizeTag)((0, import_core.resolvePathString)(path, params));
+  const segments = resolvedPath.split("/");
+  const depth = calculateSegmentDepth(resolvedPath, groups);
+  const baseSegments = segments.slice(0, depth);
+  if (baseSegments.length === 0 || !baseSegments[0]) {
+    return false;
   }
-  return [];
+  const base = baseSegments.join("/");
+  return [base, `${base}/*`];
 }
 function invalidationPlugin(config = {}) {
-  const { defaultMode = "all" } = config;
+  const { autoInvalidate = true, groups = [] } = config;
   return (0, import_core.createSpooshPlugin)({
     name: PLUGIN_NAME,
     operations: ["write", "queue"],
-    exports(context) {
-      return {
-        setDefaultMode(value) {
-          context.temp.set(INVALIDATION_DEFAULT_KEY, value);
-        }
-      };
-    },
     afterResponse(context, response) {
       const t = context.tracer?.(PLUGIN_NAME);
       if (!response.error) {
-        const tags = resolveInvalidateTags(context, defaultMode);
+        const params = context.request.params;
+        const invalidateOption = context.pluginOptions?.invalidate;
+        const isAutoDisabled = context.temp.get(AUTO_INVALIDATE_DISABLED_KEY);
+        const effectiveAutoInvalidate = isAutoDisabled ? false : autoInvalidate;
+        const tags = resolveInvalidateTags(
+          context.path,
+          params,
+          invalidateOption,
+          effectiveAutoInvalidate,
+          groups
+        );
+        if (tags === false) {
+          t?.skip("Invalidation disabled", { color: "muted" });
+          return;
+        }
         if (tags.includes("*")) {
           t?.log("Refetch all", { color: "warning" });
           context.eventEmitter.emit("refetchAll", void 0);
           return;
         }
         if (tags.length > 0) {
-          t?.log("Invalidated tags", {
+          t?.log("Invalidated patterns", {
             color: "info",
-            info: [{ label: "Tags", value: tags }]
+            info: [{ label: "Patterns", value: tags }]
           });
           context.stateManager.markStale(tags);
           context.eventEmitter.emit("invalidate", tags);
         } else {
-          t?.skip("No tags to invalidate", { color: "muted" });
+          t?.skip("No patterns to invalidate", { color: "muted" });
         }
       }
     },
-    instanceApi(context) {
+    api(context) {
       const { stateManager, eventEmitter } = context;
       const et = context.eventTracer?.(PLUGIN_NAME);
       const invalidate = (input) => {
-        const tags = Array.isArray(input) ? input : [input];
-        if (tags.includes("*")) {
+        const rawPatterns = Array.isArray(input) ? input : [input];
+        if (rawPatterns.includes("*") || rawPatterns.includes("/*")) {
           et?.emit("Refetch all (manual)", { color: "warning" });
           eventEmitter.emit("refetchAll", void 0);
           return;
         }
-        if (tags.length > 0) {
-          et?.emit(`Invalidated: ${tags.join(", ")}`, { color: "info" });
-          stateManager.markStale(tags);
-          eventEmitter.emit("invalidate", tags);
+        const patterns = rawPatterns.map(import_core.normalizeTag);
+        if (patterns.includes("*")) {
+          et?.emit("Refetch all (manual)", { color: "warning" });
+          eventEmitter.emit("refetchAll", void 0);
+          return;
+        }
+        if (patterns.length > 0) {
+          et?.emit(`Invalidated: ${patterns.join(", ")}`, { color: "info" });
+          stateManager.markStale(patterns);
+          eventEmitter.emit("invalidate", patterns);
         }
       };
       return { invalidate };
+    },
+    internal(context) {
+      return {
+        disableAutoInvalidate() {
+          context.temp.set(AUTO_INVALIDATE_DISABLED_KEY, true);
+        }
+      };
     }
   });
 }

package/dist/index.mjs

@@ -1,99 +1,122 @@
 // src/plugin.ts
 import {
   resolvePathString,
-  createSpooshPlugin
+  createSpooshPlugin,
+  normalizeTag
 } from "@spoosh/core";
 var PLUGIN_NAME = "spoosh:invalidation";
-var INVALIDATION_DEFAULT_KEY = "invalidation:defaultMode";
-function resolveModeTags(context, mode) {
-  const params = context.request.params;
-  switch (mode) {
-    case "all":
-      return context.tags.map((tag) => resolvePathString(tag, params));
-    case "self":
-      return [resolvePathString(context.path, params)];
-    case "none":
-      return [];
+var AUTO_INVALIDATE_DISABLED_KEY = "invalidation:autoDisabled";
+function calculateSegmentDepth(path, groups) {
+  if (groups.length === 0) return 1;
+  const sortedGroups = [...groups].sort((a, b) => b.length - a.length);
+  for (const group of sortedGroups) {
+    const normalizedGroup = group.replace(/^\/+|\/+$/g, "");
+    if (path === normalizedGroup || path.startsWith(normalizedGroup + "/")) {
+      return normalizedGroup.split("/").length + 1;
+    }
   }
+  return 1;
 }
-function resolveInvalidateTags(context, defaultMode) {
-  const invalidateOption = context.pluginOptions?.invalidate;
-  if (!invalidateOption) {
-    const overrideDefault = context.temp.get(INVALIDATION_DEFAULT_KEY);
-    const effectiveDefault = overrideDefault ?? defaultMode;
-    return resolveModeTags(context, effectiveDefault);
+function resolveInvalidateTags(path, params, invalidateOption, autoInvalidate, groups) {
+  if (invalidateOption === false) {
+    return false;
+  }
+  if (invalidateOption === "*" || invalidateOption === "/*") {
+    return ["*"];
   }
   if (typeof invalidateOption === "string") {
-    if (invalidateOption === "all" || invalidateOption === "self" || invalidateOption === "none") {
-      return resolveModeTags(context, invalidateOption);
+    const normalized = normalizeTag(invalidateOption);
+    if (normalized === "*") {
+      return ["*"];
     }
-    return [invalidateOption];
+    return [normalized];
   }
   if (Array.isArray(invalidateOption)) {
-    const tags = [];
-    let mode = "none";
-    for (const item of invalidateOption) {
-      if (item === "all" || item === "self") {
-        mode = item;
-      } else if (typeof item === "string") {
-        tags.push(item);
-      }
-    }
-    tags.push(...resolveModeTags(context, mode));
-    return [...new Set(tags)];
+    return [...new Set(invalidateOption.map(normalizeTag))];
+  }
+  if (!autoInvalidate) {
+    return false;
+  }
+  const resolvedPath = normalizeTag(resolvePathString(path, params));
+  const segments = resolvedPath.split("/");
+  const depth = calculateSegmentDepth(resolvedPath, groups);
+  const baseSegments = segments.slice(0, depth);
+  if (baseSegments.length === 0 || !baseSegments[0]) {
+    return false;
   }
-  return [];
+  const base = baseSegments.join("/");
+  return [base, `${base}/*`];
 }
 function invalidationPlugin(config = {}) {
-  const { defaultMode = "all" } = config;
+  const { autoInvalidate = true, groups = [] } = config;
   return createSpooshPlugin({
     name: PLUGIN_NAME,
     operations: ["write", "queue"],
-    exports(context) {
-      return {
-        setDefaultMode(value) {
-          context.temp.set(INVALIDATION_DEFAULT_KEY, value);
-        }
-      };
-    },
     afterResponse(context, response) {
       const t = context.tracer?.(PLUGIN_NAME);
       if (!response.error) {
-        const tags = resolveInvalidateTags(context, defaultMode);
+        const params = context.request.params;
+        const invalidateOption = context.pluginOptions?.invalidate;
+        const isAutoDisabled = context.temp.get(AUTO_INVALIDATE_DISABLED_KEY);
+        const effectiveAutoInvalidate = isAutoDisabled ? false : autoInvalidate;
+        const tags = resolveInvalidateTags(
+          context.path,
+          params,
+          invalidateOption,
+          effectiveAutoInvalidate,
+          groups
+        );
+        if (tags === false) {
+          t?.skip("Invalidation disabled", { color: "muted" });
+          return;
+        }
         if (tags.includes("*")) {
           t?.log("Refetch all", { color: "warning" });
           context.eventEmitter.emit("refetchAll", void 0);
           return;
         }
         if (tags.length > 0) {
-          t?.log("Invalidated tags", {
+          t?.log("Invalidated patterns", {
             color: "info",
-            info: [{ label: "Tags", value: tags }]
+            info: [{ label: "Patterns", value: tags }]
           });
           context.stateManager.markStale(tags);
           context.eventEmitter.emit("invalidate", tags);
         } else {
-          t?.skip("No tags to invalidate", { color: "muted" });
+          t?.skip("No patterns to invalidate", { color: "muted" });
         }
       }
     },
-    instanceApi(context) {
+    api(context) {
       const { stateManager, eventEmitter } = context;
       const et = context.eventTracer?.(PLUGIN_NAME);
       const invalidate = (input) => {
-        const tags = Array.isArray(input) ? input : [input];
-        if (tags.includes("*")) {
+        const rawPatterns = Array.isArray(input) ? input : [input];
+        if (rawPatterns.includes("*") || rawPatterns.includes("/*")) {
           et?.emit("Refetch all (manual)", { color: "warning" });
           eventEmitter.emit("refetchAll", void 0);
           return;
         }
-        if (tags.length > 0) {
-          et?.emit(`Invalidated: ${tags.join(", ")}`, { color: "info" });
-          stateManager.markStale(tags);
-          eventEmitter.emit("invalidate", tags);
+        const patterns = rawPatterns.map(normalizeTag);
+        if (patterns.includes("*")) {
+          et?.emit("Refetch all (manual)", { color: "warning" });
+          eventEmitter.emit("refetchAll", void 0);
+          return;
+        }
+        if (patterns.length > 0) {
+          et?.emit(`Invalidated: ${patterns.join(", ")}`, { color: "info" });
+          stateManager.markStale(patterns);
+          eventEmitter.emit("invalidate", patterns);
         }
       };
       return { invalidate };
+    },
+    internal(context) {
+      return {
+        disableAutoInvalidate() {
+          context.temp.set(AUTO_INVALIDATE_DISABLED_KEY, true);
+        }
+      };
     }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/plugin-invalidation",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Cache invalidation plugin for Spoosh - auto-invalidates after mutations",
   "license": "MIT",
   "repository": {
@@ -33,10 +33,10 @@
     }
   },
   "peerDependencies": {
-    "@spoosh/core": ">=0.15.0"
+    "@spoosh/core": ">=0.18.0"
   },
   "devDependencies": {
-    "@spoosh/core": "0.15.1",
+    "@spoosh/core": "0.18.0",
     "@spoosh/test-utils": "0.3.0"
   },
   "scripts": {
@@ -44,6 +44,6 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src --max-warnings 0",
-    "format": "prettier --write 'src/**/*.ts'"
+    "format": "prettier --write 'src/**/*.ts' '*.md'"
   }
 }