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

packages/plugin/src/plugin/actions/action.ts:112

• setSettings is now correctly constrained to T, but getSettings still exposes an unconstrained generic (getSettings<U extends JsonObject = T>()), so callers can still bypass Action<T> by explicitly providing an unrelated U. If the goal is to make Action<T> actually enforce settings shape (per #133), getSettings should also be constrained to return Promise<T> without a caller-supplied generic.

	 * @param value Settings to persist.
	 * @returns `Promise` resolved when the settings are sent to Stream Deck.
	 */
	public setSettings(value: T): Promise<void> {
		settingsCache.delete(this.id);

packages/plugin/src/plugin/actions/action.ts:27

• Removing the default type parameter from Action<T> makes bare Action type references invalid. There is at least one remaining usage (packages/plugin/src/plugin/actions/__tests__/action.test.ts has let action!: Action;) that will fail TypeScript compilation unless updated to include a concrete type argument (e.g. Action<JsonObject>).

export class Action<T extends JsonObject> extends ActionContext {

packages/plugin/src/plugin/actions/singleton-action.ts:111

• setTitle is implemented by KeyAction and DialAction, not ActionBase, so this newly targeted API link cannot resolve to a real member.

	 * Occurs when the user updates an action's title settings in the Stream Deck application. See also {@link ActionBase.setTitle}.

packages/plugin/src/plugin/actions/dial.ts:58

• setFeedback is declared on DialAction, not ActionBase, so this API link cannot resolve correctly.

	 * Use in conjunction with {@link ActionBase.setFeedback} to update the layout's current items' settings.

packages/plugin/src/plugin/actions/action-base.ts:120

• The core regression is type-level, but the updated tests only exercise runtime forwarding with actions effectively typed as JsonObject. A future reintroduction of a method-level generic would therefore pass them. Add a compile-time case using a concrete settings type that accepts its schema and marks an unrelated object with @ts-expect-error.

	public setSettings(value: TSettings): Promise<void> {

packages/plugin/src/plugin/actions/action-base.ts:46

• This method no longer declares U, so the @template U tag is stale; the trailing action.D is also erroneous. Document the class-level settings type through the return value instead.

	 * Gets the settings associated this action instance.
	 * @template U The type of settings associated with the action.D
	 * @returns Promise containing the action instance's settings.

packages/plugin/src/plugin/actions/singleton-action.ts:105

• ActionBase has no sendToPropertyInspector method; messages to the property inspector are sent by streamDeck.ui. The current link points users to a nonexistent API.

This issue also appears on line 111 of the same file.

	 * Occurs when a message was sent to the plugin _from_ the property inspector. The plugin can also send messages _to_ the property inspector using {@link ActionBase.sendToPropertyInspector}.

packages/plugin/src/plugin/actions/service.ts:177

• ActionBase does not define setTitle; the operation belongs to the concrete key and dial action classes. Link those actual API members instead.

	 * Occurs when the user updates an action's title settings in the Stream Deck application. See also {@link ActionBase.setTitle}.

packages/plugin/src/plugin/actions/dial.ts:41

• setFeedbackLayout is declared on DialAction, not ActionBase, so this link now targets a nonexistent member.

This issue also appears on line 58 of the same file.

	 * to users, and can be assigned in the manifest, or dynamically via {@link ActionBase.setFeedbackLayout}.

packages/plugin/src/plugin/actions/tests/action.test.ts:336

• This assertion invokes showAlert on the KeyAction declared above; ActionBase has no such method. The updated documentation link therefore points to a nonexistent member.

		 * Asserts {@link ActionBase.showAlert} forwards the command to the {@link connection}.

Previously missed (8) — in code that hasn't changed since the last review.

packages/plugin/src/plugin/actions/action-base.ts:45

• This method no longer declares U, so the @template U documentation is stale and describes the loophole this refactor removes. Document the action-bound settings type instead.

	 * Gets the settings associated this action instance.
	 * @template U The type of settings associated with the action.D

packages/plugin/src/plugin/actions/action-base.ts:48

• The core change is a compile-time contract, but the updated tests only exercise runtime behavior and the package build excludes __tests__. Add a type-checked fixture that verifies unrelated values and explicit return-type overrides are rejected, while the declared settings type is accepted.

	public async getSettings(): Promise<TSettings> {

.changeset/free-oranges-lose.md:5

• NeoInfobarAction also lost its default settings type and is publicly exported, so this breaking-change note omits one affected API.

`Action`, `KeyAction`, and `DialAction` types now require their setting type be defined.

packages/plugin/src/plugin/actions/singleton-action.ts:105

• ActionBase has no sendToPropertyInspector method; that API belongs to streamDeck.ui, so this new link cannot resolve to the documented operation.

	 * Occurs when a message was sent to the plugin _from_ the property inspector. The plugin can also send messages _to_ the property inspector using {@link ActionBase.sendToPropertyInspector}.

packages/plugin/src/plugin/actions/singleton-action.ts:111

• ActionBase does not define setTitle; only concrete key and dial actions do. Remove this unresolved link from the public event documentation.

	 * Occurs when the user updates an action's title settings in the Stream Deck application. See also {@link ActionBase.setTitle}.

packages/plugin/src/plugin/actions/service.ts:177

• ActionBase does not define setTitle, so this link points to a nonexistent member. Keep the event description without that invalid cross-reference.

	 * Occurs when the user updates an action's title settings in the Stream Deck application. See also {@link ActionBase.setTitle}.

packages/plugin/src/plugin/actions/dial.ts:41

• setFeedbackLayout is declared on DialAction, not ActionBase; the new link targets a nonexistent base-class member.

This issue also appears on line 58 of the same file.

	 * to users, and can be assigned in the manifest, or dynamically via {@link ActionBase.setFeedbackLayout}.

packages/plugin/src/plugin/actions/tests/action.test.ts:336

• This test invokes showAlert on a KeyAction, while ActionBase has no such method. The updated link therefore points to a nonexistent member.

		 * Asserts {@link ActionBase.showAlert} forwards the command to the {@link connection}.

packages/plugin/src/plugin/actions/dial.ts:58

• setFeedback is declared on DialAction, not ActionBase; update the link so generated documentation resolves to the actual method.

	 * Use in conjunction with {@link ActionBase.setFeedback} to update the layout's current items' settings.

Previously missed (4) — in code that hasn't changed since the last review.

packages/plugin/src/plugin/actions/action-base.ts:47

• The JSDoc for getSettings still mentions a generic U and contains a typo (action.D), but the method no longer has a generic parameter. This documentation is now incorrect and misleading.

	/**
	 * Gets the settings associated this action instance.
	 * @template U The type of settings associated with the action.D
	 * @returns Promise containing the action instance's settings.
	 */

packages/plugin/src/plugin/actions/neo-infobar.ts:11

• DialAction and KeyAction use TSettings for their settings type parameter, but NeoInfobarAction uses T. Aligning the generic parameter name improves consistency and readability across action types.

/**
 * Provides a contextualized instance of an infobar action found on Stream Deck Neo.
 * @template T The type of settings associated with the action.
 */
export class NeoInfobarAction<T extends JsonObject> extends ActionBase<T> {

packages/plugin/src/plugin/actions/singleton-action.ts:71

• Typo in JSDoc: "when the the settings" has a duplicated word.

	 * Occurs when the settings associated with an action instance are requested using {@link ActionBase.getSettings}, or when the the settings were updated by the property inspector.

packages/plugin/src/plugin/actions/service.ts:34

• ActionBase is imported as a value but not used anywhere in this module (it only appears in JSDoc). This can trigger unused-import errors in TS/lint configurations and also adds an unnecessary runtime import.

import { ActionBase } from "./action-base.js";
import type { Action } from "./action.js";

Previously missed (3) — in code that hasn't changed since the last review.

packages/plugin/src/plugin/actions/singleton-action.ts:105

• ActionBase doesn’t define sendToPropertyInspector (the API is on streamDeck.ui). The JSDoc link currently points to a non-existent member.

This issue also appears on line 111 of the same file.

	 * Occurs when a message was sent to the plugin _from_ the property inspector. The plugin can also send messages _to_ the property inspector using {@link ActionBase.sendToPropertyInspector}.

packages/plugin/src/plugin/actions/dial.ts:42

• setFeedbackLayout is a DialAction method (not on ActionBase), so this JSDoc link points to a non-existent member.

This issue also appears on line 56 of the same file.

	 * Sets the feedback for the current layout associated with this action instance, allowing for the visual items to be updated. Layouts are a powerful way to provide dynamic information
	 * to users, and can be assigned in the manifest, or dynamically via {@link ActionBase.setFeedbackLayout}.
	 *

packages/plugin/src/plugin/actions/action-base.ts:45

• Minor grammar: missing “with” in this sentence.

	 * Gets the settings associated this action instance.
	 * @returns Promise containing the action instance's settings.

packages/plugin/src/plugin/actions/singleton-action.ts:111

• ActionBase doesn’t define setTitle; it’s implemented on KeyAction/DialAction. The JSDoc link should point to the actual API surface.

	 * Occurs when the user updates an action's title settings in the Stream Deck application. See also {@link ActionBase.setTitle}.

packages/plugin/src/plugin/actions/dial.ts:59

• setFeedback is a DialAction method (not on ActionBase), so this JSDoc link currently points to a non-existent member.

	/**
	 * Sets the layout associated with this action instance. The layout must be either a built-in layout identifier, or path to a local layout JSON file within the plugin's folder.
	 * Use in conjunction with {@link ActionBase.setFeedback} to update the layout's current items' settings.
	 * @param layout Name of a pre-defined layout, or relative path to a custom one.

Previously missed (4) — in code that hasn't changed since the last review.

packages/plugin/src/plugin/actions/singleton-action.ts:22

• ActionBase is only referenced in JSDoc in this file, so this type-only import is unused and is likely to fail strict linting (unused imports). Remove the import (or switch the JSDoc links to an import-qualified reference if you need ActionBase for documentation).

import type streamDeck from "../index.js";
import type { Action } from "../index.js";
import type { ActionBase } from "./action-base.js";
import { actionStore } from "./store.js";

packages/plugin/src/plugin/actions/singleton-action.ts:72

• The JSDoc links now reference ActionBase.*, but @elgato/streamdeck only exports ./dist/plugin/index.js (package.json exports), and ./actions/index.ts does not re-export ActionBase. This means consumers can’t import ActionBase from the public entrypoint and generated docs may have broken links. Consider re-exporting ActionBase (type-only is fine) from ./actions/index.ts / root index, or adjust the JSDoc links to reference methods on the concrete action types instead.

	/**
	 * Occurs when the settings associated with an action instance are requested using {@link ActionBase.getSettings}, or when the settings were updated by the property inspector.
	 * @param ev Information about the event, including the source action and contextual payload information.

packages/plugin/src/plugin/actions/action-base.ts:44

• Minor grammar in the new JSDoc: “associated this action instance” should be “associated with this action instance”.

	 * Gets the settings associated this action instance.

packages/plugin/src/plugin/actions/action-base.ts:149

• Use strict equality when comparing event contexts. ev.context and this.id are both expected to be strings, so === avoids accidental coercion and is consistent with typical TS style.

			if (ev.context == this.id) {