@stackonward/image

Browser image helpers for Alibaba Cloud OSS-style CDN URLs, aspect-ratio probing, Canvas compression, side-by-side image merging, and downloads.

Every host, signing marker, breakpoint, and diagnostic sink is supplied by the consumer. The package does not embed product CDN addresses or credentials.

Install

pnpm add @stackonward/image

CDN URL processing

import { createOssImageHelper } from "@stackonward/image";

const images = createOssImageHelper({
  cdnHosts: ["cdn.example.com"],
});

const thumbnail = images.buildUrl("https://cdn.example.com/media/photo.jpg", {
  width: 480,
  quality: 80,
  format: "webp",
});

Only configured CDN hosts receive x-oss-process parameters. Widths snap to the configured breakpoints to limit cache fragmentation. Signed URLs, unknown hosts, and requests with no effective transformation pass through unchanged. GIF and SVG sources skip format conversion.

Aspect-ratio probing

import { createImageRatioProbe } from "@stackonward/image";

const ratios = createImageRatioProbe(images, {
  defaultRatio: 4 / 3,
  probeTimeout: 3_000,
});

await ratios.probeImageRatios(imageUrls);
const ratio = ratios.getCachedRatio(imageUrls[0]);

The probe loads tiny configured CDN derivatives, deduplicates concurrent work, and caches height / width. It skips URLs that the CDN helper leaves unchanged so probing cannot accidentally load a full-resolution third-party image.

Canvas operations

import { compressImage, mergeDualImages } from "@stackonward/image";

const compressed = await compressImage(file, {
  maxDimension: 2048,
  quality: 0.9,
  minSizeMB: 1,
});

const merged = await mergeDualImages(leftUrl, rightUrl, { targetHeight: 720 });

compressImage returns the original file when compression is unnecessary, unsupported, unavailable outside the browser, or would increase the file size. Animated GIF and SVG inputs are not rasterized. mergeDualImages requires a browser and rejects when it cannot load or render both sources.

Public API

| Export | Purpose | | ----------------------- | --------------------------------------------------------- | | createOssImageHelper | Build eligible OSS processing URLs and detect signed URLs | | createImageRatioProbe | Deduplicated thumbnail probing and ratio cache | | compressImage | Best-effort browser JPEG resize and recompression | | mergeDualImages | Merge two images horizontally at one target height | | downloadFile | Trigger a browser download for a File |

Canvas operations accept an optional ImageLogger. Without an injected logger, the package stays silent. Do not pass signed URLs or sensitive query strings to diagnostic sinks.

Compatibility

• ESM with TypeScript declarations
• Modern browsers for probing and Canvas operations
• URL construction is safe to import in non-browser runtimes

License

MIT