thumbo

thumbo

A high-performant thumbnail creation library

_{Built with Rust 🦀 & WebAssembly 🕸}

✅ Features

• High-performance
• Web worker pool
• Built with Rust & Web Assembly
• Uses transferable objects
• Easy to use APIs
• Supports Png, Jpeg, Gif, Ico and Svg

🚴 Usage

Install the package from npm:

yarn add thumbo

import Thumbo, { Transfer } from "thumbo";

Thumbo.init().then(async () => {
  Thumbo.thumbnail(
    Transfer(await (await fetch("/path/to/img.png")).arrayBuffer()),
    Thumbo.ImageFormat.Png,
    20,
    20
  ).then((thumbnailBuffer) => {
    document.getElementById("img1").src = URL.createObjectURL(
      new Blob([thumbnailBuffer])
    );
  });

  Thumbo.thumbnailFromUrl(
    "https://example.com/image.png",
    Thumbo.ImageFormat.Png,
    20,
    20
  ).then((thumbnailBuffer) => {
    document.getElementById("img2").src = URL.createObjectURL(
      new Blob([thumbnailBuffer])
    );
  });
});

⚙️ API Reference

Thumbo.init(config: InitOptions): Promise<void>

Initiates thumbo. The initiation proccess includes:

• Downloads the thumbo-core WebAssembly bundle from unpkg.com
• Complies the WASM binary
• Starts a pool of web workers(8 workers are pooled by default, however, you can control the number of wokers to be spawned) to take thumbnail creation tasks
• After the afore mentioned steps are completed, isInitialized field is set true.

InitOptions

InitOptions interface provides the configuration for the init method.

interface InitOptions {
  /** Url to fetch the thumbo-core WASM bundle. Defaults to the bundle hosted on unpkg. */
  wasmUrl?: string;
  /** Maximum no. of tasks to run on one worker thread at a time. Defaults to one. */
  concurrency?: number;
  /** Maximum no. of jobs to be queued for execution before throwing an error. */
  maxQueuedJobs?: number;
  /** Gives that pool a name to be used for debug logging, letting you distinguish between log output of different pools. */
  name?: string;
  /** No. of worker threads to spawn and to be managed by the pool. */
  size?: number;
}

Transfer(transferable: Transferable): TransferDescriptor

Mark transferable objects within an arbitrary object or array as being a transferable object. They will then not be serialized and deserialized on messaging with the main thread, but ownership of them will be tranferred to the receiving thread.

Only array buffers, message ports and few more special types of objects can be transferred, but it's much faster than serializing and deserializing them.

Returns a TransferDescriptor, a container that holds the arraybuffer to be transferred.

Note: The transferable object cannot be accessed by this thread again unless the receiving thread transfers it back again!

Transferable: transferable Array buffer, message port or similar.

See https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast

Thumbo.ImageFormat

Enums of supported image formats. Thumbo supports thumbnail creation for the following formats:

• Png
• Jpeg
• Gif
• Ico
• Svg

Thumbo.thumbnail(bufferDescriptor: TransferDescriptor, format: ImageFormat, width: number, height: number): Promise<ArrayBuffer>

Creates a thumbnail from the provided arraybuffer transfer descriptor. The provided arraybuffer is transferred to the worker for processing, once the task is completed, the newly created thumbnail arraybuffer is transferred back to the main thread.

Thumbo.thumbnailFromUrl(url: string, format: ImageFormat, width: number, height: number): Promise<ArrayBuffer>

Creates a thumbnail from the provided Url. Once the task is completed, the created thumbnail arraybuffer is transferred to the main thread.

Thumbo.workers

Returns the workers in the pool

Note: Accessing this property before thumbo is initialized will throw an error.

Thumbo.completed(allowResolvingImmediately: boolean)

Returns a promise that resolves once the task queue is emptied. Promise will be rejected if any task fails.

allowResolvingImmediately Set to true to resolve immediately if task queue is currently empty.

Thumbo.settled(allowResolvingImmediately: boolean)

Returns a promise that resolves once the task queue is emptied. Failing tasks will not cause the promise to be rejected.

allowResolvingImmediately Set to true to resolve immediately if task queue is currently empty.

Note: Calling this function before thumbo is initialized will throw an error.

Thumbo.uninit(force: boolean)

Returns a promise that resolves once the task queue is emptied. Failing tasks will not cause the promise to be rejected.

force Set to true to kill the thread even if it cannot be stopped gracefully.

Note: Calling this function before thumbo is initialized will throw an error.