formdata-builder

O formdata-builder é um utilitário de type-safety para a construção de objetos a partir de um FormData. Desenvolvido em TypeScript, integra-se ao Valibot para a validação de tipos e esquemas. Foi criado com o objetivo de simplificar o acesso e a transformação de dados provenientes de FormData em Server Actions do Next.js, mas pode ser utilizado em qualquer situação em que a manipulação de dados de FormData seja necessária.

Conceito

A operação é simples. Os dados são obtidos de uma propriedade retornada pelo getAll() ou get() de um FormData. Em seguida, esses valores podem ser validados e/ou transformados, e, por último, são incorporados a um objeto interno. Esse objeto se torna o resultado quando o método build é chamado.

Tecnologias

• Bun (Para rodar e testar)
• TypeScript
• Valibot

Instalação

npm:

npm install formdata-builder valibot

yarn:

yarn add formdata-builder valibot

pnpm:

pnpm add formdata-builder valibot

bun:

bun add formdata-builder valibot

Exemplo de Utilização

O exemplo abaixo simula uma simples transformação de dados de um FormData que contém informações para criar um post, recebendo um título e gerando a partir dele um slug. Ao final, um objeto com título e slug é retornado.

import { createFormDataBuilder } from 'formdata-builder';
import { Input, object, string, optional } from 'valibot';

// Função utilitária
import { slugify } from './utils'

// Valibot schema
const schema = object({
  title: string(),
  slug: optional(string()),
});

// Inferindo o tipo do schema
type SchemaType = Input<typeof schema>;

// Server Component
export default function Page() {
  // Server Action
  async function create(formData: FormData) {
    'use server'
    const builder = createFormDataBuilder<SchemaType>(formData);
    const data = builder
      // Transfere o título para o slug
      .transfer('title', 'slug', { transform: slugify })
      .build(schema);
  }
 
  return (
    <form action={create}>
      <input name="title" id="title" placeholder="Digite um título" />
      <button type="submit">Enviar</button>
    </form>
  )
}

Métodos

A instância do builder retornada por createFormDataBuilder<SchemaType>(formData) contém 5 métodos, cuja utilidade varia dependendo do tipo ou da transformação necessária do dado. Os métodos são:

1. single: Valida e/ou transforma uma propriedade única do FormData.
2. array: Valida e/ou transforma propriedades pertencentes à mesma propriedade do FormData.
3. transfer: Transfere, valida e/ou transforma valores de propriedades de um FormData para outra propriedade presente no seu schema.
4. innerTransfer: Transfere, valida e/ou transforma valores já transformados para outra propriedade presente no seu schema.
5. build: Retorna todos os dados transformados e os valores não transformados pelos métodos anteriores. Também pode ser utilizado para validar o objeto-resultado utilizando um schema.

Opções

As opções são um objeto opcional que pode ser passado para os métodos principais. Elas contém propriedades para validar, transformar e tornar opcional.

• transform: Recebe uma callback que transforma um valor e o retorna.
• schema: Recebe um esquema do Valibot, utilizado para validar tanto o objeto transformado quanto o valor bruto.
• required: Indica se a ausência da propriedade em FormData deve retornar um erro ou não. O padrão é true.

Contribuindo

Se deseja contribuir para o formdata-builder, a melhor abordagem é fazer um fork deste repositório e abrir uma solicitação de pull quando concluir a implementação da sua funcionalidade. Se encontrar bugs ou simplesmente quiser fazer uma pergunta, sinta-se à vontade para abrir uma issue.

Licença

O formdata-builder é lançado sob a licença MIT.