@darksnow-ui/commander/docs/useInvoker-guide.md

Command pattern implementation with React hooks for building command palettes and keyboard-driven UIs

# useInvoker Hook - Guia Completo

O `useInvoker` é um hook que retorna **diretamente a função de execução** de um comando, eliminando a necessidade de chamar `.invoke()`. É a forma mais simples e direta de executar comandos no Commander.

## 📋 Índice

- [Visão Geral](#visão-geral)
- [Hook Principal](#hook-principal---useinvoker)
- [Hooks Especializados](#hooks-especializados)
  - [useAction](#1-useaction---para-comandos-sem-parâmetros)
  - [useCommandState](#2-usecommandstate---com-estado-completo)
  - [useSafeInvoker](#3-usesafeinvoker---execução-segura)
  - [useBoundInvoker](#4-useboundinvoker---input-pré-configurado)
  - [useToggleInvoker](#5-usetoggleinvoker---comandos-toggle)
  - [useBatchInvoker](#6-usebatchinvoker---execução-sequencial)
  - [useParallelInvoker](#7-useparallelinvoker---execução-paralela)
- [Comparação com useCommand](#comparação-com-usecommand)
- [Exemplos Práticos](#exemplos-práticos)
- [Casos de Uso Avançados](#casos-de-uso-avançados)

## 🎯 Visão Geral

O `useInvoker` e sua família de hooks especializados fornecem acesso direto e simplificado aos comandos:

```tsx
// useCommand - precisa chamar .invoke()
const command = useCommand("file:save");
await command.invoke(data);

// useInvoker - executa diretamente!
const save = useInvoker("file:save");
await save(data); // 🎯 Direto ao ponto!

// Família de hooks especializados
const logout = useAction("user:logout"); // Sem parâmetros
await logout();

const safeCall = useSafeInvoker("api:risky"); // Nunca lança erro
const result = await safeCall();

const saveUser = useBoundInvoker("user:save", {
  // Input pré-configurado
  createdBy: currentUser.id,
});
await saveUser({ name: "João" });

const toggle = useToggleInvoker("ui:dark-mode"); // Estados booleanos
await toggle(true);

const batch = useBatchInvoker([
  // Execução sequencial
  "validate",
  "process",
  "save",
]);
await batch(inputs);

const parallel = useParallelInvoker([
  // Execução paralela
  "api:users",
  "api:stats",
  "api:logs",
]);
const results = await parallel();
```

## 🔧 Hook Principal - useInvoker

### Assinatura

```tsx
useInvoker<TInput, TOutput>(
  key: CommandKey,
  options?: UseInvokerOptions<TInput, TOutput>
): (input?: TInput) => Promise<TOutput>

// SEMPRE retorna uma função de execução direta
```

### Configurações Disponíveis

```tsx
interface UseInvokerOptions<TInput, TOutput> {
  // Execução
  source?: CommandSource; // 'api' | 'palette' | 'shortcut'
  throwOnError?: boolean; // Default: true

  // Input
  defaultInput?: Partial<TInput>; // Input padrão mesclado

  // Callbacks
  onSuccess?: (result: TOutput) => void;
  onError?: (error: Error) => void;
}
```

> **Nota**: Para funcionalidades avançadas como retry, debounce, throttle, validação ou transformação, use `useCommand` diretamente.

### Exemplos Básicos

```tsx
// 1. Execução simples
function LogoutButton() {
  const logout = useInvoker("user:logout");

  return <button onClick={() => logout()}>Sair</button>;
}

// 2. Com input
function SaveButton({ document }) {
  const saveDoc = useInvoker<SaveInput, SaveResult>("document:save");

  const handleSave = async () => {
    const result = await saveDoc({
      id: document.id,
      content: document.content,
    });
    toast.success(`Salvo: ${result.filename}`);
  };

  return <button onClick={handleSave}>Salvar</button>;
}

// 3. Com configurações
function SmartUploader() {
  const upload = useInvoker("file:upload", {
    throwOnError: false,
    defaultInput: { quality: "high" },

    onSuccess: (result) => {
      analytics.track("file_uploaded", { size: result.size });
    },

    onError: (error) => {
      notification.error("Upload falhou: " + error.message);
    },
  });

  const handleUpload = async (file: File) => {
    const result = await upload({ file });
    if (result) {
      setUploadedFiles((prev) => [...prev, result]);
    }
  };
}

// 4. Quando precisar de estado, use useCommand
function FileUploader() {
  const uploader = useCommand("file:upload", {
    onSuccess: (result) => toast.success("Upload concluído!"),
  });

  return (
    <div>
      <input
        type="file"
        onChange={(e) => uploader.invoke({ file: e.target.files[0] })}
        disabled={uploader.isLoading}
      />

      {uploader.isLoading && <Spinner />}
      {uploader.lastError && (
        <div className="error">{uploader.lastError.message}</div>
      )}
    </div>
  );
}
```

## 🎪 Hooks Especializados

### 1. useAction - Para Comandos Sem Parâmetros

Otimizado para comandos que não recebem input (ou sempre usam o mesmo input).

```tsx
useAction(key: CommandKey): () => Promise<TOutput>
```

#### Exemplos

```tsx
// Ações simples
function NavigationButtons() {
  const goHome = useAction("navigation:home");
  const openSettings = useAction("modal:settings");
  const refreshData = useAction("data:refresh");

  return (
    <div className="flex gap-2">
      <button onClick={goHome}>🏠 Home</button>
      <button onClick={openSettings}>⚙️ Configurações</button>
      <button onClick={refreshData}>🔄 Atualizar</button>
    </div>
  );
}

// Comandos do sistema
function SystemActions() {
  const clearCache = useAction("system:clear-cache");
  const exportLogs = useAction("system:export-logs");
  const runHealthCheck = useAction("system:health-check");

  const handleClearCache = async () => {
    if (confirm("Limpar cache?")) {
      await clearCache();
      toast.success("Cache limpo!");
    }
  };

  return (
    <div className="admin-panel">
      <button onClick={handleClearCache}>Limpar Cache</button>
      <button onClick={exportLogs}>Exportar Logs</button>
      <button onClick={runHealthCheck}>Health Check</button>
    </div>
  );
}

// Ações de usuário
function UserActions() {
  const logout = useAction("user:logout");
  const deleteAccount = useAction("user:delete-account");

  const handleDeleteAccount = async () => {
    const confirmed = await showConfirmDialog({
      title: "Deletar Conta",
      message: "Esta ação é irreversível!",
      confirmText: "Deletar",
      cancelText: "Cancelar",
    });

    if (confirmed) {
      await deleteAccount();
      // Usuário será redirecionado automaticamente
    }
  };

  return (
    <div className="user-menu">
      <button onClick={logout}>Sair</button>
      <button onClick={handleDeleteAccount} className="danger">
        Deletar Conta
      </button>
    </div>
  );
}
```

### 2. useCommandState - Com Estado Completo

Simplesmente um alias para `useCommand`, mantido para compatibilidade.

```tsx
useCommandState<TInput, TOutput>(
  key: CommandKey,
  options?: UseInvokerOptions
): CommandInvoker<TInput, TOutput>
```

> **Nota**: Com a refatoração, `useCommandState` é funcionalmente idêntico a `useCommand`. Considere usar `useCommand` diretamente.

#### Exemplos

```tsx
// Monitor de operações
function OperationMonitor() {
  const backup = useCommandState("system:backup");
  const sync = useCommandState("data:sync");
  const cleanup = useCommandState("system:cleanup");

  const operations = [
    { name: "Backup", command: backup },
    { name: "Sincronização", command: sync },
    { name: "Limpeza", command: cleanup },
  ];

  return (
    <div className="operations-panel">
      <h3>Status das Operações</h3>
      {operations.map(({ name, command }) => (
        <div key={name} className="operation-row">
          <span>{name}</span>

          {command.isLoading && <Spinner />}

          {command.lastExecution && (
            <span className="last-run">
              Última execução: {formatDistanceToNow(command.lastExecution)}
            </span>
          )}

          {command.lastError && (
            <span className="error">❌ {command.lastError.message}</span>
          )}

          <button onClick={() => command.invoke()} disabled={command.isLoading}>
            Executar
          </button>
        </div>
      ))}
    </div>
  );
}

// Dashboard com métricas
function SystemDashboard() {
  const healthCheck = useCommandState("system:health-check");
  const getMetrics = useCommandState("system:metrics");

  // Auto-refresh a cada 30 segundos
  useInterval(() => {
    if (!healthCheck.isLoading) {
      healthCheck.invoke();
    }
    if (!getMetrics.isLoading) {
      getMetrics.invoke();
    }
  }, 30000);

  return (
    <div className="dashboard">
      <div className="health-card">
        <h4>System Health</h4>

        {healthCheck.isLoading && <Spinner />}

        {healthCheck.lastResult && (
          <div className={`status ${healthCheck.lastResult.status}`}>
            {healthCheck.lastResult.status.toUpperCase()}
          </div>
        )}

        <div className="stats">
          <span>Checks realizados: {healthCheck.executionCount}</span>
        </div>
      </div>

      <div className="metrics-card">
        <h4>Métricas</h4>

        {getMetrics.lastResult && (
          <div className="metrics">
            <div>CPU: {getMetrics.lastResult.cpu}%</div>
            <div>Memória: {getMetrics.lastResult.memory}%</div>
            <div>Disco: {getMetrics.lastResult.disk}%</div>
          </div>
        )}
      </div>
    </div>
  );
}
```

### 3. useSafeInvoker - Execução Segura

Nunca lança erros, sempre retorna `ExecutionResult`.

```tsx
useSafeInvoker<TInput, TOutput>(
  key: CommandKey,
  options?: Omit<UseInvokerOptions, 'throwOnError'>
): (input?: TInput) => Promise<ExecutionResult<TOutput>>

interface ExecutionResult<T> {
  success: boolean
  result?: T
  error?: Error
  command: CommandKey
}
```

#### Exemplos

```tsx
// API calls não-críticas
function OptionalFeatures() {
  const loadRecommendations = useSafeInvoker("ai:recommendations");
  const loadAnalytics = useSafeInvoker("analytics:load");

  const [recommendations, setRecommendations] = useState(null);
  const [analytics, setAnalytics] = useState(null);

  useEffect(() => {
    // Carrega recursos opcionais sem quebrar a UI
    Promise.all([
      loadRecommendations({ userId: currentUser.id }),
      loadAnalytics({ period: "7d" }),
    ]).then(([recResult, analyticsResult]) => {
      if (recResult.success) {
        setRecommendations(recResult.result);
      }

      if (analyticsResult.success) {
        setAnalytics(analyticsResult.result);
      }
    });
  }, []);

  return (
    <div className="optional-features">
      {recommendations && <RecommendationsWidget data={recommendations} />}

      {analytics && <AnalyticsWidget data={analytics} />}
    </div>
  );
}

// Operações em batch com falhas toleradas
function BatchProcessor() {
  const processItem = useSafeInvoker("item:process");

  const [results, setResults] = useState([]);
  const [isProcessing, setIsProcessing] = useState(false);

  const processBatch = async (items) => {
    setIsProcessing(true);
    const results = [];

    for (const item of items) {
      const result = await processItem({ item });
      results.push({
        item,
        success: result.success,
        data: result.result,
        error: result.error?.message,
      });
    }

    setResults(results);
    setIsProcessing(false);

    const successCount = results.filter((r) => r.success).length;
    toast.success(`${successCount}/${items.length} itens processados`);
  };

  return (
    <div className="batch-processor">
      <button
        onClick={() => processBatch(selectedItems)}
        disabled={isProcessing}
      >
        {isProcessing ? "Processando..." : "Processar Lote"}
      </button>

      {results.length > 0 && (
        <div className="results">
          {results.map((result, index) => (
            <div
              key={index}
              className={`result ${result.success ? "success" : "error"}`}
            >
              <span>{result.item.name}</span>
              {result.success ? (
                <span className="success">✅ Sucesso</span>
              ) : (
                <span className="error">❌ {result.error}</span>
              )}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

// Fallbacks e degradação graciosa
function DataVisualization() {
  const loadLiveData = useSafeInvoker("data:live");
  const loadCachedData = useSafeInvoker("data:cached");

  const [data, setData] = useState(null);
  const [dataSource, setDataSource] = useState("loading");

  useEffect(() => {
    const loadData = async () => {
      // Tenta dados ao vivo primeiro
      const liveResult = await loadLiveData();

      if (liveResult.success) {
        setData(liveResult.result);
        setDataSource("live");
        return;
      }

      // Fallback para dados em cache
      const cachedResult = await loadCachedData();

      if (cachedResult.success) {
        setData(cachedResult.result);
        setDataSource("cached");
      } else {
        setDataSource("unavailable");
      }
    };

    loadData();
  }, []);

  if (dataSource === "loading") {
    return <div>Carregando dados...</div>;
  }

  if (dataSource === "unavailable") {
    return <div>Dados indisponíveis no momento</div>;
  }

  return (
    <div className="data-viz">
      {dataSource === "cached" && (
        <div className="warning">
          ⚠️ Exibindo dados em cache (dados ao vivo indisponíveis)
        </div>
      )}

      <DataChart data={data} />
    </div>
  );
}
```

### 4. useBoundInvoker - Input Pré-configurado

Combina input padrão com input fornecido na execução.

```tsx
useBoundInvoker<TInput, TOutput>(
  key: CommandKey,
  boundInput: Partial<TInput>,
  options?: Omit<UseInvokerOptions, 'defaultInput'>
): (input?: Partial<TInput>) => Promise<TOutput>
```

#### Exemplos

```tsx
// Usuário atual em contexto
function CurrentUserActions() {
  const currentUser = useCurrentUser();

  // Input sempre inclui userId atual
  const updateProfile = useBoundInvoker("user:update", {
    userId: currentUser.id,
  });

  const changePassword = useBoundInvoker("user:change-password", {
    userId: currentUser.id,
  });

  const deleteAccount = useBoundInvoker("user:delete", {
    userId: currentUser.id,
  });

  const handleUpdateProfile = async (profileData) => {
    // userId é adicionado automaticamente
    await updateProfile({
      name: profileData.name,
      email: profileData.email,
      // userId já está incluído
    });
  };

  const handleChangePassword = async (passwords) => {
    await changePassword({
      currentPassword: passwords.current,
      newPassword: passwords.new,
      // userId já está incluído
    });
  };
}

// Contexto de workspace
function WorkspaceCommands() {
  const { currentWorkspace } = useWorkspace();

  // Comandos sempre executam no workspace atual
  const createProject = useBoundInvoker("project:create", {
    workspaceId: currentWorkspace.id,
    createdBy: getCurrentUser().id,
  });

  const inviteUser = useBoundInvoker("workspace:invite", {
    workspaceId: currentWorkspace.id,
    invitedBy: getCurrentUser().id,
  });

  const updateSettings = useBoundInvoker("workspace:update-settings", {
    workspaceId: currentWorkspace.id,
  });

  return (
    <div className="workspace-actions">
      <button
        onClick={() =>
          createProject({
            name: "Novo Projeto",
            template: "web-app",
          })
        }
      >
        Criar Projeto
      </button>

      <button
        onClick={() =>
          inviteUser({
            email: "user@example.com",
            role: "member",
          })
        }
      >
        Convidar Usuário
      </button>
    </div>
  );
}

// Configurações de API
function ApiCommands() {
  const apiConfig = useApiConfig();

  // Todas as chamadas incluem configuração padrão
  const apiCall = useBoundInvoker("api:call", {
    baseUrl: apiConfig.baseUrl,
    timeout: apiConfig.timeout,
    retries: 3,
    headers: {
      Authorization: `Bearer ${apiConfig.token}`,
      "User-Agent": "MyApp/1.0",
    },
  });

  const uploadFile = useBoundInvoker("api:upload", {
    baseUrl: apiConfig.baseUrl,
    headers: {
      Authorization: `Bearer ${apiConfig.token}`,
    },
    timeout: 60000, // Upload tem timeout maior
  });

  // Uso simplificado
  const fetchUsers = () =>
    apiCall({
      endpoint: "/users",
      method: "GET",
    });

  const createUser = (userData) =>
    apiCall({
      endpoint: "/users",
      method: "POST",
      body: userData,
    });

  const uploadAvatar = (file) =>
    uploadFile({
      endpoint: "/avatars",
      file: file,
    });
}

// Formulários com dados parciais
function FormCommands() {
  const { formData } = useFormContext();

  // Salvamento sempre inclui dados base do formulário
  const saveStep = useBoundInvoker("form:save-step", {
    formId: formData.id,
    userId: formData.userId,
    sessionId: formData.sessionId,
  });

  const validateStep = useBoundInvoker("form:validate-step", {
    formId: formData.id,
    formType: formData.type,
  });

  // Uso nos componentes de step
  const saveStep1 = (stepData) =>
    saveStep({
      step: 1,
      data: stepData,
    });

  const saveStep2 = (stepData) =>
    saveStep({
      step: 2,
      data: stepData,
    });

  const validateCurrentStep = (stepNumber, data) =>
    validateStep({
      step: stepNumber,
      data: data,
    });
}
```

### 5. useToggleInvoker - Comandos Toggle

Especializado para comandos que trabalham com estados booleanos.

```tsx
useToggleInvoker(
  key: CommandKey,
  options?: Omit<UseInvokerOptions<boolean, boolean>, 'defaultInput'>
): (state?: boolean) => Promise<boolean>
```

#### Exemplos

```tsx
// Sistema de preferências
function UserPreferences() {
  const toggleDarkMode = useToggleInvoker("preferences:dark-mode");
  const toggleNotifications = useToggleInvoker("preferences:notifications");
  const toggleAutoSave = useToggleInvoker("preferences:auto-save");

  const [isDarkMode, setIsDarkMode] = useState(false);
  const [hasNotifications, setHasNotifications] = useState(true);
  const [hasAutoSave, setHasAutoSave] = useState(true);

  const handleDarkModeToggle = async () => {
    const newState = await toggleDarkMode(!isDarkMode);
    setIsDarkMode(newState);
  };

  const handleNotificationsToggle = async () => {
    const newState = await toggleNotifications(!hasNotifications);
    setHasNotifications(newState);
  };

  return (
    <div className="preferences">
      <label>
        <input
          type="checkbox"
          checked={isDarkMode}
          onChange={handleDarkModeToggle}
        />
        Modo Escuro
      </label>

      <label>
        <input
          type="checkbox"
          checked={hasNotifications}
          onChange={handleNotificationsToggle}
        />
        Notificações
      </label>

      <label>
        <input
          type="checkbox"
          checked={hasAutoSave}
          onChange={() => toggleAutoSave(!hasAutoSave).then(setHasAutoSave)}
        />
        Salvamento Automático
      </label>
    </div>
  );
}

// Controles de visibilidade
function VisibilityControls() {
  const toggleSidebar = useToggleInvoker("ui:toggle-sidebar");
  const toggleDevTools = useToggleInvoker("ui:toggle-devtools");
  const toggleFullscreen = useToggleInvoker("ui:toggle-fullscreen");

  return (
    <div className="ui-controls">
      <button onClick={() => toggleSidebar()}>Alternar Barra Lateral</button>

      <button onClick={() => toggleDevTools()}>DevTools</button>

      <button onClick={() => toggleFullscreen()}>Tela Cheia</button>
    </div>
  );
}

// Feature flags
function FeatureFlags() {
  const toggleFeature = useToggleInvoker("feature:toggle");
  const [features, setFeatures] = useState({
    newDashboard: false,
    betaEditor: false,
    experimentalApi: false,
  });

  const handleToggleFeature = async (featureName) => {
    const newState = await toggleFeature({
      feature: featureName,
      enabled: !features[featureName],
    });

    setFeatures((prev) => ({
      ...prev,
      [featureName]: newState,
    }));
  };

  return (
    <div className="feature-flags">
      <h3>Features Experimentais</h3>

      {Object.entries(features).map(([feature, enabled]) => (
        <div key={feature}>
          <label>
            <input
              type="checkbox"
              checked={enabled}
              onChange={() => handleToggleFeature(feature)}
            />
            {feature}
          </label>
        </div>
      ))}
    </div>
  );
}
```

### 6. useBatchInvoker - Execução Sequencial

Executa múltiplos comandos em sequência, com controle de erro e progresso.

```tsx
useBatchInvoker(
  keys: CommandKey[],
  options?: {
    source?: CommandSource
    stopOnError?: boolean
    onProgress?: (completed: number, total: number) => void
  }
): (inputs?: any[], batchOptions?: { stopOnError?: boolean }) => Promise<ExecutionResult[]>
```

#### Exemplos

```tsx
// Processamento de múltiplos arquivos
function BatchFileProcessor() {
  const processFiles = useBatchInvoker(
    ["file:validate", "file:optimize", "file:upload", "file:index"],
    {
      stopOnError: true,
      onProgress: (completed, total) => {
        console.log(`Processado ${completed}/${total}`);
      },
    },
  );

  const [progress, setProgress] = useState({ completed: 0, total: 0 });
  const [results, setResults] = useState([]);

  const handleProcessFiles = async (files) => {
    const inputs = [
      { files }, // para validate
      { files }, // para optimize
      { files }, // para upload
      { uploadedFiles: files }, // para index
    ];

    const batchResults = await processFiles(inputs, {
      stopOnError: false, // continua mesmo com erros
    });

    setResults(batchResults);

    const successful = batchResults.filter((r) => r.success).length;
    toast.info(`${successful}/${batchResults.length} operações concluídas`);
  };

  return (
    <div className="batch-processor">
      <FileDropzone onDrop={handleProcessFiles} />

      {results.length > 0 && (
        <div className="results">
          <h4>Resultados do Processamento:</h4>
          {results.map((result, idx) => (
            <div key={idx} className={result.success ? "success" : "error"}>
              Etapa {idx + 1}: {result.success ? "✅" : "❌"}
              {result.error && <span>{result.error.message}</span>}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

// Pipeline de implantação
function DeploymentPipeline() {
  const deploySteps = useBatchInvoker(
    [
      "build:compile",
      "test:unit",
      "test:integration",
      "deploy:staging",
      "test:e2e",
      "deploy:production",
    ],
    {
      stopOnError: true, // para na primeira falha
      onProgress: (step, total) => {
        updateDeploymentStatus({
          currentStep: step,
          totalSteps: total,
          percentage: (step / total) * 100,
        });
      },
    },
  );

  const [isDeploying, setIsDeploying] = useState(false);
  const [deploymentLog, setDeploymentLog] = useState([]);

  const startDeployment = async () => {
    setIsDeploying(true);
    setDeploymentLog([]);

    const config = {
      branch: "main",
      environment: "production",
      version: "2.0.0",
    };

    // Cada comando recebe a mesma config
    const inputs = Array(6).fill(config);

    const results = await deploySteps(inputs);

    // Processa resultados
    results.forEach((result, idx) => {
      const stepName = [
        "Compilação",
        "Testes Unitários",
        "Testes de Integração",
        "Deploy Staging",
        "Testes E2E",
        "Deploy Produção",
      ][idx];

      setDeploymentLog((prev) => [
        ...prev,
        {
          step: stepName,
          success: result.success,
          error: result.error?.message,
          timestamp: new Date(),
        },
      ]);
    });

    setIsDeploying(false);

    const allSuccessful = results.every((r) => r.success);
    if (allSuccessful) {
      toast.success("Deploy concluído com sucesso!");
    } else {
      toast.error("Deploy falhou!");
    }
  };

  return (
    <div className="deployment-pipeline">
      <button onClick={startDeployment} disabled={isDeploying}>
        {isDeploying ? "Deployment em progresso..." : "Iniciar Deploy"}
      </button>

      <div className="deployment-log">
        {deploymentLog.map((entry, idx) => (
          <div
            key={idx}
            className={`log-entry ${entry.success ? "success" : "error"}`}
          >
            <span>{entry.step}</span>
            <span>{entry.success ? "✅" : "❌"}</span>
            {entry.error && <span className="error-msg">{entry.error}</span>}
          </div>
        ))}
      </div>
    </div>
  );
}

// Wizard multi-etapas
function SetupWizard() {
  const setupSteps = useBatchInvoker([
    "setup:check-requirements",
    "setup:install-dependencies",
    "setup:configure-database",
    "setup:create-admin",
    "setup:initial-data",
  ]);

  const [currentStep, setCurrentStep] = useState(0);
  const [setupData, setSetupData] = useState({});

  const runSetup = async () => {
    const inputs = [
      { os: navigator.platform },
      { packageManager: "npm" },
      { database: setupData.database },
      { admin: setupData.admin },
      { sampleData: setupData.includeSampleData },
    ];

    const results = await setupSteps(inputs, {
      stopOnError: true,
    });

    if (results.every((r) => r.success)) {
      router.push("/dashboard");
    }
  };
}
```

### 7. useParallelInvoker - Execução Paralela

Executa múltiplos comandos em paralelo, retornando Promise.allSettled results.

```tsx
useParallelInvoker(
  keys: CommandKey[],
  options?: { source?: CommandSource }
): (inputs?: any[]) => Promise<PromiseSettledResult<any>[]>
```

#### Exemplos

```tsx
// Carregamento paralelo de dados do dashboard
function DashboardData() {
  const loadDashboardData = useParallelInvoker([
    "stats:revenue",
    "stats:users",
    "stats:orders",
    "chart:sales",
    "notifications:unread",
  ]);

  const [dashboardData, setDashboardData] = useState({
    revenue: null,
    users: null,
    orders: null,
    salesChart: null,
    notifications: null,
  });

  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    const loadData = async () => {
      setIsLoading(true);

      // Inputs para cada comando
      const inputs = [
        { period: "30d" }, // revenue
        { status: "active" }, // users
        { status: "pending" }, // orders
        { range: "last-month" }, // sales chart
        { limit: 10 }, // notifications
      ];

      const results = await loadDashboardData(inputs);

      // Processa resultados
      setDashboardData({
        revenue: results[0].status === "fulfilled" ? results[0].value : null,
        users: results[1].status === "fulfilled" ? results[1].value : null,
        orders: results[2].status === "fulfilled" ? results[2].value : null,
        salesChart: results[3].status === "fulfilled" ? results[3].value : null,
        notifications:
          results[4].status === "fulfilled" ? results[4].value : null,
      });

      setIsLoading(false);

      // Log de erros
      results.forEach((result, idx) => {
        if (result.status === "rejected") {
          console.error(
            `Falha ao carregar ${["revenue", "users", "orders", "chart", "notifications"][idx]}:`,
            result.reason,
          );
        }
      });
    };

    loadData();
  }, []);

  if (isLoading) return <DashboardSkeleton />;

  return (
    <div className="dashboard">
      {dashboardData.revenue && <RevenueCard data={dashboardData.revenue} />}
      {dashboardData.users && <UsersCard data={dashboardData.users} />}
      {dashboardData.orders && <OrdersCard data={dashboardData.orders} />}
      {dashboardData.salesChart && (
        <SalesChart data={dashboardData.salesChart} />
      )}
      {dashboardData.notifications && (
        <NotificationsList data={dashboardData.notifications} />
      )}
    </div>
  );
}

// Busca em múltiplas fontes
function UniversalSearch() {
  const searchAllSources = useParallelInvoker([
    "search:users",
    "search:products",
    "search:orders",
    "search:documents",
    "search:help",
  ]);

  const [searchResults, setSearchResults] = useState({});
  const [isSearching, setIsSearching] = useState(false);

  const handleSearch = async (query) => {
    if (!query.trim()) return;

    setIsSearching(true);

    // Mesmo query para todas as fontes
    const inputs = Array(5).fill({ query, limit: 5 });

    const results = await searchAllSources(inputs);

    const processedResults = {
      users: results[0].status === "fulfilled" ? results[0].value : [],
      products: results[1].status === "fulfilled" ? results[1].value : [],
      orders: results[2].status === "fulfilled" ? results[2].value : [],
      documents: results[3].status === "fulfilled" ? results[3].value : [],
      help: results[4].status === "fulfilled" ? results[4].value : [],
    };

    setSearchResults(processedResults);
    setIsSearching(false);
  };

  return (
    <div className="universal-search">
      <SearchInput
        onSearch={handleSearch}
        placeholder="Buscar em todo o sistema..."
      />

      {isSearching && <SearchSpinner />}

      <div className="search-results">
        {Object.entries(searchResults).map(
          ([category, items]) =>
            items.length > 0 && (
              <div key={category} className="result-category">
                <h4>{category}</h4>
                {items.map((item) => (
                  <SearchResultItem key={item.id} item={item} />
                ))}
              </div>
            ),
        )}
      </div>
    </div>
  );
}

// Validação paralela de formulário
function ComplexFormValidation() {
  const validateFields = useParallelInvoker([
    "validate:email",
    "validate:cpf",
    "validate:phone",
    "validate:address",
    "validate:credit-card",
  ]);

  const [errors, setErrors] = useState({});
  const [isValidating, setIsValidating] = useState(false);

  const validateForm = async (formData) => {
    setIsValidating(true);

    const inputs = [
      { email: formData.email },
      { cpf: formData.cpf },
      { phone: formData.phone },
      { address: formData.address },
      { creditCard: formData.creditCard },
    ];

    const results = await validateFields(inputs);

    const validationErrors = {};
    const fieldNames = ["email", "cpf", "phone", "address", "creditCard"];

    results.forEach((result, idx) => {
      if (
        result.status === "rejected" ||
        (result.status === "fulfilled" && !result.value.isValid)
      ) {
        validationErrors[fieldNames[idx]] =
          result.status === "rejected"
            ? "Erro ao validar campo"
            : result.value.error;
      }
    });

    setErrors(validationErrors);
    setIsValidating(false);

    return Object.keys(validationErrors).length === 0;
  };

  return { validateForm, errors, isValidating };
}
```

## 🆚 Comparação com useCommand

| Aspecto            | useCommand              | useInvoker        |
| ------------------ | ----------------------- | ----------------- |
| **Retorno**        | CommandInvoker (objeto) | Função direta     |
| **Uso**            | `cmd.invoke(data)`      | `cmd(data)`       |
| **Estado**         | Sempre disponível       | Use `useCommand`  |
| **Configurações**  | Todas disponíveis       | Essenciais apenas |
| **Retry/Debounce** | ✅ Sim                  | ❌ Não            |
| **Transformações** | ✅ Sim                  | ❌ Não            |
| **Casos de Uso**   | Complexos               | Simples e diretos |

### Quando Usar Cada Um

```tsx
// Use useCommand quando precisar de:
// ✅ Estado (isLoading, lastResult, etc)
// ✅ Múltiplos métodos (invoke, attempt, execute)
// ✅ Configurações avançadas (retry, debounce, throttle)
// ✅ Transformações de dados
// ✅ Validação de input

const command = useCommand("complex:operation", {
  retry: 3,
  debounce: 500,
  transformInput: (input) => ({ ...input, timestamp: Date.now() }),
  validateInput: (input) => (input.name ? true : "Nome obrigatório"),
});

// Acesso ao estado
console.log(command.isLoading);
console.log(command.lastResult);

// Múltiplos métodos
await command.invoke(data); // Lança erro se falhar
await command.attempt(data); // Retorna ExecutionResult
await command.execute(data); // Com callbacks inline

// Use useInvoker quando quiser:
// ✅ Execução direta e simples
// ✅ Sintaxe mínima
// ✅ Sem necessidade de estado
// ✅ Performance otimizada

const save = useInvoker("file:save");
await save(data); // Simples e direto!

// Para ações específicas
const logout = useAction("user:logout");
await logout();

const safeCall = useSafeInvoker("risky:operation");
const result = await safeCall(); // Nunca lança erro
```

## 🎯 Casos de Uso Avançados

### 1. Sistema de Notificações

```tsx
function NotificationSystem() {
  // Ações diretas para tipos de notificação
  const showSuccess = useAction("notification:success");
  const showError = useAction("notification:error");
  const showWarning = useAction("notification:warning");

  // Notificação customizada com input bound
  const showCustom = useBoundInvoker("notification:custom", {
    duration: 5000,
    position: "top-right",
    dismissible: true,
  });

  // Toast com estado para controle
  const toast = useCommandState("notification:toast");

  const notify = {
    success: (message) => showSuccess({ message }),
    error: (message) => showError({ message }),
    warning: (message) => showWarning({ message }),

    custom: (message, options = {}) =>
      showCustom({
        message,
        ...options,
      }),

    progress: (message) =>
      toast.invoke({
        type: "progress",
        message,
        showProgress: true,
      }),
  };

  return { notify, toast };
}

// Uso no app
function App() {
  const { notify } = useNotificationSystem();

  const handleSave = async () => {
    notify.progress("Salvando documento...");

    try {
      await saveDocument();
      notify.success("Documento salvo!");
    } catch (error) {
      notify.error("Erro ao salvar: " + error.message);
    }
  };
}
```

### 2. Sistema de Cache Inteligente

```tsx
function SmartCache() {
  // Cache hit/miss com estado
  const cacheGet = useCommandState("cache:get");
  const cacheSet = useSafeInvoker("cache:set");
  const cacheInvalidate = useAction("cache:invalidate");

  const useCache = (key, fetcher, options = {}) => {
    const [data, setData] = useState(null);
    const [loading, setLoading] = useState(true);

    useEffect(() => {
      const loadData = async () => {
        setLoading(true);

        // Tenta cache primeiro
        const cached = await cacheGet.invoke({ key });

        if (cached && !isExpired(cached, options.ttl)) {
          setData(cached.data);
          setLoading(false);
          return;
        }

        // Cache miss - busca dados
        try {
          const freshData = await fetcher();
          setData(freshData);

          // Salva no cache (safe - não quebra se falhar)
          await cacheSet({
            key,
            data: freshData,
            timestamp: Date.now(),
          });
        } catch (error) {
          console.error("Fetch failed:", error);
        } finally {
          setLoading(false);
        }
      };

      loadData();
    }, [key]);

    const invalidate = () => {
      cacheInvalidate({ key });
      setData(null);
    };

    return { data, loading, invalidate, cacheHit: cacheGet.lastResult };
  };

  return { useCache };
}

// Uso
function UserProfile({ userId }) {
  const { useCache } = useSmartCache();

  const {
    data: user,
    loading,
    invalidate,
  } = useCache(
    `user:${userId}`,
    () => fetchUser(userId),
    { ttl: 5 * 60 * 1000 }, // 5 minutos
  );

  if (loading) return <Spinner />;

  return (
    <div>
      <UserInfo user={user} />
      <button onClick={invalidate}>Atualizar</button>
    </div>
  );
}
```

### 3. Upload Manager

```tsx
function UploadManager() {
  // Upload único com estado completo
  const singleUpload = useCommandState("file:upload-single");

  // Upload em lote (seguro para continuar mesmo com falhas)
  const batchUpload = useSafeInvoker("file:upload-batch");

  // Operações bound ao usuário atual
  const currentUser = useCurrentUser();
  const uploadToGallery = useBoundInvoker("file:upload-gallery", {
    userId: currentUser.id,
    gallery: "user-uploads",
  });

  const uploadToProject = useBoundInvoker("file:upload-project", {
    userId: currentUser.id,
  });

  const uploadStates = new Map();

  const uploadFile = async (file, destination = "general") => {
    const uploadId = generateId();

    switch (destination) {
      case "gallery":
        return await uploadToGallery({ file, uploadId });

      case "project":
        const projectId = getCurrentProject().id;
        return await uploadToProject({ file, uploadId, projectId });

      default:
        return await singleUpload.invoke({ file, uploadId });
    }
  };

  const uploadMultiple = async (files) => {
    const result = await batchUpload(
      files.map((file) => ({
        file,
        uploadId: generateId(),
      })),
    );

    if (result.success) {
      return result.result;
    } else {
      // Processa resultados parciais
      const { successful, failed } = result.error.partialResults || {};

      toast.info(
        `${successful?.length || 0} arquivos enviados, ${failed?.length || 0} falharam`,
      );

      return { successful, failed };
    }
  };

  return {
    uploadFile,
    uploadMultiple,
    singleUploadState: singleUpload,
    clearUploadHistory: () => singleUpload.reset(),
  };
}

// Componente de upload
function FileUploadZone() {
  const { uploadFile, uploadMultiple, singleUploadState } = useUploadManager();

  const handleDrop = async (files) => {
    if (files.length === 1) {
      await uploadFile(files[0], "gallery");
    } else {
      await uploadMultiple(files);
    }
  };

  return (
    <div
      className="upload-zone"
      onDrop={handleDrop}
      data-uploading={singleUploadState.isLoading}
    >
      {singleUploadState.isLoading ? (
        <div className="upload-progress">
          <Spinner />
          <span>Enviando arquivo...</span>
        </div>
      ) : (
        <div className="upload-hint">
          Arraste arquivos aqui ou clique para selecionar
        </div>
      )}

      {singleUploadState.lastError && (
        <div className="upload-error">
          ❌ {singleUploadState.lastError.message}
          <button onClick={singleUploadState.clearError}>×</button>
        </div>
      )}
    </div>
  );
}
```

## 🎭 Patterns Avançados

### 1. Command Factory Pattern

```tsx
function useCommandFactory() {
  const createCRUDCommands = (entity) => ({
    create: useBoundInvoker(`${entity}:create`, {
      createdBy: getCurrentUser().id,
    }),

    update: useBoundInvoker(`${entity}:update`, {
      updatedBy: getCurrentUser().id,
    }),

    delete: useSafeInvoker(`${entity}:delete`),

    list: useCommandState(`${entity}:list`),

    get: useInvoker(`${entity}:get`),
  });

  return { createCRUDCommands };
}

// Uso
function UserManagement() {
  const { createCRUDCommands } = useCommandFactory();
  const userCommands = createCRUDCommands("user");

  return (
    <div>
      <button onClick={() => userCommands.create({ name: "João" })}>
        Criar Usuário
      </button>

      <button onClick={() => userCommands.list.invoke()}>
        Listar Usuários
      </button>

      {userCommands.list.isLoading && <Spinner />}
    </div>
  );
}
```

### 2. State Machine Integration

```tsx
function useWorkflowState() {
  const transitions = {
    start: useAction("workflow:start"),
    pause: useAction("workflow:pause"),
    resume: useAction("workflow:resume"),
    complete: useAction("workflow:complete"),
    cancel: useAction("workflow:cancel"),
  };

  const status = useCommandState("workflow:status");

  const canTransition = (from, to) => {
    const validTransitions = {
      idle: ["start"],
      running: ["pause", "complete", "cancel"],
      paused: ["resume", "cancel"],
      completed: ["start"],
      cancelled: ["start"],
    };

    return validTransitions[from]?.includes(to) || false;
  };

  return { transitions, status, canTransition };
}
```

## 🎯 Resumo

A família `useInvoker` fornece acesso direto e simplificado aos comandos:

### Hooks de Execução Direta

- **`useInvoker`** - Retorna diretamente a função de execução
- **`useAction`** - Para comandos sem parâmetros
- **`useSafeInvoker`** - Execução que nunca lança erro
- **`useBoundInvoker`** - Com input pré-configurado
- **`useToggleInvoker`** - Para comandos toggle (boolean)

### Hooks de Execução em Lote

- **`useBatchInvoker`** - Execução sequencial com controle de progresso
- **`useParallelInvoker`** - Execução paralela com Promise.allSettled

### Hook de Estado

- **`useCommandState`** - Alias para useCommand (considere usar useCommand diretamente)

Para casos que necessitam de estado, múltiplos métodos de execução ou configurações avançadas, use `useCommand` diretamente.