From b57fa279c5885e89ff25e757048c28a34724c6df Mon Sep 17 00:00:00 2001
From: Eric Peterson <ericpeterson@spotify.com>
Date: Sun, 2 May 2021 16:45:47 +0200
Subject: [PATCH] Clean up and document exported types

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>
---
 .../backend-common/src/cache/CacheClient.ts   | 21 +++++++++++++
 .../backend-common/src/cache/CacheManager.ts  |  5 +--
 packages/backend-common/src/cache/index.ts    |  3 +-
 packages/backend-common/src/cache/types.ts    | 31 +++++++++++++++++++
 4 files changed, 55 insertions(+), 5 deletions(-)
 create mode 100644 packages/backend-common/src/cache/types.ts

diff --git a/packages/backend-common/src/cache/CacheClient.ts b/packages/backend-common/src/cache/CacheClient.ts
index 9146131a10..0716b159cb 100644
--- a/packages/backend-common/src/cache/CacheClient.ts
+++ b/packages/backend-common/src/cache/CacheClient.ts
@@ -23,12 +23,33 @@ type CacheClientArgs = {
   pluginId: string;
 };
 
+/**
+ * A pre-configured, storage agnostic cache client suitable for use by
+ * Backstage plugins.
+ */
 export interface CacheClient {
+  /**
+   * Reads data from a cache store for the given key.
+   */
   get(key: string): Promise<JsonValue>;
+
+  /**
+   * Writes the given data to a cache store, associated with the given key. An
+   * optional TTL may also be provided, otherwise it defaults to the TTL that
+   * was provided when the client was instantiated.
+   */
   set(key: string, value: JsonValue, ttl?: number): Promise<void>;
+
+  /**
+   * Removes the given key from the cache store.
+   */
   delete(key: string): Promise<void>;
 }
 
+/**
+ * A simple, concrete implementation of the CacheClient, suitable for almost
+ * all uses in Backstage.
+ */
 export class ConcreteCacheClient implements CacheClient {
   private readonly client: cacheManager.Cache;
   private readonly pluginId: string;
diff --git a/packages/backend-common/src/cache/CacheManager.ts b/packages/backend-common/src/cache/CacheManager.ts
index f1c3b279fd..de27bb0e3d 100644
--- a/packages/backend-common/src/cache/CacheManager.ts
+++ b/packages/backend-common/src/cache/CacheManager.ts
@@ -21,10 +21,7 @@ import Memcache from 'memcache-pp';
 // @ts-expect-error
 import memcachedStore from 'cache-manager-memcached-store';
 import { ConcreteCacheClient, CacheClient } from './CacheClient';
-
-export type PluginCacheManager = {
-  getClient: (ttl: number) => CacheClient;
-};
+import { PluginCacheManager } from './types';
 
 /**
  * Implements a Cache Manager which will automatically create new cache clients
diff --git a/packages/backend-common/src/cache/index.ts b/packages/backend-common/src/cache/index.ts
index ba1625d043..c233621bd4 100644
--- a/packages/backend-common/src/cache/index.ts
+++ b/packages/backend-common/src/cache/index.ts
@@ -14,5 +14,6 @@
  * limitations under the License.
  */
 
-export * from './CacheClient';
+export type { CacheClient } from './CacheClient';
 export * from './CacheManager';
+export * from './types';
diff --git a/packages/backend-common/src/cache/types.ts b/packages/backend-common/src/cache/types.ts
new file mode 100644
index 0000000000..f1b9e96709
--- /dev/null
+++ b/packages/backend-common/src/cache/types.ts
@@ -0,0 +1,31 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { CacheClient } from './CacheClient';
+
+/**
+ * The PluginCacheManager manages access to cache stores that Plugins get.
+ */
+export type PluginCacheManager = {
+  /**
+   * getClient provides backend plugins cache connections for itself.
+   *
+   * The purpose of this method is to allow plugins to get isolated data
+   * stores so that plugins are discouraged from cache-level integration
+   * and/or cache key collisions.
+   */
+  getClient: (ttl: number) => CacheClient;
+};