@smartive/datocms-utils 2.1.5 → 2.2.1

package/.github/workflows/release.yml

@@ -5,24 +5,29 @@ on:
     branches:
       - main
 
+permissions:
+  contents: write # to be able to publish a GitHub release
+  issues: write # to be able to comment on released issues
+  pull-requests: write # to be able to comment on released pull requests
+  id-token: write # to enable use of OIDC for trusted publishing and npm provenance
+
 jobs:
   release:
     name: Build & release
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
         with:
           node-version: 24
       - run: npm ci
       - run: npm run build
       - name: semantic release
-        uses: cycjimmy/semantic-release-action@v5
+        uses: cycjimmy/semantic-release-action@v6
         with:
-          semantic_version: 24
+          semantic_version: 25
           extra_plugins: |
             @semantic-release/changelog@6
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/test.yml

@@ -15,8 +15,8 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
         with:
           node-version: 24
       - run: npm ci

package/CHANGELOG.md

@@ -1,6 +1,6 @@
-## [2.1.5](https://github.com/smartive/datocms-utils/compare/v2.1.4...v2.1.5) (2025-11-13)
+## [2.2.1](https://github.com/smartive/datocms-utils/compare/v2.2.0...v2.2.1) (2026-02-12)
 
 
 ### Bug Fixes
 
-* remove semantic-release dependency in order to fix CI/CD ([c70291a](https://github.com/smartive/datocms-utils/commit/c70291a0fd51f2faadaa0c25bd6fad8fc6cd49d3))
+* add missing repository.url to package.json ([#206](https://github.com/smartive/datocms-utils/issues/206)) ([d88733e](https://github.com/smartive/datocms-utils/commit/d88733e374bf7ac0161e6a4439032ea6ad2a99b8))

package/README.md

@@ -34,6 +34,69 @@ CREATE TABLE IF NOT EXISTS query_cache_tags (
 );
 ```
 
+### Utilities for DatoCMS Cache Tags (Redis)
+
+The following utilities provide Redis-based alternatives to the Postgres cache tags implementation above. They work with [DatoCMS cache tags](https://www.datocms.com/docs/content-delivery-api/cache-tags) and any Redis instance.
+
+- `redis.storeQueryCacheTags`: Stores the cache tags of a query in Redis.
+- `redis.queriesReferencingCacheTags`: Retrieves the queries that reference cache tags.
+- `redis.deleteCacheTags`: Deletes cache tags from Redis.
+- `redis.truncateCacheTags`: Wipes out all cache tags from Redis.
+
+The Redis connection is automatically initialized on first use using the `REDIS_URL` environment variable.
+
+#### Environment Variables
+
+Add your Redis connection URL to your `.env.local` file:
+
+```bash
+# Required: Redis connection URL
+# For Upstash Redis
+REDIS_URL=rediss://default:your-token@your-endpoint.upstash.io:6379
+
+# For Redis Cloud or other providers
+REDIS_URL=redis://username:password@your-redis-host:6379
+
+# For local development
+REDIS_URL=redis://localhost:6379
+
+# Optional: Key prefix for separating production/preview environments
+# Useful when using the same Redis instance for multiple environments
+REDIS_KEY_PREFIX=prod        # For production
+REDIS_KEY_PREFIX=preview     # For preview/staging
+# Leave empty for development (no prefix)
+```
+
+**Note**: Similar to how the Postgres version uses different table names, use `REDIS_KEY_PREFIX` to separate data between environments when using the same Redis instance.
+
+#### Usage Example
+
+```typescript
+// Recommended: Use namespaces for clarity
+import { generateQueryId, redis } from '@smartive/datocms-utils';
+
+const queryId = generateQueryId(query, variables);
+
+// Store cache tags for a query
+await redis.storeQueryCacheTags(queryId, ['item:42', 'product', 'category:5']);
+
+// Find all queries that reference specific tags
+const affectedQueries = await redis.queriesReferencingCacheTags(['item:42']);
+
+// Delete cache tags (keys will be recreated on next query)
+await redis.deleteCacheTags(['item:42']);
+```
+
+#### Redis Data Structure
+
+The Redis implementation uses Sets to track query-to-tag relationships:
+
+- **Cache tag keys**: `{prefix}{tag}` → Set of query IDs
+
+Where `{prefix}` is the optional `REDIS_KEY_PREFIX` environment variable (e.g., `prod:`, `preview:`).
+
+When cache tags are invalidated, their keys are deleted entirely. Fresh mappings are created when queries run again.
+
 ### Other Utilities
 
 - `classNames`: Cleans and joins an array of inputs with possible undefined or boolean values. Useful for tailwind classnames.

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

@@ -0,0 +1,39 @@
+import { type CacheTag } from './types';
+/**
+ * Stores the cache tags of a query in Redis.
+ *
+ * For each cache tag, adds the query ID to a Redis Set. Sets are unordered
+ * collections of unique strings, perfect for tracking which queries use which tags.
+ *
+ * @param {string} queryId Unique query ID
+ * @param {CacheTag[]} cacheTags Array of cache tags
+ *
+ */
+export declare const storeQueryCacheTags: (queryId: string, cacheTags: CacheTag[]) => Promise<void>;
+/**
+ * Retrieves the query IDs that reference any of the specified cache tags.
+ *
+ * Uses Redis SUNION to efficiently find all queries associated with the given tags.
+ *
+ * @param {CacheTag[]} cacheTags Array of cache tags to check
+ * @returns Array of unique query IDs
+ *
+ */
+export declare const queriesReferencingCacheTags: (cacheTags: CacheTag[]) => Promise<string[]>;
+/**
+ * Deletes the specified cache tags from Redis.
+ *
+ * This removes the cache tag keys entirely. When queries are revalidated and
+ * 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
+ *
+ */
+export declare const deleteCacheTags: (cacheTags: CacheTag[]) => Promise<number>;
+/**
+ * Wipes out all cache tags from Redis.
+ *
+ * ⚠️ **Warning**: This will delete all cache tag data. Use with caution!
+ */
+export declare const truncateCacheTags: () => Promise<void>;

package/dist/cache-tags-redis.js

@@ -0,0 +1,80 @@
+import { Redis } from 'ioredis';
+let redis = null;
+const getRedis = () => {
+    redis ??= new Redis(process.env.REDIS_URL, {
+        maxRetriesPerRequest: 3,
+        lazyConnect: true,
+    });
+    return redis;
+};
+const keyPrefix = process.env.REDIS_KEY_PREFIX ? `${process.env.REDIS_KEY_PREFIX}:` : '';
+/**
+ * Stores the cache tags of a query in Redis.
+ *
+ * For each cache tag, adds the query ID to a Redis Set. Sets are unordered
+ * collections of unique strings, perfect for tracking which queries use which tags.
+ *
+ * @param {string} queryId Unique query ID
+ * @param {CacheTag[]} cacheTags Array of cache tags
+ *
+ */
+export const storeQueryCacheTags = async (queryId, cacheTags) => {
+    if (!cacheTags?.length) {
+        return;
+    }
+    const redis = getRedis();
+    const pipeline = redis.pipeline();
+    for (const tag of cacheTags) {
+        pipeline.sadd(`${keyPrefix}${tag}`, queryId);
+    }
+    await pipeline.exec();
+};
+/**
+ * Retrieves the query IDs that reference any of the specified cache tags.
+ *
+ * Uses Redis SUNION to efficiently find all queries associated with the given tags.
+ *
+ * @param {CacheTag[]} cacheTags Array of cache tags to check
+ * @returns Array of unique query IDs
+ *
+ */
+export const queriesReferencingCacheTags = async (cacheTags) => {
+    if (!cacheTags?.length) {
+        return [];
+    }
+    const redis = getRedis();
+    const keys = cacheTags.map((tag) => `${keyPrefix}${tag}`);
+    return redis.sunion(...keys);
+};
+/**
+ * Deletes the specified cache tags from Redis.
+ *
+ * This removes the cache tag keys entirely. When queries are revalidated and
+ * 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
+ *
+ */
+export const deleteCacheTags = async (cacheTags) => {
+    if (!cacheTags?.length) {
+        return 0;
+    }
+    const redis = getRedis();
+    const keys = cacheTags.map((tag) => `${keyPrefix}${tag}`);
+    return redis.del(...keys);
+};
+/**
+ * Wipes out all cache tags from Redis.
+ *
+ * ⚠️ **Warning**: This will delete all cache tag data. Use with caution!
+ */
+export const truncateCacheTags = async () => {
+    const redis = getRedis();
+    const pattern = `${keyPrefix}*`;
+    const keys = await redis.keys(pattern);
+    if (keys.length > 0) {
+        await redis.del(...keys);
+    }
+};
+//# sourceMappingURL=cache-tags-redis.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache-tags-redis.js","sourceRoot":"","sources":["../src/cache-tags-redis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,IAAI,KAAK,GAAiB,IAAI,CAAC;AAE/B,MAAM,QAAQ,GAAG,GAAU,EAAE;IAC3B,KAAK,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAU,EAAE;QAC1C,oBAAoB,EAAE,CAAC;QACvB,WAAW,EAAE,IAAI;KAClB,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AAEzF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,EAAE,OAAe,EAAE,SAAqB,EAAiB,EAAE;IACjG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;IAElC,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC,GAAG,SAAS,GAAG,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,EAAE,SAAqB,EAAqB,EAAE;IAC5F,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,GAAG,GAAG,EAAE,CAAC,CAAC;IAE1D,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;AAC/B,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAAE,SAAqB,EAAmB,EAAE;IAC9E,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS,GAAG,GAAG,EAAE,CAAC,CAAC;IAE1D,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;AAC5B,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,IAAmB,EAAE;IACzD,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,OAAO,GAAG,GAAG,SAAS,GAAG,CAAC;IAChC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEvC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC,CAAC"}

package/dist/cache-tags.d.ts

@@ -1,21 +1,5 @@
-import { DocumentNode } from 'graphql';
-import { CacheTag } from './types';
-/**
- * Converts the value of DatoCMS's `X-Cache-Tags` header into an array of strings typed as `CacheTag`.
- * For example, it transforms `'tag-a tag-2 other-tag'` into `['tag-a', 'tag-2', 'other-tag']`.
- *
- * @param string String value of the `X-Cache-Tags` header
- * @returns Array of strings typed as `CacheTag`
- */
-export declare function parseXCacheTagsResponseHeader(string?: null | string): CacheTag[];
-/**
- * Generates a unique query ID based on the query document and its variables.
- *
- * @param {DocumentNode} document Query document
- * @param {TVariables} variables Query variables
- * @returns Unique query ID
- */
-export declare const generateQueryId: <TVariables = unknown>(document: DocumentNode, variables?: TVariables) => string;
+import { type CacheTag } from './types';
+export { generateQueryId, parseXCacheTagsResponseHeader } from './utils';
 /**
  * Stores the cache tags of a query in the database.
  *
@@ -32,11 +16,23 @@ export declare const storeQueryCacheTags: (queryId: string, cacheTags: CacheTag[
  * @returns Array of query IDs
  */
 export declare const queriesReferencingCacheTags: (cacheTags: CacheTag[], tableId: string) => Promise<string[]>;
+/**
+ * Deletes the specified cache tags from the database.
+ *
+ * This removes the cache tag keys entirely. When queries are revalidated and
+ * run again, fresh cache tag mappings will be created.
+ *
+ * @param {CacheTag[]} cacheTags Array of cache tags to delete
+ * @param {string} tableId Database table ID
+ *
+ */
+export declare const deleteCacheTags: (cacheTags: CacheTag[], tableId: string) => Promise<void>;
 /**
  * Deletes the cache tags of a query from the database.
  *
  * @param {string} queryId Unique query ID
  * @param {string} tableId Database table ID
+ * @deprecated Use `deleteCacheTags` instead.
  */
 export declare const deleteQueries: (queryIds: string[], tableId: string) => Promise<void>;
 /**

package/dist/cache-tags.js

@@ -1,32 +1,5 @@
 import { sql } from '@vercel/postgres';
-import { createHash } from 'crypto';
-import { print } from 'graphql';
-/**
- * Converts the value of DatoCMS's `X-Cache-Tags` header into an array of strings typed as `CacheTag`.
- * For example, it transforms `'tag-a tag-2 other-tag'` into `['tag-a', 'tag-2', 'other-tag']`.
- *
- * @param string String value of the `X-Cache-Tags` header
- * @returns Array of strings typed as `CacheTag`
- */
-export function parseXCacheTagsResponseHeader(string) {
-    if (!string) {
-        return [];
-    }
-    return (string.split(' ') || []).map((tag) => tag);
-}
-/**
- * Generates a unique query ID based on the query document and its variables.
- *
- * @param {DocumentNode} document Query document
- * @param {TVariables} variables Query variables
- * @returns Unique query ID
- */
-export const generateQueryId = (document, variables) => {
-    return createHash('sha1')
-        .update(print(document))
-        .update(JSON.stringify(variables) || '')
-        .digest('hex');
-};
+export { generateQueryId, parseXCacheTagsResponseHeader } from './utils';
 /**
  * Stores the cache tags of a query in the database.
  *
@@ -57,11 +30,29 @@ export const queriesReferencingCacheTags = async (cacheTags, tableId) => {
     const { rows } = await sql.query(`SELECT DISTINCT query_id FROM ${tableId} WHERE cache_tag IN (${placeholders})`, cacheTags);
     return rows.map((row) => row.query_id);
 };
+/**
+ * Deletes the specified cache tags from the database.
+ *
+ * This removes the cache tag keys entirely. When queries are revalidated and
+ * run again, fresh cache tag mappings will be created.
+ *
+ * @param {CacheTag[]} cacheTags Array of cache tags to delete
+ * @param {string} tableId Database table ID
+ *
+ */
+export const deleteCacheTags = async (cacheTags, tableId) => {
+    if (cacheTags.length === 0) {
+        return;
+    }
+    const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
+    await sql.query(`DELETE FROM ${tableId} WHERE cache_tag IN (${placeholders})`, cacheTags);
+};
 /**
  * Deletes the cache tags of a query from the database.
  *
  * @param {string} queryId Unique query ID
  * @param {string} tableId Database table ID
+ * @deprecated Use `deleteCacheTags` instead.
  */
 export const deleteQueries = async (queryIds, tableId) => {
     if (!queryIds?.length) {

package/dist/cache-tags.js.map

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

package/dist/classnames.js.map

@@ -1 +1 @@
-{"version":3,"file":"classnames.js","sourceRoot":"","sources":["../src/classnames.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAG,UAA4C,EAAU,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC"}
+{"version":3,"file":"classnames.js","sourceRoot":"","sources":["../src/classnames.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAG,UAA4C,EAAU,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './cache-tags';
+export * as postgres from './cache-tags';
+export * as redis from './cache-tags-redis';
 export * from './classnames';
 export * from './links';
 export * from './types';

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from './cache-tags';
+export * as postgres from './cache-tags';
+export * as redis from './cache-tags-redis';
 export * from './classnames';
 export * from './links';
 export * from './types';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,OAAO,KAAK,QAAQ,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,KAAK,MAAM,oBAAoB,CAAC;AAC5C,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}

package/dist/links.js.map

@@ -1 +1 @@
-{"version":3,"file":"links.js","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,WAAmB,EAAU,EAAE;IACxD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,qFAAqF;IACrF,MAAM,kBAAkB,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAE9D,OAAO,OAAO,kBAAkB,EAAE,CAAC;AACrC,CAAC,CAAC"}
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,WAAmB,EAAU,EAAE;IACxD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,qFAAqF;IACrF,MAAM,kBAAkB,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAE9D,OAAO,OAAO,kBAAkB,EAAE,CAAC;AACrC,CAAC,CAAC"}

package/dist/types.d.ts

@@ -1,6 +1,17 @@
+/**
+ * A branded type for cache tags. This is created by intersecting `string`
+ * with `{ readonly _: unique symbol }`, making it a unique type.
+ * Although it is fundamentally a string, it is treated as a distinct type
+ * due to the unique symbol.
+ */
 export type CacheTag = string & {
     readonly _: unique symbol;
 };
+/**
+ * A type representing the structure of a webhook payload for cache tag invalidation.
+ * It includes the entity type, event type, and the entity details which contain
+ * the cache tags to be invalidated.
+ */
 export type CacheTagsInvalidateWebhook = {
     entity_type: 'cda_cache_tags';
     event_type: 'invalidate';

package/dist/utils.d.ts

@@ -0,0 +1,18 @@
+import { type DocumentNode } from 'graphql';
+import { type CacheTag } from './types';
+/**
+ * Converts the value of DatoCMS's `X-Cache-Tags` header into an array of strings typed as `CacheTag`.
+ * For example, it transforms `'tag-a tag-2 other-tag'` into `['tag-a', 'tag-2', 'other-tag']`.
+ *
+ * @param string String value of the `X-Cache-Tags` header
+ * @returns Array of strings typed as `CacheTag`
+ */
+export declare const parseXCacheTagsResponseHeader: (string?: null | string) => CacheTag[];
+/**
+ * Generates a unique query ID based on the query document and its variables.
+ *
+ * @param {DocumentNode} document Query document
+ * @param {TVariables} variables Query variables
+ * @returns Unique query ID
+ */
+export declare const generateQueryId: <TVariables = unknown>(document: DocumentNode, variables?: TVariables) => string;

package/dist/utils.js

@@ -0,0 +1,24 @@
+import { print } from 'graphql';
+import { createHash } from 'node:crypto';
+/**
+ * Converts the value of DatoCMS's `X-Cache-Tags` header into an array of strings typed as `CacheTag`.
+ * For example, it transforms `'tag-a tag-2 other-tag'` into `['tag-a', 'tag-2', 'other-tag']`.
+ *
+ * @param string String value of the `X-Cache-Tags` header
+ * @returns Array of strings typed as `CacheTag`
+ */
+export const parseXCacheTagsResponseHeader = (string) => (string?.split(' ') ?? []).map((tag) => tag);
+/**
+ * Generates a unique query ID based on the query document and its variables.
+ *
+ * @param {DocumentNode} document Query document
+ * @param {TVariables} variables Query variables
+ * @returns Unique query ID
+ */
+export const generateQueryId = (document, variables) => {
+    return createHash('sha1')
+        .update(print(document))
+        .update(JSON.stringify(variables) || '')
+        .digest('hex');
+};
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartive/datocms-utils",
-  "version": "2.1.5",
+  "version": "2.2.1",
   "description": "A set of utilities and helpers to work with DatoCMS in a Next.js project.",
   "source": "src/index.ts",
   "main": "dist/index.js",
@@ -18,17 +18,30 @@
   ],
   "author": "smartive AG",
   "license": "MIT",
+  "repository": {
+    "url": "https://github.com/smartive/datocms-utils",
+    "type": "git"
+  },
   "devDependencies": {
-    "@smartive/eslint-config": "^7.0.0",
-    "@smartive/prettier-config": "^3.1.2",
-    "@types/node": "^24.0.0",
-    "eslint": "^9.39.1",
-    "eslint-import-resolver-typescript": "^4.4.4",
-    "prettier": "^3.3.3",
-    "typescript": "^5.6.2"
+    "@smartive/eslint-config": "7.0.1",
+    "@smartive/prettier-config": "3.1.2",
+    "@types/node": "24.10.12",
+    "eslint": "9.39.2",
+    "eslint-import-resolver-typescript": "4.4.4",
+    "prettier": "3.8.1",
+    "typescript": "5.9.3",
+    "ioredis": "5.9.2"
   },
   "dependencies": {
     "@vercel/postgres": "^0.10.0",
     "graphql": "^16.9.0"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.4.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
   }
 }

package/renovate.json

@@ -1,10 +1,4 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
-  "extends": [
-    "local>smartive/renovate-config",
-    ":automergeRequireAllStatusChecks",
-    ":automergeDisabled",
-    ":automergeStableNonMajor",
-    ":pinOnlyDevDependencies"
-  ]
+  "extends": ["github>smartive/renovate-config:best-practices-lib"]
 }

package/src/cache-tags-redis.ts

@@ -0,0 +1,96 @@
+import { Redis } from 'ioredis';
+import { type CacheTag } from './types';
+
+let redis: Redis | null = null;
+
+const getRedis = (): Redis => {
+  redis ??= new Redis(process.env.REDIS_URL!, {
+    maxRetriesPerRequest: 3,
+    lazyConnect: true,
+  });
+
+  return redis;
+};
+
+const keyPrefix = process.env.REDIS_KEY_PREFIX ? `${process.env.REDIS_KEY_PREFIX}:` : '';
+
+/**
+ * Stores the cache tags of a query in Redis.
+ *
+ * For each cache tag, adds the query ID to a Redis Set. Sets are unordered
+ * collections of unique strings, perfect for tracking which queries use which tags.
+ *
+ * @param {string} queryId Unique query ID
+ * @param {CacheTag[]} cacheTags Array of cache tags
+ *
+ */
+export const storeQueryCacheTags = async (queryId: string, cacheTags: CacheTag[]): Promise<void> => {
+  if (!cacheTags?.length) {
+    return;
+  }
+
+  const redis = getRedis();
+  const pipeline = redis.pipeline();
+
+  for (const tag of cacheTags) {
+    pipeline.sadd(`${keyPrefix}${tag}`, queryId);
+  }
+
+  await pipeline.exec();
+};
+
+/**
+ * Retrieves the query IDs that reference any of the specified cache tags.
+ *
+ * Uses Redis SUNION to efficiently find all queries associated with the given tags.
+ *
+ * @param {CacheTag[]} cacheTags Array of cache tags to check
+ * @returns Array of unique query IDs
+ *
+ */
+export const queriesReferencingCacheTags = async (cacheTags: CacheTag[]): Promise<string[]> => {
+  if (!cacheTags?.length) {
+    return [];
+  }
+
+  const redis = getRedis();
+  const keys = cacheTags.map((tag) => `${keyPrefix}${tag}`);
+
+  return redis.sunion(...keys);
+};
+
+/**
+ * Deletes the specified cache tags from Redis.
+ *
+ * This removes the cache tag keys entirely. When queries are revalidated and
+ * 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
+ *
+ */
+export const deleteCacheTags = async (cacheTags: CacheTag[]): Promise<number> => {
+  if (!cacheTags?.length) {
+    return 0;
+  }
+
+  const redis = getRedis();
+  const keys = cacheTags.map((tag) => `${keyPrefix}${tag}`);
+
+  return redis.del(...keys);
+};
+
+/**
+ * Wipes out all cache tags from Redis.
+ *
+ * ⚠️ **Warning**: This will delete all cache tag data. Use with caution!
+ */
+export const truncateCacheTags = async (): Promise<void> => {
+  const redis = getRedis();
+  const pattern = `${keyPrefix}*`;
+  const keys = await redis.keys(pattern);
+
+  if (keys.length > 0) {
+    await redis.del(...keys);
+  }
+};

package/src/cache-tags.ts

@@ -1,38 +1,7 @@
 import { sql } from '@vercel/postgres';
-import { createHash } from 'crypto';
-import { DocumentNode, print } from 'graphql';
-import { CacheTag } from './types';
+import { type CacheTag } from './types';
 
-/**
- * Converts the value of DatoCMS's `X-Cache-Tags` header into an array of strings typed as `CacheTag`.
- * For example, it transforms `'tag-a tag-2 other-tag'` into `['tag-a', 'tag-2', 'other-tag']`.
- *
- * @param string String value of the `X-Cache-Tags` header
- * @returns Array of strings typed as `CacheTag`
- */
-
-export function parseXCacheTagsResponseHeader(string?: null | string) {
-  if (!string) {
-    return [];
-  }
-
-  return (string.split(' ') || []).map((tag) => tag as CacheTag);
-}
-
-/**
- * Generates a unique query ID based on the query document and its variables.
- *
- * @param {DocumentNode} document Query document
- * @param {TVariables} variables Query variables
- * @returns Unique query ID
- */
-
-export const generateQueryId = <TVariables = unknown>(document: DocumentNode, variables?: TVariables): string => {
-  return createHash('sha1')
-    .update(print(document))
-    .update(JSON.stringify(variables) || '')
-    .digest('hex');
-};
+export { generateQueryId, parseXCacheTagsResponseHeader } from './utils';
 
 /**
  * Stores the cache tags of a query in the database.
@@ -41,7 +10,6 @@ export const generateQueryId = <TVariables = unknown>(document: DocumentNode, va
  * @param {CacheTag[]} cacheTags Array of cache tags
  * @param {string} tableId Database table ID
  */
-
 export const storeQueryCacheTags = async (queryId: string, cacheTags: CacheTag[], tableId: string) => {
   if (!cacheTags?.length) {
     return;
@@ -60,7 +28,6 @@ export const storeQueryCacheTags = async (queryId: string, cacheTags: CacheTag[]
  * @param {string} tableId Database table ID
  * @returns Array of query IDs
  */
-
 export const queriesReferencingCacheTags = async (cacheTags: CacheTag[], tableId: string): Promise<string[]> => {
   if (!cacheTags?.length) {
     return [];
@@ -76,13 +43,32 @@ export const queriesReferencingCacheTags = async (cacheTags: CacheTag[], tableId
   return rows.map((row) => row.query_id);
 };
 
+/**
+ * Deletes the specified cache tags from the database.
+ *
+ * This removes the cache tag keys entirely. When queries are revalidated and
+ * run again, fresh cache tag mappings will be created.
+ *
+ * @param {CacheTag[]} cacheTags Array of cache tags to delete
+ * @param {string} tableId Database table ID
+ *
+ */
+export const deleteCacheTags = async (cacheTags: CacheTag[], tableId: string) => {
+  if (cacheTags.length === 0) {
+    return;
+  }
+  const placeholders = cacheTags.map((_, i) => `$${i + 1}`).join(',');
+
+  await sql.query(`DELETE FROM ${tableId} WHERE cache_tag IN (${placeholders})`, cacheTags);
+};
+
 /**
  * Deletes the cache tags of a query from the database.
  *
  * @param {string} queryId Unique query ID
  * @param {string} tableId Database table ID
+ * @deprecated Use `deleteCacheTags` instead.
  */
-
 export const deleteQueries = async (queryIds: string[], tableId: string) => {
   if (!queryIds?.length) {
     return;
@@ -97,7 +83,6 @@ export const deleteQueries = async (queryIds: string[], tableId: string) => {
  *
  * @param {string} tableId Database table ID
  */
-
 export async function truncateCacheTags(tableId: string) {
   await sql.query(`DELETE FROM ${tableId}`);
 }

package/src/classnames.ts

@@ -4,5 +4,4 @@
  * @param classNames Array of class names
  * @returns Clean string to be used for class name
  */
-
 export const classNames = (...classNames: (string | undefined | boolean)[]): string => classNames.filter(Boolean).join(' ');

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from './cache-tags';
+export * as postgres from './cache-tags';
+export * as redis from './cache-tags-redis';
 export * from './classnames';
 export * from './links';
 export * from './types';

package/src/links.ts

@@ -4,7 +4,6 @@
  * @param phoneNumber Phone number
  * @returns `tel:` link for the phone number
  */
-
 export const getTelLink = (phoneNumber: string): string => {
   if (typeof phoneNumber !== 'string') {
     throw new Error('Phone number must be a string.');

package/src/types.ts

@@ -1,5 +1,16 @@
+/**
+ * A branded type for cache tags. This is created by intersecting `string`
+ * with `{ readonly _: unique symbol }`, making it a unique type.
+ * Although it is fundamentally a string, it is treated as a distinct type
+ * due to the unique symbol.
+ */
 export type CacheTag = string & { readonly _: unique symbol };
 
+/**
+ * A type representing the structure of a webhook payload for cache tag invalidation.
+ * It includes the entity type, event type, and the entity details which contain
+ * the cache tags to be invalidated.
+ */
 export type CacheTagsInvalidateWebhook = {
   entity_type: 'cda_cache_tags';
   event_type: 'invalidate';

package/src/utils.ts

@@ -0,0 +1,27 @@
+import { print, type DocumentNode } from 'graphql';
+import { createHash } from 'node:crypto';
+import { type CacheTag } from './types';
+
+/**
+ * Converts the value of DatoCMS's `X-Cache-Tags` header into an array of strings typed as `CacheTag`.
+ * For example, it transforms `'tag-a tag-2 other-tag'` into `['tag-a', 'tag-2', 'other-tag']`.
+ *
+ * @param string String value of the `X-Cache-Tags` header
+ * @returns Array of strings typed as `CacheTag`
+ */
+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.
+ *
+ * @param {DocumentNode} document Query document
+ * @param {TVariables} variables Query variables
+ * @returns Unique query ID
+ */
+export const generateQueryId = <TVariables = unknown>(document: DocumentNode, variables?: TVariables): string => {
+  return createHash('sha1')
+    .update(print(document))
+    .update(JSON.stringify(variables) || '')
+    .digest('hex');
+};