@smartive/datocms-utils 1.0.0

package/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@smartive/eslint-config"]
+}

package/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release npm package
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: Build & release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build
+      - name: semantic release
+        uses: cycjimmy/semantic-release-action@v3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Test
+
+on:
+  pull_request:
+    branches:
+      - '**'
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Lint & test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run build

package/.prettierrc.json

@@ -0,0 +1 @@
+"@smartive/prettier-config"

package/.releaserc.json

@@ -0,0 +1,10 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    "@semantic-release/github"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 1.0.0 (2024-09-25)
+
+
+### Features
+
+* update README ([8ffb069](https://github.com/smartive/datocms-utils/commit/8ffb069a8d3dceed6fffc400b0b77f7f481904f4))

package/LICENSE

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

package/README.md

@@ -0,0 +1,39 @@
+# smartive DatoCMS Utilities
+
+A set of utilities and helpers to work with DatoCMS in a Next.js project.
+
+## Installation
+
+```bash
+npm install @smartive/datocms-utils
+```
+
+## Usage
+
+Import and use the utilities you need in your project. The following utilities are available.
+
+## Utilities
+
+### Utilities for DatoCMS Cache Tags
+
+The following utilities are used to work with [DatoCMS cache tags](https://www.datocms.com/docs/content-delivery-api/cache-tags) and a [Vercel Postgres database](https://vercel.com/docs/storage/vercel-postgres).
+
+- `storeQueryCacheTags`: Stores the cache tags of a query in the database.
+- `queriesReferencingCacheTags`: Retrieves the queries that reference cache tags.
+- `deleteQueries`: Deletes the cache tags of a query from the database.
+
+#### Setup Postgres database
+
+In order for the above utilites to work, you need to setup a the following database. You can use the following SQL script to do that:
+
+```sql
+CREATE TABLE IF NOT EXISTS query_cache_tags (
+  query_id TEXT NOT NULL,
+  cache_tag TEXT NOT NULL,
+  PRIMARY KEY (query_id, cache_tag)
+);
+```
+
+### Other Utilities
+
+- `classNames`: Cleans and joins an array of inputs with possible undefined or boolean values. Useful for tailwind classnames.

package/dist/cache-tags.d.ts

@@ -0,0 +1,38 @@
+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 {Record<string, unknown>} variables Query variables
+ * @returns Unique query ID
+ */
+export declare const generateQueryId: (document: DocumentNode, variables?: Record<string, unknown>) => string;
+/**
+ * Stores the cache tags of a query in the database.
+ *
+ * @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 queries that reference cache tags.
+ *
+ * @param {CacheTag[]} cacheTags Array of cache tags
+ * @returns Array of query IDs
+ */
+export declare const queriesReferencingCacheTags: (cacheTags: CacheTag[]) => Promise<string[]>;
+/**
+ * Deletes the cache tags of a query from the database.
+ *
+ * @param {string} queryId Unique query ID
+ */
+export declare const deleteQueries: (queryIds: string[]) => Promise<void>;

package/dist/cache-tags.js

@@ -0,0 +1,57 @@
+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 {Record<string, unknown>} variables Query variables
+ * @returns Unique query ID
+ */
+export const generateQueryId = (document, variables) => {
+    return createHash('sha1')
+        .update(print(document))
+        .update(JSON.stringify(variables) || '')
+        .digest('hex');
+};
+/**
+ * Stores the cache tags of a query in the database.
+ *
+ * @param {string} queryId Unique query ID
+ * @param {CacheTag[]} cacheTags Array of cache tags
+ */
+export const storeQueryCacheTags = async (queryId, cacheTags) => {
+    await sql.query(`INSERT INTO query_cache_tags VALUES ${cacheTags.map((cacheTag) => `('${queryId}', '${cacheTag}')`).join()} ON CONFLICT DO NOTHING`);
+};
+/**
+ * Retrieves the queries that reference cache tags.
+ *
+ * @param {CacheTag[]} cacheTags Array of cache tags
+ * @returns Array of query IDs
+ */
+export const queriesReferencingCacheTags = async (cacheTags) => {
+    const { rows } = await sql.query(`SELECT DISTINCT query_id FROM query_cache_tags WHERE cache_tag IN (${cacheTags.map((cacheTag) => `'${cacheTag}'`).join(', ')})`);
+    return rows.map((row) => row.query_id);
+};
+/**
+ * Deletes the cache tags of a query from the database.
+ *
+ * @param {string} queryId Unique query ID
+ */
+export const deleteQueries = async (queryIds) => {
+    await sql.query(`DELETE FROM query_cache_tags WHERE query_id IN (${queryIds.map((id) => `'${id}'`).join(', ')})`);
+};
+//# sourceMappingURL=cache-tags.js.map

package/dist/cache-tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-tags.js","sourceRoot":"","sources":["../src/cache-tags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAgB,KAAK,EAAE,MAAM,SAAS,CAAC;AAG9C;;;;;;GAMG;AAEH,MAAM,UAAU,6BAA6B,CAAC,MAAsB;IAClE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAe,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAAsB,EAAE,SAAmC,EAAU,EAAE;IACrG,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;AAEF;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,EAAE,OAAe,EAAE,SAAqB,EAAE,EAAE;IAClF,MAAM,GAAG,CAAC,KAAK,CACb,uCAAuC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,OAAO,OAAO,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,yBAAyB,CACpI,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,EAAE,SAAqB,EAAqB,EAAE;IAC5F,MAAM,EAAE,IAAI,EAAE,GAAqC,MAAM,GAAG,CAAC,KAAK,CAChE,sEAAsE,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACjI,CAAC;IAEF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACzC,CAAC,CAAC;AAEF;;;;GAIG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,QAAkB,EAAE,EAAE;IACxD,MAAM,GAAG,CAAC,KAAK,CAAC,mDAAmD,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpH,CAAC,CAAC"}

package/dist/classnames.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Cleans and joins an array of inputs with possible undefined or boolean values.
+ *
+ * @param classNames Array of class names
+ * @returns Clean string to be used for class name
+ */
+export declare const classNames: (...classNames: (string | undefined | boolean)[]) => string;

package/dist/classnames.js

@@ -0,0 +1,8 @@
+/**
+ * Cleans and joins an array of inputs with possible undefined or boolean values.
+ *
+ * @param classNames Array of class names
+ * @returns Clean string to be used for class name
+ */
+export const classNames = (...classNames) => classNames.filter(Boolean).join(' ');
+//# sourceMappingURL=classnames.js.map

package/dist/classnames.js.map

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './cache-tags';
+export * from './classnames';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './cache-tags';
+export * from './classnames';
+export * from './types';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/types.d.ts

@@ -0,0 +1,3 @@
+export type CacheTag = string & {
+    readonly _: unique symbol;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@smartive/datocms-utils",
+  "version": "1.0.0",
+  "description": "A set of utilities and helpers to work with DatoCMS in a Next.js project.",
+  "source": "src/index.ts",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "lint": "prettier --check src && eslint src",
+    "publish": "semantic-release"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "datocms"
+  ],
+  "author": "smartive AG",
+  "license": "MIT",
+  "devDependencies": {
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/commit-analyzer": "13.0.0",
+    "@semantic-release/gitlab": "^13.2.1",
+    "@semantic-release/npm": "12.0.1",
+    "@semantic-release/release-notes-generator": "14.0.1",
+    "@smartive/eslint-config": "^5.1.0",
+    "@smartive/prettier-config": "^3.1.2",
+    "@types/node": "^22.7.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.3",
+    "semantic-release": "^24.1.1",
+    "typescript": "^5.6.2"
+  },
+  "dependencies": {
+    "@vercel/postgres": "^0.10.0",
+    "graphql": "^16.9.0"
+  }
+}

package/renovate.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["local>smartive/renovate-config"]
+}

package/src/cache-tags.ts

@@ -0,0 +1,73 @@
+import { sql } from '@vercel/postgres';
+import { createHash } from 'crypto';
+import { DocumentNode, print } 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 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 {Record<string, unknown>} variables Query variables
+ * @returns Unique query ID
+ */
+
+export const generateQueryId = (document: DocumentNode, variables?: Record<string, unknown>): string => {
+  return createHash('sha1')
+    .update(print(document))
+    .update(JSON.stringify(variables) || '')
+    .digest('hex');
+};
+
+/**
+ * Stores the cache tags of a query in the database.
+ *
+ * @param {string} queryId Unique query ID
+ * @param {CacheTag[]} cacheTags Array of cache tags
+ */
+
+export const storeQueryCacheTags = async (queryId: string, cacheTags: CacheTag[]) => {
+  await sql.query(
+    `INSERT INTO query_cache_tags VALUES ${cacheTags.map((cacheTag) => `('${queryId}', '${cacheTag}')`).join()} ON CONFLICT DO NOTHING`,
+  );
+};
+
+/**
+ * Retrieves the queries that reference cache tags.
+ *
+ * @param {CacheTag[]} cacheTags Array of cache tags
+ * @returns Array of query IDs
+ */
+
+export const queriesReferencingCacheTags = async (cacheTags: CacheTag[]): Promise<string[]> => {
+  const { rows }: { rows: { query_id: string }[] } = await sql.query(
+    `SELECT DISTINCT query_id FROM query_cache_tags WHERE cache_tag IN (${cacheTags.map((cacheTag) => `'${cacheTag}'`).join(', ')})`,
+  );
+
+  return rows.map((row) => row.query_id);
+};
+
+/**
+ * Deletes the cache tags of a query from the database.
+ *
+ * @param {string} queryId Unique query ID
+ */
+
+export const deleteQueries = async (queryIds: string[]) => {
+  await sql.query(`DELETE FROM query_cache_tags WHERE query_id IN (${queryIds.map((id) => `'${id}'`).join(', ')})`);
+};

package/src/classnames.ts

@@ -0,0 +1,8 @@
+/**
+ * Cleans and joins an array of inputs with possible undefined or boolean values.
+ *
+ * @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

@@ -0,0 +1,3 @@
+export * from './cache-tags';
+export * from './classnames';
+export * from './types';

package/src/types.ts

@@ -0,0 +1 @@
+export type CacheTag = string & { readonly _: unique symbol };

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "./dist/",
+    "rootDirs": ["./src"],
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitReturns": true,
+    "noImplicitAny": true,
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "module": "esnext",
+    "target": "esnext"
+  },
+  "include": ["./src/**/*"]
+}