Files SDK

O que é o Files SDK?

O Files SDK é um SDK unificado de armazenamento que expõe uma única API consistente para interagir com backends de armazenamento de objetos e blobs. O objetivo é permitir que você chame as mesmas operações de alto nível — como upload, download, list, delete e helpers relacionados — enquanto utiliza diferentes provedores nos bastidores.

Ele funciona roteando as requisições por meio de um adaptador específico do provedor. Isso mantém as partes compartilhadas dos fluxos de armazenamento estáveis, permitindo que as diferenças entre provedores (como comportamentos relacionados a URLs ou certos casos de borda) sejam tratadas dentro do adaptador, sem alterar os pontos de chamada.

Principais recursos

• Única classe Files para todos os provedores: Use uma única superfície de API para operações comuns de armazenamento (upload, download, list, delete, head, exists, copy e helpers de URL), em vez de escrever código específico para cada backend.
• Seleção de provedor baseada em adaptador no momento da construção: O adaptador é fixado ao instanciar new Files({ adapter: ... }), evitando padrões de “escolher provedor por chamada” que complicariam o uso.
• Suporte a entradas web-standard: Aceita File, Blob, ReadableStream, ArrayBuffer e string como entradas para uploads.
• Executa onde fetch é executado: Projetado para funcionar em ambientes como Node, Bun, Workers e Vercel (conforme indicado na página) para comportamento consistente em tempo de execução.
• Escape hatch do provedor via files.raw: Quando você precisa de funcionalidade específica do provedor, você pode acessar o cliente nativo por meio de uma propriedade (files.raw), tipada por adaptador.
• Tratamento de erros normalizado: Erros são expostos como um único tipo FilesError com um código normalizado entre provedores, com o erro original do provedor como causa.

Como usar o Files SDK

1. Instale o SDK (e apenas os adaptadores que pretende usar como dependências de pares):
   • npm install files-sdk
2. Importe Files e um adaptador de provedor, então crie uma instância de Files com o adaptador configurado para seu bucket/região (por exemplo, S3).
3. Chame os métodos compartilhados na instância, como:
   • files.upload(key, input)
   • files.download(key)
   • files.head(key)
   • files.list({ prefix })
   • files.delete(key)
4. Use files.raw se precisar acessar recursos específicos do provedor que não são covered by the common API surface.

Um exemplo mínimo da página:

import { Files } from "files-sdk";
import { s3 } from "files-sdk/s3";

const files = new Files({
  adapter: s3({ bucket: "uploads", region: "us-east-1" }),
});

await files.upload("hello.txt", "world");
const file = await files.download("hello.txt");
const meta = await files.head("hello.txt");
const items = await files.list();
await files.delete("hello.txt");

Casos de uso

• Construir uma camada de armazenamento que pode trocar provedores: Inicie com um backend (ex.: armazenamento S3-compatible) e later migrate to another adapter without rewriting your application’s upload/download/list/delete logic.
• Lidar consistentemente com entradas de arquivos browser-like em código backend: Use os tipos de entrada suportados pelo SDK (File, Blob, ReadableStream, ArrayBuffer, string) quando seu servidor recebe objetos de arquivos web-standard.
• Organizar uploads por prefixes e gerenciar ciclos de vida de objetos no nível do aplicativo: Use list({ prefix }) and delete(key) patterns to implement app-managed collections or “folders” over object storage.
• Integrar com ambientes baseados na disponibilidade de fetch: Implante código em Node, Bun, Workers ou Vercel enquanto depende das mesmas chamadas de API e entradas.
• Use erros normalizados para retry/handling consistente: Catch FilesError with a normalized code and inspect the original cause when provider-specific details are needed.

FAQ

Quais operações de armazenamento o Files SDK padroniza?

O SDK padroniza uma superfície de métodos compartilhados entre adaptadores, incluindo upload, download, delete, list, head, exists, copy e helpers relacionados a URLs (os comportamentos exatos de URL podem variar por provedor).

Como eu seleciono um provedor de armazenamento?

Crie uma instância de Files com um adaptador no momento da construção (por exemplo, s3({ bucket: ..., region: ... })). O adaptador被固定 para essa instância.

Quais tipos de entrada eu posso upload?

O SDK aceita File, Blob, ReadableStream, ArrayBuffer e string como inputs de upload.

O que acontece quando eu preciso de funcionalidade não abrange by the common API?

Use o escape hatch files.raw to access the native client exposed by the chosen adapter. This is intended for provider-specific features such as the items mentioned on the page (e.g., versioning, lifecycle, ACLs, multipart) that are not part of the shared interface.

Eu preciso instalar a dependência nativa de todo provedor?

No. A página descreve o SDK nativo de cada provedor como uma dependência de pares opcional: instale apenas os adaptadores (e seus pacotes nativos requeridos) for the providers you actually use. If an adapter is imported without its peer dependency installed, Node will throw ERR_MODULE_NOT_FOUND indicating the missing package.

Alternativas

• SDKs de armazenamento específicos de provedores (ex.: clientes nativos S3/GCS/Azure): Oferecem cobertura completa dos provedores, mas geralmente exigem caminhos de código diferentes para cada backend e tratamento separado de tarefas comuns.
• Camadas de abstração de armazenamento de objetos sem entradas web-standard: Algumas abstrações fornecem uma interface unificada, mas podem não oferecer suporte ao mesmo conjunto de tipos de entrada nativos da web ou às premissas de runtime orientadas a fetch.
• Bibliotecas de upload de arquivos no servidor com opção de backend de armazenamento: Úteis quando o objetivo principal é o tratamento de uploads, mas podem não expor o mesmo conjunto de operações padronizadas (head/exists/copy/url helpers) e acesso via escape hatch ao cliente nativo.
• Integração HTTP direta a endpoints de objeto/Blob: Se você precisar de controle máximo, chamar as APIs HTTP dos provedores por conta própria evita a abstração, mas transfere listagem, assinatura, normalização de erros e diferenças entre provedores para sua aplicação.