refactor(!): improved type-narrowing when working with action settings (relates #133)

.changeset/free-oranges-lose.md

@@ -0,0 +1,5 @@
+---
+"@elgato/streamdeck": major
+---
+
+`Action`, `KeyAction`, and `DialAction` types now require their setting type be defined.

.changeset/pink-jars-admire.md

@@ -0,0 +1,5 @@
+---
+"@elgato/streamdeck": major
+---
+
+Updated `getSettings` and `setSettings` so that the settings type is correctly bound to the type defined on the action.

.changeset/some-kings-taste.md

@@ -0,0 +1,5 @@
+---
+"@elgato/streamdeck": major
+---
+
+Updated `Action` type to represent a union of possible action types, such as key, dial, or Neo infobar.

packages/plugin/src/plugin/actions/__tests__/action.test.ts

@@ -7,7 +7,7 @@ import { connection } from "../../connection.js";
 import { Device } from "../../devices/device.js";
 import { deviceStore } from "../../devices/store.js";
 import { logger } from "../../logging/index.js";
-import { Action } from "../action.js";
+import { ActionBase } from "../action-base.js";
 import { settingsCache } from "../cache.js";
 import { actionConfig } from "../config.js";
 import { DialAction } from "../dial.js";
@@ -59,14 +59,14 @@ describe("Action", () => {
 	});
 
 	/**
-	 * Asserts the constructor of {@link Action} sets the properties from the source.
+	 * Asserts the constructor of {@link ActionBase} sets the properties from the source.
 	 */
 	it("constructor sets properties from source", () => {
 		// Arrange, act.
-		const action = new Action(source);
+		const action = new ActionBase(source);
 
 		// Assert.
-		expect(action).toBeInstanceOf(Action);
+		expect(action).toBeInstanceOf(ActionBase);
 		expect(action.controllerType).toBe("Keypad");
 		expect(action.device).toBe(device);
 		expect(action.id).toBe(source.context);
@@ -85,11 +85,11 @@ describe("Action", () => {
 		});
 
 		/**
-		 * Asserts {@link Action.getSettings} returns cached settings when the cache is valid.
+		 * Asserts {@link ActionBase.getSettings} returns cached settings when the cache is valid.
 		 */
 		it("getSettings returns cached settings", async () => {
 			// Arrange.
-			const action = new Action(source);
+			const action = new ActionBase(source);
 			const cachedSettings = { name: "Cached" };
 			const spyOnTrace = vi.spyOn(logger, "trace");
 			settingsCache.set(action.id, cachedSettings);
@@ -118,11 +118,11 @@ describe("Action", () => {
 		});
 
 		/**
-		 * Asserts {@link Action.getSettings} ignores cached settings when experimental message identifiers are disabled.
+		 * Asserts {@link ActionBase.getSettings} ignores cached settings when experimental message identifiers are disabled.
 		 */
 		it("getSettings ignores cached settings", async () => {
 			// Arrange.
-			const action = new Action(source);
+			const action = new ActionBase(source);
 			const spyOnTrace = vi.spyOn(logger, "trace");
 			settingsCache.set(action.id, { name: "Cached" });
 
@@ -164,11 +164,11 @@ describe("Action", () => {
 		});
 
 		/**
-		 * Asserts {@link Action.getSettings} requests settings from the connection and does not populate cache.
+		 * Asserts {@link ActionBase.getSettings} requests settings from the connection and does not populate cache.
 		 */
 		it("getSettings fetches without populating cache", async () => {
 			// Arrange.
-			const action = new Action(source);
+			const action = new ActionBase(source);
 
 			// Array, act (Command).
 			const settings = action.getSettings();
@@ -262,7 +262,7 @@ describe("Action", () => {
 	 * Asserts type-checking when the controller is "Keypad".
 	 */
 	test("keypad type assertion", () => {
-		const action = new Action({
+		const action = new ActionBase({
 			...source,
 			payload: {
 				...source.payload,
@@ -291,15 +291,15 @@ describe("Action", () => {
 	});
 
 	describe("sending", () => {
-		let action!: KeyAction;
+		let action!: KeyAction<Settings>;
 		beforeAll(() => (action = new KeyAction(source)));
 
 		/**
-		 * Asserts {@link Action.setSettings} invalidates the settings cache.
+		 * Asserts {@link ActionBase.setSettings} invalidates the settings cache.
 		 */
 		it("setSettings invalidates cache", async () => {
 			// Arrange.
-			const action = new Action(source);
+			const action = new ActionBase(source);
 			settingsCache.set(action.id, { name: "Cached" });
 
 			// Act.
@@ -313,7 +313,7 @@ describe("Action", () => {
 		});
 
 		/**
-		 * Asserts {@link Action.setSettings} forwards the command to the {@link connection}.
+		 * Asserts {@link ActionBase.setSettings} forwards the command to the {@link connection}.
 		 */
 		it("setSettings", async () => {
 			// Arrange, act.
@@ -333,7 +333,7 @@ describe("Action", () => {
 		});
 
 		/**
-		 * Asserts {@link Action.showAlert} forwards the command to the {@link connection}.
+		 * Asserts {@link ActionBase.showAlert} forwards the command to the {@link connection}.
 		 */
 		it("showAlert", async () => {
 			// Arrange, act.

packages/plugin/src/plugin/actions/__tests__/dial.test.ts

@@ -1,3 +1,4 @@
+import type { JsonObject } from "@elgato/utils";
 import { beforeAll, describe, expect, it, vi } from "vitest";
 
 import {
@@ -8,11 +9,10 @@ import {
 	type SetTriggerDescription,
 	type WillAppear,
 } from "../../../api/index.js";
-import type { JsonObject } from "../../../common/json.js";
 import { connection } from "../../connection.js";
 import { Device } from "../../devices/device.js";
 import { deviceStore } from "../../devices/store.js";
-import { Action } from "../action.js";
+import { ActionBase } from "../action-base.js";
 import { DialAction } from "../dial.js";
 
 vi.mock("../../devices/store.js");
@@ -63,7 +63,7 @@ describe("DialAction", () => {
 		const action = new DialAction(source);
 
 		// Assert.
-		expect(action).toBeInstanceOf(Action);
+		expect(action).toBeInstanceOf(ActionBase);
 		expect(action.coordinates).not.toBeUndefined();
 		expect(action.coordinates?.column).toBe(1);
 		expect(action.coordinates?.row).toBe(2);
@@ -115,7 +115,7 @@ describe("DialAction", () => {
 
 		// Act.
 		const jsonStr = JSON.stringify(action);
-		const jsonObj: DialAction = JSON.parse(jsonStr);
+		const jsonObj: DialAction<JsonObject> = JSON.parse(jsonStr);
 
 		// Assert.
 		expect(jsonObj.controllerType).toBe(action.controllerType);
@@ -126,7 +126,7 @@ describe("DialAction", () => {
 	});
 
 	describe("sending", () => {
-		let action!: DialAction;
+		let action!: DialAction<JsonObject>;
 		beforeAll(() => (action = new DialAction(source)));
 
 		/**

packages/plugin/src/plugin/actions/__tests__/key.test.ts

@@ -1,3 +1,4 @@
+import type { JsonObject } from "@elgato/utils";
 import { beforeAll, describe, expect, it, vi } from "vitest";
 
 import {
@@ -9,11 +10,10 @@ import {
 	Target,
 	type WillAppear,
 } from "../../../api/index.js";
-import type { JsonObject } from "../../../common/json.js";
 import { connection } from "../../connection.js";
 import { Device } from "../../devices/device.js";
 import { deviceStore } from "../../devices/store.js";
-import { Action } from "../action.js";
+import { ActionBase } from "../action-base.js";
 import { KeyAction } from "../key.js";
 
 vi.mock("../../devices/store.js");
@@ -64,7 +64,7 @@ describe("KeyAction", () => {
 		const action = new KeyAction(source);
 
 		// Assert.
-		expect(action).toBeInstanceOf(Action);
+		expect(action).toBeInstanceOf(ActionBase);
 		expect(action.coordinates).not.toBeUndefined();
 		expect(action.coordinates?.column).toBe(1);
 		expect(action.coordinates?.row).toBe(2);
@@ -147,7 +147,7 @@ describe("KeyAction", () => {
 
 		// Act.
 		const jsonStr = JSON.stringify(action);
-		const jsonObj: KeyAction = JSON.parse(jsonStr);
+		const jsonObj: KeyAction<JsonObject> = JSON.parse(jsonStr);
 
 		// Assert.
 		expect(jsonObj.controllerType).toBe(action.controllerType);
@@ -159,7 +159,7 @@ describe("KeyAction", () => {
 	});
 
 	describe("sending", () => {
-		let action!: KeyAction;
+		let action!: KeyAction<JsonObject>;
 		beforeAll(() => (action = new KeyAction(source)));
 
 		/**