image-renditions 0.0.0-stage → 0.2.0

package/dist/sharp.mjs

@@ -0,0 +1,205 @@
+import { r as formatContentTypes, s as assertInteger, t as MAX_DIMENSION } from "./recipe-BavgOq0b.mjs";
+import { t as RenditionError } from "./error-DViVpVmH.mjs";
+import sharp from "sharp";
+//#region src/processors/sharp/resize.ts
+/**
+* Plans the crop and resize of a source of the given size; an absent step is skipped.
+*
+* An image the recipe would scale beyond {@link MAX_DIMENSION} on a side is scaled less, so it stays whole and comes out smaller than the recipe box.
+* Under `cover`, the long side is cut before scaling instead, so the rendition keeps the box.
+*/
+function planResize(recipe, width, height) {
+	const options = {
+		width: recipe.width,
+		height: recipe.height,
+		fit: recipe.fit,
+		position: recipe.position,
+		background: recipe.background && parseColor(recipe.background),
+		withoutEnlargement: !recipe.enlarge
+	};
+	const sized = recipe.width !== void 0 || recipe.height !== void 0;
+	const scale = computeResizeScale(recipe, width, height) ?? 1;
+	const factor = recipe.enlarge ? scale : Math.min(scale, 1);
+	const longest = Math.max(width, height);
+	if (Math.round(longest * factor) <= 16383 || recipe.fit === "fill") return { resize: sized ? options : void 0 };
+	if (recipe.fit === "cover") {
+		if (factor <= 1) return { resize: options };
+		const vertical = height > width;
+		const across = vertical ? width : height;
+		const boxAcross = vertical ? recipe.width : recipe.height;
+		const boxAlong = vertical ? recipe.height : recipe.width;
+		const fitting = Math.floor(MAX_DIMENSION * across / boxAcross);
+		const start = recipe.position === (vertical ? "top" : "left");
+		const end = recipe.position === (vertical ? "bottom" : "right");
+		const length = !start && !end && (longest - fitting) % 2 === 1 && (fitting - 1) * boxAcross >= boxAlong * across ? fitting - 1 : fitting;
+		const slack = longest - length;
+		const offset = start ? 0 : end ? slack : Math.floor(slack / 2);
+		return {
+			extract: vertical ? {
+				left: 0,
+				top: offset,
+				width,
+				height: length
+			} : {
+				left: offset,
+				top: 0,
+				width: length,
+				height
+			},
+			resize: options
+		};
+	}
+	const box = recipe.fit === "outside" ? {} : {
+		width: recipe.width,
+		height: recipe.height
+	};
+	return { resize: {
+		width: box.width ?? 16383,
+		height: box.height ?? 16383,
+		fit: "inside",
+		withoutEnlargement: !recipe.enlarge
+	} };
+}
+/**
+* Factor that brings a source of the given size to the recipe box, before any `enlarge` limit.
+*
+* Returns `undefined` when the recipe sets no size or the source size is unknown.
+* For `fill`, it is the factor of the side that needs more scaling.
+*/
+function computeResizeScale({ width, height, fit }, sourceWidth, sourceHeight) {
+	const scales = [width && sourceWidth ? width / sourceWidth : void 0, height && sourceHeight ? height / sourceHeight : void 0].filter((scale) => scale !== void 0);
+	if (scales.length === 0) return;
+	return fit === "inside" || fit === "contain" ? Math.min(...scales) : Math.max(...scales);
+}
+/**
+* Estimates an upper bound of the rendition area of a source of the given size, in pixels.
+*
+* `contain` pads the image to the box, `cover`, `fill` and `inside` keep each side within the box, and other recipes keep the scaled size of the source.
+*/
+function estimateRenditionArea(recipe, width, height) {
+	if (recipe.fit === "contain") return recipe.width * recipe.height;
+	const scale = computeResizeScale(recipe, width, height) ?? 1;
+	const factor = recipe.enlarge ? scale : Math.min(scale, 1);
+	const scaledWidth = Math.ceil(width * factor);
+	const scaledHeight = Math.ceil(height * factor);
+	return recipe.fit === void 0 || recipe.fit === "outside" ? scaledWidth * scaledHeight : Math.min(scaledWidth, recipe.width) * Math.min(scaledHeight, recipe.height);
+}
+/** Converts a normalized `#rrggbbaa` color to the form sharp accepts. */
+function parseColor(color) {
+	const parseChannel = (index) => Number.parseInt(color.slice(1 + index * 2, 3 + index * 2), 16);
+	return {
+		r: parseChannel(0),
+		g: parseChannel(1),
+		b: parseChannel(2),
+		alpha: parseChannel(3) / 255
+	};
+}
+//#endregion
+//#region src/processors/sharp/processor.ts
+/** Rasterization density SVG renders at when no scaling is needed, in DPI. */
+const SVG_BASE_DENSITY = 72;
+/**
+* Creates a processor backed by sharp and libvips.
+*
+* @throws {RangeError} When a limit is not a non-negative integer.
+*/
+function createSharpProcessor({ maxInputPixels = 1e8, maxAnimationPixels = 5e7, maxFrames = 1e3 } = {}) {
+	assertInteger("maxInputPixels", maxInputPixels, 0, Number.MAX_SAFE_INTEGER);
+	assertInteger("maxAnimationPixels", maxAnimationPixels, 0, Number.MAX_SAFE_INTEGER);
+	assertInteger("maxFrames", maxFrames, 0, Number.MAX_SAFE_INTEGER);
+	const limits = {
+		maxAnimationPixels,
+		maxFrames
+	};
+	return {
+		assertRecipe,
+		async process(source, recipe) {
+			assertRecipe(recipe);
+			const data = await render(source, recipe, maxInputPixels, limits).catch((error) => {
+				throw error instanceof RenditionError ? error : new RenditionError("unsupported-source", "The source cannot be processed.", { cause: error });
+			});
+			return {
+				data: new Uint8Array(data),
+				contentType: formatContentTypes[recipe.format]
+			};
+		}
+	};
+}
+async function render(source, recipe, maxInputPixels, limits) {
+	const input = {
+		failOn: "error",
+		limitInputPixels: maxInputPixels
+	};
+	const metadata = await sharp(source, {
+		...input,
+		limitInputPixels: false
+	}).metadata();
+	assertPixels(metadata.width, metadata.height, maxInputPixels);
+	let { width, height } = metadata.autoOrient;
+	let density;
+	if (metadata.format === "svg") {
+		const needed = computeResizeScale(recipe, width, height) ?? 1;
+		const scale = recipe.fit === "cover" || recipe.fit === "fill" ? needed : Math.min(needed, MAX_DIMENSION / Math.max(width, height, 1));
+		density = Math.min(Math.max(SVG_BASE_DENSITY * scale, 1), 1e5);
+		const raster = (await sharp(source, {
+			...input,
+			density,
+			limitInputPixels: false
+		}).metadata()).autoOrient;
+		assertPixels(raster.width, raster.height, maxInputPixels);
+		width = raster.width;
+		height = raster.height;
+	}
+	const frames = keepsAnimation(recipe, metadata, limits) ? {
+		animated: true,
+		limitInputPixels: limits.maxAnimationPixels
+	} : { pages: 1 };
+	let pipeline = sharp(source, {
+		...input,
+		density,
+		...frames
+	}).autoOrient();
+	const { extract, resize } = planResize(recipe, width, height);
+	if (extract) pipeline = pipeline.extract(extract);
+	if (resize) pipeline = pipeline.resize(resize);
+	if (recipe.format === "jpeg") pipeline = pipeline.flatten({ background: parseColor(recipe.background) });
+	pipeline = pipeline.toColourspace("srgb");
+	switch (recipe.format) {
+		case "avif": return pipeline.avif({
+			quality: recipe.quality,
+			effort: recipe.effort
+		}).toBuffer();
+		case "webp": return pipeline.webp({
+			quality: recipe.quality,
+			effort: recipe.effort
+		}).toBuffer();
+		case "jpeg": return pipeline.jpeg({ quality: recipe.quality }).toBuffer();
+		case "png": return pipeline.png().toBuffer();
+	}
+}
+/**
+* Whether a rendition keeps the animation of a source, judged by the metadata of its first frame.
+*
+* Sharp resizes and crops the frames one by one, so the planned geometry of the first frame applies to every frame.
+*/
+function keepsAnimation(recipe, { format, pages = 1, width, height, orientation = 1 }, { maxAnimationPixels, maxFrames }) {
+	if (recipe.animation !== "preserve" || format !== "gif" && format !== "webp" || pages < 2 || orientation !== 1) return false;
+	const pixels = Math.max(width * height, estimateRenditionArea(recipe, width, height)) * pages;
+	return (maxFrames === 0 || pages <= maxFrames) && (maxAnimationPixels === 0 || pixels <= maxAnimationPixels);
+}
+/**
+* Checks that sharp can keep an animation where a recipe asks for it.
+*
+* @throws {RangeError} When the recipe keeps an animation in a format other than `webp` or crops it by content.
+*/
+function assertRecipe({ animation, format, position }) {
+	if (animation !== "preserve") return;
+	if (format !== "webp") throw new RangeError(`Animations cannot be encoded as ${format}.`);
+	if (position === "entropy" || position === "attention") throw new RangeError(`Position "${position}" cannot crop an animation.`);
+}
+/** Fails as `source-too-large` when an image of the size exceeds the pixel limit, unless the limit is `0`. */
+function assertPixels(width, height, maxInputPixels) {
+	if (maxInputPixels > 0 && width * height > maxInputPixels) throw new RenditionError("source-too-large", `The source of ${width}×${height} pixels exceeds the limit of ${maxInputPixels}.`);
+}
+//#endregion
+export { createSharpProcessor };

package/dist/stores-P-TUmax4.d.mts

@@ -0,0 +1,42 @@
+//#region src/server/stores.d.ts
+/** Encoded rendition ready to be stored. */
+interface EncodedImage {
+  data: Uint8Array;
+  /** MIME type of `data`, such as `image/avif`. */
+  contentType: string;
+}
+/** Options of a single storage call. */
+interface StoreCallOptions {
+  /** Aborts the call when the operation times out. */
+  signal: AbortSignal;
+}
+/**
+ * Storage of immutable source images.
+ *
+ * Sources are assumed never to change under the same key: a rendition is generated once and is not refreshed.
+ */
+interface SourceStore {
+  /**
+   * Reads a source object.
+   *
+   * Resolves to `undefined` when the object does not exist.
+   * Rejects with a `RenditionError` of reason `source-too-large` when the object exceeds a size limit.
+   */
+  read(key: string, options: StoreCallOptions): Promise<Uint8Array | undefined>;
+}
+/** Storage of published renditions, each served from a public URL. */
+interface ResultStore {
+  /** Checks whether an object is published under the key. */
+  exists(key: string, options: StoreCallOptions): Promise<boolean>;
+  /**
+   * Publishes an object under the key.
+   *
+   * Overwriting an existing object with an equivalent rendition must be safe, because concurrent replicas may render the same key.
+   * Readers must never observe a partially written object.
+   */
+  write(key: string, image: EncodedImage, options: StoreCallOptions): Promise<void>;
+  /** Public URL of the object under the key, percent-encoded so it can be sent in a `Location` header. */
+  url(key: string): string;
+}
+//#endregion
+export { StoreCallOptions as i, ResultStore as n, SourceStore as r, EncodedImage as t };

package/dist/url-BAU5GYXC.mjs

@@ -0,0 +1,81 @@
+import { i as formatExtensions, o as serializeRecipe } from "./recipe-BavgOq0b.mjs";
+import { n as isSafePath, r as isSafeScope, t as encodePath } from "./path-hNFUjCbA.mjs";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+//#region src/hash.ts
+/** Length of a recipe hash in hex digits, which keeps 128 bits of SHA-256. */
+const RECIPE_HASH_LENGTH = 32;
+/** Identifies a recipe by the truncated SHA-256 of its canonical serialization. */
+function hashRecipe(recipe) {
+	return bytesToHex(sha256(utf8ToBytes(serializeRecipe(recipe)))).slice(0, 32);
+}
+//#endregion
+//#region src/url.ts
+/** Version segment of the rendition URL format this library builds and parses. */
+const URL_FORMAT_VERSION = "v1";
+/** Mount path of the rendition handler unless a catalog sets another one. */
+const DEFAULT_BASE_PATH = "/_renditions";
+/**
+* Formats the path of a rendition URL: `<basePath>/v1/[<scope>/]<label>.<hash>.<extension>/<path>`.
+*
+* @throws {RangeError} When a part is unsafe to put into the URL.
+*/
+function formatRenditionPath(basePath, { scope, label, hash, format, path }) {
+	assertBasePath(basePath);
+	if (scope !== void 0 && !isSafeScope(scope)) throw new RangeError(`Invalid rendition scope "${scope}".`);
+	const extension = formatExtensions[format];
+	if (!isSafeLabel(label) || !isHash(hash) || !extension) throw new RangeError(`Invalid rendition variant "${label}.${hash}.${extension ?? format}".`);
+	if (!isSafePath(path)) throw new RangeError(`Unsafe rendition source path "${path}".`);
+	return `${basePath}/v1/${scope === void 0 ? "" : `${scope}/`}${label}.${hash}.${extension}/${encodePath(path)}`;
+}
+/**
+* Parses the path of a rendition URL, ignoring any query string.
+*
+* Returns `undefined` for a path outside `basePath`, another URL format version, or malformed or unsafe parts.
+*/
+function parseRenditionPath(basePath, url) {
+	const prefix = `${basePath}/v1/`;
+	const pathname = url.split("?", 1)[0];
+	if (!pathname.startsWith(prefix)) return;
+	const parts = pathname.slice(prefix.length).split("/");
+	const scope = isSafeScope(parts[0]) ? parts.shift() : void 0;
+	const [variant, ...encodedSegments] = parts;
+	if (!variant) return;
+	const [, label = "", hash = "", extension] = /^(.+)\.([^.]+)\.([^.]+)$/.exec(variant) ?? [];
+	const format = formats.find((format) => formatExtensions[format] === extension);
+	if (!isSafeLabel(label) || !isHash(hash) || !format) return;
+	const segments = encodedSegments.map(decodeSegment);
+	if (segments.some((segment) => segment === void 0 || segment.includes("/"))) return;
+	const path = segments.join("/");
+	return isSafePath(path) ? {
+		scope,
+		label,
+		hash,
+		format,
+		path
+	} : void 0;
+}
+/**
+* Checks that a base path is absolute, has no trailing slash and needs no URL encoding.
+*
+* @throws {RangeError} When the base path is invalid.
+*/
+function assertBasePath(basePath) {
+	if (!/^(?:\/[\w.~-]+)+$/.test(basePath)) throw new RangeError(`Invalid rendition base path "${basePath}".`);
+}
+const formats = Object.keys(formatExtensions);
+function isSafeLabel(label) {
+	return /^[\w@.-]{1,64}$/.test(label);
+}
+function isHash(hash) {
+	return hash.length === 32 && /^[\da-f]+$/.test(hash);
+}
+function decodeSegment(segment) {
+	try {
+		return decodeURIComponent(segment);
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { parseRenditionPath as a, formatRenditionPath as i, URL_FORMAT_VERSION as n, RECIPE_HASH_LENGTH as o, assertBasePath as r, hashRecipe as s, DEFAULT_BASE_PATH as t };

package/dist/url-BVH3ZB0F.d.mts

@@ -0,0 +1,38 @@
+import { s as RenditionFormat } from "./recipe-BT8D60Qb.mjs";
+//#region src/url.d.ts
+/** Version segment of the rendition URL format this library builds and parses. */
+declare const URL_FORMAT_VERSION = "v1";
+/** Mount path of the rendition handler unless a catalog sets another one. */
+declare const DEFAULT_BASE_PATH = "/_renditions";
+/** Parts of a rendition URL. */
+interface RenditionAddress {
+  /** Application-defined space the logical path belongs to, such as a tenant. */
+  scope?: string;
+  /** Human-readable variant name; the server ignores it and resolves the recipe by `hash`. */
+  label: string;
+  hash: string;
+  /** Output format, which also lets a server locate a rendition whose recipe it no longer knows. */
+  format: RenditionFormat;
+  /** Logical source path inside the scope. */
+  path: string;
+}
+/**
+ * Formats the path of a rendition URL: `<basePath>/v1/[<scope>/]<label>.<hash>.<extension>/<path>`.
+ *
+ * @throws {RangeError} When a part is unsafe to put into the URL.
+ */
+declare function formatRenditionPath(basePath: string, { scope, label, hash, format, path }: RenditionAddress): string;
+/**
+ * Parses the path of a rendition URL, ignoring any query string.
+ *
+ * Returns `undefined` for a path outside `basePath`, another URL format version, or malformed or unsafe parts.
+ */
+declare function parseRenditionPath(basePath: string, url: string): RenditionAddress | undefined;
+/**
+ * Checks that a base path is absolute, has no trailing slash and needs no URL encoding.
+ *
+ * @throws {RangeError} When the base path is invalid.
+ */
+declare function assertBasePath(basePath: string): void;
+//#endregion
+export { formatRenditionPath as a, assertBasePath as i, RenditionAddress as n, parseRenditionPath as o, URL_FORMAT_VERSION as r, DEFAULT_BASE_PATH as t };

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "image-renditions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "On-demand image transformations that persist every result to durable storage and keep app servers stateless.",
+  "homepage": "https://github.com/IlyaSemenov/image-renditions#readme",
+  "bugs": "https://github.com/IlyaSemenov/image-renditions/issues",
+  "license": "MIT",
+  "author": "Ilya Semenov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IlyaSemenov/image-renditions.git"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./fs": "./dist/fs.mjs",
+    "./h3": "./dist/h3.mjs",
+    "./nuxt": "./dist/nuxt.mjs",
+    "./nuxt/runtime": "./dist/nuxt/runtime.mjs",
+    "./s3": "./dist/s3.mjs",
+    "./server": "./dist/server.mjs",
+    "./sharp": "./dist/sharp.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint --fix && oxfmt",
+    "lint:check": "oxlint && oxfmt --check",
+    "prepare": "lefthook install",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "test:nuxt": "bun run build && bun tests/nuxt-build.ts",
+    "types": "tsc && tsc -p tests/tsconfig.json && tsc -p tests/h3-v1/tsconfig.json"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.4.0",
+    "jiti": "^2.7.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.5",
+    "@aws-sdk/client-s3": "^3.1150.0",
+    "@changesets/cli": "^3.0.3",
+    "@ilyasemenov/oxc-config": "^0.1.1",
+    "@tsconfig/bun": "^1.0.11",
+    "@types/bun": "^1.4.3",
+    "h3": "^2.0.2",
+    "h3-v1": "npm:h3@^1.15.11",
+    "nuxt": "^4.6.1",
+    "oxfmt": "^0.73.0",
+    "oxlint": "^1.88.0",
+    "publint": "^0.3.25",
+    "sharp": "^0.35.5",
+    "tsdown": "^0.23.1",
+    "typescript": "^7.0.2",
+    "vue": "^3.5.44"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.1150.0",
+    "h3": "^1.15.0 || ^2.0.0",
+    "nuxt": "^4.0.0",
+    "sharp": "^0.35.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "h3": {
+      "optional": true
+    },
+    "nuxt": {
+      "optional": true
+    },
+    "sharp": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "packageManager": "bun@1.4.3"
+}