noob-components/.trellis/spec/plugs-composables/use-refresh-flags.md

useRefreshFlags

Auto-refresh flag management with Vuex store integration.

Purpose

Watches refresh flags in Vuex store and triggers callbacks when matching flags are set. Used for coordinated auto-refresh across components.

Signature

export function useRefreshFlags(
  flags: string[],
  cb: () => void | Promise<void>,
  match?: "any" | "all",
  token?: string
): void

Parameters

Parameter	Type	Default	Description
flags	string[]	required	Flag names to watch
cb	() => void | Promise<void>	required	Callback when flag matches
match	"any" | "all"	"any"	Match any flag or all flags
token	string	route.path	Unique token for this watcher

Match Behavior

• "any": Trigger when any flag is set and this token hasn't consumed it
• "all": Trigger when all flags are set and this token hasn't consumed them

Vuex Store Structure

Expects state.refreshFlags to be a Map structure:

state.refreshFlags: Map<string, Set<string>>
// flag name -> Set of tokens that have consumed it

Usage Pattern

// Example: plugs/composables/useRefreshFlags.ts
import { useRefreshFlags } from "plugs/composables";

// Watch for any of these flags
useRefreshFlags(["userUpdated", "roleChanged"], async () => {
  await query();
});

// Watch for all flags
useRefreshFlags(["fetchUsers", "fetchDepartments"], async () => {
  await query();
}, "all");

// With custom token
useRefreshFlags(["refresh"], () => {
  query();
}, "any", "my-unique-component-id");

Key Implementation Details

1. Token auto-detection: Uses route.path as default token if not provided
2. Flag consumption: After callback executes, calls unsetRefreshFlag Vuex action to mark flags as consumed by this token
3. Reactive tracking: Explicitly accesses state.refreshFlags to ensure Vue tracks the dependency

Dependencies

• vue - watch
• vue-router - useRoute
• vuex - useStore

Anti-patterns

• Do not use the same token for multiple independent watchers; each logical unit should have unique token
• Do not forget to dispatch unsetRefreshFlag for consumed flags (handled automatically)