slonik-interceptor-query-cache 3.3.1 → 3.3.2

package/package.json

@@ -41,6 +41,7 @@
     "node": ">=16.0"
   },
   "files": [
+    "src",
     "dist"
   ],
   "keywords": [
@@ -66,5 +67,5 @@
     "test:ava": "nyc ava --verbose --serial"
   },
   "types": "./dist/index.d.ts",
-  "version": "3.3.1"
+  "version": "3.3.2"
 }

package/src/Logger.ts

@@ -0,0 +1,5 @@
+import { Roarr } from 'roarr';
+
+export const Logger = Roarr.child({
+  package: 'slonik-interceptor-query-cache',
+});

package/src/factories/createQueryCacheInterceptor.ts

@@ -0,0 +1,129 @@
+import { Logger } from '../Logger';
+import { extractCacheAttributes, normalizeCacheAttributes } from '../utilities';
+import {
+  type Interceptor,
+  type Query,
+  type QueryResult,
+  type QueryResultRow,
+} from 'slonik';
+
+const log = Logger.child({
+  namespace: 'createQueryCacheInterceptor',
+});
+
+type Sandbox = {
+  cache: {
+    cacheAttributes: CacheAttributes;
+  };
+};
+
+export type CacheAttributes = {
+  discardEmpty: boolean;
+  key: string;
+  ttl: number;
+};
+
+type Storage = {
+  get: (
+    query: Query,
+    cacheAttributes: CacheAttributes,
+  ) => Promise<QueryResult<QueryResultRow> | null>;
+  set: (
+    query: Query,
+    cacheAttributes: CacheAttributes,
+    queryResult: QueryResult<QueryResultRow>,
+  ) => Promise<void>;
+};
+
+type ConfigurationInput = {
+  storage: Storage;
+};
+
+type Configuration = {
+  storage: Storage;
+};
+
+export const createQueryCacheInterceptor = (
+  configurationInput: ConfigurationInput,
+): Interceptor => {
+  const configuration: Configuration = {
+    ...configurationInput,
+  };
+
+  return {
+    beforeQueryExecution: async (context, query) => {
+      if (context.transactionId) {
+        return null;
+      }
+
+      const cacheAttributes = (context.sandbox as Sandbox).cache
+        ?.cacheAttributes;
+
+      if (!cacheAttributes) {
+        return null;
+      }
+
+      const maybeResult = await configuration.storage.get(
+        query,
+        cacheAttributes,
+      );
+
+      if (maybeResult) {
+        log.debug(
+          {
+            queryId: context.queryId,
+          },
+          'query is served from cache',
+        );
+
+        return maybeResult;
+      }
+
+      return null;
+    },
+    beforeQueryResult: async (context, query, result) => {
+      if (context.transactionId) {
+        return null;
+      }
+
+      const cacheAttributes = (context.sandbox as Sandbox).cache
+        ?.cacheAttributes;
+
+      if (cacheAttributes) {
+        if (cacheAttributes.discardEmpty && result.rowCount === 0) {
+          log.debug(
+            '@cache-discard-empty is set and the query result is empty; not caching',
+          );
+        } else {
+          await configuration.storage.set(query, cacheAttributes, result);
+        }
+      }
+
+      return null;
+    },
+    beforeTransformQuery: async (context, query) => {
+      if (context.transactionId) {
+        return null;
+      }
+
+      const extractedCacheAttributes = extractCacheAttributes(
+        query.sql,
+        query.values,
+      );
+
+      if (!extractedCacheAttributes) {
+        return null;
+      }
+
+      const cacheAttributes = normalizeCacheAttributes(
+        extractedCacheAttributes,
+      );
+
+      context.sandbox.cache = {
+        cacheAttributes,
+      };
+
+      return null;
+    },
+  };
+};

package/src/factories/createQueryContext.ts

@@ -0,0 +1,16 @@
+import { type QueryContext } from 'slonik';
+
+export default () => {
+  return {
+    connectionId: '1',
+    log: {
+      getContext: () => {
+        return {
+          connectionId: '1',
+          poolId: '1',
+        };
+      },
+    },
+    poolId: '1',
+  } as unknown as QueryContext;
+};

package/src/factories/index.ts

@@ -0,0 +1 @@
+export { createQueryCacheInterceptor } from './createQueryCacheInterceptor';

package/src/index.ts

@@ -0,0 +1 @@
+export { createQueryCacheInterceptor } from './factories';

package/src/utilities/extractCacheAttributes.test.ts

@@ -0,0 +1,92 @@
+import { extractCacheAttributes } from './extractCacheAttributes';
+import test from 'ava';
+
+test('returns null when query does not contain cache attributes', (t) => {
+  t.is(extractCacheAttributes('', []), null);
+});
+
+test('extracts @cache-ttl', (t) => {
+  t.deepEqual(extractCacheAttributes('-- @cache-ttl 60', []), {
+    bodyHash: '46b9dd2b0ba88d13233b3feb',
+    discardEmpty: false,
+    key: 'query:$bodyHash:$valueHash',
+    ttl: 60,
+    valueHash: 'ec784925b52067bce01fd820',
+  });
+});
+
+test('extracts @cache-discard-empty', (t) => {
+  t.deepEqual(
+    extractCacheAttributes(
+      '-- @cache-ttl 60\n-- @cache-discard-empty false',
+      [],
+    ),
+    {
+      bodyHash: '46b9dd2b0ba88d13233b3feb',
+      discardEmpty: false,
+      key: 'query:$bodyHash:$valueHash',
+      ttl: 60,
+      valueHash: 'ec784925b52067bce01fd820',
+    },
+  );
+
+  t.deepEqual(
+    extractCacheAttributes(
+      '-- @cache-ttl 60\n-- @cache-discard-empty true',
+      [],
+    ),
+    {
+      bodyHash: '46b9dd2b0ba88d13233b3feb',
+      discardEmpty: true,
+      key: 'query:$bodyHash:$valueHash',
+      ttl: 60,
+      valueHash: 'ec784925b52067bce01fd820',
+    },
+  );
+});
+
+test('computes the parameter value hash', (t) => {
+  t.deepEqual(extractCacheAttributes('-- @cache-ttl 60', [1]), {
+    bodyHash: '46b9dd2b0ba88d13233b3feb',
+    discardEmpty: false,
+    key: 'query:$bodyHash:$valueHash',
+    ttl: 60,
+    valueHash: '62eb54746ae2932850f8d6ff',
+  });
+});
+
+test('computes the body hash; white spaces do not affect the body hash', (t) => {
+  t.deepEqual(extractCacheAttributes('-- @cache-ttl 60\nSELECT 1', []), {
+    bodyHash: '553ebdb024592064ca4c2c3a',
+    discardEmpty: false,
+    key: 'query:$bodyHash:$valueHash',
+    ttl: 60,
+    valueHash: 'ec784925b52067bce01fd820',
+  });
+
+  t.deepEqual(extractCacheAttributes('-- @cache-ttl 60\n\nSELECT 1', []), {
+    bodyHash: '553ebdb024592064ca4c2c3a',
+    discardEmpty: false,
+    key: 'query:$bodyHash:$valueHash',
+    ttl: 60,
+    valueHash: 'ec784925b52067bce01fd820',
+  });
+});
+
+test('computes the body hash; comments do not affect the body hash', (t) => {
+  t.deepEqual(extractCacheAttributes('-- @cache-ttl 60\nSELECT 1', []), {
+    bodyHash: '553ebdb024592064ca4c2c3a',
+    discardEmpty: false,
+    key: 'query:$bodyHash:$valueHash',
+    ttl: 60,
+    valueHash: 'ec784925b52067bce01fd820',
+  });
+
+  t.deepEqual(extractCacheAttributes('-- @cache-ttl 120\nSELECT 1', []), {
+    bodyHash: '553ebdb024592064ca4c2c3a',
+    discardEmpty: false,
+    key: 'query:$bodyHash:$valueHash',
+    ttl: 120,
+    valueHash: 'ec784925b52067bce01fd820',
+  });
+});

package/src/utilities/extractCacheAttributes.ts

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { type PrimitiveValueExpression } from 'slonik';
+import stripComments from 'strip-comments';
+
+const hash = (subject: string) => {
+  return createHash('shake256', {
+    outputLength: 12,
+  })
+    .update(subject)
+    .digest('hex');
+};
+
+export type ExtractedCacheAttributes = {
+  bodyHash: string;
+  discardEmpty: boolean;
+  key: string;
+  ttl: number;
+  valueHash: string;
+};
+
+// TODO throw an error if an unknown attribute is used
+export const extractCacheAttributes = (
+  subject: string,
+  values: readonly PrimitiveValueExpression[],
+): ExtractedCacheAttributes | null => {
+  const ttl = /-- @cache-ttl (\d+)/u.exec(subject)?.[1];
+
+  // https://github.com/jonschlinkert/strip-comments/issues/71
+  const bodyHash = hash(
+    stripComments(subject)
+      .replaceAll(/^\s*--.*$/gmu, '')
+      .replaceAll(/\s/gu, ''),
+  );
+
+  const discardEmpty =
+    (/-- @cache-discard-empty (true|false)/u.exec(subject)?.[1] ?? 'false') ===
+    'true';
+
+  const valueHash = hash(JSON.stringify(values));
+
+  if (ttl) {
+    const key =
+      /-- @cache-key ([$\w\-:/]+)/iu.exec(subject)?.[1] ??
+      'query:$bodyHash:$valueHash';
+
+    return {
+      bodyHash,
+      discardEmpty,
+      key,
+      ttl: Number(ttl),
+      valueHash,
+    };
+  }
+
+  return null;
+};

package/src/utilities/index.ts

@@ -0,0 +1,2 @@
+export { extractCacheAttributes } from './extractCacheAttributes';
+export { normalizeCacheAttributes } from './normalizeCacheAttributes';

package/src/utilities/normalizeCacheAttributes.test.ts

@@ -0,0 +1,19 @@
+import { normalizeCacheAttributes } from './normalizeCacheAttributes';
+import test from 'ava';
+
+test('replaces $bodyHash and $valueHash', (t) => {
+  t.deepEqual(
+    normalizeCacheAttributes({
+      bodyHash: 'foo',
+      discardEmpty: false,
+      key: '$bodyHash:$valueHash',
+      ttl: 60,
+      valueHash: 'bar',
+    }),
+    {
+      discardEmpty: false,
+      key: 'foo:bar',
+      ttl: 60,
+    },
+  );
+});

package/src/utilities/normalizeCacheAttributes.ts

@@ -0,0 +1,14 @@
+import { type CacheAttributes } from '../factories/createQueryCacheInterceptor';
+import { type ExtractedCacheAttributes } from './extractCacheAttributes';
+
+export const normalizeCacheAttributes = (
+  extractedCacheAttributes: ExtractedCacheAttributes,
+): CacheAttributes => {
+  return {
+    discardEmpty: extractedCacheAttributes.discardEmpty,
+    key: extractedCacheAttributes.key
+      .replaceAll('$bodyHash', extractedCacheAttributes.bodyHash)
+      .replaceAll('$valueHash', extractedCacheAttributes.valueHash),
+    ttl: extractedCacheAttributes.ttl,
+  };
+};