# canvas-thumbnail-cache

> Draw images into a canvas square grid for fast retrieval at a thumbnail size.

Latest version **2.2.0** (published 2025-01-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install canvas-thumbnail-cache
pnpm add canvas-thumbnail-cache
yarn add canvas-thumbnail-cache
bun add canvas-thumbnail-cache
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2025-01-03 |
| First published | 2021-01-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.0.0 |
| Dependencies | 1 |
| Unpacked size | 18.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Damien Seguin |
| Maintainers | dmnsgn |
| Keywords | canvas, thumbnails, cache |

## Links

- npm: https://www.npmjs.com/package/canvas-thumbnail-cache
- Repository: https://github.com/dmnsgn/canvas-thumbnail-cache
- Issues: https://github.com/dmnsgn/canvas-thumbnail-cache/issues
- Funding: https://paypal.me/dmnsgn
- npm.io page: https://npm.io/package/canvas-thumbnail-cache

## Dependencies (1)

- [canvas-context](https://npm.io/package/canvas-context.md) ^3.3.0

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 2.2.0 (latest) — 2025-01-03
- 2.1.3 — 2024-10-02
- 2.1.2 — 2024-07-06
- 2.1.1 — 2022-04-02
- 2.1.0 — 2021-10-02
- 2.0.1 — 2021-04-17
- 2.0.0 — 2021-04-17
- 1.0.0 — 2021-01-14

## README

# canvas-thumbnail-cache

[![npm version](https://img.shields.io/npm/v/canvas-thumbnail-cache)](https://www.npmjs.com/package/canvas-thumbnail-cache)
[![stability-stable](https://img.shields.io/badge/stability-stable-green.svg)](https://www.npmjs.com/package/canvas-thumbnail-cache)
[![npm minzipped size](https://img.shields.io/bundlephobia/minzip/canvas-thumbnail-cache)](https://bundlephobia.com/package/canvas-thumbnail-cache)
[![dependencies](https://img.shields.io/librariesio/release/npm/canvas-thumbnail-cache)](https://github.com/dmnsgn/canvas-thumbnail-cache/blob/main/package.json)
[![types](https://img.shields.io/npm/types/canvas-thumbnail-cache)](https://github.com/microsoft/TypeScript)
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fa6673.svg)](https://conventionalcommits.org)
[![styled with prettier](https://img.shields.io/badge/styled_with-Prettier-f8bc45.svg?logo=prettier)](https://github.com/prettier/prettier)
[![linted with eslint](https://img.shields.io/badge/linted_with-ES_Lint-4B32C3.svg?logo=eslint)](https://github.com/eslint/eslint)
[![license](https://img.shields.io/github/license/dmnsgn/canvas-thumbnail-cache)](https://github.com/dmnsgn/canvas-thumbnail-cache/blob/main/LICENSE.md)

Draw images into a canvas square grid for fast retrieval at a thumbnail size.

[![paypal](https://img.shields.io/badge/donate-paypal-informational?logo=paypal)](https://paypal.me/dmnsgn)
[![coinbase](https://img.shields.io/badge/donate-coinbase-informational?logo=coinbase)](https://commerce.coinbase.com/checkout/56cbdf28-e323-48d8-9c98-7019e72c97f3)
[![twitter](https://img.shields.io/twitter/follow/dmnsgn?style=social)](https://twitter.com/dmnsgn)

![](https://raw.githubusercontent.com/dmnsgn/canvas-thumbnail-cache/main/screenshot.gif)

## Installation

```bash
npm install canvas-thumbnail-cache
```

## Usage

```js
import CanvasThumbnailCache from "canvas-thumbnail-cache";
import createCanvasContext from "canvas-context";
import AsyncPreloader from "async-preloader";

const { canvas, context } = createCanvasContext("2d", {
  willReadFrequently: true,
});
document.body.appendChild(canvas);

const COUNT = 50;

const thumbnailsCache = new CanvasThumbnailCache({
  context,
  slotSize: 128,
});

const items = Array.from({ length: COUNT }, (_, index) => {
  let size = [(100 + index * 10) % 200, 200];
  if (index % 2 === 0) size.reverse();
  return {
    id: index,
    src: `https://picsum.photos/${size.join("/")}`,
    loader: "Image",
    body: "blob",
    options: {
      crossOrigin: "anonymous",
    },
  };
});

items.map(async (item) => {
  const image = await AsyncPreloader.loadItem(item);

  thumbnailsCache.add(item.id, image);
});
```

## API

<!-- api-start -->

## Classes

<dl>
<dt><a href="#CanvasThumbnailCache">CanvasThumbnailCache</a></dt>
<dd></dd>
</dl>

## Typedefs

<dl>
<dt><a href="#Slot">Slot</a> : <code>object</code></dt>
<dd></dd>
<dt><a href="#Options">Options</a> : <code>object</code></dt>
<dd></dd>
</dl>

<a name="CanvasThumbnailCache"></a>

## CanvasThumbnailCache

**Kind**: global class

- [CanvasThumbnailCache](#CanvasThumbnailCache)
  - [new CanvasThumbnailCache([options])](#new_CanvasThumbnailCache_new)
  - [.slotDrawSize](#CanvasThumbnailCache+slotDrawSize) ⇒ <code>number</code>
  - [.reset()](#CanvasThumbnailCache+reset)
  - [.add(key, source)](#CanvasThumbnailCache+add) ⇒ [<code>Slot</code>](#Slot)
  - [.get(key)](#CanvasThumbnailCache+get) ⇒ [<code>Slot</code>](#Slot)
  - [.remove(key)](#CanvasThumbnailCache+remove)

<a name="new_CanvasThumbnailCache_new"></a>

### new CanvasThumbnailCache([options])

Creates an instance of CanvasThumbnailCache.

| Param     | Type                             | Default         |
| --------- | -------------------------------- | --------------- |
| [options] | [<code>Options</code>](#Options) | <code>{}</code> |

<a name="CanvasThumbnailCache+slotDrawSize"></a>

### canvasThumbnailCache.slotDrawSize ⇒ <code>number</code>

Retrieve the slot draw size (slot size without padding)

**Kind**: instance property of [<code>CanvasThumbnailCache</code>](#CanvasThumbnailCache)
<a name="CanvasThumbnailCache+reset"></a>

### canvasThumbnailCache.reset()

Reset and clear the canvas size and empty the thumbnails cache.

**Kind**: instance method of [<code>CanvasThumbnailCache</code>](#CanvasThumbnailCache)
<a name="CanvasThumbnailCache+add"></a>

### canvasThumbnailCache.add(key, source) ⇒ [<code>Slot</code>](#Slot)

Add an image (or anything that can be draw into a 2D canvas) to the cache and return its slot.

**Kind**: instance method of [<code>CanvasThumbnailCache</code>](#CanvasThumbnailCache)

| Param  | Type                           | Description                                                                                          |
| ------ | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| key    | <code>string</code>            | Slots map key                                                                                        |
| source | <code>CanvasImageSource</code> | HTMLImageElement, SVGImageElement, HTMLVideoElement, HTMLCanvasElement, ImageBitmap, OffscreenCanvas |

<a name="CanvasThumbnailCache+get"></a>

### canvasThumbnailCache.get(key) ⇒ [<code>Slot</code>](#Slot)

Get a slot

The slot can also be retrieved with get and the key passed when calling `thumbnailsCache.add(key, source)`.

**Kind**: instance method of [<code>CanvasThumbnailCache</code>](#CanvasThumbnailCache)

| Param | Type                |
| ----- | ------------------- |
| key   | <code>string</code> |

<a name="CanvasThumbnailCache+remove"></a>

### canvasThumbnailCache.remove(key)

Remove the specified image from the cache and clear its slot.

**Kind**: instance method of [<code>CanvasThumbnailCache</code>](#CanvasThumbnailCache)

| Param | Type                |
| ----- | ------------------- |
| key   | <code>string</code> |

<a name="Slot"></a>

## Slot : <code>object</code>

**Kind**: global typedef
**Properties**

| Name | Type                | Description                      |
| ---- | ------------------- | -------------------------------- |
| x    | <code>number</code> | Horizontal position in the grid. |
| y    | <code>number</code> | Vertical position in the grid.   |

<a name="Options"></a>

## Options : <code>object</code>

**Kind**: global typedef
**Properties**

| Name       | Type                                  | Default                                                                       | Description                                                                      |
| ---------- | ------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [context]  | <code>CanvasRenderingContext2D</code> | <code>createCanvasContext(&quot;2d&quot;, { offscreen: true }).context</code> | Canvas to render thumbnails too. Will try to get an offscreen canvas by default. |
| [size]     | <code>number</code>                   | <code>2</code>                                                                | Size of the canvas at start: a square with sides of length `slotSize * size`.    |
| [slotSize] | <code>number</code>                   | <code>64</code>                                                               | Size of the thumbnails. Will be drawn from center of the grid slot.              |
| [padding]  | <code>number</code>                   | <code>0</code>                                                                | Padding around the thumbnails, inside the slots.                                 |

<!-- api-end -->

## License

MIT. See [license file](https://github.com/dmnsgn/canvas-thumbnail-cache/blob/main/LICENSE.md).

---
_Source: https://npm.io/package/canvas-thumbnail-cache · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._