@smartive/datocms-utils 3.0.0-next.9 → 3.1.0

package/README.md

@@ -14,13 +14,13 @@ npm install @smartive/datocms-utils
 
 #### `classNames`
 
-Cleans and joins an array of class names, filtering out undefined and boolean values.
+Cleans and joins an array of class names (strings and numbers), filtering out undefined and boolean values.
 
 ```typescript
 import { classNames } from '@smartive/datocms-utils';
 
-const className = classNames('btn', isActive && 'btn-active', undefined, 'btn-primary');
-// Result: "btn btn-active btn-primary"
+const className = classNames('btn', isActive && 'btn-active', 42, undefined, 'btn-primary');
+// Result: "btn btn-active 42 btn-primary"
 ```
 
 #### `getTelLink`
@@ -41,10 +41,10 @@ Utilities for managing [DatoCMS cache tags](https://www.datocms.com/docs/content
 #### Core Utilities
 
 ```typescript
-import { generateQueryId, parseXCacheTagsResponseHeader } from '@smartive/datocms-utils/cache';
+import { generateQueryId, parseXCacheTagsResponseHeader } from '@smartive/datocms-utils/cache-tags';
 
 // Generate a unique ID for a GraphQL query
-const queryId = generateQueryId(document, variables);
+const queryId = generateQueryId(document, variables, headers);
 
 // Parse DatoCMS's X-Cache-Tags header
 const tags = parseXCacheTagsResponseHeader('tag-a tag-2 other-tag');
@@ -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
 
@@ -83,8 +83,12 @@ npm install @neondatabase/serverless
 import { NeonCacheTagsProvider } from '@smartive/datocms-utils/cache-tags/neon';
 
 const provider = new NeonCacheTagsProvider({
-  connectionString: process.env.DATABASE_URL!,
+  connectionUrl: process.env.DATABASE_URL!,
   table: 'query_cache_tags',
+  throwOnError: false,  // Optional: Disable error throwing, defaults to `true`
+  onError(error, ctx) { // Optional: Custom error callback
+    console.error('CacheTagsProvider error', { error, context: ctx });
+  },
 });
 
 // Store cache tags for a query
@@ -118,13 +122,14 @@ npm install ioredis
 import { RedisCacheTagsProvider } from '@smartive/datocms-utils/cache-tags/redis';
 
 const provider = new RedisCacheTagsProvider({
-  url: process.env.REDIS_URL!,
+  connectionUrl: process.env.REDIS_URL!,
   keyPrefix: 'prod:', // Optional: namespace for multi-environment setups
+  throwOnError: process.env.NODE_ENV === 'development', // Optional: Disable error throwing in production - defaults to `true`
 });
 
 // Same API as Neon provider
 await provider.storeQueryCacheTags(queryId, ['item:42', 'product']);
-const queries = await store.queriesReferencingCacheTags(['item:42']);
+const queries = await provider.queriesReferencingCacheTags(['item:42']);
 await provider.deleteCacheTags(['item:42']);
 await provider.truncateCacheTags();
 ```
@@ -154,16 +159,16 @@ Both providers implement:
 ### Complete Example
 
 ```typescript
-import { generateQueryId, parseXCacheTagsResponseHeader } from '@smartive/datocms-utils/cache';
+import { generateQueryId, parseXCacheTagsResponseHeader } from '@smartive/datocms-utils/cache-tags';
 import { RedisCacheTagsProvider } from '@smartive/datocms-utils/cache-tags/redis';
 
 const provider = new RedisCacheTagsProvider({
-  url: process.env.REDIS_URL!,
+  connectionUrl: process.env.REDIS_URL!,
   keyPrefix: 'myapp:',
 });
 
 // After making a DatoCMS query
-const queryId = generateQueryId(query, variables);
+const queryId = generateQueryId(document, variables, request.headers);
 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.warn(`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,IAAI,CAAC,qBAAqB,QAAQ,IAAI,MAAM,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAE1E,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,16 +19,24 @@ 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>;
+    /**
+     * Validates and quotes a PostgreSQL identifier (table name, column name, etc.) to prevent SQL injection.
+     * @param identifier The identifier to validate and quote
+     * @returns The properly quoted identifier
+     * @throws Error if the identifier is invalid
+     */
+    private static quoteIdentifier;
 }
 export {};

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

@@ -1,44 +1,72 @@
 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 = table;
+        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 === 0) {
-            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.
+     * @param identifier The identifier to validate and quote
+     * @returns The properly quoted identifier
+     * @throws Error if the identifier is invalid
+     */
+    static quoteIdentifier(identifier) {
+        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.`);
+        }
+        // Quote the identifier using double quotes to prevent SQL injection
+        // Handle schema-qualified names (e.g., "schema.table")
+        // Escape any double quotes within the identifier by doubling them
+        return identifier
+            .split('.')
+            .map((part) => `"${part.replace(/"/g, '""')}"`)
+            .join('.');
     }
 }
 //# sourceMappingURL=neon.js.map

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":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAuBhD;;GAEG;AACH,MAAM,OAAO,qBAAqB;IACf,GAAG,CAAC;IACJ,KAAK,CAAC;IAEvB,YAAY,EAAE,aAAa,EAAE,KAAK,EAA+B;QAC/D,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,aAAa,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAEM,KAAK,CAAC,mBAAmB,CAAC,OAAe,EAAE,SAAqB;QACrE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;YACvB,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClE,MAAM,YAAY,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEzF,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,KAAK,WAAW,YAAY,yBAAyB,EAAE,IAAI,CAAC,CAAC;IACxG,CAAC;IAEM,KAAK,CAAC,2BAA2B,CAAC,SAAqB;QAC5D,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,YAAY,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEpE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CACnC,iCAAiC,IAAI,CAAC,KAAK,wBAAwB,YAAY,GAAG,EAClF,SAAS,CACV,CAAC;QAEF,OAAO,IAAI,CAAC,MAAM,CAAW,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE;YAC7C,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACrC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC9B,CAAC;YAED,OAAO,QAAQ,CAAC;QAClB,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC;IAEM,KAAK,CAAC,eAAe,CAAC,SAAqB;QAChD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,YAAY,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEpE,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,KAAK,wBAAwB,YAAY,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC3H,CAAC;IAEM,KAAK,CAAC,iBAAiB;QAC5B,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC3E,CAAC;CACF"}
+{"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,16 +12,24 @@ 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>;
+    /**
+     * Retrieves all keys matching the given pattern using the Redis SCAN command.
+     * This method is more efficient than using the KEYS command, especially for large datasets.
+     *
+     * @returns An array of matching keys
+     */
+    private getKeys;
 }
 export {};

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,36 +15,71 @@ 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 pattern = `${this.keyPrefix}*`;
-        const keys = await this.redis.keys(pattern);
-        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.
+     * This method is more efficient than using the KEYS command, especially for large datasets.
+     *
+     * @returns An array of matching keys
+     */
+    async getKeys() {
+        return new Promise((resolve, reject) => {
+            const keys = [];
+            const stream = this.redis.scanStream({
+                match: `${this.keyPrefix}*`,
+                count: 1000,
+            });
+            stream.on('data', (resultKeys) => {
+                keys.push(...resultKeys);
+            });
+            stream.on('end', () => {
+                resolve(keys);
+            });
+            stream.on('error', (err) => {
+                reject(err);
+            });
+        });
     }
 }
 //# sourceMappingURL=redis.js.map

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":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAgBhC;;GAEG;AACH,MAAM,OAAO,sBAAsB;IAChB,KAAK,CAAC;IACN,SAAS,CAAC;IAE3B,YAAY,EAAE,aAAa,EAAE,SAAS,EAAgC;QACpE,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,aAAa,EAAE;YACpC,oBAAoB,EAAE,CAAC;YACvB,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,SAAS,IAAI,EAAE,CAAC;IACnC,CAAC;IAEM,KAAK,CAAC,mBAAmB,CAAC,OAAe,EAAE,SAAqB;QACrE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;YACvB,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QAEvC,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC;QACpD,CAAC;QAED,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACxB,CAAC;IAEM,KAAK,CAAC,2BAA2B,CAAC,SAAqB;QAC5D,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC,CAAC;QAE/D,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IACpC,CAAC;IAEM,KAAK,CAAC,eAAe,CAAC,SAAqB;QAChD,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;YACvB,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC,CAAC;QAE/D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IACjC,CAAC;IAEM,KAAK,CAAC,iBAAiB;QAC5B,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,SAAS,GAAG,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE5C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IACvC,CAAC;CACF"}
+{"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

@@ -50,7 +50,7 @@ export interface CacheTagsProvider {
      * run again, fresh cache tag mappings will be created.
      *
      * @param {CacheTag[]} cacheTags Array of cache tags to delete
-     * @returns Number of keys deleted, or null if there was an error
+     * @returns Number of keys deleted
      *
      */
     deleteCacheTags(cacheTags: CacheTag[]): Promise<number>;
@@ -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/dist/cache-tags/utils.d.ts

@@ -9,10 +9,11 @@ import { type CacheTag } from './types.js';
  */
 export declare const parseXCacheTagsResponseHeader: (string?: null | string) => CacheTag[];
 /**
- * Generates a unique query ID based on the query document and its variables.
+ * Generates a unique query ID based on the query document, its variables, and optional HTTP headers.
  *
  * @param {DocumentNode} document Query document
- * @param {TVariables} variables Query variables
+ * @param {TVariables} variables Optional query variables
+ * @param {HeadersInit} headers Optional HTTP headers that might affect the query result (e.g., for authentication)
  * @returns Unique query ID
  */
-export declare const generateQueryId: <TVariables = unknown>(document: DocumentNode, variables?: TVariables) => string;
+export declare const generateQueryId: <TVariables = unknown>(document: DocumentNode, variables?: TVariables, headers?: HeadersInit) => string;

package/dist/cache-tags/utils.js

@@ -9,16 +9,18 @@ import { createHash } from 'node:crypto';
  */
 export const parseXCacheTagsResponseHeader = (string) => (string?.split(' ') ?? []).map((tag) => tag);
 /**
- * Generates a unique query ID based on the query document and its variables.
+ * Generates a unique query ID based on the query document, its variables, and optional HTTP headers.
  *
  * @param {DocumentNode} document Query document
- * @param {TVariables} variables Query variables
+ * @param {TVariables} variables Optional query variables
+ * @param {HeadersInit} headers Optional HTTP headers that might affect the query result (e.g., for authentication)
  * @returns Unique query ID
  */
-export const generateQueryId = (document, variables) => {
+export const generateQueryId = (document, variables, headers) => {
     return createHash('sha1')
         .update(print(document))
         .update(JSON.stringify(variables) || '')
+        .update(JSON.stringify(headers) || '')
         .digest('hex');
 };
 //# sourceMappingURL=utils.js.map

package/dist/cache-tags/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/cache-tags/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAqB,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,MAAsB,EAAE,EAAE,CACtE,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAe,CAAC,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAuB,QAAsB,EAAE,SAAsB,EAAU,EAAE;IAC9G,OAAO,UAAU,CAAC,MAAM,CAAC;SACtB,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;SACvB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;SACvC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/cache-tags/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAqB,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,MAAsB,EAAE,EAAE,CACtE,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAe,CAAC,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,QAAsB,EACtB,SAAsB,EACtB,OAAqB,EACb,EAAE;IACV,OAAO,UAAU,CAAC,MAAM,CAAC;SACtB,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;SACvB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;SACvC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;SACrC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartive/datocms-utils",
-  "version": "3.0.0-next.9",
+  "version": "3.1.0",
   "description": "A set of utilities and helpers to work with DatoCMS in a Next.js project.",
   "type": "module",
   "source": "./src/index.ts",
@@ -53,11 +53,11 @@
     "@neondatabase/serverless": "1.0.2",
     "@smartive/eslint-config": "7.0.1",
     "@smartive/prettier-config": "3.1.2",
-    "@types/node": "24.10.12",
+    "@types/node": "24.10.13",
     "eslint": "9.39.2",
     "eslint-import-resolver-typescript": "4.4.4",
     "graphql": "16.12.0",
-    "ioredis": "5.9.2",
+    "ioredis": "5.9.3",
     "prettier": "3.8.1",
     "rimraf": "6.1.2",
     "typescript": "5.9.3"

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.warn(`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,60 +22,115 @@ 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 = table;
+    this.table = NeonCacheTagsProvider.quoteIdentifier(table);
   }
 
   public async storeQueryCacheTags(queryId: string, cacheTags: CacheTag[]) {
-    if (!cacheTags?.length) {
-      return;
-    }
+    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(',');
+        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);
+        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 [];
-    }
+    return this.wrap(
+      'queriesReferencingCacheTags',
+      [cacheTags],
+      async () => {
+        if (!cacheTags?.length) {
+          return [];
+        }
 
-    const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
+        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,
-    );
+        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 rows.reduce<string[]>((queryIds, row) => {
+          if (typeof row.query_id === 'string') {
+            queryIds.push(row.query_id);
+          }
 
-      return queryIds;
-    }, []);
+          return queryIds;
+        }, []);
+      },
+      [],
+    );
   }
 
   public async deleteCacheTags(cacheTags: CacheTag[]) {
-    if (cacheTags.length === 0) {
-      return 0;
-    }
-    const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
+    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;
+        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,
+    );
+  }
+
+  /**
+   * Validates and quotes a PostgreSQL identifier (table name, column name, etc.) to prevent SQL injection.
+   * @param identifier The identifier to validate and quote
+   * @returns The properly quoted identifier
+   * @throws Error if the identifier is invalid
+   */
+  private static quoteIdentifier(identifier: string): string {
+    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.`,
+      );
+    }
+
+    // Quote the identifier using double quotes to prevent SQL injection
+    // Handle schema-qualified names (e.g., "schema.table")
+    // Escape any double quotes within the identifier by doubling them
+    return identifier
+      .split('.')
+      .map((part) => `"${part.replace(/"/g, '""')}"`)
+      .join('.');
   }
 }

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,107 @@ 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 pattern = `${this.keyPrefix}*`;
-    const keys = await this.redis.keys(pattern);
-
-    if (keys.length === 0) {
-      return 0;
-    }
+    return this.wrap(
+      'truncateCacheTags',
+      [],
+      async () => {
+        const keys = await this.getKeys();
+
+        if (keys.length === 0) {
+          return 0;
+        }
+
+        return await this.redis.del(...keys);
+      },
+      0,
+    );
+  }
 
-    return await this.redis.del(...keys);
+  /**
+   * Retrieves all keys matching the given pattern using the Redis SCAN command.
+   * This method is more efficient than using the KEYS command, especially for large datasets.
+   *
+   * @returns An array of matching keys
+   */
+  private async getKeys(): Promise<string[]> {
+    return new Promise((resolve, reject) => {
+      const keys: string[] = [];
+
+      const stream = this.redis.scanStream({
+        match: `${this.keyPrefix}*`,
+        count: 1000,
+      });
+
+      stream.on('data', (resultKeys: string[]) => {
+        keys.push(...resultKeys);
+      });
+
+      stream.on('end', () => {
+        resolve(keys);
+      });
+
+      stream.on('error', (err) => {
+        reject(err);
+      });
+    });
   }
 }

package/src/cache-tags/types.ts

@@ -52,7 +52,7 @@ export interface CacheTagsProvider {
    * run again, fresh cache tag mappings will be created.
    *
    * @param {CacheTag[]} cacheTags Array of cache tags to delete
-   * @returns Number of keys deleted, or null if there was an error
+   * @returns Number of keys deleted
    *
    */
   deleteCacheTags(cacheTags: CacheTag[]): Promise<number>;
@@ -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;
+};

package/src/cache-tags/utils.ts

@@ -13,15 +13,21 @@ export const parseXCacheTagsResponseHeader = (string?: null | string) =>
   (string?.split(' ') ?? []).map((tag) => tag as CacheTag);
 
 /**
- * Generates a unique query ID based on the query document and its variables.
+ * Generates a unique query ID based on the query document, its variables, and optional HTTP headers.
  *
  * @param {DocumentNode} document Query document
- * @param {TVariables} variables Query variables
+ * @param {TVariables} variables Optional query variables
+ * @param {HeadersInit} headers Optional HTTP headers that might affect the query result (e.g., for authentication)
  * @returns Unique query ID
  */
-export const generateQueryId = <TVariables = unknown>(document: DocumentNode, variables?: TVariables): string => {
+export const generateQueryId = <TVariables = unknown>(
+  document: DocumentNode,
+  variables?: TVariables,
+  headers?: HeadersInit,
+): string => {
   return createHash('sha1')
     .update(print(document))
     .update(JSON.stringify(variables) || '')
+    .update(JSON.stringify(headers) || '')
     .digest('hex');
 };