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

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

# useCommand Hook - Guia Completo

O `useCommand` é o hook fundamental para executar comandos existentes no Commander com controle total sobre configurações, estado e callbacks.

## 📋 Índice

- [Visão Geral](#visão-geral)
- [Assinaturas e Tipos](#assinaturas-e-tipos)
- [Configurações](#configurações)
- [Exemplos Práticos](#exemplos-práticos)
- [Estado e Tracking](#estado-e-tracking)
- [Tratamento de Erros](#tratamento-de-erros)
- [Performance e Otimizações](#performance-e-otimizações)

## 🎯 Visão Geral

O `useCommand` oferece múltiplas formas de uso, desde execução simples até controle completo com tracking de estado:

```tsx
// 1. Execução simples
const saveFile = useCommand("file:save");
await saveFile({ filename: "doc.txt" });

// 2. Com configurações
const saveFile = useCommand("file:save", {
  throwOnError: false,
  timeout: 5000,
});

// 3. Com tracking de estado completo
const saveFile = useCommand("file:save", {
  trackState: true,
});
console.log(saveFile.isLoading, saveFile.lastResult);

// 4. Objeto completo de controle
const saveFile = useCommand("file:save", {
  returnInvoker: true,
});
```

## 🔧 Assinaturas e Tipos

### Assinaturas Disponíveis

```tsx
// 1. Básico - retorna função invoke
useCommand<TInput, TOutput>(key: CommandKey): (input?: TInput) => Promise<TOutput>

// 2. Com opções - retorna função configurada
useCommand<TInput, TOutput>(
  key: CommandKey,
  options: UseCommandOptions & { returnInvoker?: false }
): (input?: TInput) => Promise<TOutput>

// 3. Objeto completo - returnInvoker: true
useCommand<TInput, TOutput>(
  key: CommandKey,
  options: UseCommandOptions & { returnInvoker: true }
): CommandInvoker<TInput, TOutput>

// 4. Com tracking - trackState: true
useCommand<TInput, TOutput>(
  key: CommandKey,
  options: UseCommandOptions & { trackState: true }
): CommandInvoker<TInput, TOutput>
```

### Interface CommandInvoker

```tsx
interface CommandInvoker<TInput, TOutput> {
  // Estado do comando
  exists: boolean;
  isAvailable: boolean;
  isLoading: boolean;

  // Resultados e histórico
  lastResult: TOutput | null;
  lastError: Error | null;
  lastInput: TInput | null;
  lastExecution: Date | null;
  executionCount: number;

  // Comando completo
  command: Command<TInput, TOutput> | null;

  // Métodos de execução
  invoke: (input?: TInput) => Promise<TOutput>;
  attempt: (input?: TInput) => Promise<ExecutionResult<TOutput>>;
  execute: (
    input?: TInput,
    callbacks?: ExecuteCallbacks,
  ) => Promise<TOutput | null>;

  // Verificações
  canInvoke: (input?: TInput) => Promise<boolean>;
  validateInput: (input?: TInput) => boolean | string;

  // Utilitários
  reset: () => void;
  clearError: () => void;
  refresh: () => void;
}
```

## ⚙️ Configurações

### UseCommandOptions Interface

```tsx
interface UseCommandOptions<TInput, TOutput> {
  // Execução
  source?: "palette" | "shortcut" | "api"; // Default: 'api'
  throwOnError?: boolean; // Default: true
  timeout?: number; // Timeout em ms

  // Retry & Debounce
  retry?: number; // Tentativas (default: 0)
  retryDelay?: number | ((attempt: number) => number);
  debounce?: number; // Debounce em ms
  throttle?: number; // Throttle em ms

  // Input handling
  defaultInput?: Partial<TInput>; // Input padrão
  validateInput?: (input?: TInput) => boolean | string;
  transformInput?: (input?: TInput) => TInput;

  // Output handling
  transformOutput?: (output: TOutput) => TOutput;

  // Callbacks
  onSuccess?: (result: TOutput, input?: TInput) => void;
  onError?: (error: Error, input?: TInput) => void;
  onFinally?: (input?: TInput) => void;

  // Estado
  trackState?: boolean; // Ativa tracking
  returnInvoker?: boolean; // Retorna objeto completo
  resetOnKeyChange?: boolean; // Reset ao mudar key
}
```

## 📚 Exemplos Práticos

### 1. Execução Básica

```tsx
function FileEditor() {
  // Forma mais simples
  const saveFile = useCommand<SaveInput, SaveResult>("file:save");

  const handleSave = async () => {
    try {
      const result = await saveFile({
        filename: "document.txt",
        content: editorContent,
      });
      toast.success(`Salvo: ${result.filename}`);
    } catch (error) {
      toast.error("Erro ao salvar");
    }
  };

  return <button onClick={handleSave}>Save</button>;
}
```

### 2. Com Configurações Avançadas

```tsx
function RobustUploader() {
  const uploadFile = useCommand("file:upload", {
    retry: 3, // 3 tentativas
    retryDelay: (attempt) => attempt * 1000, // Delay progressivo
    timeout: 30000, // 30s timeout
    throwOnError: false, // Não lança erro

    defaultInput: {
      quality: "high",
      compress: true,
    },

    validateInput: (input) => {
      if (!input?.file) return "Arquivo obrigatório";
      if (input.file.size > 10_000_000) return "Arquivo muito grande";
      return true;
    },

    transformInput: (input) => ({
      ...input,
      uploadedAt: new Date(),
      userId: getCurrentUser().id,
    }),

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

    onError: (error, input) => {
      logger.error("Upload failed", { error, filename: input?.file.name });
    },
  });

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

### 3. Com Tracking de Estado

```tsx
function SmartFileUploader() {
  const uploader = useCommand("file:upload", {
    trackState: true,
    debounce: 500, // Evita uploads múltiplos

    onSuccess: (result) => {
      toast.success(`Upload concluído: ${result.filename}`);
    },
  });

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

      {/* Estado visual */}
      {uploader.isLoading && (
        <div className="flex items-center gap-2">
          <Spinner />
          <span>Enviando arquivo...</span>
        </div>
      )}

      {/* Histórico */}
      {uploader.lastResult && (
        <div className="text-green-600">
          ✅ Último upload: {uploader.lastResult.filename}
          <br />
          📊 Total de uploads: {uploader.executionCount}
        </div>
      )}

      {/* Erro */}
      {uploader.lastError && (
        <div className="text-red-600">
          ❌ Erro: {uploader.lastError.message}
          <button onClick={uploader.clearError}>Limpar</button>
        </div>
      )}

      {/* Controles */}
      <div className="flex gap-2 mt-4">
        <button onClick={() => uploader.reset()} disabled={uploader.isLoading}>
          Reset Estado
        </button>

        <button onClick={uploader.refresh}>Verificar Disponibilidade</button>
      </div>
    </div>
  );
}
```

### 4. Validação e Transformação

```tsx
function UserProfileEditor() {
  const updateProfile = useCommand("user:update", {
    // Validação personalizada
    validateInput: (input) => {
      const errors = [];
      if (!input?.email?.includes("@")) errors.push("Email inválido");
      if (!input?.name?.trim()) errors.push("Nome obrigatório");
      return errors.length > 0 ? errors.join(", ") : true;
    },

    // Transformação de input
    transformInput: (input) => ({
      ...input,
      email: input.email?.toLowerCase(),
      name: input.name?.trim(),
      updatedAt: new Date().toISOString(),
    }),

    // Transformação de output
    transformOutput: (result) => ({
      ...result,
      avatarUrl: result.avatar ? `/avatars/${result.avatar}` : null,
    }),

    trackState: true,
  });

  const handleSubmit = async (formData) => {
    // A validação ocorre automaticamente
    const result = await updateProfile.invoke(formData);
    if (result) {
      // Output já foi transformado
      setUser(result);
    }
  };
}
```

### 5. Execução com Callbacks Inline

```tsx
function DocumentProcessor() {
  const processDoc = useCommand("document:process", {
    returnInvoker: true,
    timeout: 60000, // 1 minuto para processamento
  });

  const handleProcess = async (document) => {
    // Usando execute com callbacks inline
    const result = await processDoc.execute(
      { documentId: document.id },
      {
        onSuccess: (result) => {
          notification.success({
            title: "Processamento Concluído",
            message: `Documento processado em ${result.duration}ms`,
          });
        },

        onError: (error) => {
          notification.error({
            title: "Erro no Processamento",
            message: error.message,
            action: {
              label: "Tentar Novamente",
              onClick: () => handleProcess(document),
            },
          });
        },

        onFinally: () => {
          analytics.track("document_process_attempt", {
            documentId: document.id,
          });
        },
      },
    );
  };

  // Ou usando attempt para execução segura
  const handleSafeProcess = async (document) => {
    const result = await processDoc.attempt({ documentId: document.id });

    if (result.success) {
      console.log("Sucesso:", result.result);
    } else {
      console.error("Erro:", result.error);
    }
  };
}
```

## 📊 Estado e Tracking

### Estados Disponíveis

```tsx
const command = useCommand("my:command", { trackState: true });

// Estados booleanos
command.exists; // Comando existe no Commander
command.isAvailable; // Comando disponível (when() = true)
command.isLoading; // Execução em andamento

// Resultados e histórico
command.lastResult; // Último resultado bem-sucedido
command.lastError; // Último erro ocorrido
command.lastInput; // Último input utilizado
command.lastExecution; // Data da última execução
command.executionCount; // Número total de execuções

// Comando original
command.command; // Objeto Command completo
```

### Ciclo de Vida dos Estados

```tsx
// Estado inicial
isLoading: false
lastResult: null
lastError: null
executionCount: 0

// Durante execução
invoke() → isLoading: true

// Sucesso
→ isLoading: false
→ lastResult: [resultado]
→ lastError: null
→ executionCount: +1
→ lastExecution: new Date()

// Erro
→ isLoading: false
→ lastResult: [mantém anterior]
→ lastError: [erro]
→ executionCount: +1
→ lastExecution: new Date()
```

### Reset e Limpeza

```tsx
// Reset completo
command.reset(); // Limpa tudo, volta ao estado inicial

// Limpeza seletiva
command.clearError(); // Remove apenas lastError

// Refresh
command.refresh(); // Re-verifica isAvailable
```

## 🚨 Tratamento de Erros

### Estratégias de Erro

```tsx
// 1. Throw (padrão)
const command = useCommand("risky:operation");
try {
  await command();
} catch (error) {
  // Trata erro
}

// 2. Return null
const command = useCommand("risky:operation", {
  throwOnError: false,
});
const result = await command(); // null se erro

// 3. ExecutionResult
const command = useCommand("risky:operation", {
  returnInvoker: true,
});
const result = await command.attempt();
if (result.success) {
  // result.result
} else {
  // result.error
}
```

### Retry Automático

```tsx
const command = useCommand("unreliable:api", {
  retry: 3,
  retryDelay: (attempt) => {
    // Exponential backoff
    return Math.min(1000 * Math.pow(2, attempt), 10000);
  },

  onError: (error, input) => {
    console.log(`Tentativa falhou: ${error.message}`);
  },
});
```

## ⚡ Performance e Otimizações

### Debounce e Throttle

```tsx
// Debounce - aguarda pausa na entrada
const searchCommand = useCommand("search:execute", {
  debounce: 300, // Aguarda 300ms sem nova execução
  transformInput: (input) => ({
    ...input,
    timestamp: Date.now(),
  }),
});

// Throttle - limita frequência
const saveCommand = useCommand("auto:save", {
  throttle: 5000, // Máximo 1 save a cada 5s
  throwOnError: false,
});
```

### Memoização e Re-renders

```tsx
// ✅ Bom - não recria a cada render
const command = useCommand("stable:command", {
  trackState: true,
});

// ⚠️ Cuidado - recria options a cada render
const command = useCommand("unstable:command", {
  onSuccess: (result) => {
    // Nova função a cada render
    console.log(result);
  },
});

// ✅ Melhor - callback memoizado
const handleSuccess = useCallback((result) => {
  console.log(result);
}, []);

const command = useCommand("stable:command", {
  onSuccess: handleSuccess,
});
```

### Reset Inteligente

```tsx
const command = useCommand(dynamicKey, {
  trackState: true,
  resetOnKeyChange: true, // Reset automático quando key muda
});

// Equivale a:
useEffect(() => {
  command.reset();
}, [dynamicKey]);
```

## 🔍 Verificações e Validações

### Verificação de Disponibilidade

```tsx
const command = useCommand("conditional:command", {
  returnInvoker: true,
});

// Verificação manual
const canExecute = await command.canInvoke({ userId: 123 });
if (canExecute) {
  await command.invoke({ userId: 123 });
}

// Verificação automática (padrão)
// invoke() já verifica disponibilidade automaticamente
```

### Validação Personalizada

```tsx
const command = useCommand("user:create", {
  validateInput: (input) => {
    // Retorna true = válido
    // Retorna string = mensagem de erro
    // Retorna false = erro genérico

    if (!input?.email) return "Email é obrigatório";
    if (!input?.password || input.password.length < 8) {
      return "Senha deve ter pelo menos 8 caracteres";
    }
    return true;
  },

  throwOnError: false, // Para capturar erros de validação
});
```

## 📈 Casos de Uso Avançados

### 1. Command Chaining

```tsx
function DocumentWorkflow() {
  const processDoc = useCommand("document:process", { trackState: true });
  const generatePDF = useCommand("pdf:generate", { trackState: true });
  const sendEmail = useCommand("email:send", { trackState: true });

  const runWorkflow = async (document) => {
    try {
      // Processamento
      const processed = await processDoc.invoke({ document });

      // Geração PDF
      const pdf = await generatePDF.invoke({
        content: processed.content,
      });

      // Envio por email
      await sendEmail.invoke({
        to: document.author.email,
        attachment: pdf.url,
      });

      toast.success("Workflow concluído!");
    } catch (error) {
      toast.error(`Workflow falhou: ${error.message}`);
    }
  };

  const isWorkflowRunning =
    processDoc.isLoading || generatePDF.isLoading || sendEmail.isLoading;

  return (
    <div>
      <button
        onClick={() => runWorkflow(currentDocument)}
        disabled={isWorkflowRunning}
      >
        {isWorkflowRunning ? "Processando..." : "Executar Workflow"}
      </button>

      {/* Status de cada etapa */}
      <div className="mt-4 space-y-2">
        <WorkflowStep
          label="Processamento"
          status={getStepStatus(processDoc)}
        />
        <WorkflowStep label="Geração PDF" status={getStepStatus(generatePDF)} />
        <WorkflowStep label="Envio Email" status={getStepStatus(sendEmail)} />
      </div>
    </div>
  );
}
```

### 2. Conditional Execution

```tsx
function SmartSaveButton() {
  const autoSave = useCommand("document:auto-save", {
    trackState: true,
    throttle: 10000, // Auto-save máximo a cada 10s
    throwOnError: false,
  });

  const manualSave = useCommand("document:save", {
    trackState: true,
    onSuccess: () => toast.success("Documento salvo!"),
  });

  // Auto-save quando conteúdo muda
  useEffect(() => {
    if (documentContent && hasUnsavedChanges) {
      autoSave.invoke({ content: documentContent });
    }
  }, [documentContent]);

  // Save manual
  const handleManualSave = async () => {
    const result = await manualSave.invoke({
      content: documentContent,
      force: true, // Força save mesmo se auto-save recente
    });
  };

  const lastSaveTime = Math.max(
    autoSave.lastExecution?.getTime() || 0,
    manualSave.lastExecution?.getTime() || 0,
  );

  return (
    <div>
      <button onClick={handleManualSave} disabled={manualSave.isLoading}>
        {manualSave.isLoading ? "Salvando..." : "Salvar"}
      </button>

      <div className="text-sm text-gray-500">
        {lastSaveTime && (
          <span>Último save: {formatDistanceToNow(lastSaveTime)}</span>
        )}
        {autoSave.isLoading && (
          <span className="ml-2">• Auto-save em andamento</span>
        )}
      </div>
    </div>
  );
}
```

## 🎯 Boas Práticas

### 1. Tipagem Consistente

```tsx
// ✅ Defina interfaces claras
interface SaveDocumentInput {
  content: string;
  title: string;
  tags?: string[];
}

interface SaveDocumentOutput {
  id: string;
  url: string;
  savedAt: Date;
}

const saveDoc = useCommand<SaveDocumentInput, SaveDocumentOutput>("doc:save");
```

### 2. Error Boundaries

```tsx
function DocumentEditor() {
  const saveDoc = useCommand("doc:save", {
    onError: (error, input) => {
      // Log para monitoramento
      logger.error("Save failed", {
        error: error.message,
        documentId: input?.id,
      });

      // Fallback local
      localStorage.setItem("unsaved_doc", JSON.stringify(input));
    },
  });
}
```

### 3. Loading States Granulares

```tsx
function MultiStepForm() {
  const validateStep = useCommand("form:validate-step", { trackState: true });
  const submitForm = useCommand("form:submit", { trackState: true });

  const isValidating = validateStep.isLoading;
  const isSubmitting = submitForm.isLoading;
  const isProcessing = isValidating || isSubmitting;

  return (
    <form>
      {/* Campos do formulário */}

      <button
        type="button"
        onClick={() => validateStep.invoke({ step: currentStep })}
        disabled={isProcessing}
      >
        {isValidating ? "Validando..." : "Validar Etapa"}
      </button>

      <button
        type="submit"
        onClick={() => submitForm.invoke(formData)}
        disabled={isProcessing || !isFormValid}
      >
        {isSubmitting ? "Enviando..." : "Enviar"}
      </button>
    </form>
  );
}
```

O `useCommand` é o hook mais poderoso e flexível do Commander, oferecendo controle total sobre execução, estado e comportamento dos comandos.