@verevoir/assets

Asset management for Verevoir — a pluggable BlobStore interface for binary data, metadata persistence via StorageAdapter, and automatic dimension extraction via Sharp.

What It Does

• BlobStore — pluggable interface for binary storage (put/get/delete). Ships with MemoryBlobStore; S3/R2 implementations follow later.
• AssetManager — orchestrates StorageAdapter (metadata) + BlobStore (binary data) for upload, download, get, delete, list, and updateMetadata operations.
• Metadata Extraction — reads pixel dimensions from bitmap images via Sharp on upload. SVG and video get null dimensions.
• Hotspot — mutable focal point (0–1 range) for smart cropping. Set via updateMetadata().

Install

npm install @verevoir/assets

Quick Example

import { AssetManager, MemoryBlobStore } from '@verevoir/assets';
import { MemoryAdapter } from '@verevoir/storage';

const storage = new MemoryAdapter();
const blobStore = new MemoryBlobStore();
await storage.connect();

const manager = new AssetManager({ storage, blobStore });

// Upload — dimensions extracted automatically
const asset = await manager.upload({
  data: imageBuffer,
  filename: 'hero.jpg',
  contentType: 'image/jpeg',
  createdBy: 'user-1',
});
// asset.width → 1920, asset.height → 1080

// Set a hotspot
await manager.updateMetadata(asset.id, {
  hotspot: { x: 0.5, y: 0.3 },
});

// Download
const result = await manager.download(asset.id);
// result.asset — metadata, result.data — Uint8Array

// List
const assets = await manager.list({ limit: 10 });

// Delete
await manager.delete(asset.id);

API

AssetManager

| Method | Description | | ---------------------------- | --------------------------------------------------------------------------- | | upload(input) | Store binary data + create metadata. Extracts dimensions for bitmap images. | | get(id) | Retrieve asset metadata by ID, or null. | | download(id) | Retrieve metadata + binary data, or null. | | delete(id) | Delete both blob and metadata. Throws if not found. | | list(options?) | List assets with optional filtering, sorting, pagination. | | updateMetadata(id, update) | Update mutable fields (hotspot, filename). Throws if not found. |

Asset Record

| Field | Type | Description | | ------------- | ---------------------- | ---------------------------------------------- | | id | string | Unique identifier | | filename | string | Original filename (mutable via updateMetadata) | | contentType | string | MIME type | | size | number | Byte size | | blobKey | string | Key in the BlobStore | | createdBy | string | Uploader identity | | type | 'image' \| 'video' | Derived from MIME prefix | | format | 'bitmap' \| 'vector' | SVG → vector, everything else → bitmap | | width | number \| null | Pixel width (null for SVG/video) | | height | number \| null | Pixel height (null for SVG/video) | | hotspot | Hotspot \| null | Focal point { x: 0–1, y: 0–1 } | | createdAt | Date | Creation timestamp | | updatedAt | Date | Last update timestamp |

Architecture

| File | Responsibility | | ----------------- | -------------------------------------------------------------------------------------------- | | src/types.ts | Core interfaces: BlobStore, Asset, Hotspot, AssetMetadataUpdate, UploadInput, DownloadResult | | src/metadata.ts | extractMetadata() — Sharp-based dimension extraction for bitmap images | | src/memory.ts | MemoryBlobStore — Map-based in-memory blob storage with defensive copies | | src/manager.ts | AssetManager — orchestrates StorageAdapter + BlobStore for asset CRUD | | src/index.ts | Public API exports |

Design Decisions

• Blob before metadata — orphaned blob is recoverable; orphaned metadata is not.
• Blob-immutable, metadata-mutable — binary data never changes. Hotspot and filename can be updated.
• Sharp for extraction only — reads dimensions on upload; never used for runtime resizing.
• Null dimensions for video and SVG — video would need ffprobe; SVG has no inherent pixel size.
• Uint8Array not Buffer — more portable across environments.

Documentation

• Media — assets, imgproxy URLs, and image display
• Integration Guide — connecting content models, storage, editor, and more

Development

npm install    # Install dependencies
make build     # Compile TypeScript
make test      # Run test suite
make lint      # Check formatting