Clean up and document exported types

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

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;

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

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';

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;
+};