@foxglove/extension 2.23.0 → 2.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxglove/extension",
-  "version": "2.23.0",
+  "version": "2.25.0",
   "license": "MIT",
   "author": {
     "name": "Foxglove Technologies",

package/src/experimental.ts

@@ -0,0 +1,135 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+
+import { Immutable } from "./immutable";
+import {
+  ExtensionContext as BaseExtensionContext,
+  RegisterMessageConverterArgs as LegacyRegisterMessageConverterArgs,
+  MessageEvent,
+} from "./stable";
+
+/**
+ * The experimental namespace contains experimental APIs that are not yet stable and WILL change or
+ * be REMOVED at any time.
+ *
+ * These APIS are provided for isolated testing and feedback.You should avoid shipping org
+ * extensions which depend on them because they WILL break in different versions of Foxglove and
+ * can be CHANGED or REMOVED at any time.
+ *
+ * @hidden
+ */
+export namespace Experimental {
+  type TopicConverterReturnType = (messageEvent: Immutable<MessageEvent>) => unknown;
+  /**
+   * This type represents the arguments you pass to
+   * {@link ExtensionContext.registerMessageConverter} when you want to register a topic message
+   * converter.
+   *
+   * @category Message converters
+   */
+  export type RegisterMessageConverterArgsTopic = {
+    type: "topic";
+    inputTopics: string[];
+    outputTopic: string;
+    schemaName: string;
+    create: () => TopicConverterReturnType;
+  };
+
+  /**
+   * This type represents the arguments you pass to
+   * {@link ExtensionContext.registerMessageConverter} when you want to register a schema message
+   * converter.
+   *
+   * `schema` converters allow you to leverage Foxglove's built-in visualization panels by
+   * transforming messages to adhere to Foxglove-supported schemas — for example, you can convert
+   * your custom GPS messages to
+   * [`foxglove.LocationFix`](https://docs.foxglove.dev/docs/visualization/message-schemas/location-fix)
+   * messages for visualization in the [Map
+   * panel](https://docs.foxglove.dev/docs/visualization/panels/map).
+   *
+   * See the [Creating a message
+   * converter](https://docs.foxglove.dev/docs/visualization/extensions/guides/create-message-converter)
+   * guide for more details.
+   *
+   * @category Message converters
+   */
+  export type RegisterMessageConverterArgsSchema<Src = unknown> = {
+    type: "schema";
+
+    /** The source message schema name. This is the schema name of the original message. */
+    fromSchemaName: string;
+
+    /**
+     * The converted message schema name. This is the schema name of the message you will output
+     * from the converter.
+     */
+    toSchemaName: string;
+
+    /**
+     * A function which takes the original message and returns the converted message.
+     *
+     * If the function returns `undefined`, the output is ignored, and no message is provided to the
+     * panel. This is useful if you want to selectively output converted messages depending on the
+     * input messages' contents.
+     */
+    converter: (msg: Src, event: Immutable<MessageEvent<Src>>) => unknown;
+  };
+
+  export type RegisterMessageConverterArgs =
+    | LegacyRegisterMessageConverterArgs
+    | RegisterMessageConverterArgsSchema
+    | RegisterMessageConverterArgsTopic;
+
+  export interface ExtensionContext extends BaseExtensionContext {
+    /**
+     * `registerMessageConverter` registers converters to transform message data within Foxglove.
+     *
+     * You can register two kinds of converters: `schema` and `topic`.
+     *
+     * `schema` converters transform messages of one schema into another. Most often this is used to
+     * turn messages using a custom or proprietary schema into a well-known Foxglove schema for
+     * visualization in one of the built-in panels. `schema` converters allow a built-in panel which
+     * requires well-known messages to natively support visualizing any topic for which there is a
+     * schema converter registered. An example is converting an `acme.Gps` message to
+     * `foxglove.LocationFix` to visualize any topics which publish `acme.Gps` messages in the
+     * built-in map panel.
+     *
+     * See: {@link RegisterMessageConverterArgsSchema}.
+     *
+     * `topic` converters transform messages from one-or-more input topics to a new in-app topic.
+     * Topic converters are more flexible than schema converters but require more logic and
+     * decisions to implement. They can transform existing data into new topics for plotting,
+     * inspecting, and visualizing. Topic converters can combine data from several input topics,
+     * maintain state, and create messages from these multiple topics. They can also do the opposite
+     * - take a single topic and turn it into multiple output topics.
+     *
+     * See: {@link RegisterMessageConverterArgsTopic}.
+     */
+    registerMessageConverter(args: RegisterMessageConverterArgs): void;
+    /**
+     * @deprecated Use `registerMessageConverter` with `type: "schema"` or `type: "topic"` instead.
+     */
+    registerMessageConverter<Src>(args: LegacyRegisterMessageConverterArgs<Src>): void;
+    /**
+     * Register a schema message converter.
+     *
+     * See: {@link RegisterMessageConverterArgsSchema}.
+     */
+    registerMessageConverter<Src>(args: RegisterMessageConverterArgsSchema<Src>): void;
+    /**
+     * Register a topic message converter.
+     *
+     * See: {@link RegisterMessageConverterArgsTopic}.
+     */
+    registerMessageConverter(args: RegisterMessageConverterArgsTopic): void;
+  }
+
+  export interface ExtensionModule {
+    /**
+     * This function will be called when your extension is loaded. In this function, you can register
+     * your custom panels or other types of extension features.
+     */
+    activate: ExtensionActivate;
+  }
+
+  export type ExtensionActivate = (extensionContext: ExtensionContext) => void;
+}