07-debuggable-state/02-action-design.md

Action design

Action design

Actions represent **explicit events** that cause state transitions.

Well-designed actions make debugging and reasoning about state changes much easier. They act as a clear log of what happened in the system.

Purpose of actions

Actions answer the question:

"What happened that caused the state to change?"

Reducers then answer:

"How does the state change because of that action?"

Keeping this separation is important for clarity.

Action design rules

Good actions should:

• have descriptive names
• represent a meaningful event
• carry explicit payload data
• be scoped to a feature when possible

Examples:

• FILES_ADD
• FILES_REMOVE
• EDITOR_SET_CONTENT
• DEBUGGER_SET_CLIENT

Avoid vague names such as:

• SET_DATA
• UPDATE
• CHANGE

These names make debugging harder.

Payload design

Payloads should be explicit objects.

Good:

{ file }

Avoid implicit or ambiguous payload structures.

Action creators

Action creators should live in the feature actions file and produce predictable action objects.

Example:

import { action } from "/vroqjs/system/store/action.js";

const _addFile = action("FILES_ADD");

export const addFile = (file) => _addFile({ file });

Final rule

Action names should clearly describe the event that occurred so state transitions are easy to inspect and debug.