@smartive/datocms-utils 3.0.0-next.11 → 3.0.0-next.13

package/README.md

@@ -53,7 +53,7 @@ const tags = parseXCacheTagsResponseHeader('tag-a tag-2 other-tag');
 
 #### Storage Providers
 
-The package provides two storage backends for cache tags: **Neon (Postgres)** and **Redis**. Both implement the same `CacheTagsProvider` interface.
+The package provides multiple storage backends for cache tags: **Neon (Postgres)**, **Redis**, and **Noop**. All implement the same `CacheTagsProvider` interface, with the Noop provider being especially useful for testing and development.
 
 ##### Neon (Postgres) Provider
 
@@ -163,7 +163,7 @@ const provider = new RedisCacheTagsProvider({
 });
 
 // After making a DatoCMS query
-const queryId = generateQueryId(query, variables);
+const queryId = generateQueryId(document, variables);
 const cacheTags = parseXCacheTagsResponseHeader(response.headers['x-cache-tags']);
 await provider.storeQueryCacheTags(queryId, cacheTags);
 

package/dist/cache-tags/provider/base.d.ts

@@ -0,0 +1,15 @@
+import type { CacheTag, CacheTagsProvider, CacheTagsProviderErrorHandlingConfig } from '../types.js';
+/**
+ * An abstract base class for `CacheTagsProvider` implementations that adds error handling and logging.
+ */
+export declare abstract class AbstractErrorHandlingCacheTagsProvider implements CacheTagsProvider {
+    protected readonly providerName: string;
+    protected readonly throwOnError: boolean;
+    protected readonly onError?: CacheTagsProviderErrorHandlingConfig['onError'];
+    protected constructor(providerName: string, config?: CacheTagsProviderErrorHandlingConfig);
+    abstract storeQueryCacheTags(queryId: string, cacheTags: CacheTag[]): Promise<void>;
+    abstract queriesReferencingCacheTags(cacheTags: CacheTag[]): Promise<string[]>;
+    abstract deleteCacheTags(cacheTags: CacheTag[]): Promise<number>;
+    abstract truncateCacheTags(): Promise<number>;
+    protected wrap<T>(method: keyof CacheTagsProvider, args: unknown[], fn: () => Promise<T>, fallback: T): Promise<T>;
+}

package/dist/cache-tags/provider/base.js

@@ -0,0 +1,35 @@
+/**
+ * An abstract base class for `CacheTagsProvider` implementations that adds error handling and logging.
+ */
+export class AbstractErrorHandlingCacheTagsProvider {
+    providerName;
+    throwOnError;
+    onError;
+    constructor(providerName, config = {}) {
+        this.providerName = providerName;
+        this.throwOnError = config.throwOnError ?? true;
+        this.onError = config.onError;
+    }
+    async wrap(method, args, fn, fallback) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const provider = this.providerName;
+            // Call onError callback if provided, but guard against exceptions
+            // to prevent masking the original provider error
+            try {
+                this.onError?.(error, { provider, method, args });
+            }
+            catch (handlerError) {
+                console.error(`Error handler itself failed in ${provider}.${method}.`, { handlerError });
+            }
+            if (this.throwOnError) {
+                throw error;
+            }
+            console.debug(`Error occurred in ${provider}.${method}.`, { error, args });
+            return fallback;
+        }
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/cache-tags/provider/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/cache-tags/provider/base.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAgB,sCAAsC;IAKrC;IAJF,YAAY,CAAU;IACtB,OAAO,CAAmD;IAE7E,YACqB,YAAoB,EACvC,SAA+C,EAAE;QAD9B,iBAAY,GAAZ,YAAY,CAAQ;QAGvC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC;QAChD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAChC,CAAC;IAUS,KAAK,CAAC,IAAI,CAAI,MAA+B,EAAE,IAAe,EAAE,EAAoB,EAAE,QAAW;QACzG,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC;YAEnC,kEAAkE;YAClE,iDAAiD;YACjD,IAAI,CAAC;gBACH,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YACpD,CAAC;YAAC,OAAO,YAAY,EAAE,CAAC;gBACtB,OAAO,CAAC,KAAK,CAAC,kCAAkC,QAAQ,IAAI,MAAM,GAAG,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;YAC3F,CAAC;YAED,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACtB,MAAM,KAAK,CAAC;YACd,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,qBAAqB,QAAQ,IAAI,MAAM,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAE3E,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;CACF"}

package/dist/cache-tags/provider/neon.d.ts

@@ -1,5 +1,6 @@
-import { type CacheTag, type CacheTagsProvider } from '../types.js';
-type NeonCacheTagsProviderConfig = {
+import type { CacheTag, CacheTagsProvider, CacheTagsProviderErrorHandlingConfig } from '../types.js';
+import { AbstractErrorHandlingCacheTagsProvider } from './base.js';
+type NeonCacheTagsProviderBaseConfig = {
     /**
      * Neon connection string. You can find it in the "Connection" tab of your Neon project dashboard.
      * Has the format `postgresql://user:pass@host/db`
@@ -18,14 +19,15 @@ type NeonCacheTagsProviderConfig = {
      */
     readonly table: string;
 };
+export type NeonCacheTagsProviderConfig = NeonCacheTagsProviderBaseConfig & CacheTagsProviderErrorHandlingConfig;
 /**
  * A `CacheTagsProvider` implementation that uses Neon as the storage backend.
  */
-export declare class NeonCacheTagsProvider implements CacheTagsProvider {
+export declare class NeonCacheTagsProvider extends AbstractErrorHandlingCacheTagsProvider implements CacheTagsProvider {
     private readonly sql;
     private readonly table;
-    constructor({ connectionUrl, table }: NeonCacheTagsProviderConfig);
-    storeQueryCacheTags(queryId: string, cacheTags: CacheTag[]): Promise<void>;
+    constructor({ connectionUrl, table, throwOnError, onError }: NeonCacheTagsProviderConfig);
+    storeQueryCacheTags(queryId: string, cacheTags: CacheTag[]): Promise<void | undefined>;
     queriesReferencingCacheTags(cacheTags: CacheTag[]): Promise<string[]>;
     deleteCacheTags(cacheTags: CacheTag[]): Promise<number>;
     truncateCacheTags(): Promise<number>;

package/dist/cache-tags/provider/neon.js

@@ -1,44 +1,54 @@
 import { neon } from '@neondatabase/serverless';
+import { AbstractErrorHandlingCacheTagsProvider } from './base.js';
 /**
  * A `CacheTagsProvider` implementation that uses Neon as the storage backend.
  */
-export class NeonCacheTagsProvider {
+export class NeonCacheTagsProvider extends AbstractErrorHandlingCacheTagsProvider {
     sql;
     table;
-    constructor({ connectionUrl, table }) {
+    constructor({ connectionUrl, table, throwOnError, onError }) {
+        super('NeonCacheTagsProvider', { throwOnError, onError });
         this.sql = neon(connectionUrl, { fullResults: true });
         this.table = NeonCacheTagsProvider.quoteIdentifier(table);
     }
     async storeQueryCacheTags(queryId, cacheTags) {
-        if (!cacheTags?.length) {
-            return;
-        }
-        const tags = cacheTags.flatMap((_, i) => [queryId, cacheTags[i]]);
-        const placeholders = cacheTags.map((_, i) => `($${2 * i + 1}, $${2 * i + 2})`).join(',');
-        await this.sql.query(`INSERT INTO ${this.table} VALUES ${placeholders} ON CONFLICT DO NOTHING`, tags);
+        return this.wrap('storeQueryCacheTags', [queryId, cacheTags], async () => {
+            if (!cacheTags?.length) {
+                return;
+            }
+            const tags = cacheTags.flatMap((_, i) => [queryId, cacheTags[i]]);
+            const placeholders = cacheTags.map((_, i) => `($${2 * i + 1}, $${2 * i + 2})`).join(',');
+            await this.sql.query(`INSERT INTO ${this.table} VALUES ${placeholders} ON CONFLICT DO NOTHING`, tags);
+        }, undefined);
     }
     async queriesReferencingCacheTags(cacheTags) {
-        if (!cacheTags?.length) {
-            return [];
-        }
-        const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
-        const { rows } = await this.sql.query(`SELECT DISTINCT query_id FROM ${this.table} WHERE cache_tag IN (${placeholders})`, cacheTags);
-        return rows.reduce((queryIds, row) => {
-            if (typeof row.query_id === 'string') {
-                queryIds.push(row.query_id);
+        return this.wrap('queriesReferencingCacheTags', [cacheTags], async () => {
+            if (!cacheTags?.length) {
+                return [];
             }
-            return queryIds;
+            const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
+            const { rows } = await this.sql.query(`SELECT DISTINCT query_id FROM ${this.table} WHERE cache_tag IN (${placeholders})`, cacheTags);
+            return rows.reduce((queryIds, row) => {
+                if (typeof row.query_id === 'string') {
+                    queryIds.push(row.query_id);
+                }
+                return queryIds;
+            }, []);
         }, []);
     }
     async deleteCacheTags(cacheTags) {
-        if (!cacheTags?.length) {
-            return 0;
-        }
-        const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
-        return (await this.sql.query(`DELETE FROM ${this.table} WHERE cache_tag IN (${placeholders})`, cacheTags)).rowCount ?? 0;
+        return this.wrap('deleteCacheTags', [cacheTags], async () => {
+            if (!cacheTags?.length) {
+                return 0;
+            }
+            const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
+            return ((await this.sql.query(`DELETE FROM ${this.table} WHERE cache_tag IN (${placeholders})`, cacheTags)).rowCount ?? 0);
+        }, 0);
     }
     async truncateCacheTags() {
-        return (await this.sql.query(`DELETE FROM ${this.table}`)).rowCount ?? 0;
+        return this.wrap('truncateCacheTags', [], async () => {
+            return (await this.sql.query(`DELETE FROM ${this.table}`)).rowCount ?? 0;
+        }, 0);
     }
     /**
      * Validates and quotes a PostgreSQL identifier (table name, column name, etc.) to prevent SQL injection.
@@ -47,9 +57,6 @@ export class NeonCacheTagsProvider {
      * @throws Error if the identifier is invalid
      */
     static quoteIdentifier(identifier) {
-        // Validate that the identifier contains only valid characters
-        // PostgreSQL identifiers can contain letters, digits, underscores, and dollar signs
-        // They can also contain dots for schema-qualified names
         if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)?$/.test(identifier)) {
             throw new Error(`Invalid table name: ${identifier}. Table names must start with a letter, underscore, or dollar sign and contain only letters, digits, underscores, and dollar signs. Schema-qualified names (e.g., "schema.table") are supported.`);
         }

package/dist/cache-tags/provider/neon.js.map

@@ -1 +1 @@
-{"version":3,"file":"neon.js","sourceRoot":"","sources":["../../../src/cache-tags/provider/neon.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"neon.js","sourceRoot":"","sources":["../../../src/cache-tags/provider/neon.ts"],"names":[],"mappings":"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"}

package/dist/cache-tags/provider/redis.d.ts

@@ -1,5 +1,6 @@
-import { type CacheTag, type CacheTagsProvider } from '../types.js';
-type RedisCacheTagsProviderConfig = {
+import type { CacheTag, CacheTagsProvider, CacheTagsProviderErrorHandlingConfig } from '../types.js';
+import { AbstractErrorHandlingCacheTagsProvider } from './base.js';
+type RedisCacheTagsProviderBaseConfig = {
     /**
      * Redis connection string. For example, `redis://user:pass@host:port/db`.
      */
@@ -11,14 +12,15 @@ type RedisCacheTagsProviderConfig = {
      */
     readonly keyPrefix?: string;
 };
+export type RedisCacheTagsProviderConfig = RedisCacheTagsProviderBaseConfig & CacheTagsProviderErrorHandlingConfig;
 /**
  * A `CacheTagsProvider` implementation that uses Redis as the storage backend.
  */
-export declare class RedisCacheTagsProvider implements CacheTagsProvider {
+export declare class RedisCacheTagsProvider extends AbstractErrorHandlingCacheTagsProvider implements CacheTagsProvider {
     private readonly redis;
     private readonly keyPrefix;
-    constructor({ connectionUrl, keyPrefix }: RedisCacheTagsProviderConfig);
-    storeQueryCacheTags(queryId: string, cacheTags: CacheTag[]): Promise<void>;
+    constructor({ connectionUrl, keyPrefix, throwOnError, onError }: RedisCacheTagsProviderConfig);
+    storeQueryCacheTags(queryId: string, cacheTags: CacheTag[]): Promise<void | undefined>;
     queriesReferencingCacheTags(cacheTags: CacheTag[]): Promise<string[]>;
     deleteCacheTags(cacheTags: CacheTag[]): Promise<number>;
     truncateCacheTags(): Promise<number>;

package/dist/cache-tags/provider/redis.js

@@ -1,11 +1,13 @@
 import { Redis } from 'ioredis';
+import { AbstractErrorHandlingCacheTagsProvider } from './base.js';
 /**
  * A `CacheTagsProvider` implementation that uses Redis as the storage backend.
  */
-export class RedisCacheTagsProvider {
+export class RedisCacheTagsProvider extends AbstractErrorHandlingCacheTagsProvider {
     redis;
     keyPrefix;
-    constructor({ connectionUrl, keyPrefix }) {
+    constructor({ connectionUrl, keyPrefix, throwOnError, onError }) {
+        super('RedisCacheTagsProvider', { throwOnError, onError });
         this.redis = new Redis(connectionUrl, {
             maxRetriesPerRequest: 3,
             lazyConnect: true,
@@ -13,35 +15,47 @@ export class RedisCacheTagsProvider {
         this.keyPrefix = keyPrefix ?? '';
     }
     async storeQueryCacheTags(queryId, cacheTags) {
-        if (!cacheTags?.length) {
-            return;
-        }
-        const pipeline = this.redis.pipeline();
-        for (const tag of cacheTags) {
-            pipeline.sadd(`${this.keyPrefix}${tag}`, queryId);
-        }
-        await pipeline.exec();
+        return this.wrap('storeQueryCacheTags', [queryId, cacheTags], async () => {
+            if (!cacheTags?.length) {
+                return;
+            }
+            const pipeline = this.redis.pipeline();
+            for (const tag of cacheTags) {
+                pipeline.sadd(`${this.keyPrefix}${tag}`, queryId);
+            }
+            const results = await pipeline.exec();
+            const error = results?.find(([err]) => err)?.[0];
+            if (error) {
+                throw error;
+            }
+        }, undefined);
     }
     async queriesReferencingCacheTags(cacheTags) {
-        if (!cacheTags?.length) {
-            return [];
-        }
-        const keys = cacheTags.map((tag) => `${this.keyPrefix}${tag}`);
-        return this.redis.sunion(...keys);
+        return this.wrap('queriesReferencingCacheTags', [cacheTags], async () => {
+            if (!cacheTags?.length) {
+                return [];
+            }
+            const keys = cacheTags.map((tag) => `${this.keyPrefix}${tag}`);
+            return this.redis.sunion(...keys);
+        }, []);
     }
     async deleteCacheTags(cacheTags) {
-        if (!cacheTags?.length) {
-            return 0;
-        }
-        const keys = cacheTags.map((tag) => `${this.keyPrefix}${tag}`);
-        return this.redis.del(...keys);
+        return this.wrap('deleteCacheTags', [cacheTags], async () => {
+            if (!cacheTags?.length) {
+                return 0;
+            }
+            const keys = cacheTags.map((tag) => `${this.keyPrefix}${tag}`);
+            return this.redis.del(...keys);
+        }, 0);
     }
     async truncateCacheTags() {
-        const keys = await this.getKeys();
-        if (keys.length === 0) {
-            return 0;
-        }
-        return await this.redis.del(...keys);
+        return this.wrap('truncateCacheTags', [], async () => {
+            const keys = await this.getKeys();
+            if (keys.length === 0) {
+                return 0;
+            }
+            return await this.redis.del(...keys);
+        }, 0);
     }
     /**
      * Retrieves all keys matching the given pattern using the Redis SCAN command.

package/dist/cache-tags/provider/redis.js.map

@@ -1 +1 @@
-{"version":3,"file":"redis.js","sourceRoot":"","sources":["../../../src/cache-tags/provider/redis.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"redis.js","sourceRoot":"","sources":["../../../src/cache-tags/provider/redis.ts"],"names":[],"mappings":"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"}

package/dist/cache-tags/types.d.ts

@@ -61,3 +61,22 @@ export interface CacheTagsProvider {
      */
     truncateCacheTags(): Promise<number>;
 }
+export type CacheTagsProviderErrorHandlingConfig = {
+    /**
+     * If false, errors are suppressed and a fallback value is returned.
+     * Default: true
+     */
+    throwOnError?: boolean;
+    /**
+     * Optional callback invoked when an error occurs in a `CacheTagsProvider` method,
+     * useful for logging and telemetry.
+     *
+     * Called before the error is either thrown (when `throwOnError` is true or
+     * undefined) or suppressed (when `throwOnError` is false).
+     */
+    onError?: (error: unknown, ctx: {
+        provider: string;
+        method: keyof CacheTagsProvider;
+        args: unknown[];
+    }) => void;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartive/datocms-utils",
-  "version": "3.0.0-next.11",
+  "version": "3.0.0-next.13",
   "description": "A set of utilities and helpers to work with DatoCMS in a Next.js project.",
   "type": "module",
   "source": "./src/index.ts",

package/src/cache-tags/provider/base.ts

@@ -0,0 +1,48 @@
+import type { CacheTag, CacheTagsProvider, CacheTagsProviderErrorHandlingConfig } from '../types.js';
+
+/**
+ * An abstract base class for `CacheTagsProvider` implementations that adds error handling and logging.
+ */
+export abstract class AbstractErrorHandlingCacheTagsProvider implements CacheTagsProvider {
+  protected readonly throwOnError: boolean;
+  protected readonly onError?: CacheTagsProviderErrorHandlingConfig['onError'];
+
+  protected constructor(
+    protected readonly providerName: string,
+    config: CacheTagsProviderErrorHandlingConfig = {},
+  ) {
+    this.throwOnError = config.throwOnError ?? true;
+    this.onError = config.onError;
+  }
+
+  public abstract storeQueryCacheTags(queryId: string, cacheTags: CacheTag[]): Promise<void>;
+
+  public abstract queriesReferencingCacheTags(cacheTags: CacheTag[]): Promise<string[]>;
+
+  public abstract deleteCacheTags(cacheTags: CacheTag[]): Promise<number>;
+
+  public abstract truncateCacheTags(): Promise<number>;
+
+  protected async wrap<T>(method: keyof CacheTagsProvider, args: unknown[], fn: () => Promise<T>, fallback: T): Promise<T> {
+    try {
+      return await fn();
+    } catch (error) {
+      const provider = this.providerName;
+
+      // Call onError callback if provided, but guard against exceptions
+      // to prevent masking the original provider error
+      try {
+        this.onError?.(error, { provider, method, args });
+      } catch (handlerError) {
+        console.error(`Error handler itself failed in ${provider}.${method}.`, { handlerError });
+      }
+
+      if (this.throwOnError) {
+        throw error;
+      }
+      console.debug(`Error occurred in ${provider}.${method}.`, { error, args });
+
+      return fallback;
+    }
+  }
+}

package/src/cache-tags/provider/neon.ts

@@ -1,7 +1,8 @@
 import { neon } from '@neondatabase/serverless';
-import { type CacheTag, type CacheTagsProvider } from '../types.js';
+import type { CacheTag, CacheTagsProvider, CacheTagsProviderErrorHandlingConfig } from '../types.js';
+import { AbstractErrorHandlingCacheTagsProvider } from './base.js';
 
-type NeonCacheTagsProviderConfig = {
+type NeonCacheTagsProviderBaseConfig = {
   /**
    * Neon connection string. You can find it in the "Connection" tab of your Neon project dashboard.
    * Has the format `postgresql://user:pass@host/db`
@@ -21,61 +22,94 @@ type NeonCacheTagsProviderConfig = {
   readonly table: string;
 };
 
+export type NeonCacheTagsProviderConfig = NeonCacheTagsProviderBaseConfig & CacheTagsProviderErrorHandlingConfig;
+
 /**
  * A `CacheTagsProvider` implementation that uses Neon as the storage backend.
  */
-export class NeonCacheTagsProvider implements CacheTagsProvider {
+export class NeonCacheTagsProvider extends AbstractErrorHandlingCacheTagsProvider implements CacheTagsProvider {
   private readonly sql;
   private readonly table;
 
-  constructor({ connectionUrl, table }: NeonCacheTagsProviderConfig) {
+  constructor({ connectionUrl, table, throwOnError, onError }: NeonCacheTagsProviderConfig) {
+    super('NeonCacheTagsProvider', { throwOnError, onError });
     this.sql = neon(connectionUrl, { fullResults: true });
     this.table = NeonCacheTagsProvider.quoteIdentifier(table);
   }
 
   public async storeQueryCacheTags(queryId: string, cacheTags: CacheTag[]) {
-    if (!cacheTags?.length) {
-      return;
-    }
-
-    const tags = cacheTags.flatMap((_, i) => [queryId, cacheTags[i]]);
-    const placeholders = cacheTags.map((_, i) => `($${2 * i + 1}, $${2 * i + 2})`).join(',');
-
-    await this.sql.query(`INSERT INTO ${this.table} VALUES ${placeholders} ON CONFLICT DO NOTHING`, tags);
+    return this.wrap(
+      'storeQueryCacheTags',
+      [queryId, cacheTags],
+      async () => {
+        if (!cacheTags?.length) {
+          return;
+        }
+
+        const tags = cacheTags.flatMap((_, i) => [queryId, cacheTags[i]]);
+        const placeholders = cacheTags.map((_, i) => `($${2 * i + 1}, $${2 * i + 2})`).join(',');
+
+        await this.sql.query(`INSERT INTO ${this.table} VALUES ${placeholders} ON CONFLICT DO NOTHING`, tags);
+      },
+      undefined,
+    );
   }
 
   public async queriesReferencingCacheTags(cacheTags: CacheTag[]): Promise<string[]> {
-    if (!cacheTags?.length) {
-      return [];
-    }
-
-    const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
-
-    const { rows } = await this.sql.query(
-      `SELECT DISTINCT query_id FROM ${this.table} WHERE cache_tag IN (${placeholders})`,
-      cacheTags,
+    return this.wrap(
+      'queriesReferencingCacheTags',
+      [cacheTags],
+      async () => {
+        if (!cacheTags?.length) {
+          return [];
+        }
+
+        const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
+
+        const { rows } = await this.sql.query(
+          `SELECT DISTINCT query_id FROM ${this.table} WHERE cache_tag IN (${placeholders})`,
+          cacheTags,
+        );
+
+        return rows.reduce<string[]>((queryIds, row) => {
+          if (typeof row.query_id === 'string') {
+            queryIds.push(row.query_id);
+          }
+
+          return queryIds;
+        }, []);
+      },
+      [],
     );
-
-    return rows.reduce<string[]>((queryIds, row) => {
-      if (typeof row.query_id === 'string') {
-        queryIds.push(row.query_id);
-      }
-
-      return queryIds;
-    }, []);
   }
 
   public async deleteCacheTags(cacheTags: CacheTag[]) {
-    if (!cacheTags?.length) {
-      return 0;
-    }
-    const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
-
-    return (await this.sql.query(`DELETE FROM ${this.table} WHERE cache_tag IN (${placeholders})`, cacheTags)).rowCount ?? 0;
+    return this.wrap(
+      'deleteCacheTags',
+      [cacheTags],
+      async () => {
+        if (!cacheTags?.length) {
+          return 0;
+        }
+        const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
+
+        return (
+          (await this.sql.query(`DELETE FROM ${this.table} WHERE cache_tag IN (${placeholders})`, cacheTags)).rowCount ?? 0
+        );
+      },
+      0,
+    );
   }
 
   public async truncateCacheTags() {
-    return (await this.sql.query(`DELETE FROM ${this.table}`)).rowCount ?? 0;
+    return this.wrap(
+      'truncateCacheTags',
+      [],
+      async () => {
+        return (await this.sql.query(`DELETE FROM ${this.table}`)).rowCount ?? 0;
+      },
+      0,
+    );
   }
 
   /**
@@ -85,9 +119,6 @@ export class NeonCacheTagsProvider implements CacheTagsProvider {
    * @throws Error if the identifier is invalid
    */
   private static quoteIdentifier(identifier: string): string {
-    // Validate that the identifier contains only valid characters
-    // PostgreSQL identifiers can contain letters, digits, underscores, and dollar signs
-    // They can also contain dots for schema-qualified names
     if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)?$/.test(identifier)) {
       throw new Error(
         `Invalid table name: ${identifier}. Table names must start with a letter, underscore, or dollar sign and contain only letters, digits, underscores, and dollar signs. Schema-qualified names (e.g., "schema.table") are supported.`,

package/src/cache-tags/provider/redis.ts

@@ -1,7 +1,8 @@
 import { Redis } from 'ioredis';
-import { type CacheTag, type CacheTagsProvider } from '../types.js';
+import type { CacheTag, CacheTagsProvider, CacheTagsProviderErrorHandlingConfig } from '../types.js';
+import { AbstractErrorHandlingCacheTagsProvider } from './base.js';
 
-type RedisCacheTagsProviderConfig = {
+type RedisCacheTagsProviderBaseConfig = {
   /**
    * Redis connection string. For example, `redis://user:pass@host:port/db`.
    */
@@ -14,14 +15,17 @@ type RedisCacheTagsProviderConfig = {
   readonly keyPrefix?: string;
 };
 
+export type RedisCacheTagsProviderConfig = RedisCacheTagsProviderBaseConfig & CacheTagsProviderErrorHandlingConfig;
+
 /**
  * A `CacheTagsProvider` implementation that uses Redis as the storage backend.
  */
-export class RedisCacheTagsProvider implements CacheTagsProvider {
+export class RedisCacheTagsProvider extends AbstractErrorHandlingCacheTagsProvider implements CacheTagsProvider {
   private readonly redis;
   private readonly keyPrefix;
 
-  constructor({ connectionUrl, keyPrefix }: RedisCacheTagsProviderConfig) {
+  constructor({ connectionUrl, keyPrefix, throwOnError, onError }: RedisCacheTagsProviderConfig) {
+    super('RedisCacheTagsProvider', { throwOnError, onError });
     this.redis = new Redis(connectionUrl, {
       maxRetriesPerRequest: 3,
       lazyConnect: true,
@@ -30,47 +34,79 @@ export class RedisCacheTagsProvider implements CacheTagsProvider {
   }
 
   public async storeQueryCacheTags(queryId: string, cacheTags: CacheTag[]) {
-    if (!cacheTags?.length) {
-      return;
-    }
-
-    const pipeline = this.redis.pipeline();
-
-    for (const tag of cacheTags) {
-      pipeline.sadd(`${this.keyPrefix}${tag}`, queryId);
-    }
-
-    await pipeline.exec();
+    return this.wrap(
+      'storeQueryCacheTags',
+      [queryId, cacheTags],
+      async () => {
+        if (!cacheTags?.length) {
+          return;
+        }
+
+        const pipeline = this.redis.pipeline();
+
+        for (const tag of cacheTags) {
+          pipeline.sadd(`${this.keyPrefix}${tag}`, queryId);
+        }
+
+        const results = await pipeline.exec();
+        const error = results?.find(([err]) => err)?.[0];
+        if (error) {
+          throw error;
+        }
+      },
+      undefined,
+    );
   }
 
   public async queriesReferencingCacheTags(cacheTags: CacheTag[]) {
-    if (!cacheTags?.length) {
-      return [];
-    }
-
-    const keys = cacheTags.map((tag) => `${this.keyPrefix}${tag}`);
-
-    return this.redis.sunion(...keys);
+    return this.wrap(
+      'queriesReferencingCacheTags',
+      [cacheTags],
+      async () => {
+        if (!cacheTags?.length) {
+          return [];
+        }
+
+        const keys = cacheTags.map((tag) => `${this.keyPrefix}${tag}`);
+
+        return this.redis.sunion(...keys);
+      },
+      [],
+    );
   }
 
   public async deleteCacheTags(cacheTags: CacheTag[]) {
-    if (!cacheTags?.length) {
-      return 0;
-    }
-
-    const keys = cacheTags.map((tag) => `${this.keyPrefix}${tag}`);
-
-    return this.redis.del(...keys);
+    return this.wrap(
+      'deleteCacheTags',
+      [cacheTags],
+      async () => {
+        if (!cacheTags?.length) {
+          return 0;
+        }
+
+        const keys = cacheTags.map((tag) => `${this.keyPrefix}${tag}`);
+
+        return this.redis.del(...keys);
+      },
+      0,
+    );
   }
 
   public async truncateCacheTags() {
-    const keys = await this.getKeys();
-
-    if (keys.length === 0) {
-      return 0;
-    }
-
-    return await this.redis.del(...keys);
+    return this.wrap(
+      'truncateCacheTags',
+      [],
+      async () => {
+        const keys = await this.getKeys();
+
+        if (keys.length === 0) {
+          return 0;
+        }
+
+        return await this.redis.del(...keys);
+      },
+      0,
+    );
   }
 
   /**

package/src/cache-tags/types.ts

@@ -64,3 +64,20 @@ export interface CacheTagsProvider {
    */
   truncateCacheTags(): Promise<number>;
 }
+
+export type CacheTagsProviderErrorHandlingConfig = {
+  /**
+   * If false, errors are suppressed and a fallback value is returned.
+   * Default: true
+   */
+  throwOnError?: boolean;
+
+  /**
+   * Optional callback invoked when an error occurs in a `CacheTagsProvider` method,
+   * useful for logging and telemetry.
+   *
+   * Called before the error is either thrown (when `throwOnError` is true or
+   * undefined) or suppressed (when `throwOnError` is false).
+   */
+  onError?: (error: unknown, ctx: { provider: string; method: keyof CacheTagsProvider; args: unknown[] }) => void;
+};