Merged in feat/common-package (pull request #2333)

feat: Add common package

* Add isEdge, safeTry and dataCache to new common package

* Add eslint and move prettier config

* Fix yarn lock

* Clean up tests

* Add lint-staged config to common

* Add missing dependencies


Approved-by: Joakim Jäderberg

packages/common/dataCache/Cache.ts

@@ -0,0 +1,102 @@
+import type { CacheOrGetOptions } from "./cacheOrGetOptions"
+
+const ONE_HOUR_IN_SECONDS = 3_600 as const
+const ONE_DAY_IN_SECONDS = 86_400 as const
+
+export const namedCacheTimeMap: Record<NamedCacheTimes, number> = {
+  "no cache": 0,
+  "1m": 60,
+  "5m": 300,
+  "10m": 600,
+  "1h": ONE_HOUR_IN_SECONDS,
+  "3h": ONE_HOUR_IN_SECONDS * 3,
+  "6h": ONE_HOUR_IN_SECONDS * 6,
+  "1d": ONE_DAY_IN_SECONDS,
+  "3d": ONE_DAY_IN_SECONDS * 3,
+  max: ONE_DAY_IN_SECONDS * 30,
+} as const
+
+export const namedCacheTimes = [
+  "no cache",
+  "1m",
+  "5m",
+  "10m",
+  "1h",
+  "3h",
+  "6h",
+  "1d",
+  "3d",
+  "max",
+] as const
+
+export type NamedCacheTimes = (typeof namedCacheTimes)[number]
+
+/**
+ * Retrieves the cache time in seconds based on the given cache time.
+ * @param cacheTime - The time value to determine, either a named cache time or a number of seconds.
+ * @returns The cache time in seconds.
+ */
+export const getCacheTimeInSeconds = (cacheTime: CacheTime): number => {
+  if (typeof cacheTime === "number") {
+    if (cacheTime < 0 || !Number.isInteger(cacheTime)) {
+      return 0
+    }
+
+    return cacheTime
+  }
+
+  return namedCacheTimeMap[cacheTime] ?? 0
+}
+
+export type CacheTime = NamedCacheTimes | number
+
+export type DataCache = {
+  /**
+   * Type of cache
+   */
+  type: "edge" | "redis" | "in-memory" | "unstable-cache"
+
+  /**
+   * Helper function that retrieves from the cache if it exists, otherwise calls the callback and caches the result.
+   * If the call fails, the cache is not updated.
+   * @param key The cache key
+   * @param getDataFromSource An async function that provides a value to cache
+   * @param ttl Time to live, either a named cache time or a number of seconds
+   * @param opts Options to control cache behavior when retrieving or storing data.
+   * @returns The cached value or the result from the callback
+   */
+  cacheOrGet: <T>(
+    key: string | string[],
+    getDataFromSource: (
+      overrideTTL?: (cacheTime: CacheTime) => void
+    ) => Promise<T>,
+    ttl: CacheTime,
+    opts?: CacheOrGetOptions
+  ) => Promise<T>
+
+  /**
+   * Get a value from the cache, if it exists
+   * @see `cacheOrGet` for a more convenient way to cache values
+   * @param key The cache key to retrieve the value for
+   * @returns The cached value or undefined if not found
+   */
+  get: <T>(key: string) => Promise<T | undefined>
+
+  /**
+   * Sets a value in the cache.
+   * @see `cacheOrGet` for a more convenient way to cache values
+   * @param key CacheKey to set
+   * @param obj Value to be cached
+   * @param ttl Time to live, either a named cache time or a number of seconds
+   * @returns A promise that resolves when the value has been cached
+   */
+  set: <T>(key: string, obj: T, ttl: CacheTime) => Promise<void>
+
+  /**
+   * Deletes a key from the cache
+   * @param key CacheKey to delete
+   * @param fuzzy If true, does a wildcard delete. *key*
+   * @returns
+   */
+  deleteKey: (key: string, opts?: { fuzzy?: boolean }) => Promise<void>
+}

packages/common/dataCache/DistributedCache/cacheOrGet.ts

@@ -0,0 +1,50 @@
+import {
+  type CacheOrGetOptions,
+  shouldGetFromCache,
+} from "../cacheOrGetOptions"
+import { cacheLogger } from "../logger"
+import { generateCacheKey } from "./generateCacheKey"
+import { get } from "./get"
+import { set } from "./set"
+
+import type { CacheTime, DataCache } from "../Cache"
+
+export const cacheOrGet: DataCache["cacheOrGet"] = async <T>(
+  key: string | string[],
+  callback: (overrideTTL: (cacheTime: CacheTime) => void) => Promise<T>,
+  ttl: CacheTime,
+  opts?: CacheOrGetOptions
+) => {
+  const cacheKey = generateCacheKey(key, {
+    includeGitHashInKey: opts?.includeGitHashInKey ?? true,
+  })
+
+  let cachedValue: Awaited<T> | undefined = undefined
+  if (shouldGetFromCache(opts)) {
+    cachedValue = await get<T>(cacheKey)
+  }
+
+  let realTTL = ttl
+
+  const overrideTTL = function (cacheTime: CacheTime) {
+    realTTL = cacheTime
+  }
+
+  if (!cachedValue) {
+    const perf = performance.now()
+    const data = await callback(overrideTTL)
+
+    const size = JSON.stringify(data).length / (1024 * 1024)
+    if (size >= 5) {
+      cacheLogger.warn(`'${key}' is larger than 5MB!`)
+    }
+    cacheLogger.debug(
+      `Fetching data took ${(performance.now() - perf).toFixed(2)}ms ${size.toFixed(4)}MB for '${key}'`
+    )
+
+    await set<T>(cacheKey, data, realTTL)
+    return data
+  }
+
+  return cachedValue
+}

packages/common/dataCache/DistributedCache/client.ts

@@ -0,0 +1,18 @@
+import { env } from "../../env/server"
+import { cacheOrGet } from "./cacheOrGet"
+import { deleteKey } from "./deleteKey"
+import { get } from "./get"
+import { set } from "./set"
+
+import type { DataCache } from "../Cache"
+
+export const API_KEY = env.REDIS_API_KEY ?? ""
+export async function createDistributedCache(): Promise<DataCache> {
+  return {
+    type: "redis",
+    get,
+    set,
+    cacheOrGet,
+    deleteKey,
+  } satisfies DataCache
+}

packages/common/dataCache/DistributedCache/deleteKey.ts

@@ -0,0 +1,45 @@
+import * as Sentry from "@sentry/nextjs"
+
+import { safeTry } from "@scandic-hotels/common/utils/safeTry"
+
+import { cacheLogger } from "../logger"
+import { API_KEY } from "./client"
+import { getCacheEndpoint } from "./endpoints"
+
+export async function deleteKey(key: string, opts?: { fuzzy?: boolean }) {
+  const perf = performance.now()
+  const endpoint = getCacheEndpoint(key)
+
+  if (opts?.fuzzy) {
+    endpoint.searchParams.set("fuzzy", "true")
+  }
+
+  const [response, error] = await safeTry(
+    fetch(endpoint, {
+      method: "DELETE",
+      cache: "no-cache",
+      headers: {
+        "x-api-key": API_KEY,
+      },
+      signal: AbortSignal.timeout(10_000),
+    })
+  )
+
+  if (!response || !response.ok || error) {
+    if (response?.status !== 404) {
+      Sentry.captureException(error ?? new Error("Unable to DELETE cachekey"), {
+        extra: {
+          cacheKey: key,
+          statusCode: response?.status,
+          statusText: response?.statusText,
+        },
+      })
+    }
+
+    return undefined
+  }
+
+  cacheLogger.debug(
+    `Delete '${key}' took ${(performance.now() - perf).toFixed(2)}ms`
+  )
+}

packages/common/dataCache/DistributedCache/endpoints.ts

@@ -0,0 +1,12 @@
+import { env } from "../../env/server"
+
+export function getCacheEndpoint(key: string) {
+  if (!env.REDIS_API_HOST) {
+    throw new Error("REDIS_API_HOST is not set")
+  }
+
+  const url = new URL(`/api/cache`, env.REDIS_API_HOST)
+  url.searchParams.set("key", encodeURIComponent(key))
+
+  return url
+}

packages/common/dataCache/DistributedCache/generateCacheKey/getBranchPrefix.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest"
+
+import { getBranchPrefix } from "./getBranchPrefix"
+
+describe("getBranchPrefix", () => {
+  it("should return empty string for production branches", () => {
+    expect(getBranchPrefix("production")).toBe("")
+    expect(getBranchPrefix("prod")).toBe("")
+    expect(getBranchPrefix("release")).toBe("")
+    expect(getBranchPrefix("release-v1")).toBe("")
+    expect(getBranchPrefix("release-v1.2")).toBe("")
+    expect(getBranchPrefix("release-v1.2.3")).toBe("")
+    expect(getBranchPrefix("release-v1.2.3-rc1")).toBe("")
+    expect(getBranchPrefix("release-v1.2-beta")).toBe("")
+    expect(getBranchPrefix("release-v1-preview")).toBe("")
+  })
+
+  it("should return branch name for non-production branches", () => {
+    expect(getBranchPrefix("feature/hello")).toBe("feature/hello")
+    expect(getBranchPrefix("fix/stuff")).toBe("fix/stuff")
+    expect(getBranchPrefix("releasee")).toBe("releasee")
+    expect(getBranchPrefix("release-vA")).toBe("release-vA")
+    expect(getBranchPrefix("release-v1.A")).toBe("release-v1.A")
+    expect(getBranchPrefix("release-v1.2.A")).toBe("release-v1.2.A")
+    expect(getBranchPrefix("release-v1.2.A-rc1")).toBe("release-v1.2.A-rc1")
+    expect(getBranchPrefix("release-v1.A-beta")).toBe("release-v1.A-beta")
+    expect(getBranchPrefix("release-vA-preview")).toBe("release-vA-preview")
+  })
+})

packages/common/dataCache/DistributedCache/generateCacheKey/getBranchPrefix.ts

@@ -0,0 +1,26 @@
+/**
+ * This will match release branches
+ * @example
+ * release-v1.2.3
+ * release-v1.2
+ * release-v1
+ * release-v1.2.3-alpha
+ * release-v1.2-beta
+ * release-v1-preview
+ */
+const releaseRegex = /^release-v\d+(?:\.\d+){0,2}(?:-\w+)?$/
+
+/**
+ * If the branch is a production branch reuse the same prefix so that we can reuse the cache between pre-prod and prod
+ * @param branch
+ * @returns
+ */
+export const getBranchPrefix = (branch: string) => {
+  const isProdBranch =
+    branch === "production" ||
+    branch === "prod" ||
+    branch === "release" ||
+    releaseRegex.test(branch)
+
+  return isProdBranch ? "" : branch
+}

packages/common/dataCache/DistributedCache/generateCacheKey/getPrefix.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+vi.mock("@/env/server", () => ({
+  env: {
+    NODE_ENV: "test",
+  },
+}))
+
+import { env } from "../../../env/server"
+import { getPrefix } from "./getPrefix"
+
+const mockedEnv = env as { BRANCH: string; GIT_SHA: string }
+
+describe("getPrefix", () => {
+  beforeEach(() => {
+    vi.resetModules()
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it.each([
+    "prod",
+    "production",
+    "release",
+    "release-v1",
+    "release-v2",
+    "release-v2-alpha",
+    "release-v2.1-alpha",
+    "release-v2.1.2-alpha",
+  ])(
+    "should return gitsha for production branches when name is '%s'",
+    (branchName: string) => {
+      mockedEnv.BRANCH = branchName
+      mockedEnv.GIT_SHA = "gitsha"
+
+      const result = getPrefix({
+        includeGitHashInKey: true,
+        includeBranchPrefix: true,
+      })
+
+      expect(result).toBe("gitsha")
+    }
+  )
+
+  it.each([
+    "fix/stuff",
+    "feat/my-feature",
+    "feature/my-feature",
+    "releasee",
+    "release-vA",
+    "FEAT",
+  ])(
+    "should return branch name and gitsha for non-production branches when name is '%s'",
+    (branchName: string) => {
+      mockedEnv.BRANCH = branchName
+      mockedEnv.GIT_SHA = "gitsha"
+
+      const result = getPrefix({
+        includeGitHashInKey: true,
+        includeBranchPrefix: true,
+      })
+
+      expect(result).toBe(`${"gitsha"}:${branchName}`)
+    }
+  )
+
+  it("should throw if BRANCH and/or GIT_SHA is not set", () => {
+    mockedEnv.BRANCH = "hasBranch"
+    mockedEnv.GIT_SHA = ""
+
+    expect(() =>
+      getPrefix({
+        includeBranchPrefix: true,
+        includeGitHashInKey: true,
+      })
+    ).toThrow("Unable to getPrefix, GIT_SHA must be set")
+
+    mockedEnv.BRANCH = ""
+    mockedEnv.GIT_SHA = "hasGitSha"
+
+    expect(() =>
+      getPrefix({
+        includeBranchPrefix: true,
+        includeGitHashInKey: true,
+      })
+    ).toThrow("Unable to getPrefix, BRANCH must be set")
+  })
+
+  it("should return dev or local user if running locally", () => {
+    vi.stubEnv("NODE_ENV", "development")
+    vi.stubEnv("USER", "test_user")
+    vi.stubEnv("USERNAME", "test_username")
+
+    mockedEnv.BRANCH = ""
+    mockedEnv.GIT_SHA = ""
+
+    expect(
+      getPrefix({
+        includeGitHashInKey: false,
+        includeBranchPrefix: false,
+      })
+    ).toBe("test_user")
+
+    process.env.USER = ""
+
+    expect(
+      getPrefix({
+        includeGitHashInKey: false,
+        includeBranchPrefix: false,
+      })
+    ).toBe("test_username")
+
+    process.env.USERNAME = ""
+    expect(
+      getPrefix({
+        includeGitHashInKey: false,
+        includeBranchPrefix: false,
+      })
+    ).toBe("dev")
+  })
+})

packages/common/dataCache/DistributedCache/generateCacheKey/getPrefix.ts

@@ -0,0 +1,41 @@
+import { env } from "../../../env/server"
+import { getBranchPrefix } from "./getBranchPrefix"
+
+export function getPrefix(options: {
+  includeGitHashInKey: boolean
+  includeBranchPrefix: boolean
+}): string {
+  const prefixTokens = []
+
+  const includeGitHashInKey = options.includeGitHashInKey
+  const includeBranchPrefix = options.includeBranchPrefix
+
+  if (process.env.NODE_ENV === "development") {
+    const devPrefix = process.env.USER || process.env.USERNAME || "dev"
+    return `${devPrefix}`
+  }
+
+  if (includeGitHashInKey) {
+    const gitSha = env.GIT_SHA?.trim().substring(0, 7)
+
+    if (!gitSha) {
+      throw new Error("Unable to getPrefix, GIT_SHA must be set")
+    }
+
+    prefixTokens.push(gitSha)
+  }
+
+  if (includeBranchPrefix) {
+    const branch = env.BRANCH?.trim()
+
+    if (!branch) {
+      throw new Error("Unable to getPrefix, BRANCH must be set")
+    }
+    const branchPrefix = getBranchPrefix(branch)
+    if (branchPrefix) {
+      prefixTokens.push(branchPrefix)
+    }
+  }
+
+  return prefixTokens.join(":")
+}

packages/common/dataCache/DistributedCache/generateCacheKey/index.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from "vitest"
+
+vi.mock("./getPrefix", () => ({
+  getPrefix: vi.fn(() => "gitsha"),
+}))
+
+import { generateCacheKey } from "./index"
+
+describe("generateCacheKey", () => {
+  beforeEach(() => {
+    vi.resetModules()
+  })
+
+  it("generates cachekey with prefix and key using string", () => {
+    expect(generateCacheKey("key1")).toBe("gitsha:key1")
+  })
+
+  it("generates cachekey with prefix and key using array", () => {
+    expect(generateCacheKey(["key1"])).toBe("gitsha:key1")
+  })
+
+  it("generates cachekey with prefix and keys", () => {
+    const actual = generateCacheKey(["key1", "key2"])
+    expect(actual).toBe("gitsha:key1_key2")
+  })
+
+  it("should throw an error if no keys are provided", () => {
+    expect(() => generateCacheKey([])).toThrow("No keys provided")
+  })
+
+  it("should throw an error if only invalid keys are provided", () => {
+    expect(() => generateCacheKey(["", undefined, null] as string[])).toThrow(
+      "No keys provided"
+    )
+    expect(() => generateCacheKey("")).toThrow("No keys provided")
+  })
+})

packages/common/dataCache/DistributedCache/generateCacheKey/index.ts

@@ -0,0 +1,22 @@
+import { getPrefix } from "./getPrefix"
+
+export function generateCacheKey(
+  key: string | string[],
+  options?: { includeGitHashInKey?: boolean }
+): string {
+  const includeGitHashInKey = options?.includeGitHashInKey ?? true
+  const keyArray = (Array.isArray(key) ? key : [key]).filter(Boolean)
+
+  if (keyArray.length === 0) {
+    throw new Error("No keys provided")
+  }
+
+  const prefix = getPrefix({
+    includeGitHashInKey,
+    includeBranchPrefix: true,
+  })
+
+  const keyTokens = [prefix, keyArray.join("_")].filter(Boolean).join(":")
+
+  return keyTokens
+}

packages/common/dataCache/DistributedCache/get.ts

@@ -0,0 +1,61 @@
+import * as Sentry from "@sentry/nextjs"
+
+import { safeTry } from "@scandic-hotels/common/utils/safeTry"
+
+import { cacheLogger } from "../logger"
+import { API_KEY } from "./client"
+import { deleteKey } from "./deleteKey"
+import { getCacheEndpoint } from "./endpoints"
+
+export async function get<T>(key: string) {
+  const perf = performance.now()
+
+  const [response, error] = await safeTry(
+    fetch(getCacheEndpoint(key), {
+      method: "GET",
+      cache: "no-cache",
+      headers: {
+        "x-api-key": API_KEY,
+      },
+      signal: AbortSignal.timeout(3_000),
+    })
+  )
+
+  if (!response || !response.ok || error) {
+    if (response?.status === 404) {
+      cacheLogger.debug(
+        `Miss '${key}' took ${(performance.now() - perf).toFixed(2)}ms`
+      )
+      return undefined
+    }
+
+    Sentry.captureException(error ?? new Error("Unable to GET cachekey"), {
+      extra: {
+        cacheKey: key,
+        statusCode: response?.status,
+        statusText: response?.statusText,
+      },
+    })
+    return undefined
+  }
+
+  const [data, jsonError] = await safeTry(
+    response.json() as Promise<{ data: T }>
+  )
+
+  if (jsonError) {
+    cacheLogger.error("Failed to parse cache response", {
+      key,
+      error: jsonError,
+    })
+
+    await deleteKey(key)
+    return undefined
+  }
+
+  cacheLogger.debug(
+    `Hit '${key}' took ${(performance.now() - perf).toFixed(2)}ms`
+  )
+
+  return data?.data
+}

packages/common/dataCache/DistributedCache/index.ts

@@ -0,0 +1 @@
+export { createDistributedCache } from "./client"

packages/common/dataCache/DistributedCache/set.ts

@@ -0,0 +1,32 @@
+import * as Sentry from "@sentry/nextjs"
+
+import { safeTry } from "@scandic-hotels/common/utils/safeTry"
+
+import { type CacheTime, getCacheTimeInSeconds } from "../Cache"
+import { API_KEY } from "./client"
+import { getCacheEndpoint } from "./endpoints"
+
+export async function set<T>(key: string, value: T, ttl: CacheTime) {
+  const [response, error] = await safeTry(
+    fetch(getCacheEndpoint(key), {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": API_KEY,
+      },
+      body: JSON.stringify({ data: value, ttl: getCacheTimeInSeconds(ttl) }),
+      cache: "no-cache",
+      signal: AbortSignal.timeout(3_000),
+    })
+  )
+
+  if (!response || !response.ok || error) {
+    Sentry.captureException(error ?? new Error("Unable to SET cachekey"), {
+      extra: {
+        cacheKey: key,
+        statusCode: response?.status,
+        statusText: response?.statusText,
+      },
+    })
+  }
+}

packages/common/dataCache/MemoryCache/InMemoryCache/cacheMap.ts

@@ -0,0 +1,9 @@
+export const cacheMap = new Map<
+  string,
+  {
+    /** Absolute expiration timestamp (`Date.now()`) */
+    expiresAt: number
+    /** The cached data */
+    data: unknown
+  }
+>()

packages/common/dataCache/MemoryCache/InMemoryCache/cacheOrGet.ts

@@ -0,0 +1,48 @@
+import {
+  type CacheOrGetOptions,
+  shouldGetFromCache,
+} from "../../cacheOrGetOptions"
+import { cacheLogger } from "../../logger"
+import { get } from "./get"
+import { set } from "./set"
+
+import type { CacheTime, DataCache } from "../../Cache"
+
+export const cacheOrGet: DataCache["cacheOrGet"] = async <T>(
+  key: string | string[],
+  callback: (overrideTTL?: (cacheTime: CacheTime) => void) => Promise<T>,
+  ttl: CacheTime,
+  opts?: CacheOrGetOptions
+): Promise<T> => {
+  if (Array.isArray(key)) {
+    key = key.join("-")
+  }
+
+  let realTTL = ttl
+  const overrideTTL = function (cacheTime: CacheTime) {
+    realTTL = cacheTime
+  }
+
+  let cached: Awaited<T> | undefined = undefined
+  if (shouldGetFromCache(opts)) {
+    cached = await get(key)
+    if (cached) {
+      return cached
+    }
+
+    cacheLogger.debug(`Miss for key '${key}'`)
+  }
+
+  try {
+    const data = await callback(overrideTTL)
+    await set(key, data, realTTL)
+
+    return data
+  } catch (e) {
+    cacheLogger.error(
+      `Error while fetching data for key '${key}', avoid caching`,
+      e
+    )
+    throw e
+  }
+}

packages/common/dataCache/MemoryCache/InMemoryCache/deleteKey.ts

@@ -0,0 +1,16 @@
+import { cacheLogger } from "../../logger"
+import { cacheMap } from "./cacheMap"
+
+export async function deleteKey(key: string, opts?: { fuzzy?: boolean }) {
+  cacheLogger.debug("Deleting key", key)
+  if (opts?.fuzzy) {
+    cacheMap.forEach((_, k) => {
+      if (k.includes(key)) {
+        cacheMap.delete(k)
+      }
+    })
+    return
+  }
+
+  cacheMap.delete(key)
+}

packages/common/dataCache/MemoryCache/InMemoryCache/get.ts

@@ -0,0 +1,22 @@
+import { cacheLogger } from "../../logger"
+import { cacheMap } from "./cacheMap"
+
+export async function get<T>(key: string): Promise<T | undefined> {
+  const cached = cacheMap.get(key)
+  if (!cached) {
+    return undefined
+  }
+
+  if (cached.expiresAt < Date.now()) {
+    cacheLogger.debug(`Expired for key '${key}'`)
+    cacheMap.delete(key)
+    return undefined
+  }
+  if (cached.data === undefined) {
+    cacheLogger.debug(`Data is undefined for key '${key}'`)
+    cacheMap.delete(key)
+    return undefined
+  }
+
+  return cached.data as T
+}

packages/common/dataCache/MemoryCache/InMemoryCache/index.ts

@@ -0,0 +1,10 @@
+import { cacheOrGet } from "./cacheOrGet"
+import { deleteKey } from "./deleteKey"
+import { get } from "./get"
+import { set } from "./set"
+
+import type { DataCache } from "../../Cache"
+
+export async function createInMemoryCache(): Promise<DataCache> {
+  return { type: "in-memory", cacheOrGet, deleteKey, get, set }
+}

packages/common/dataCache/MemoryCache/InMemoryCache/set.ts

@@ -0,0 +1,13 @@
+import { type CacheTime, getCacheTimeInSeconds } from "../../Cache"
+import { cacheMap } from "./cacheMap"
+
+export async function set<T>(
+  key: string,
+  data: T,
+  ttl: CacheTime
+): Promise<void> {
+  cacheMap.set(key, {
+    data: data,
+    expiresAt: Date.now() + getCacheTimeInSeconds(ttl) * 1000,
+  })
+}

packages/common/dataCache/MemoryCache/createMemoryCache.ts

@@ -0,0 +1,6 @@
+import { type DataCache } from "../Cache"
+import { createInMemoryCache } from "./InMemoryCache"
+
+export function createMemoryCache(): Promise<DataCache> {
+  return createInMemoryCache()
+}

packages/common/dataCache/cacheOrGetOptions.ts

@@ -0,0 +1,28 @@
+/**
+ * Options to control cache behavior when retrieving or storing data.
+ *
+ * - "cache-first": Default behaviour, check if the needed data is available in the cache first. If the data is found, it is returned immediately. Otherwise, the data is fetched and then cached.
+ * - "fetch-then-cache": Always fetch the data first, and then update the cache with the freshly fetched data.
+ */
+export type CacheStrategy = "cache-first" | "fetch-then-cache"
+export type CacheOrGetOptions = {
+  cacheStrategy?: CacheStrategy
+  includeGitHashInKey?: boolean
+}
+
+export function defaultCacheOrGetOptions(
+  opts: CacheOrGetOptions = {}
+): CacheOrGetOptions {
+  return {
+    cacheStrategy: "cache-first",
+    ...opts,
+  }
+}
+
+export function shouldGetFromCache(
+  opts: CacheOrGetOptions | undefined
+): boolean {
+  opts = defaultCacheOrGetOptions(opts)
+
+  return opts.cacheStrategy === "cache-first"
+}

packages/common/dataCache/index.ts

@@ -0,0 +1,25 @@
+import { env } from "../env/server"
+import { isEdge } from "../utils/isEdge"
+import { createMemoryCache } from "./MemoryCache/createMemoryCache"
+import { type DataCache } from "./Cache"
+import { createDistributedCache } from "./DistributedCache"
+import { cacheLogger } from "./logger"
+
+export type { CacheTime, DataCache } from "./Cache"
+
+export async function getCacheClient(): Promise<DataCache> {
+  if (global.cacheClient) {
+    return global.cacheClient
+  }
+
+  global.cacheClient = env.REDIS_API_HOST
+    ? createDistributedCache()
+    : createMemoryCache()
+
+  const cacheClient = await global.cacheClient
+  cacheLogger.debug(
+    `Creating ${cacheClient.type} cache on ${isEdge ? "edge" : "server"} runtime`
+  )
+
+  return global.cacheClient
+}

packages/common/dataCache/logger.ts

@@ -0,0 +1,44 @@
+export const cacheLogger = {
+  async debug(message: string, ...args: unknown[]): Promise<void> {
+    console.debug(`${await loggerPrefix()} ${message}`, ...args)
+  },
+  async warn(message: string, ...args: unknown[]): Promise<void> {
+    console.warn(`${await loggerPrefix()} Warning - ${message}`, ...args)
+  },
+  async error(message: string, ...args: unknown[]): Promise<void> {
+    console.error(`${await loggerPrefix()} Error - ${message}`, ...args)
+  },
+}
+
+async function loggerPrefix() {
+  const instancePrefix = await getCachePrefix()
+  return `[Cache] ${instancePrefix ?? ""}`.trim()
+}
+
+async function getCachePrefix() {
+  const cacheCreated = await isPromiseResolved(global.cacheClient)
+
+  if (!cacheCreated.resolved) {
+    return null
+  }
+
+  const instanceType = cacheCreated.value?.type
+  if (!instanceType) {
+    return null
+  }
+
+  return `[${instanceType}]`
+}
+
+function isPromiseResolved<T>(promise: Promise<T> | undefined) {
+  if (!promise) {
+    return { resolved: false, value: undefined }
+  }
+
+  const check = Promise.race([promise, Promise.resolve("__PENDING__")])
+
+  return check.then((result) => ({
+    resolved: result !== "__PENDING__",
+    value: result !== "__PENDING__" ? (result as Awaited<T>) : undefined,
+  }))
+}