@backstage/backend-plugin-api 0.0.0-nightly-20230209023017 → 0.0.0-nightly-20230211022721

package/CHANGELOG.md

@@ -1,12 +1,13 @@
 # @backstage/backend-plugin-api
 
-## 0.0.0-nightly-20230209023017
+## 0.0.0-nightly-20230211022721
 
 ### Minor Changes
 
 - e716946103: **BREAKING**: Split out the hook for both lifecycle services so that the first parameter of `addShutdownHook` is the hook function, and the second is the options.
 - 0ff03319be: **BREAKING**: The plugin ID option passed to `createBackendPlugin` is now `pluginId`, rather than just `id`. This is to make it match `createBackendModule` more closely.
 - 71a5ec0f06: **BREAKING**: Switched out `LogMeta` type for `JsonObject`.
+- 5febb216fe: **BREAKING**: The `CacheService` has been changed to remove the indirection of `getClient`, instead making the `CacheClient` methods directly available on the `CacheService`. In order to allow for the creation of clients with default options, there is now a new `.withOptions` method that must be implemented as part of the service interface.
 - b86efa2d04: Switch `ServiceFactory` to be an opaque type, keeping only the `service` field as public API, but also adding a type parameter for the service scope.
 - 610d65e143: Switched `BackendFeature` to be an opaque type.
 
@@ -21,10 +22,10 @@
   dependencies to plugins (should only ever be done for modules). This has no
   practical effect on code that was already well behaved.
 - Updated dependencies
-  - @backstage/backend-tasks@0.0.0-nightly-20230209023017
+  - @backstage/backend-tasks@0.0.0-nightly-20230211022721
   - @backstage/config@1.0.6
   - @backstage/types@1.0.2
-  - @backstage/plugin-auth-node@0.0.0-nightly-20230209023017
+  - @backstage/plugin-auth-node@0.0.0-nightly-20230211022721
   - @backstage/plugin-permission-common@0.7.3
 
 ## 0.4.0-next.2

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "0.0.0-nightly-20230209023017",
+  "version": "0.0.0-nightly-20230211022721",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.d.ts

@@ -93,35 +93,39 @@ export declare interface BackendPluginRegistrationPoints {
 }
 
 /**
- * A pre-configured, storage agnostic cache client suitable for use by
+ * A pre-configured, storage agnostic cache service suitable for use by
  * Backstage plugins.
  *
  * @public
  */
-export declare interface CacheClient {
+export declare interface CacheService {
     /**
      * Reads data from a cache store for the given key. If no data was found,
      * returns undefined.
      */
-    get(key: string): Promise<JsonValue | undefined>;
+    get<TValue extends JsonValue>(key: string): Promise<TValue | undefined>;
     /**
      * 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, options?: CacheClientSetOptions): Promise<void>;
+    set(key: string, value: JsonValue, options?: CacheServiceSetOptions): Promise<void>;
     /**
      * Removes the given key from the cache store.
      */
     delete(key: string): Promise<void>;
+    /**
+     * Creates a new {@link CacheService} instance with the given options.
+     */
+    withOptions(options: CacheServiceOptions): CacheService;
 }
 
 /**
- * Options given when constructing a {@link CacheClient}.
+ * Options passed to {@link CacheService.withOptions}.
  *
  * @public
  */
-export declare type CacheClientOptions = {
+export declare type CacheServiceOptions = {
     /**
      * An optional default TTL (in milliseconds) to be set when getting a client
      * instance. If not provided, data will persist indefinitely by default (or
@@ -131,11 +135,11 @@ export declare type CacheClientOptions = {
 };
 
 /**
- * Options passed to {@link CacheClient.set}.
+ * Options passed to {@link CacheService.set}.
  *
  * @public
  */
-export declare type CacheClientSetOptions = {
+export declare type CacheServiceSetOptions = {
     /**
      * Optional TTL in milliseconds. Defaults to the TTL provided when the client
      * was set up (or no TTL if none are provided).
@@ -143,24 +147,6 @@ export declare type CacheClientSetOptions = {
     ttl?: number;
 };
 
-/**
- * Manages access to cache stores that plugins get.
- *
- * @public
- */
-export declare interface CacheService {
-    /**
-     * Provides backend plugins cache connections for themselves.
-     *
-     * @remarks
-     *
-     * 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: (options?: CacheClientOptions) => CacheClient;
-}
-
 /**
  * @public
  */

package/dist/index.beta.d.ts

@@ -93,35 +93,39 @@ export declare interface BackendPluginRegistrationPoints {
 }
 
 /**
- * A pre-configured, storage agnostic cache client suitable for use by
+ * A pre-configured, storage agnostic cache service suitable for use by
  * Backstage plugins.
  *
  * @public
  */
-export declare interface CacheClient {
+export declare interface CacheService {
     /**
      * Reads data from a cache store for the given key. If no data was found,
      * returns undefined.
      */
-    get(key: string): Promise<JsonValue | undefined>;
+    get<TValue extends JsonValue>(key: string): Promise<TValue | undefined>;
     /**
      * 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, options?: CacheClientSetOptions): Promise<void>;
+    set(key: string, value: JsonValue, options?: CacheServiceSetOptions): Promise<void>;
     /**
      * Removes the given key from the cache store.
      */
     delete(key: string): Promise<void>;
+    /**
+     * Creates a new {@link CacheService} instance with the given options.
+     */
+    withOptions(options: CacheServiceOptions): CacheService;
 }
 
 /**
- * Options given when constructing a {@link CacheClient}.
+ * Options passed to {@link CacheService.withOptions}.
  *
  * @public
  */
-export declare type CacheClientOptions = {
+export declare type CacheServiceOptions = {
     /**
      * An optional default TTL (in milliseconds) to be set when getting a client
      * instance. If not provided, data will persist indefinitely by default (or
@@ -131,11 +135,11 @@ export declare type CacheClientOptions = {
 };
 
 /**
- * Options passed to {@link CacheClient.set}.
+ * Options passed to {@link CacheService.set}.
  *
  * @public
  */
-export declare type CacheClientSetOptions = {
+export declare type CacheServiceSetOptions = {
     /**
      * Optional TTL in milliseconds. Defaults to the TTL provided when the client
      * was set up (or no TTL if none are provided).
@@ -143,24 +147,6 @@ export declare type CacheClientSetOptions = {
     ttl?: number;
 };
 
-/**
- * Manages access to cache stores that plugins get.
- *
- * @public
- */
-export declare interface CacheService {
-    /**
-     * Provides backend plugins cache connections for themselves.
-     *
-     * @remarks
-     *
-     * 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: (options?: CacheClientOptions) => CacheClient;
-}
-
 /**
  * @public
  */

package/dist/index.d.ts

@@ -93,35 +93,39 @@ export declare interface BackendPluginRegistrationPoints {
 }
 
 /**
- * A pre-configured, storage agnostic cache client suitable for use by
+ * A pre-configured, storage agnostic cache service suitable for use by
  * Backstage plugins.
  *
  * @public
  */
-export declare interface CacheClient {
+export declare interface CacheService {
     /**
      * Reads data from a cache store for the given key. If no data was found,
      * returns undefined.
      */
-    get(key: string): Promise<JsonValue | undefined>;
+    get<TValue extends JsonValue>(key: string): Promise<TValue | undefined>;
     /**
      * 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, options?: CacheClientSetOptions): Promise<void>;
+    set(key: string, value: JsonValue, options?: CacheServiceSetOptions): Promise<void>;
     /**
      * Removes the given key from the cache store.
      */
     delete(key: string): Promise<void>;
+    /**
+     * Creates a new {@link CacheService} instance with the given options.
+     */
+    withOptions(options: CacheServiceOptions): CacheService;
 }
 
 /**
- * Options given when constructing a {@link CacheClient}.
+ * Options passed to {@link CacheService.withOptions}.
  *
  * @public
  */
-export declare type CacheClientOptions = {
+export declare type CacheServiceOptions = {
     /**
      * An optional default TTL (in milliseconds) to be set when getting a client
      * instance. If not provided, data will persist indefinitely by default (or
@@ -131,11 +135,11 @@ export declare type CacheClientOptions = {
 };
 
 /**
- * Options passed to {@link CacheClient.set}.
+ * Options passed to {@link CacheService.set}.
  *
  * @public
  */
-export declare type CacheClientSetOptions = {
+export declare type CacheServiceSetOptions = {
     /**
      * Optional TTL in milliseconds. Defaults to the TTL provided when the client
      * was set up (or no TTL if none are provided).
@@ -143,24 +147,6 @@ export declare type CacheClientSetOptions = {
     ttl?: number;
 };
 
-/**
- * Manages access to cache stores that plugins get.
- *
- * @public
- */
-export declare interface CacheService {
-    /**
-     * Provides backend plugins cache connections for themselves.
-     *
-     * @remarks
-     *
-     * 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: (options?: CacheClientOptions) => CacheClient;
-}
-
 /**
  * @public
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/backend-plugin-api",
   "description": "Core API used by Backstage backend plugins",
-  "version": "0.0.0-nightly-20230209023017",
+  "version": "0.0.0-nightly-20230211022721",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
@@ -33,9 +33,9 @@
     "start": "backstage-cli package start"
   },
   "dependencies": {
-    "@backstage/backend-tasks": "^0.0.0-nightly-20230209023017",
+    "@backstage/backend-tasks": "^0.0.0-nightly-20230211022721",
     "@backstage/config": "^1.0.6",
-    "@backstage/plugin-auth-node": "^0.0.0-nightly-20230209023017",
+    "@backstage/plugin-auth-node": "^0.0.0-nightly-20230211022721",
     "@backstage/plugin-permission-common": "^0.7.3",
     "@backstage/types": "^1.0.2",
     "@types/express": "^4.17.6",
@@ -43,7 +43,7 @@
     "knex": "^2.0.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.0.0-nightly-20230209023017"
+    "@backstage/cli": "^0.0.0-nightly-20230211022721"
   },
   "files": [
     "dist",