Zippo

Biblioteca profissional de compressão de imagens em JavaScript puro, facilmente consumível em frameworks como React.

Características

• 🚀 Vanilla JavaScript - Baseado em Canvas API, sem dependências
• 📦 Múltiplos Formatos - Suporte a Blob, File e DataURL
• 🎨 Redimensionamento Inteligente - Mantém aspect ratio automaticamente
• ⚡ Performance - Uso de Promises para operações assíncronas
• 🔧 Flexível - Configuração de qualidade e dimensões
• 📱 Compatível - Funciona em navegadores modernos
• 📦 ESM e UMD - Suporte para importação moderna e via CDN

Instalação

NPM

npm install @nascimentodeveloper/zippo

Yarn

yarn add @nascimentodeveloper/zippo

CDN (UMD)

<script src="https://unpkg.com/@nascimentodeveloper/zippo/dist/zippo.umd.js"></script>

Uso Básico

Importação ESM

import Zippo from '@nascimentodeveloper/zippo';

Importação UMD (via CDN)

// Após incluir o script, Zippo estará disponível globalmente
const Zippo = window.Zippo;

Exemplo Básico

// Obter arquivo de input
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

// Comprimir imagem
const compressed = await Zippo.compress(file, {
  quality: 0.8,
  maxWidth: 1920,
  maxHeight: 1080
});

// compressed é um Blob
console.log('Tamanho original:', file.size);
console.log('Tamanho comprimido:', compressed.size);

Exemplo com React

import { useState } from 'react';
import Zippo from '@nascimentodeveloper/zippo';

function ImageCompressor() {
  const [compressed, setCompressed] = useState(null);

  const handleCompress = async (event) => {
    const file = event.target.files[0];
    if (!file) return;

    try {
      const result = await Zippo.compress(file, {
        quality: 0.8,
        maxWidth: 1920,
        maxHeight: 1080,
        output: 'blob'
      });

      setCompressed(result);
    } catch (error) {
      console.error('Erro ao comprimir:', error);
    }
  };

  return (
    <div>
      <input type="file" onChange={handleCompress} accept="image/*" />
      {compressed && (
        <img src={URL.createObjectURL(compressed)} alt="Comprimida" />
      )}
    </div>
  );
}

API

Zippo.compress(file, options)

Comprime uma imagem.

Parâmetros:

• file (File | Blob): Arquivo de imagem a ser comprimido
• options (Object, opcional): Opções de compressão
  • quality (number, padrão: 0.8): Qualidade de compressão (0.1 a 1.0)
  • maxWidth (number, opcional): Largura máxima (mantém aspect ratio)
  • maxHeight (number, opcional): Altura máxima (mantém aspect ratio)
  • width (number, opcional): Largura exata (sobrescreve maxWidth)
  • height (number, opcional): Altura exata (sobrescreve maxHeight)
  • format (string, opcional): Formato de saída ('image/jpeg' | 'image/png' | 'image/webp')
  • output (string, padrão: 'blob'): Formato de saída ('blob' | 'file' | 'dataurl')

Retorna: Promise<Blob | File | string>

Exemplo:

// Comprimir como Blob
const blob = await Zippo.compress(file, {
  quality: 0.8,
  maxWidth: 1920
});

// Comprimir como File
const fileResult = await Zippo.compress(file, {
  quality: 0.8,
  output: 'file'
});

// Comprimir como DataURL
const dataURL = await Zippo.compress(file, {
  quality: 0.8,
  output: 'dataurl'
});

Zippo.isSupported(file)

Valida se um arquivo é uma imagem suportada.

Parâmetros:

• file (File | Blob): Arquivo a ser validado

Retorna: boolean

Exemplo:

const file = fileInput.files[0];
if (Zippo.isSupported(file)) {
  const compressed = await Zippo.compress(file);
}

Zippo.getImageInfo(file)

Obtém informações de uma imagem sem processá-la.

Parâmetros:

• file (File | Blob): Arquivo de imagem

Retorna: Promise<{width: number, height: number, size: number, type: string}>

Exemplo:

const info = await Zippo.getImageInfo(file);
console.log(`Dimensões: ${info.width}x${info.height}`);
console.log(`Tamanho: ${info.size} bytes`);

Formatos Suportados

• JPEG / JPG
• PNG
• WebP
• GIF
• BMP

Opções de Redimensionamento

maxWidth / maxHeight

Redimensiona a imagem mantendo o aspect ratio, limitando pela dimensão máxima especificada.

// Reduz para no máximo 1920px de largura
const compressed = await Zippo.compress(file, {
  maxWidth: 1920
});

width / height

Define dimensões exatas. Se apenas uma for especificada, a outra é calculada mantendo o aspect ratio.

// Redimensiona para 800x600 (pode distorcer)
const compressed = await Zippo.compress(file, {
  width: 800,
  height: 600
});

// Redimensiona para 800px de largura (altura calculada)
const compressed = await Zippo.compress(file, {
  width: 800
});

Qualidade

A qualidade de compressão varia de 0.1 (maior compressão, menor qualidade) a 1.0 (menor compressão, maior qualidade).

// Alta compressão (arquivo menor)
const small = await Zippo.compress(file, { quality: 0.3 });

// Baixa compressão (arquivo maior, melhor qualidade)
const high = await Zippo.compress(file, { quality: 1.0 });

Tratamento de Erros

try {
  const compressed = await Zippo.compress(file, {
    quality: 0.8
  });
} catch (error) {
  console.error('Erro ao comprimir:', error.message);
  // Possíveis erros:
  // - "File is required"
  // - "File must be a supported image type"
  // - "Quality must be between 0.1 and 1.0"
  // - "Compression failed: ..."
}

Exemplos

Exemplo React

Um exemplo completo e funcional está disponível em examples/react-example/:

cd examples/react-example
npm install
npm run dev

O exemplo demonstra:

• Upload de imagem
• Configuração de opções de compressão
• Visualização comparativa (original vs comprimida)
• Download da imagem comprimida
• Cálculo de taxa de compressão

Desenvolvimento

Instalação de Dependências

npm install

Build

# Build ESM e UMD
npm run build

# Build apenas ESM
npm run build:esm

# Build apenas UMD
npm run build:umd

# Gerar TypeScript definitions
npm run build:types

Testes

# Rodar testes
npm test

# Testes em modo watch
npm run test:watch

# Cobertura de testes
npm run test:coverage

Linting

# Verificar código
npm run lint

# Corrigir automaticamente
npm run lint:fix

# Formatação
npm run format

Estrutura do Projeto

/src
  /core                    # Lógica de manipulação de Canvas
    canvas-manager.js      # Gerenciamento de Canvas API
    image-processor.js     # Processamento de imagem
    format-converter.js    # Conversão entre formatos
    utils.js               # Utilitários
  /api                     # Interface pública
    index.js               # Ponto de entrada principal
    compress.js            # Função principal compress()
  /workers                 # Web Workers (futuro)
  index.js                 # Export principal

Roadmap

• [ ] Suporte a Web Workers para processamento paralelo
• [ ] Suporte a OffscreenCanvas
• [ ] Suporte a formatos adicionais (AVIF)
• [ ] Cache de Canvas reutilizáveis
• [ ] Interface para plugins

Licença

ISC

Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou pull request.