WASM Image Processor

O módulo azion/wasm-image-processor é a biblioteca da Azion Lib para processamento de imagens. Ele usa WebAssembly para carregar uma imagem de uma URL, redimensioná-la e retorná-la como um Response no formato JPEG, PNG ou WebP. Ele não faz chamadas de API e não precisa de token.

Instale o pacote:

npm install azion

O pacote azion recebe apenas correções de bugs, e a manutenção dele termina em dezembro de 2026.

loadImage retorna um objeto WasmImage, e resize, getImageResponse e clean são métodos dele. As funções retornam o resultado diretamente e lançam um erro quando falham. loadImage também é o export padrão do módulo.

O módulo é executado no Node.js e dentro de uma function servida localmente com azion dev. Os exemplos das quatro funções são módulos ES em TypeScript que usam await de nível superior, executados no Node.js. Eles importam os tipos com import type.

loadImage

Busca uma imagem por HTTP e a carrega em um objeto WasmImage.

function loadImage(pathOrURL: string): Promise<WasmImage>;

Parâmetro	Tipo	Obrigatório	Descrição
`pathOrURL`	`string`	Sim	A URL da imagem. O path da URL deve terminar em uma extensão de arquivo: `.jpg`, `.jpeg`, `.png`, `.gif` ou `.bmp`.

Retorna uma promise de um WasmImage. A função recusa uma URL cujo path não termina em uma dessas extensões de arquivo, como /image/png, e lança um erro quando o servidor responde com um status de erro. O nome do parâmetro menciona um path, mas no Node.js um caminho de arquivo local falha com TypeError: fetch failed. As mensagens estão em Erros.

Este exemplo carrega uma imagem PNG e imprime o tamanho dela:

TypeScript

01import { loadImage } from 'azion/wasm-image-processor';

02import type { WasmImage } from 'azion/wasm-image-processor';

const image: WasmImage = await loadImage('https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png');

05console.log(`Loaded ${image.width()}x${image.height()}`);

Saída:

Loaded 272x92

resize

Redimensiona uma imagem. Um método de WasmImage.

resize(width: number, height: number, usePercent?: boolean): WasmImage;

Parâmetro	Tipo	Obrigatório	Descrição
`width`	`number`	Sim	A largura final. Um multiplicador da largura atual (`0.5` é a metade) quando `usePercent` é `true`, ou pixels quando é `false`.
`height`	`number`	Sim	A altura final. Um multiplicador da altura atual (`0.5` é a metade) quando `usePercent` é `true`, ou pixels quando é `false`.
`usePercent`	`boolean`	Não	Como `width` e `height` são lidos. Padrão: `true`.

Retorna um novo WasmImage com a imagem redimensionada. A imagem original não muda de tamanho.

Com o usePercent padrão, 1 é 100% do tamanho atual: 0.5 reduz a imagem à metade, e 50 a torna 50 vezes maior. Uma imagem de 272 × 92 redimensionada com resize(50, 50) passa a ter 13600 × 4600. Passe false como terceiro argumento para informar o tamanho em pixels.

Este exemplo redimensiona uma imagem para a metade do tamanho e depois para 100 × 34 pixels:

TypeScript

01import { loadImage } from 'azion/wasm-image-processor';

02import type { WasmImage } from 'azion/wasm-image-processor';

const image: WasmImage = await loadImage('https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png');

05const half: WasmImage = image.resize(0.5, 0.5); // usePercent defaults to true: 0.5 = 50%

06console.log(`resize(0.5, 0.5): ${half.width()}x${half.height()}`);

07const fixed: WasmImage = image.resize(100, 34, false); // pixels

08console.log(`resize(100, 34, false): ${fixed.width()}x${fixed.height()}`);

Saída:

Texto

01resize(0.5, 0.5): 136x46

02resize(100, 34, false): 100x34

getImageResponse

Codifica uma imagem em um formato e a retorna como um Response. Um método de WasmImage.

getImageResponse(format: SupportedImageFormat, quality?: number): Response;

Parâmetro	Tipo	Obrigatório	Descrição
`format`	`SupportedImageFormat`	Sim	O formato da imagem: `'jpeg'`, `'png'` ou `'webp'`.
`quality`	`number`	Não	A qualidade da imagem, para `'jpeg'`. Padrão: `100.0`.

Retorna um Response com status 200, a imagem codificada como body e o header content-type do formato: image/jpeg, image/png ou image/webp. Uma function pode retornar essa resposta sem alterações.

Este exemplo codifica uma imagem como WebP e imprime o status, o content type e o tamanho do body:

TypeScript

01import { loadImage } from 'azion/wasm-image-processor';

02import type { WasmImage, SupportedImageFormat } from 'azion/wasm-image-processor';

const image: WasmImage = await loadImage('https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png');

05const format: SupportedImageFormat = 'webp';

06const imageResponse: Response = image.getImageResponse(format);

console.log(imageResponse.status, imageResponse.headers.get('content-type'), (await imageResponse.arrayBuffer()).byteLength, 'bytes');

Saída:

200 image/webp 9056 bytes

clean

Libera a memória que guarda uma imagem. Um método de WasmImage.

clean(): void;

O método não recebe parâmetros e não retorna nada. Depois de clean(), a imagem não pode mais ser usada: uma chamada como getImageResponse lança null pointer passed to rust. Um Response que getImageResponse retornou antes de clean() continua legível, então chame clean() por último.

Este exemplo codifica uma imagem como JPEG, libera a imagem e depois lê a resposta:

TypeScript

01import { loadImage } from 'azion/wasm-image-processor';

02import type { WasmImage } from 'azion/wasm-image-processor';

const image: WasmImage = await loadImage('https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png');

05const response = image.getImageResponse('jpeg'); // use the image first

06image.clean(); // then free its memory; the image cannot be used after this

07console.log('cleaned; response still readable:', (await response.arrayBuffer()).byteLength, 'bytes');

Saída:

cleaned; response still readable: 34984 bytes

Redimensionar e converter uma imagem em uma function

Esta function carrega uma imagem PNG, a redimensiona para a metade do tamanho e a retorna como WebP:

JavaScript

01import { loadImage } from 'azion/wasm-image-processor';

03export default {

04 async fetch() {

05 const image = await loadImage('https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png');

06 const response = image.resize(0.5, 0.5).getImageResponse('webp');

07 image.clean();

08 return response;

09 },

10};

Com a function servida localmente com azion dev, uma requisição salva o body da resposta em um arquivo e imprime o status, o content type e o tamanho:

Texto

01$ curl -o image.webp -w '%{http_code} %{content_type} size=%{size_download}\n' http://localhost:3333/img

02200 image/webp size=3490

O arquivo salvo é uma imagem WebP.

Erros

As funções lançam estes erros. Capture-os com try/catch em volta da chamada.

Mensagem	Causa	O que fazer
`Invalid image extension. Supported: jpg,jpeg,png,gif,bmp`	O path da URL passada para `loadImage` não termina em uma extensão de imagem.	Use uma URL cujo path termine em `.jpg`, `.jpeg`, `.png`, `.gif` ou `.bmp`.
`Error getting image. Http status code: 404`	O servidor da URL respondeu com um status de erro. A mensagem carrega o código de status.	Verifique se a URL serve a imagem.
`TypeError: fetch failed`	No Node.js, `loadImage` recebeu um caminho de arquivo local.	Passe a URL da imagem.
`null pointer passed to rust`	A imagem foi usada depois de clean.	Chame `clean()` depois do último uso da imagem.

Tipos

O módulo exporta estes tipos. Importe-os com import type.

WasmImage

A imagem que loadImage e resize retornam: um PhotonImage encapsulado, com métodos para processá-lo.

Membro	Tipo	Descrição
`image`	`PhotonImage`	A instância de `PhotonImage` que guarda os dados da imagem.
`width()`	`number`	Retorna a largura da imagem, em pixels.
`height()`	`number`	Retorna a altura da imagem, em pixels.
`resize(width, height, usePercent?)`	`WasmImage`	Retorna uma cópia redimensionada da imagem. Consulte resize.
`getImageResponse(format, quality?)`	`Response`	Retorna a imagem codificada em um formato. Consulte getImageResponse.
`clean()`	`void`	Libera a memória da imagem. Consulte clean.

SupportedImageFormat

Os formatos que getImageResponse codifica.

type SupportedImageFormat = 'webp' | 'jpeg' | 'png';

Recursos relacionados

Azion Lib

As bibliotecas que a Azion Lib oferece e o pacote que contém cada uma.

Como a Azion Lib funciona

Onde cada módulo é executado, no Node.js e dentro de uma function.

Response

O objeto de resposta que getImageResponse retorna.

Azion CLI dev

Sirva uma function localmente e requisite as imagens que ela retorna.