@backstage/plugin-signals-node 0.1.0-next.1 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @backstage/plugin-signals-node
 
+## 0.1.0
+
+### Minor Changes
+
+- 6c1547a: **BREAKING** Type definition added to signal recipients
+
+  Update to use `{type: 'broadcast'}` instead `null` and `{type: 'user', entityRef: ''}`
+  instead string entity references
+
+- daf85dc: BREAKING CHANGE: Migrates signals to use the `EventsService` and makes it mandatory
+
+### Patch Changes
+
+- 6d84ee6: Renamed `SignalService` to `SignalsService` and `signalService` to `signalServiceRef`
+  to follow the naming scheme of services and their references
+- 0fb419b: Updated dependency `uuid` to `^9.0.0`.
+  Updated dependency `@types/uuid` to `^9.0.0`.
+- Updated dependencies
+  - @backstage/plugin-events-node@0.3.0
+  - @backstage/backend-common@0.21.4
+  - @backstage/plugin-auth-node@0.4.9
+  - @backstage/config@1.2.0
+  - @backstage/backend-plugin-api@0.6.14
+  - @backstage/types@1.1.1
+
+## 0.1.0-next.2
+
+### Patch Changes
+
+- 6d84ee6: Renamed `SignalService` to `SignalsService` and `signalService` to `signalServiceRef`
+  to follow the naming scheme of services and their references
+- Updated dependencies
+  - @backstage/backend-common@0.21.4-next.2
+  - @backstage/plugin-auth-node@0.4.9-next.2
+  - @backstage/backend-plugin-api@0.6.14-next.2
+  - @backstage/config@1.2.0-next.1
+  - @backstage/types@1.1.1
+  - @backstage/plugin-events-node@0.3.0-next.2
+
 ## 0.1.0-next.1
 
 ### Minor Changes

package/README.md

@@ -6,28 +6,70 @@ Signals plugin allows backend plugins to publish messages to frontend plugins.
 
 ## Getting started
 
+### New backend system
+
+In `packages/backend/index.ts`, add the signals backend:
+
+```ts
+backend.add(import('@backstage/plugin-signals-backend'));
+```
+
+To use signals in your plugin, add it as a dependency to `my-plugin/plugin.ts`:
+
+```ts
+import {
+  coreServices,
+  createBackendPlugin,
+} from '@backstage/backend-plugin-api';
+import { signalsServiceRef } from '@backstage/plugin-signals-node';
+
+export const myPlugin = createBackendPlugin({
+  pluginId: 'my-plugin',
+  register(env) {
+    env.registerInit({
+      deps: {
+        httpRouter: coreServices.httpRouter,
+        signals: signalsServiceRef,
+      },
+      async init({ httpRouter, signals }) {
+        httpRouter.use(
+          await createRouter({
+            signals,
+          }),
+        );
+      },
+    });
+  },
+});
+```
+
+### Old backend system
+
 Add SignalService to your plugin environment in `packages/backend/src/types.ts`:
 
 ```ts
-import { SignalService } from '@backstage/plugin-signals-node';
+import { SignalsService } from '@backstage/plugin-signals-node';
 
 export type PluginEnvironment = {
   // ...
-  signalService: SignalService;
+  signals: SignalsService;
 };
 ```
 
 Add it also to your `makeCreateEnv` to allow access from the other plugins:
 
 ```ts
-import { SignalService } from '@backstage/plugin-signals-node';
+import {
+  SignalsService,
+  DefaultSignalsService,
+} from '@backstage/plugin-signals-node';
 import { DefaultEventBroker } from '@backstage/plugin-events-backend';
 
 function makeCreateEnv(config: Config) {
   // ...
 
   const eventBroker = new DefaultEventBroker(root.child({ type: 'plugin' }));
-  const signalService = DefaultSignalService.create({
+  const signalsService = DefaultSignalsService.create({
     eventBroker,
   });
 
@@ -36,7 +78,7 @@ function makeCreateEnv(config: Config) {
     return {
       logger,
       eventBroker,
-      signalService,
+      signals: signalsService,
       // ...
     };
   };
@@ -49,13 +91,13 @@ To allow connections from the frontend, you should also install the `@backstage/
 
 Once you have both of the backend plugins installed, you can utilize the signal service by calling the
 `publish` method. This will publish the message to all subscribers in the frontend. To send message to
-all subscribers, you can use `null` as `recipients` parameter.
+all subscribers, you can use `broadcast` type:
 
 ```ts
 // Periodic sending example
 setInterval(async () => {
-  await signalService.publish({
-    recipients: null,
+  await signals.publish({
+    recipients: { type: 'broadcast' },
     channel: 'my_plugin',
     message: {
       message: 'hello world',
@@ -76,7 +118,7 @@ to work:
 eventBroker.publish({
   topic: 'signals',
   eventPayload: {
-    recipients: ['user:default/user1'],
+    recipients: { type: 'user', entityRef: 'user:default/user1' },
     message: {
       message: 'hello world',
     },

package/dist/index.cjs.js

@@ -11,13 +11,13 @@ var __publicField = (obj, key, value) => {
   __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
-class DefaultSignalService {
+class DefaultSignalsService {
   constructor(options) {
     __publicField(this, "events");
     ({ events: this.events } = options);
   }
   static create(options) {
-    return new DefaultSignalService(options);
+    return new DefaultSignalsService(options);
   }
   /**
    * Publishes a signal to user refs to specific topic
@@ -30,8 +30,9 @@ class DefaultSignalService {
     });
   }
 }
+const DefaultSignalService = DefaultSignalsService;
 
-const signalService = backendPluginApi.createServiceRef({
+const signalsServiceRef = backendPluginApi.createServiceRef({
   id: "signals.service",
   scope: "plugin",
   defaultFactory: async (service) => backendPluginApi.createServiceFactory({
@@ -40,11 +41,14 @@ const signalService = backendPluginApi.createServiceRef({
       events: pluginEventsNode.eventsServiceRef
     },
     factory({ events }) {
-      return DefaultSignalService.create({ events });
+      return DefaultSignalsService.create({ events });
     }
   })
 });
+const signalService = signalsServiceRef;
 
 exports.DefaultSignalService = DefaultSignalService;
+exports.DefaultSignalsService = DefaultSignalsService;
 exports.signalService = signalService;
+exports.signalsServiceRef = signalsServiceRef;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":["../src/DefaultSignalService.ts","../src/lib.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { EventsService } from '@backstage/plugin-events-node';\nimport { SignalPayload, SignalServiceOptions } from './types';\nimport { SignalService } from './SignalService';\nimport { JsonObject } from '@backstage/types';\n\n/** @public */\nexport class DefaultSignalService implements SignalService {\n  private events: EventsService;\n\n  static create(options: SignalServiceOptions) {\n    return new DefaultSignalService(options);\n  }\n\n  private constructor(options: SignalServiceOptions) {\n    ({ events: this.events } = options);\n  }\n\n  /**\n   * Publishes a signal to user refs to specific topic\n   * @param signal - Signal to publish\n   */\n  async publish<TMessage extends JsonObject = JsonObject>(\n    signal: SignalPayload<TMessage>,\n  ) {\n    await this.events.publish({\n      topic: 'signals',\n      eventPayload: signal,\n    });\n  }\n}\n","/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport {\n  createServiceFactory,\n  createServiceRef,\n} from '@backstage/backend-plugin-api';\nimport { DefaultSignalService } from './DefaultSignalService';\nimport { SignalService } from './SignalService';\nimport { eventsServiceRef } from '@backstage/plugin-events-node';\n\n/** @public */\nexport const signalService = createServiceRef<SignalService>({\n  id: 'signals.service',\n  scope: 'plugin',\n  defaultFactory: async service =>\n    createServiceFactory({\n      service,\n      deps: {\n        events: eventsServiceRef,\n      },\n      factory({ events }) {\n        return DefaultSignalService.create({ events });\n      },\n    }),\n});\n"],"names":["createServiceRef","createServiceFactory","eventsServiceRef"],"mappings":";;;;;;;;;;;;;AAqBO,MAAM,oBAA8C,CAAA;AAAA,EAOjD,YAAY,OAA+B,EAAA;AANnD,IAAQ,aAAA,CAAA,IAAA,EAAA,QAAA,CAAA,CAAA;AAON,IAAA,CAAC,EAAE,MAAA,EAAQ,IAAK,CAAA,MAAA,EAAW,GAAA,OAAA,EAAA;AAAA,GAC7B;AAAA,EANA,OAAO,OAAO,OAA+B,EAAA;AAC3C,IAAO,OAAA,IAAI,qBAAqB,OAAO,CAAA,CAAA;AAAA,GACzC;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,QACJ,MACA,EAAA;AACA,IAAM,MAAA,IAAA,CAAK,OAAO,OAAQ,CAAA;AAAA,MACxB,KAAO,EAAA,SAAA;AAAA,MACP,YAAc,EAAA,MAAA;AAAA,KACf,CAAA,CAAA;AAAA,GACH;AACF;;ACpBO,MAAM,gBAAgBA,iCAAgC,CAAA;AAAA,EAC3D,EAAI,EAAA,iBAAA;AAAA,EACJ,KAAO,EAAA,QAAA;AAAA,EACP,cAAA,EAAgB,OAAM,OAAA,KACpBC,qCAAqB,CAAA;AAAA,IACnB,OAAA;AAAA,IACA,IAAM,EAAA;AAAA,MACJ,MAAQ,EAAAC,iCAAA;AAAA,KACV;AAAA,IACA,OAAA,CAAQ,EAAE,MAAA,EAAU,EAAA;AAClB,MAAA,OAAO,oBAAqB,CAAA,MAAA,CAAO,EAAE,MAAA,EAAQ,CAAA,CAAA;AAAA,KAC/C;AAAA,GACD,CAAA;AACL,CAAC;;;;;"}
+{"version":3,"file":"index.cjs.js","sources":["../src/DefaultSignalsService.ts","../src/lib.ts"],"sourcesContent":["/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { EventsService } from '@backstage/plugin-events-node';\nimport { SignalPayload, SignalsServiceOptions } from './types';\nimport { SignalsService } from './SignalsService';\nimport { JsonObject } from '@backstage/types';\n\n/** @public */\nexport class DefaultSignalsService implements SignalsService {\n  private events: EventsService;\n\n  static create(options: SignalsServiceOptions) {\n    return new DefaultSignalsService(options);\n  }\n\n  private constructor(options: SignalsServiceOptions) {\n    ({ events: this.events } = options);\n  }\n\n  /**\n   * Publishes a signal to user refs to specific topic\n   * @param signal - Signal to publish\n   */\n  async publish<TMessage extends JsonObject = JsonObject>(\n    signal: SignalPayload<TMessage>,\n  ) {\n    await this.events.publish({\n      topic: 'signals',\n      eventPayload: signal,\n    });\n  }\n}\n\n/**\n * @public\n * @deprecated Use `DefaultSignalsService` instead\n */\nexport const DefaultSignalService = DefaultSignalsService;\n","/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport {\n  createServiceFactory,\n  createServiceRef,\n} from '@backstage/backend-plugin-api';\nimport { DefaultSignalsService } from './DefaultSignalsService';\nimport { SignalsService } from './SignalsService';\nimport { eventsServiceRef } from '@backstage/plugin-events-node';\n\n/** @public */\nexport const signalsServiceRef = createServiceRef<SignalsService>({\n  id: 'signals.service',\n  scope: 'plugin',\n  defaultFactory: async service =>\n    createServiceFactory({\n      service,\n      deps: {\n        events: eventsServiceRef,\n      },\n      factory({ events }) {\n        return DefaultSignalsService.create({ events });\n      },\n    }),\n});\n\n/**\n * @public\n * @deprecated Use `signalsServiceRef` instead\n */\nexport const signalService = signalsServiceRef;\n"],"names":["createServiceRef","createServiceFactory","eventsServiceRef"],"mappings":";;;;;;;;;;;;;AAqBO,MAAM,qBAAgD,CAAA;AAAA,EAOnD,YAAY,OAAgC,EAAA;AANpD,IAAQ,aAAA,CAAA,IAAA,EAAA,QAAA,CAAA,CAAA;AAON,IAAA,CAAC,EAAE,MAAA,EAAQ,IAAK,CAAA,MAAA,EAAW,GAAA,OAAA,EAAA;AAAA,GAC7B;AAAA,EANA,OAAO,OAAO,OAAgC,EAAA;AAC5C,IAAO,OAAA,IAAI,sBAAsB,OAAO,CAAA,CAAA;AAAA,GAC1C;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,QACJ,MACA,EAAA;AACA,IAAM,MAAA,IAAA,CAAK,OAAO,OAAQ,CAAA;AAAA,MACxB,KAAO,EAAA,SAAA;AAAA,MACP,YAAc,EAAA,MAAA;AAAA,KACf,CAAA,CAAA;AAAA,GACH;AACF,CAAA;AAMO,MAAM,oBAAuB,GAAA;;AC1B7B,MAAM,oBAAoBA,iCAAiC,CAAA;AAAA,EAChE,EAAI,EAAA,iBAAA;AAAA,EACJ,KAAO,EAAA,QAAA;AAAA,EACP,cAAA,EAAgB,OAAM,OAAA,KACpBC,qCAAqB,CAAA;AAAA,IACnB,OAAA;AAAA,IACA,IAAM,EAAA;AAAA,MACJ,MAAQ,EAAAC,iCAAA;AAAA,KACV;AAAA,IACA,OAAA,CAAQ,EAAE,MAAA,EAAU,EAAA;AAClB,MAAA,OAAO,qBAAsB,CAAA,MAAA,CAAO,EAAE,MAAA,EAAQ,CAAA,CAAA;AAAA,KAChD;AAAA,GACD,CAAA;AACL,CAAC,EAAA;AAMM,MAAM,aAAgB,GAAA;;;;;;;"}

package/dist/index.d.ts

@@ -5,32 +5,48 @@ import { JsonObject } from '@backstage/types';
 /**
  * @public
  */
-type SignalServiceOptions = {
+type SignalsServiceOptions = {
     events: EventsService;
 };
 /** @public */
 type SignalPayload<TMessage extends JsonObject = JsonObject> = {
-    recipients: string[] | string | null;
+    recipients: {
+        type: 'user';
+        entityRef: string | string[];
+    } | {
+        type: 'broadcast';
+    };
     channel: string;
     message: TMessage;
 };
 
 /** @public */
-interface SignalService {
+interface SignalsService {
     /**
      * Publishes a signal to user refs to specific topic
      * @param signal - Signal to publish
      */
     publish<TMessage extends JsonObject = JsonObject>(signal: SignalPayload<TMessage>): Promise<void>;
 }
+/**
+ * @public
+ * @deprecated Use `SignalsService` instead
+ */
+interface SignalService extends SignalsService {
+}
 
 /** @public */
-declare const signalService: _backstage_backend_plugin_api.ServiceRef<SignalService, "plugin">;
+declare const signalsServiceRef: _backstage_backend_plugin_api.ServiceRef<SignalsService, "plugin">;
+/**
+ * @public
+ * @deprecated Use `signalsServiceRef` instead
+ */
+declare const signalService: _backstage_backend_plugin_api.ServiceRef<SignalsService, "plugin">;
 
 /** @public */
-declare class DefaultSignalService implements SignalService {
+declare class DefaultSignalsService implements SignalsService {
     private events;
-    static create(options: SignalServiceOptions): DefaultSignalService;
+    static create(options: SignalsServiceOptions): DefaultSignalsService;
     private constructor();
     /**
      * Publishes a signal to user refs to specific topic
@@ -38,5 +54,10 @@ declare class DefaultSignalService implements SignalService {
      */
     publish<TMessage extends JsonObject = JsonObject>(signal: SignalPayload<TMessage>): Promise<void>;
 }
+/**
+ * @public
+ * @deprecated Use `DefaultSignalsService` instead
+ */
+declare const DefaultSignalService: typeof DefaultSignalsService;
 
-export { DefaultSignalService, SignalPayload, SignalService, SignalServiceOptions, signalService };
+export { DefaultSignalService, DefaultSignalsService, SignalPayload, SignalService, SignalsService, SignalsServiceOptions, signalService, signalsServiceRef };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-signals-node",
   "description": "Node.js library for the signals plugin",
-  "version": "0.1.0-next.1",
+  "version": "0.1.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -27,18 +27,18 @@
     "postpack": "backstage-cli package postpack"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.25.3-next.1",
+    "@backstage/cli": "^0.26.0",
     "@types/express": "^4.17.21"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@backstage/backend-common": "^0.21.4-next.1",
-    "@backstage/backend-plugin-api": "^0.6.14-next.1",
-    "@backstage/config": "^1.2.0-next.1",
-    "@backstage/plugin-auth-node": "^0.4.9-next.1",
-    "@backstage/plugin-events-node": "^0.3.0-next.1",
+    "@backstage/backend-common": "^0.21.4",
+    "@backstage/backend-plugin-api": "^0.6.14",
+    "@backstage/config": "^1.2.0",
+    "@backstage/plugin-auth-node": "^0.4.9",
+    "@backstage/plugin-events-node": "^0.3.0",
     "@backstage/types": "^1.1.1",
     "express": "^4.17.1",
     "uuid": "^9.0.0",