Actions

Actions live in <entity>.actions.ts and provide the React-facing orchestration layer for entity operations.

Responsibilities

• read live query state
• build operation input
• call workflow resolvers
• trigger confirmation or selection adapters
• call mutation hooks

Recommended API Shape

useEntityActions() => {
  executeAdd,
  executeUpdate,
  executeDelete,

  buildDeleteInput,
  buildEditInput,
  buildUpdateInput, // if needed

  getDeleteResolution,
  getEditResolution,
  getUpdateResolution,
}

Builder Functions

If getDeleteResolution or getEditResolution requires guard input, the hook should also expose the corresponding builder. This avoids forcing UI code to reimplement query-derived logic.

Action Contract Rules

• actions may read query hooks
• actions may handle “entity not found”
• actions may format item labels for confirmation UIs
• actions should not become the main home of domain rules
• actions should not silently reimplement workflow decisions

Mutation Hook Boundary

Action hooks are not the safety boundary.

If a rule blocks a write for integrity reasons, the matching mutation hook must enforce it again. Actions exist to orchestrate the correct user flow, not to be the only line of defense.

Import Guidance

App code should normally consume action hooks through:

import { useWorkProjectActions } from "@life-manager/db/hooks/actions/work";

Entity subpaths also export them when a more local import is needed.