image-tote

Canonical URL:
https://alexstevovich.com/a/image-tote-nodejs

Software URL:
https://midnightcitylights.com/software/image-tote-nodejs

A persistent image metadata registry built on top of
scan-image-geom.

Scans raster and SVG images, normalizes them into a single in-memory catalog,
and provides methods for retrieval, enumeration, and total counts.

Ideal for static-site generators, asset manifests, or image metadata caching systems.

Installation

npm install image-tote

Example

import ImageTote from 'image-tote';

// Initialize with a base directory
const tote = new ImageTote('./public/images');

// Scan directory (recursively)
await tote.update();

// Retrieve metadata for a specific image
const hero = tote.get('/hero.jpg');
console.log(hero);
/*
{
    key: "/hero.jpg",
    path: "/hero.jpg",
    width: 1920,
    height: 1080,
    aspectRatio: "1920/1080",
    orientation: "landscape",
    format: "jpg",
    filesize: 204857,
    filename: "hero.jpg"
}
*/

// Get total count
console.log(tote.count(), 'images indexed.');

// Retrieve all images
console.log(Object.keys(tote.all()));

Output Structure

{
    "/images/photo.jpg": {
        "key": "/images/photo.jpg",
        "path": "/images/photo.jpg",
        "width": 1920,
        "height": 1080,
        "aspectRatio": "1920/1080",
        "orientation": "landscape",
        "format": "jpg",
        "filesize": 204857,
        "filename": "photo.jpg"
    }
}

Methods

update()

Scans the base directory (recursively by default) using scan-image-geom
and rebuilds the internal metadata map.

get(key)

Retrieves metadata for a specific image path, e.g. /assets/photo.png.

all()

Returns the full image metadata map.

count()

Returns the total number of indexed images.

Notes

• Automatically merges raster and SVG metadata.
• Stores all image keys in normalized “/path” form.
• Lightweight, filesystem-based — no external database required.

License

Licensed under the Apache License 2.0.