docs: improve readability of WebSocket API types

src/api/command.ts

@@ -1,44 +1,52 @@
-import type { JsonValue } from "../plugin";
+import type { JsonObject, JsonValue } from "../plugin";
 import type { ActionIdentifier, DidReceiveGlobalSettings, DidReceiveSettings, State } from "./events";
 import type { FeedbackPayload } from "./layout";
 import type { Target } from "./target";
 
 /**
  * Command sent to Stream Deck.
  */
-type CommandBase<TCommand, TPayload = void> = TPayload extends void
-	? {
-			/**
-			 * Name of the command, used to identify the request.
-			 */
-			event: TCommand;
-	  }
-	: {
-			/**
-			 * Name of the command, used to identify the request.
-			 */
-			event: TCommand;
-
-			/**
-			 * Additional information supplied as part of the command.
-			 */
-			payload: TPayload;
-	  };
+type CommandBase<TCommand> = {
+	/**
+	 * Name of the command, used to identify the request.
+	 */
+	event: TCommand;
+};
 
 /**
- * A {@link CommandBase} that is associated with a specific context, e.g. action.
+ * Command sent to Stream Deck, with payload information.
  */
-type ContextualizedCommand<TCommand, TPayload = void> = CommandBase<TCommand, TPayload> & {
+type CommandBaseWithPayload<TCommand, TPayload> = CommandBase<TCommand> & {
+	/**
+	 * Additional information supplied as part of the command.
+	 */
+	payload: TPayload;
+};
+
+/**
+ * A {@link CommandBase} that is associated with a specific action identified by the context..
+ */
+type ContextualizedCommand<TCommand> = CommandBase<TCommand> & {
 	/**
 	 * Defines the context of the command, e.g. which action instance the command is intended for.
 	 */
 	context: string;
 };
 
+/**
+ * A {@link CommandBase} that is associated with a specific action identified by the context.
+ */
+type ContextualizedCommandWithPayload<TCommand, TPayload> = ContextualizedCommand<TCommand> & {
+	/**
+	 * Additional information supplied as part of the command.
+	 */
+	payload: TPayload;
+};
+
 /**
  * Sets the settings associated with an instance of an action.
  */
-export type SetSettings = ContextualizedCommand<"setSettings", unknown>;
+export type SetSettings = ContextualizedCommandWithPayload<"setSettings", JsonObject>;
 
 /**
  * Sets the settings associated with an instance of an action.
@@ -58,7 +66,7 @@ export type UIGetSettings = ActionIdentifier & GetSettings;
 /**
  * Sets the global settings associated with the plugin.
  */
-export type SetGlobalSettings = ContextualizedCommand<"setGlobalSettings", unknown>;
+export type SetGlobalSettings = ContextualizedCommandWithPayload<"setGlobalSettings", JsonObject>;
 
 /**
  * Gets the global settings associated with the plugin. Causes {@link DidReceiveGlobalSettings} to be emitted.
@@ -68,7 +76,7 @@ export type GetGlobalSettings = ContextualizedCommand<"getGlobalSettings">;
 /**
  * Opens the URL in the user's default browser.
  */
-export type OpenUrl = CommandBase<
+export type OpenUrl = CommandBaseWithPayload<
 	"openUrl",
 	{
 		/**
@@ -81,7 +89,7 @@ export type OpenUrl = CommandBase<
 /**
  * Logs a message to the file-system.
  */
-export type LogMessage = CommandBase<
+export type LogMessage = CommandBaseWithPayload<
 	"logMessage",
 	{
 		/**
@@ -93,7 +101,7 @@ export type LogMessage = CommandBase<
 /**
  * Sets the title displayed for an instance of an action.
  */
-export type SetTitle = ContextualizedCommand<
+export type SetTitle = ContextualizedCommandWithPayload<
 	"setTitle",
 	{
 		/**
@@ -116,7 +124,7 @@ export type SetTitle = ContextualizedCommand<
 /**
  * Sets the image associated with an action instance.
  */
-export type SetImage = ContextualizedCommand<
+export type SetImage = ContextualizedCommandWithPayload<
 	"setImage",
 	{
 		/**
@@ -139,12 +147,12 @@ export type SetImage = ContextualizedCommand<
 /**
  * Set's the feedback of an existing layout associated with an action instance.
  */
-export type SetFeedback = ContextualizedCommand<"setFeedback", FeedbackPayload>;
+export type SetFeedback = ContextualizedCommandWithPayload<"setFeedback", FeedbackPayload>;
 
 /**
  * Sets the layout associated with an action instance.
  */
-export type SetFeedbackLayout = ContextualizedCommand<
+export type SetFeedbackLayout = ContextualizedCommandWithPayload<
 	"setFeedbackLayout",
 	{
 		/**
@@ -167,7 +175,7 @@ export type ShowOk = ContextualizedCommand<"showOk">;
 /**
  * Sets the current state of an action instance.
  */
-export type SetState = ContextualizedCommand<
+export type SetState = ContextualizedCommandWithPayload<
 	"setState",
 	{
 		/**
@@ -180,7 +188,7 @@ export type SetState = ContextualizedCommand<
 /**
  * Sets the trigger descriptions associated with an encoder action instance.
  */
-export type SetTriggerDescription = ContextualizedCommand<
+export type SetTriggerDescription = ContextualizedCommandWithPayload<
 	"setTriggerDescription",
 	{
 		/**
@@ -210,7 +218,7 @@ export type SetTriggerDescription = ContextualizedCommand<
  *
  * NB: Plugins may only switch to profiles distributed with the plugin, as defined within the manifest, and cannot access user-defined profiles.
  */
-export type SwitchToProfile = ContextualizedCommand<
+export type SwitchToProfile = ContextualizedCommandWithPayload<
 	"switchToProfile",
 	{
 		/**
@@ -234,12 +242,12 @@ export type SwitchToProfile = ContextualizedCommand<
 /**
  * Sends a message to the property inspector.
  */
-export type SendToPropertyInspector<TPayload extends JsonValue = JsonValue> = ContextualizedCommand<"sendToPropertyInspector", TPayload>;
+export type SendToPropertyInspector<TPayload extends JsonValue = JsonValue> = ContextualizedCommandWithPayload<"sendToPropertyInspector", TPayload>;
 
 /**
  * Sends a message to the plugin.
  */
-export type SendToPlugin<TPayload extends JsonValue = JsonValue> = ActionIdentifier & CommandBase<"sendToPlugin", TPayload>;
+export type SendToPlugin<TPayload extends JsonValue = JsonValue> = ActionIdentifier & CommandBaseWithPayload<"sendToPlugin", TPayload>;
 
 /**
  * Command sent to Stream Deck, from the plugin.

src/api/events/action.ts

@@ -63,8 +63,7 @@ export type TitleParametersDidChange<TSettings extends JsonObject> = ActionEvent
 
 /**
  * Occurs when an action appears on the Stream Deck due to the user navigating to another page, profile, folder, etc. This also occurs during startup if the action is on the "front
- * page". An action refers to _all_ types of actions, e.g. keys, dials,
- * touchscreens, pedals, etc.
+ * page". An action refers to _all_ types of actions, e.g. keys, dials, touchscreens, pedals, etc.
  */
 export type WillAppear<TSettings extends JsonObject> = ActionEventMessage<"willAppear", MultiActionPayload<TSettings> | SingleActionPayload<TSettings>>;
 
@@ -91,18 +90,21 @@ export type ActionIdentifier = {
 };
 
 /**
- * Provides information for an event relating to an action, e.g. `willAppear`, `keyDown`, etc.
+ * Provides information for an event relating to an action, for example `willAppear`.
+ */
+export type ActionEventMessage<TEvent extends string, TPayload> = ActionIdentifier &
+	DeviceIdentifier &
+	EventIdentifier<TEvent> & {
+		/**
+		 * Contextualized information for this event.
+		 */
+		readonly payload: TPayload;
+	};
+
+/**
+ * Provides information for an event relating to an action, for example `propertyInspectorDidAppear`.
  */
-export type ActionEventMessage<TEvent extends string, TPayload = void> = DeviceIdentifier &
-	EventIdentifier<TEvent> &
-	(TPayload extends void
-		? ActionIdentifier
-		: ActionIdentifier & {
-				/**
-				 * Additional information about the action and event that occurred.
-				 */
-				readonly payload: TPayload;
-		  });
+export type ActionEventMessageWithoutPayload<TEvent extends string> = Omit<ActionEventMessage<TEvent, void>, "payload">;
 
 /**
  * Additional information about the action and event that occurred as part of a single-action event.

src/api/events/keypad.ts

@@ -7,24 +7,22 @@ import type { DialDown, DialUp } from "./encoder";
  *
  * NB: For dials / touchscreens see {@link DialDown}.
  */
-export type KeyDown<TSettings extends JsonObject> = ActionEventMessage<"keyDown", KeypadPayload<TSettings>>;
+export type KeyDown<TSettings extends JsonObject> = ActionEventMessage<"keyDown", MultiActionKeyGesturePayload<TSettings> | SingleActionPayload<TSettings, "Keypad">>;
 
 /**
  * Occurs when the user releases a pressed action. See also {@link KeyDown}.
  *
  * NB: For dials / touchscreens see {@link DialUp}.
  */
-export type KeyUp<TSettings extends JsonObject> = ActionEventMessage<"keyUp", KeypadPayload<TSettings>>;
+export type KeyUp<TSettings extends JsonObject> = ActionEventMessage<"keyUp", MultiActionKeyGesturePayload<TSettings> | SingleActionPayload<TSettings, "Keypad">>;
 
 /**
- * Additional information about a keypad event that occurred.
+ * Additional information about the action and event that occurred as part of a multi-action event.
  */
-type KeypadPayload<TSettings extends JsonObject> =
-	| SingleActionPayload<TSettings, "Keypad">
-	| (MultiActionPayload<TSettings> & {
-			/**
-			 * Desired state as specified by the user; only applicable to actions that have multiple states defined within the `manifest.json` file, and when this action instance is
-			 * part of a multi-action.
-			 */
-			readonly userDesiredState: State;
-	  });
+type MultiActionKeyGesturePayload<TSettings extends JsonObject> = MultiActionPayload<TSettings> & {
+	/**
+	 * Desired state as specified by the user; only applicable to actions that have multiple states defined within the `manifest.json` file, and when this action instance is
+	 * part of a multi-action.
+	 */
+	readonly userDesiredState: State;
+};

src/api/events/ui.ts

@@ -1,26 +1,21 @@
 import type { JsonValue } from "../../common/json";
-import type { ActionEventMessage } from "./action";
+import type { ActionEventMessage, ActionEventMessageWithoutPayload } from "./action";
 import type { DeviceIdentifier } from "./device";
 
 /**
  * Occurs when the property inspector associated with the action becomes visible, i.e. the user selected an action in the Stream Deck application. See also {@link PropertyInspectorDidDisappear}.
  */
-export type PropertyInspectorDidAppear = ActionEventMessage<"propertyInspectorDidAppear">;
+export type PropertyInspectorDidAppear = ActionEventMessageWithoutPayload<"propertyInspectorDidAppear">;
 
 /**
  * Occurs when the property inspector associated with the action becomes invisible, i.e. the user unselected the action in the Stream Deck application. See also {@link PropertyInspectorDidAppear}.
  */
-export type PropertyInspectorDidDisappear = ActionEventMessage<"propertyInspectorDidDisappear">;
+export type PropertyInspectorDidDisappear = ActionEventMessageWithoutPayload<"propertyInspectorDidDisappear">;
 
 /**
  * Message sent between the plugin and it's respective UI.
  */
-type PluginMessage<TEvent extends string, TPayload extends JsonValue> = Omit<ActionEventMessage<TEvent>, keyof DeviceIdentifier> & {
-	/**
-	 * Payload sent between the plugin and it's UI.
-	 */
-	readonly payload: TPayload;
-};
+type PluginMessage<TEvent extends string, TPayload extends JsonValue> = Omit<ActionEventMessage<TEvent, TPayload>, keyof DeviceIdentifier>;
 
 /**
  * Occurs when a payload was received from the UI.

src/api/registration/info.ts

@@ -73,14 +73,12 @@ export type RegistrationInfo = {
 	/**
 	 * Devices associated with the Stream Deck application; this may include devices that are not currently connected. Use `"deviceDidConnect"` event to determine which devices are active.
 	 */
-	readonly devices: [
-		DeviceInfo & {
-			/**
-			 * Unique identifier of the Stream Deck device.
-			 */
-			readonly id: string;
-		}
-	];
+	readonly devices: (DeviceInfo & {
+		/**
+		 * Unique identifier of the Stream Deck device.
+		 */
+		readonly id: string;
+	})[];
 
 	/**
 	 * Information about the plugin.

src/plugin/settings.ts

@@ -52,7 +52,7 @@ export function onDidReceiveSettings<T extends JsonObject = JsonObject>(listener
  *   connectedDate: new Date()
  * })
  */
-export function setGlobalSettings<T>(settings: T): Promise<void> {
+export function setGlobalSettings<T extends JsonObject>(settings: T): Promise<void> {
 	return connection.send({
 		event: "setGlobalSettings",
 		context: connection.registrationParameters.pluginUUID,