Anotações e inferência — quando anotar.

// variáveis inicializadas com valor — inferência direta
const titulo = "CSS em geral";          // string
const curtidas = 42;                    // number
const publicado = true;                 // boolean
const tags = ["css", "layout"];         // string[]
const artigo = { titulo: "CSS", id: 1 }; // { titulo: string; id: number }

// funções — retorno é inferido do return
function dobrar(x: number) {
  return x * 2; // TypeScript infere: number
}

// callbacks — tipo do parâmetro é inferido pelo contexto
const titulos = artigos.map(artigo => artigo.titulo);
// artigo é inferido como Artigo porque artigos é Artigo[]
// titulos é inferido como string[]

// TS erro com noImplicitAny: parâmetro 'palavras' tem tipo any implícito
function calcularTempoLeitura(palavras) {
  return Math.ceil(palavras / 238);
}

// correto: anotar o parâmetro
function calcularTempoLeitura(palavras: number): number {
  return Math.ceil(palavras / 238);
}

// sem anotação: TypeScript infere any — perde toda a proteção
let statusCarregamento;
statusCarregamento = "carregando"; // sem erro, mas sem proteção

// com anotação: o tipo está definido desde a declaração
let statusCarregamento: "carregando" | "sucesso" | "erro";
statusCarregamento = "carregando"; // ok
statusCarregamento = "desconhecido"; // TS erro: não é um dos três valores válidos

// sem anotação: TypeScript infere o retorno, mas não verifica se está correto
function buscarArtigo(id: number) {
  // se por engano você retornar undefined sem querer,
  // o tipo inferido fica Artigo | undefined — silenciosamente
  return artigos.find(a => a.id === id);
}

// com anotação: o compilador verifica que o retorno bate com a promessa
function buscarArtigo(id: number): Artigo {
  // TS erro: Type 'Artigo | undefined' is not assignable to type 'Artigo'
  // você é forçado a tratar o caso onde find retorna undefined
  return artigos.find(a => a.id === id)!; // ou: lançar erro, ou tratar
}

// alternativa honesta: declarar que pode não encontrar
function buscarArtigo(id: number): Artigo | undefined {
  return artigos.find(a => a.id === id);
}

// const: o valor não pode mudar — TypeScript infere o tipo literal
const tema = "claro";      // tipo: "claro" (literal), não string
const curtidas = 42;       // tipo: 42 (literal), não number

// let: o valor pode ser reatribuído — TypeScript infere o tipo amplo
let tema = "claro";        // tipo: string (qualquer string, não só "claro")
let curtidas = 42;         // tipo: number (qualquer number, não só 42)

tema = "escuro";           // ok — tipo é string

// anotação explícita
let tema: "claro" | "escuro" = "claro";
tema = "escuro"; // ok
tema = "noturno"; // TS erro: não é um dos dois valores válidos

// as const — só funciona na declaração inicial
let tema = "claro" as const; // tipo: "claro" — mas let não ajuda aqui
// (neste caso, use const mesmo)

// interfaces de domínio: anotar — são a fronteira do módulo
interface Artigo {
  id: number;
  titulo: string;
  descricao: string;
  tags: string[];
  curtidas: number;
  publicado: boolean;
  publicadoEm: string | null;
}

// funções exportadas: anotar parâmetros e retorno
export function renderizarCards(artigos: Artigo[], curtidos: number[]): string {
  // aqui dentro: inferir
  const publicados = artigos.filter(a => a.publicado); // Artigo[] — inferido
  const html = publicados.map(artigo => {              // string[] — inferido
    const curtido = curtidos.includes(artigo.id);      // boolean — inferido
    return `<article data-id="${artigo.id}">...</article>`;
  });
  return html.join("");
}