[Vtex] - Masterdata loader accept a generic

[IncognitaDev]

the masterdata loaders maybe can be a genric Document to improve code type verification

[decobot]

💡 Solução Detalhada - Masterdata Loader com Genérico

Excelente sugestão! Adicionar genéricos aos loaders do Masterdata do VTEX vai melhorar significativamente a type safety.

📝 Implementação

Localizar os loaders do Masterdata (provavelmente em vtex/loaders/masterdata/) e adicionar suporte a genéricos:

// vtex/loaders/masterdata/getDocument.ts
import { AppContext } from "../../mod.ts";

export interface Props {
  acronym: string;
  documentId: string;
  fields?: string[];
}

// Define um tipo base para documentos do Masterdata
export interface MasterdataDocument {
  id: string;
  [key: string]: unknown;
}

/**
 * @title Get Masterdata Document
 * @description Get a document from VTEX Masterdata with type safety
 */
export default async function getMasterdataDocument<T extends MasterdataDocument = MasterdataDocument>(
  props: Props,
  _req: Request,
  ctx: AppContext,
): Promise<T | null> {
  const { acronym, documentId, fields } = props;
  
  const url = new URL(
    `/api/dataentities/${acronym}/documents/${documentId}`,
    ctx.account
  );
  
  if (fields?.length) {
    url.searchParams.set("_fields", fields.join(","));
  }
  
  try {
    const response = await fetch(url.href, {
      headers: {
        "Content-Type": "application/json",
        "VtexIdclientAutCookie": ctx.token ?? "",
      },
    });
    
    if (!response.ok) {
      if (response.status === 404) return null;
      throw new Error(`Masterdata error: ${response.status}`);
    }
    
    return await response.json() as T;
  } catch (error) {
    console.error("Error fetching Masterdata document:", error);
    return null;
  }
}

🎯 Uso com Type Safety

Agora você pode usar com tipos específicos:

// Definir interface do seu documento
interface CustomerDocument extends MasterdataDocument {
  email: string;
  firstName: string;
  lastName: string;
  document: string;
}

// Usar com type safety
const customer = await getMasterdataDocument<CustomerDocument>({
  acronym: "CL",
  documentId: "user@example.com",
  fields: ["email", "firstName", "lastName"],
});

// TypeScript sabe que customer tem as propriedades tipadas!
if (customer) {
  console.log(customer.email); // ✅ Type-safe
  console.log(customer.firstName); // ✅ Type-safe
}

📦 Implementar para Outros Loaders

Aplicar o mesmo padrão para:

// vtex/loaders/masterdata/searchDocuments.ts
export default async function searchMasterdataDocuments<T extends MasterdataDocument = MasterdataDocument>(
  props: SearchProps,
  _req: Request,
  ctx: AppContext,
): Promise<T[]> {
  // implementação
}

// vtex/actions/masterdata/createDocument.ts
export default async function createMasterdataDocument<T extends MasterdataDocument = MasterdataDocument>(
  props: CreateProps,
  _req: Request,
  ctx: AppContext,
): Promise<T> {
  // implementação
}

✅ Checklist de Implementação

• Criar tipo base MasterdataDocument em vtex/utils/types.ts
• Atualizar getDocument loader com genérico
• Atualizar searchDocuments loader com genérico
• Atualizar createDocument action com genérico
• Atualizar updateDocument action com genérico
• Adicionar exemplos de uso na documentação
• Testar com interfaces customizadas

📚 Exemplo Completo

// types/masterdata.ts
export interface NewsletterSubscriber extends MasterdataDocument {
  email: string;
  name: string;
  isActive: boolean;
  subscribedAt: string;
}

// Em um loader ou action
import { NewsletterSubscriber } from "../types/masterdata.ts";

const subscribers = await searchMasterdataDocuments<NewsletterSubscriber>({
  acronym: "NS",
  fields: ["email", "name", "isActive"],
  where: "isActive=true",
});

subscribers.forEach((sub) => {
  // Autocomplete e type checking funcionam! 🎉
  console.log(sub.email, sub.name);
});

Esta mudança vai melhorar significativamente a DX ao trabalhar com Masterdata no VTEX!