image-renditions 0.3.0 → 0.5.0

package/README.md

@@ -33,10 +33,11 @@ The library is modular, with pluggable parts:
 
 ## When not to use it
 
-- The URL must choose the size, such as `?w=300`.
-  Here every size is a preset in your code.
-- Image processing must not share CPU with your app.
-  Here images are processed inside the app process; a separate image service, such as imgproxy, or a hosted one, such as Cloudflare Images, takes that load elsewhere.
+Use an image service such as [imgproxy](https://imgproxy.net) or [Thumbor](https://thumbor.readthedocs.io) when the URL must choose the size, such as `?w=300`.
+Such a service takes the size and other options from the URL, and to keep clients from changing them it can require URLs signed with a secret key, which must stay out of browser code.
+
+image-renditions renders only the presets of its catalog: a URL carries a hash of the preset options, and a request for any other hash renders nothing.
+Its URLs need no secret, so they can be built in the browser too, but every size must be a preset in your code.
 
 ## Quick start
 
@@ -135,7 +136,7 @@ Options of a preset, or of `defaults`, which every preset overrides field by fie
 - `format` — `avif` (default), `webp`, `jpeg` or `png`.
 - `quality` — encoder quality from 1 to 100, by default 50 for `avif` and 80 for `webp` and `jpeg`; `png` is lossless.
 - `effort` — CPU effort of the `avif` (0–9) and `webp` (0–6) encoders, 4 by default; other formats ignore it.
-- `densities` — pixel densities to render, `[1]` by default.
+- `densities` — pixel densities to render, which include `1`; `[1]` by default.
 - `animation` — `first-frame` (default) renders the first frame of animated sources, and `preserve` keeps the animation of GIF and WebP sources; see [Animation](#animation).
 - `originals` — extensions of sources shown as they are, so no option above applies to them; see [Originals](#originals).
 
@@ -167,6 +168,7 @@ renditions.url("cover", post.coverPath)
 renditions.url("avatar", path, { density: 2 })
 renditions.srcset("avatar", path)
 renditions.attrs("avatar", path) // src, srcset and size of <RenditionImg>, for your own img element
+renditions.attrs("avatar", path, { size: false }) // src and srcset, for a component that sizes the image itself
 ```
 
 `url()` and `srcset()` return `undefined` for an unsafe path.
@@ -409,6 +411,18 @@ It renders the first frame of other animated sources, such as APNG and animated
 An animation at the pixel limit may take about 4 bytes of memory per pixel, and its encoder needs more, so plan memory for `limits.concurrency` such renditions at once.
 Changing the limits keeps stored renditions as they are; bump `pipelineVersion` to render them again.
 
+When a preset keeps the animation and a GIF or WebP animation renders its first frame because of its EXIF orientation or a limit, `createRenditionServer()` passes it to `onDegradation` once the rendition is written.
+The reason is `animation-orientation`, `animation-frames` or `animation-pixels`, and the message has the values involved, so you can log such renditions and tune the limits:
+
+```ts
+const server = createRenditionServer({
+  // ...
+  onDegradation({ message, target }) {
+    console.warn(`The rendition of ${target.path} is degraded: ${message}`)
+  },
+})
+```
+
 To process images with another library, implement the [`Processor`](#extending) interface and pass your implementation to `createRenditionServer()` as `processor`.
 
 ## h3 and other frameworks
@@ -506,7 +520,7 @@ If `publicUrl` never changes, pass a longer `redirectCacheControl` to `defineRen
 
 ## Concurrency and timeouts
 
-Rendering takes the CPU and memory of the app process, so the `limits` option of `createRenditionServer()` bounds it per process:
+The `limits` option of `createRenditionServer()` bounds rendering per process:
 
 - `concurrency` — renditions processed at once, 2 by default.
 - `queueSize` — renditions waiting for a slot, 100 by default.
@@ -576,6 +590,7 @@ Implement an interface from `image-renditions/server` and pass your implementati
 - To use other storage, implement `SourceStore` or `ResultStore` and pass it as `source` or `results`.
 - To process images with another library, implement `Processor` and pass it as `processor`.
   Implement its `assertRecipe()` to reject recipes it cannot render, such as animations, when the server is created.
+  Return `degradation` from its `process()` to report an image that falls short of its recipe to `onDegradation`.
 - To share the index of published renditions between replicas, for example in Redis, implement `ReadinessIndex` and pass it as `readiness.shared`.
   If a call fails or exceeds `indexTimeout`, the server reports the error to `onError` and checks storage instead, while [outdated URLs](#outdated-urls) fail as `unknown-recipe`.
 - To render each rendition once across replicas, implement `Coordinator` as a shared lock and pass it as `coordinator`.

package/dist/{catalog-D11xkViN.d.mts → catalog-6wdmwTO7.d.mts}

@@ -2,7 +2,7 @@ import { a as RenditionAnimation, c as RenditionOptions, r as Recipe, u as Sourc
 //#region src/catalog.d.ts
 /** Named transformation in a catalog. */
 interface PresetDefinition extends RenditionOptions {
-  /** Pixel densities to render, as multipliers of `width` and `height`; defaults to `[1]`. */
+  /** Pixel densities to render, as multipliers of `width` and `height`, which include `1`; defaults to `[1]`. */
   densities?: readonly number[];
   /**
    * Extensions of source files shown as they are instead of rendered, such as `svg`, in lowercase and without the dot.

package/dist/h3.d.mts

@@ -1,4 +1,4 @@
-import { r as RenditionHandlerOptions } from "./handler-RAQFWtrg.mjs";
+import { r as RenditionHandlerOptions } from "./handler-BhkqhlYb.mjs";
 import { EventHandler, H3Event } from "h3";
 //#region src/h3.d.ts
 /** Source of the application context of a request. */

package/dist/h3.mjs

@@ -1,4 +1,4 @@
-import { t as createRenditionHandler } from "./handler-D5toFJ55.mjs";
+import { t as createRenditionHandler } from "./handler-BZx2-0oV.mjs";
 import { defineEventHandler } from "h3";
 //#region src/h3.ts
 /**

package/dist/{handler-D5toFJ55.mjs → handler-BZx2-0oV.mjs}

@@ -1,5 +1,5 @@
 import { r as toDeclaredTarget } from "./scopes-C1kzqQHz.mjs";
-import { i as parseRenditionPath } from "./url-C6PtYIEf.mjs";
+import { s as parseRenditionPath } from "./url-ookAu7xz.mjs";
 import { t as RenditionError } from "./error-DViVpVmH.mjs";
 //#region src/server/handler.ts
 const failureStatus = {

package/dist/{handler-RAQFWtrg.d.mts → handler-BhkqhlYb.d.mts}

@@ -1,8 +1,8 @@
 import { r as Recipe, s as RenditionFormat } from "./recipe-BT8D60Qb.mjs";
-import { a as RenditionTarget, t as Catalog } from "./catalog-D11xkViN.mjs";
+import { a as RenditionTarget, t as Catalog } from "./catalog-6wdmwTO7.mjs";
 import { n as RenditionAddress } from "./url-DoJdUx9J.mjs";
 import { i as StoreCallOptions, n as ResultStore, r as SourceStore } from "./stores-P-TUmax4.mjs";
-import { t as Processor } from "./processor-DvyPs-OZ.mjs";
+import { r as Processor, t as Degradation } from "./processor-Dd3jqaOW.mjs";
 //#region src/server/error.d.ts
 /** Why a rendition could not be served. */
 type RenditionFailureReason =
@@ -124,6 +124,21 @@ interface RenditionServerOptions<Context, Scope extends string = string> {
    * It is not awaited, and its own failures are ignored.
    */
   onError?(error: unknown): void;
+  /**
+   * Receives a degradation the processor reports for a rendition it rendered, such as the first frame of an animation beyond a limit, once the rendition is written.
+   *
+   * Later requests for the rendition do not report it again.
+   * It is not awaited, and its own failures are ignored.
+   */
+  onDegradation?(degradation: RenditionDegradation<Context, Scope>): void;
+}
+/** Degradation a processor reported for a rendition the server wrote. */
+interface RenditionDegradation<Context, Scope extends string = string> extends Degradation {
+  recipe: Recipe;
+  target: RenditionTarget<Scope>;
+  /** Context of the call that rendered the rendition, which may be any of the concurrent calls for it. */
+  context: Context;
+  rendition: Rendition;
 }
 /** Published rendition. */
 interface Rendition {
@@ -224,4 +239,4 @@ type RenditionHandler<Context> = (request: RenditionRequest, getContext: () => C
  */
 declare function createRenditionHandler<Context, Scope extends string = string>({ server, onFailure, redirectCacheControl }: RenditionHandlerOptions<Context, Scope>): RenditionHandler<Context>;
 //#endregion
-export { RenditionFailureReason as _, createRenditionHandler as a, RenditionServerOptions as c, MemoryReadinessIndexOptions as d, ReadinessIndex as f, RenditionError as g, createLocalCoordinator as h, RenditionRequest as i, SourceResolution as l, Coordinator as m, RenditionHandler as n, Rendition as o, createMemoryReadinessIndex as p, RenditionHandlerOptions as r, RenditionServer as s, RenditionFailure as t, createRenditionServer as u };
+export { RenditionError as _, createRenditionHandler as a, RenditionServer as c, createRenditionServer as d, MemoryReadinessIndexOptions as f, createLocalCoordinator as g, Coordinator as h, RenditionRequest as i, RenditionServerOptions as l, createMemoryReadinessIndex as m, RenditionHandler as n, Rendition as o, ReadinessIndex as p, RenditionHandlerOptions as r, RenditionDegradation as s, RenditionFailure as t, SourceResolution as u, RenditionFailureReason as v };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { a as RenditionAnimation, c as RenditionOptions, d as formatContentTypes, f as formatExtensions, i as RecipeInput, l as RenditionPosition, m as serializeRecipe, n as RECIPE_ENGINE_VERSION, o as RenditionFit, p as normalizeRecipe, r as Recipe, s as RenditionFormat, t as MAX_DIMENSION, u as SourcePolicy } from "./recipe-BT8D60Qb.mjs";
-import { a as RenditionTarget, c as defineCatalog, i as PresetName, n as CatalogDefinition, o as RenditionVariant, r as PresetDefinition, s as ScopeName, t as Catalog } from "./catalog-D11xkViN.mjs";
+import { a as RenditionTarget, c as defineCatalog, i as PresetName, n as CatalogDefinition, o as RenditionVariant, r as PresetDefinition, s as ScopeName, t as Catalog } from "./catalog-6wdmwTO7.mjs";
 import { i as parseRenditionPath, n as RenditionAddress, r as formatRenditionPath, t as DEFAULT_BASE_PATH } from "./url-DoJdUx9J.mjs";
 //#region src/hash.d.ts
 /** Identifies a recipe by the truncated SHA-256 of its canonical serialization. */

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { a as normalizeRecipe, i as formatExtensions, n as RECIPE_ENGINE_VERSION
 import { t as hashRecipe } from "./hash-CHipV1N6.mjs";
 import { n as isSafePath, r as isSafeScope, t as encodePath } from "./path-hNFUjCbA.mjs";
 import { t as assertDeclaredScope } from "./scopes-C1kzqQHz.mjs";
-import { i as parseRenditionPath, n as assertBasePath, r as formatRenditionPath, t as DEFAULT_BASE_PATH } from "./url-C6PtYIEf.mjs";
+import { a as isSafeLabel, i as formatRenditionPath, n as assertBasePath, o as joinRenditionPath, r as assertSafeTarget, s as parseRenditionPath, t as DEFAULT_BASE_PATH } from "./url-ookAu7xz.mjs";
 //#region src/catalog.ts
 /** Extensions of sources that get animated variants, as a path does not tell an animated source from a still one. */
 const ANIMATED_EXTENSIONS = ["gif", "webp"];
@@ -35,6 +35,7 @@ function defineCatalog(definition) {
 			...omitUndefined(definition.presets[preset])
 		};
 		if (densities.length === 0 || new Set(densities).size !== densities.length) throw new RangeError(`Preset "${preset}" must declare unique densities.`);
+		if (!densities.includes(1)) throw new RangeError(`Preset "${preset}" must include density 1.`);
 		if (!originals.every((extension) => /^[\da-z]+$/.test(extension))) throw new RangeError(`Preset "${preset}" must list original extensions in lowercase and without the dot.`);
 		const sortedDensities = [...densities].sort((a, b) => a - b);
 		const createVariants = (variantOptions, animation) => Object.freeze(sortedDensities.map((density) => {
@@ -45,10 +46,12 @@ function defineCatalog(definition) {
 				policy: definition.sources,
 				animation
 			}));
+			const label = density === 1 ? preset : `${preset}@${density}x`;
+			if (!isSafeLabel(label)) throw new RangeError(`Invalid variant label "${label}" of preset "${preset}".`);
 			return Object.freeze({
 				preset,
 				density,
-				label: density === 1 ? preset : `${preset}@${density}x`,
+				label,
 				recipe,
 				hash: hashRecipe(recipe)
 			});
@@ -85,15 +88,24 @@ function defineCatalog(definition) {
 		if (!found) throw new RangeError(`Preset "${preset}" has no density ${density}.`);
 		return found;
 	}
-	function formatVariantUrl({ label, hash, recipe }, { scope, path }) {
+	/** Checks a target and encodes its path, once for all the variant URLs of a call. */
+	function encodeTarget({ scope, path }) {
 		assertDeclaredScope(scopes, scope);
-		return formatRenditionPath(basePath, {
+		assertSafeTarget(scope, path);
+		return encodePath(path);
+	}
+	/**
+	* URL of a variant for a target that `encodeTarget()` has checked and encoded.
+	*
+	* The base path and the labels are checked when the catalog is defined, and hashes are always safe.
+	*/
+	function joinVariantUrl({ label, hash, recipe }, scope, encodedPath) {
+		return joinRenditionPath(basePath, {
 			scope,
 			label,
 			hash,
-			format: recipe.format,
-			path
-		});
+			format: recipe.format
+		}, encodedPath);
 	}
 	return Object.freeze({
 		basePath,
@@ -105,8 +117,12 @@ function defineCatalog(definition) {
 		isOriginal: (preset, path) => hasExtension(path, getPreset(preset).originals),
 		allVariants: Object.freeze([...variantsByHash.values()]),
 		findVariant: (hash) => variantsByHash.get(hash),
-		url: (preset, target, density) => formatVariantUrl(variant(preset, density, target.path), target),
-		srcset: (preset, target) => variants(preset, target.path).map((variant) => `${formatVariantUrl(variant, target)} ${variant.density}x`).join(", ")
+		url: (preset, target, density) => joinVariantUrl(variant(preset, density, target.path), target.scope, encodeTarget(target)),
+		srcset: (preset, target) => {
+			const found = variants(preset, target.path);
+			const encodedPath = encodeTarget(target);
+			return found.map((entry) => `${joinVariantUrl(entry, target.scope, encodedPath)} ${entry.density}x`).join(", ");
+		}
 	});
 }
 /** Whether the extension of a path is in a list of lowercase extensions. */

package/dist/nuxt/runtime.d.mts

@@ -1,4 +1,4 @@
-import { a as RenditionTarget, t as Catalog } from "../catalog-D11xkViN.mjs";
+import { a as RenditionTarget, t as Catalog } from "../catalog-6wdmwTO7.mjs";
 import { PropType } from "vue";
 //#region src/nuxt/runtime.d.ts
 /** Attributes of an `img` element showing a rendition. */
@@ -27,6 +27,13 @@ export interface RenditionUrlOptions<Scope extends string = string> {
   /** Density of the variant; defaults to `1`. */
   density?: number;
 }
+/** Options of the `img` attributes of a rendition. */
+export interface RenditionAttrsOptions<Scope extends string = string> {
+  /** Scope of the path; defaults to the module's `defaultScope`. */
+  scope?: Scope;
+  /** Whether to set `width` and `height`; `false` leaves the size to a component that sizes the image itself. */
+  size?: boolean;
+}
 /** Options of {@link createRenditionHelpers}. */
 export interface RenditionHelpersOptions<Scope extends string = string> {
   /** Scope of calls that set none. */
@@ -51,7 +58,7 @@ export declare function createRenditionHelpers<Name extends string, Scope extend
   useRenditions: () => {
     url: (preset: Name, path: string, { scope, density }?: RenditionUrlOptions<Scope>) => string | undefined;
     srcset: (preset: Name, path: string, { scope }?: Pick<RenditionUrlOptions<Scope>, "scope">) => string | undefined;
-    attrs: (preset: Name, path: string, { scope }?: Pick<RenditionUrlOptions<Scope>, "scope">) => RenditionImgAttrs;
+    attrs: (preset: Name, path: string, { scope, size }?: RenditionAttrsOptions<Scope>) => RenditionImgAttrs;
   };
   RenditionImg: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     preset: {

package/dist/nuxt/runtime.mjs

@@ -1,5 +1,6 @@
-import { n as isSafePath, r as isSafeScope } from "../path-hNFUjCbA.mjs";
+import { n as isSafePath, r as isSafeScope, t as encodePath } from "../path-hNFUjCbA.mjs";
 import { n as isDeclaredScope, r as toDeclaredTarget, t as assertDeclaredScope } from "../scopes-C1kzqQHz.mjs";
+import { o as joinRenditionPath } from "../url-ookAu7xz.mjs";
 import { t as findRenditionAttr } from "../img-attrs-BoCAHpl5.mjs";
 import { useRuntimeConfig } from "nuxt/app";
 import { defineComponent, h } from "vue";
@@ -24,20 +25,37 @@ function createRenditionHelpers(catalog, { defaultScope, useOriginalUrl, imgAttr
 		/**
 		* Target of a path in the scope of a call, or `undefined` for an unsafe path.
 		*
-		* The scope is checked here because the URL of an original does not go through the rendition URL builder, which checks it too.
+		* The path and the scope are checked here once, since the URLs below are joined from them or built by `useOriginalUrl` rather than by `catalog.url()`, which would check them.
 		*/
 		function resolveTarget(path, scope) {
 			if (!isSafePath(path)) return;
 			const resolved = scope ?? defaultScope;
 			if (resolved !== void 0 && !isSafeScope(resolved)) throw new RangeError(`Invalid rendition scope "${resolved}".`);
-			assertDeclaredScope(catalog.scopes, resolved);
-			return toDeclaredTarget(catalog.scopes, resolved, path);
+			const target = toDeclaredTarget(catalog.scopes, resolved, path);
+			if (!target) assertDeclaredScope(catalog.scopes, resolved);
+			return target;
 		}
-		function formatUrl(preset, target, density) {
-			return base + catalog.url(preset, target, density);
+		/**
+		* URL of a variant below the application base URL, for a target with an encoded path.
+		*
+		* `resolveTarget()` has checked the target and the catalog its variants, so the URL is joined without checks.
+		*/
+		function joinVariantUrl({ label, hash, recipe }, scope, encodedPath) {
+			return base + joinRenditionPath(catalog.basePath, {
+				scope,
+				label,
+				hash,
+				format: recipe.format
+			}, encodedPath);
+		}
+		/** URLs of variants of a target, which encode its path once for all of them. */
+		function formatVariantUrls(variants, { scope, path }) {
+			const encodedPath = encodePath(path);
+			return variants.map((variant) => joinVariantUrl(variant, scope, encodedPath));
 		}
-		function formatSrcset(preset, target) {
-			return catalog.variants(preset).map(({ density }) => `${formatUrl(preset, target, density)} ${density}x`).join(", ");
+		/** `srcset` value of variants and their URLs. */
+		function formatSrcset(variants, urls) {
+			return variants.map(({ density }, index) => `${urls[index]} ${density}x`).join(", ");
 		}
 		/**
 		* URL of a rendition of a logical path, or of the source itself at every declared density when the preset lists its extension in `originals`.
@@ -49,11 +67,8 @@ function createRenditionHelpers(catalog, { defaultScope, useOriginalUrl, imgAttr
 		function url(preset, path, { scope, density } = {}) {
 			const target = resolveTarget(path, scope);
 			if (!target) return;
-			if (catalog.isOriginal(preset, path)) {
-				catalog.variant(preset, density);
-				return originalUrl(target);
-			}
-			return formatUrl(preset, target, density);
+			const variant = catalog.variant(preset, density, path);
+			return catalog.isOriginal(preset, path) ? originalUrl(target) : joinVariantUrl(variant, target.scope, encodePath(path));
 		}
 		/**
 		* `srcset` attribute value listing every density of a preset.
@@ -64,28 +79,37 @@ function createRenditionHelpers(catalog, { defaultScope, useOriginalUrl, imgAttr
 		*/
 		function srcset(preset, path, { scope } = {}) {
 			const target = resolveTarget(path, scope);
-			return target && !catalog.isOriginal(preset, path) ? formatSrcset(preset, target) : void 0;
+			if (!target || catalog.isOriginal(preset, path)) return;
+			const variants = catalog.variants(preset, path);
+			return formatSrcset(variants, formatVariantUrls(variants, target));
 		}
 		/**
 		* Attributes of an `img` element showing every density of a preset.
 		*
-		* `width` and `height` are set only when the output always has the size of the preset box, so they never distort the image.
+		* `width` and `height` are set only when the output always has the size of the preset box, so they never distort the image, and `size: false` leaves them out.
 		* A source that is already a URL, such as a `blob:`, `data:` or `https:` one, is returned unchanged as `src`.
 		* A source whose extension the preset lists in `originals` gets only the `src` of the source itself.
 		* An unsafe path, such as one with a `..` segment, yields no `src`, so stored data never breaks rendering.
+		*
+		* @throws {RangeError} When the preset is unknown, or the scope is invalid or not one the catalog declares.
 		*/
-		function attrs(preset, path, { scope } = {}) {
+		function attrs(preset, path, { scope, size = true } = {}) {
 			if (/^(?:[a-z][\d+.a-z-]*:|\/\/)/i.test(path)) return { src: path };
 			const target = resolveTarget(path, scope);
 			if (!target) return {};
 			if (catalog.isOriginal(preset, path)) return { src: originalUrl(target) };
-			const { recipe } = catalog.variant(preset);
+			const variants = catalog.variants(preset, path);
+			const main = variants.findIndex(({ density }) => density === 1);
+			const { recipe } = variants[main];
+			const urls = formatVariantUrls(variants, target);
 			const boxed = recipe.fit === "contain" || (recipe.fit === "cover" || recipe.fit === "fill") && recipe.enlarge;
 			return {
-				src: formatUrl(preset, target),
-				srcset: catalog.variants(preset).length > 1 ? formatSrcset(preset, target) : void 0,
-				width: boxed ? recipe.width : void 0,
-				height: boxed ? recipe.height : void 0
+				src: urls[main],
+				...variants.length > 1 ? { srcset: formatSrcset(variants, urls) } : void 0,
+				...size && boxed ? {
+					width: recipe.width,
+					height: recipe.height
+				} : void 0
 			};
 		}
 		return {

package/dist/{processor-DvyPs-OZ.d.mts → processor-Dd3jqaOW.d.mts}

@@ -1,6 +1,22 @@
 import { r as Recipe } from "./recipe-BT8D60Qb.mjs";
 import { t as EncodedImage } from "./stores-P-TUmax4.mjs";
 //#region src/server/processor.d.ts
+/** Shortfall of a rendered image against its recipe, which a processor reports. */
+interface Degradation {
+  /** Code of the shortfall, such as `animation-frames`. */
+  reason: string;
+  /** Human-readable description with the values involved, such as an exceeded limit. */
+  message: string;
+}
+/** Image a processor renders. */
+interface ProcessedImage extends EncodedImage {
+  /**
+   * Shortfall the processor detected, such as the first frame of an animation beyond a limit.
+   *
+   * Its absence does not promise that the image renders the recipe in full.
+   */
+  degradation?: Degradation;
+}
 /** Renders a source image according to a recipe. */
 interface Processor {
   /**
@@ -8,7 +24,7 @@ interface Processor {
    *
    * Rejects with a `RenditionError` of reason `unsupported-source` when the source cannot be decoded or processed, and of reason `source-too-large` when it exceeds a size limit.
    */
-  process(source: Uint8Array, recipe: Recipe): Promise<EncodedImage>;
+  process(source: Uint8Array, recipe: Recipe): Promise<ProcessedImage>;
   /**
    * Checks that the processor renders a recipe as it describes.
    *
@@ -19,4 +35,4 @@ interface Processor {
   assertRecipe?(recipe: Recipe): void;
 }
 //#endregion
-export { Processor as t };
+export { ProcessedImage as n, Processor as r, Degradation as t };

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { _ as RenditionFailureReason, a as createRenditionHandler, c as RenditionServerOptions, d as MemoryReadinessIndexOptions, f as ReadinessIndex, g as RenditionError, h as createLocalCoordinator, i as RenditionRequest, l as SourceResolution, m as Coordinator, n as RenditionHandler, o as Rendition, p as createMemoryReadinessIndex, r as RenditionHandlerOptions, s as RenditionServer, t as RenditionFailure, u as createRenditionServer } from "./handler-RAQFWtrg.mjs";
+import { _ as RenditionError, a as createRenditionHandler, c as RenditionServer, d as createRenditionServer, f as MemoryReadinessIndexOptions, g as createLocalCoordinator, h as Coordinator, i as RenditionRequest, l as RenditionServerOptions, m as createMemoryReadinessIndex, n as RenditionHandler, o as Rendition, p as ReadinessIndex, r as RenditionHandlerOptions, s as RenditionDegradation, t as RenditionFailure, u as SourceResolution, v as RenditionFailureReason } from "./handler-BhkqhlYb.mjs";
 import { i as StoreCallOptions, n as ResultStore, r as SourceStore, t as EncodedImage } from "./stores-P-TUmax4.mjs";
-import { t as Processor } from "./processor-DvyPs-OZ.mjs";
-export { Coordinator, EncodedImage, MemoryReadinessIndexOptions, Processor, ReadinessIndex, Rendition, RenditionError, RenditionFailure, RenditionFailureReason, RenditionHandler, RenditionHandlerOptions, RenditionRequest, RenditionServer, RenditionServerOptions, ResultStore, SourceResolution, SourceStore, StoreCallOptions, createLocalCoordinator, createMemoryReadinessIndex, createRenditionHandler, createRenditionServer };
+import { n as ProcessedImage, r as Processor, t as Degradation } from "./processor-Dd3jqaOW.mjs";
+export { Coordinator, Degradation, EncodedImage, MemoryReadinessIndexOptions, ProcessedImage, Processor, ReadinessIndex, Rendition, RenditionDegradation, RenditionError, RenditionFailure, RenditionFailureReason, RenditionHandler, RenditionHandlerOptions, RenditionRequest, RenditionServer, RenditionServerOptions, ResultStore, SourceResolution, SourceStore, StoreCallOptions, createLocalCoordinator, createMemoryReadinessIndex, createRenditionHandler, createRenditionServer };

package/dist/server.mjs

@@ -3,7 +3,7 @@ import { t as hashRecipe } from "./hash-CHipV1N6.mjs";
 import { n as isSafePath } from "./path-hNFUjCbA.mjs";
 import { n as isDeclaredScope } from "./scopes-C1kzqQHz.mjs";
 import { t as RenditionError } from "./error-DViVpVmH.mjs";
-import { t as createRenditionHandler } from "./handler-D5toFJ55.mjs";
+import { t as createRenditionHandler } from "./handler-BZx2-0oV.mjs";
 //#region src/server/coordinator.ts
 /** Creates a coordinator that merges concurrent equal requests within the process. */
 function createLocalCoordinator() {
@@ -88,7 +88,7 @@ const MAX_TIMEOUT = 2 ** 31 - 1;
 * @throws {RangeError} When a limit is not an integer in its range, or the processor cannot render a variant of the catalog.
 */
 function createRenditionServer(options) {
-	const { catalog, source, results, processor, resolveSource = resolveUnscoped, onError } = options;
+	const { catalog, source, results, processor, resolveSource = resolveUnscoped, onError, onDegradation } = options;
 	const memory = createMemoryReadinessIndex(options.readiness?.memory);
 	const shared = options.readiness?.shared;
 	const coordinator = options.coordinator ?? createLocalCoordinator();
@@ -148,28 +148,26 @@ function createRenditionServer(options) {
 		try {
 			return await withTimeout(indexTimeout, call);
 		} catch (error) {
-			report(error);
+			notify(onError, error);
 			return;
 		}
 	}
-	/** Passes an error to `onError` without waiting for it, so a failing or hanging callback cannot affect the operation. */
-	function report(error) {
-		try {
-			Promise.resolve(onError?.(error)).catch(() => {});
-		} catch {}
-	}
 	function callStorage(reason, call) {
 		return withTimeout(storageTimeout, call).catch((error) => {
 			throw error instanceof RenditionError ? error : new RenditionError(reason, `Storage call failed: ${error}`, { cause: error });
 		});
 	}
 	async function render(recipe, sourceKey, key) {
-		const data = await callStorage("source-error", (signal) => source.read(sourceKey, { signal }));
-		if (!data) throw new RenditionError("source-not-found", `The source ${sourceKey} does not exist.`);
-		const image = await processor.process(data, recipe).catch((error) => {
+		const input = await callStorage("source-error", (signal) => source.read(sourceKey, { signal }));
+		if (!input) throw new RenditionError("source-not-found", `The source ${sourceKey} does not exist.`);
+		const { data, contentType, degradation } = await processor.process(input, recipe).catch((error) => {
 			throw error instanceof RenditionError ? error : new RenditionError("processing-failed", `Processing failed: ${error}`, { cause: error });
 		});
-		await callStorage("storage-error", (signal) => results.write(key, image, { signal }));
+		await callStorage("storage-error", (signal) => results.write(key, {
+			data,
+			contentType
+		}, { signal }));
+		return degradation;
 	}
 	return {
 		catalog,
@@ -180,7 +178,16 @@ function createRenditionServer(options) {
 			if (await isIndexed(rendition.url)) return rendition;
 			return coordinator.run(rendition.url, async () => {
 				if (!await isIndexed(rendition.url)) {
-					if (!await callStorage("storage-error", (signal) => results.exists(rendition.key, { signal }))) await limiter.run(() => render(recipe, sourceKey, rendition.key));
+					if (!await callStorage("storage-error", (signal) => results.exists(rendition.key, { signal }))) {
+						const degradation = await limiter.run(() => render(recipe, sourceKey, rendition.key));
+						if (degradation) notify(onDegradation, {
+							...degradation,
+							recipe,
+							target,
+							context,
+							rendition: { ...rendition }
+						});
+					}
 					await markPublished(rendition.url);
 				}
 				return rendition;
@@ -193,6 +200,12 @@ function createRenditionServer(options) {
 		resolve
 	};
 }
+/** Calls an optional callback without waiting for it, so a failing or hanging callback cannot affect the operation. */
+function notify(callback, value) {
+	try {
+		Promise.resolve(callback?.(value)).catch(() => {});
+	} catch {}
+}
 /**
 * Runs a call with an abort signal that fires after the timeout.
 *

package/dist/sharp.d.mts

@@ -1,4 +1,4 @@
-import { t as Processor } from "./processor-DvyPs-OZ.mjs";
+import { r as Processor } from "./processor-Dd3jqaOW.mjs";
 //#region src/processors/sharp/processor.d.ts
 /** Options of {@link createSharpProcessor}. */
 export interface SharpProcessorOptions {

package/dist/sharp.mjs

@@ -115,12 +115,13 @@ function createSharpProcessor({ maxInputPixels = 1e8, maxAnimationPixels = 5e7,
 		assertRecipe,
 		async process(source, recipe) {
 			assertRecipe(recipe);
-			const data = await render(source, recipe, maxInputPixels, limits).catch((error) => {
+			const { data, degradation } = 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]
+				contentType: formatContentTypes[recipe.format],
+				degradation
 			};
 		}
 	};
@@ -150,7 +151,8 @@ async function render(source, recipe, maxInputPixels, limits) {
 		width = raster.width;
 		height = raster.height;
 	}
-	const frames = keepsAnimation(recipe, metadata, limits) ? {
+	const animation = planAnimation(recipe, metadata, limits);
+	const frames = animation.animated ? {
 		animated: true,
 		limitInputPixels: limits.maxAnimationPixels
 	} : { pages: 1 };
@@ -164,6 +166,12 @@ async function render(source, recipe, maxInputPixels, limits) {
 	if (resize) pipeline = pipeline.resize(resize);
 	if (recipe.format === "jpeg") pipeline = pipeline.flatten({ background: parseColor(recipe.background) });
 	pipeline = pipeline.toColourspace("srgb");
+	return {
+		data: await encode(pipeline, recipe),
+		degradation: animation.degradation
+	};
+}
+function encode(pipeline, recipe) {
 	switch (recipe.format) {
 		case "avif": return pipeline.avif({
 			quality: recipe.quality,
@@ -178,14 +186,26 @@ async function render(source, recipe, maxInputPixels, limits) {
 	}
 }
 /**
-* Whether a rendition keeps the animation of a source, judged by the metadata of its first frame.
+* Plans 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;
+function planAnimation(recipe, { format, pages = 1, width, height, orientation = 1 }, { maxAnimationPixels, maxFrames }) {
+	if (recipe.animation !== "preserve" || format !== "gif" && format !== "webp" || pages < 2) return { animated: false };
+	if (orientation !== 1) return degrade("animation-orientation", `Sharp cannot apply the EXIF orientation ${orientation} to the frames of an animation.`);
+	if (maxFrames > 0 && pages > maxFrames) return degrade("animation-frames", `The animation of ${pages} frames exceeds the frame limit of ${maxFrames}.`);
 	const pixels = Math.max(width * height, estimateRenditionArea(recipe, width, height)) * pages;
-	return (maxFrames === 0 || pages <= maxFrames) && (maxAnimationPixels === 0 || pixels <= maxAnimationPixels);
+	if (maxAnimationPixels > 0 && pixels > maxAnimationPixels) return degrade("animation-pixels", `The animation of ${pixels} pixels exceeds the animation pixel limit of ${maxAnimationPixels}.`);
+	return { animated: true };
+}
+function degrade(reason, message) {
+	return {
+		animated: false,
+		degradation: {
+			reason,
+			message
+		}
+	};
 }
 /**
 * Checks that sharp can keep an animation where a recipe asks for it.

package/dist/{url-C6PtYIEf.mjs → url-ookAu7xz.mjs}

@@ -12,12 +12,33 @@ const DEFAULT_BASE_PATH = "/_renditions";
 */
 function formatRenditionPath(basePath, { scope, label, hash, format, path }) {
 	assertBasePath(basePath);
-	if (scope !== void 0 && !isSafeScope(scope)) throw new RangeError(`Invalid rendition scope "${scope}".`);
+	assertSafeTarget(scope, path);
 	const extension = formatExtensions[format];
 	if (!isSafeLabel(label) || !isHash(hash) || !extension) throw new RangeError(`Invalid rendition variant "${label}.${hash}.${extension ?? format}".`);
+	return joinRenditionPath(basePath, {
+		scope,
+		label,
+		hash,
+		format
+	}, encodePath(path));
+}
+/**
+* Checks that a scope and a source path are safe to put into a rendition URL.
+*
+* @throws {RangeError} When the scope or the path is unsafe.
+*/
+function assertSafeTarget(scope, path) {
+	if (scope !== void 0 && !isSafeScope(scope)) throw new RangeError(`Invalid rendition scope "${scope}".`);
 	if (!isSafePath(path)) throw new RangeError(`Unsafe rendition source path "${path}".`);
+}
+/**
+* Joins the parts of a rendition URL path without checking them, with the source path already encoded.
+*
+* It serves parts checked once for several URLs, such as the variants of a catalog for one target.
+*/
+function joinRenditionPath(basePath, { scope, label, hash, format }, encodedPath) {
 	const scopePrefix = scope === void 0 ? "" : `${scope}/`;
-	return `${basePath}/${URL_FORMAT_VERSION}/${scopePrefix}${label}.${hash}.${extension}/${encodePath(path)}`;
+	return `${basePath}/${URL_FORMAT_VERSION}/${scopePrefix}${label}.${hash}.${formatExtensions[format]}/${encodedPath}`;
 }
 /**
 * Parses the path of a rendition URL, ignoring any query string.
@@ -55,6 +76,7 @@ function assertBasePath(basePath) {
 	if (!/^(?:\/[\w.~-]+)+$/.test(basePath)) throw new RangeError(`Invalid rendition base path "${basePath}".`);
 }
 const formats = Object.keys(formatExtensions);
+/** Checks that a variant label is 1 to 64 characters that need no encoding in a URL. */
 function isSafeLabel(label) {
 	return /^[\w@.-]{1,64}$/.test(label);
 }
@@ -74,4 +96,4 @@ function decodeSegment(segment) {
 	}
 }
 //#endregion
-export { parseRenditionPath as i, assertBasePath as n, formatRenditionPath as r, DEFAULT_BASE_PATH as t };
+export { isSafeLabel as a, formatRenditionPath as i, assertBasePath as n, joinRenditionPath as o, assertSafeTarget as r, parseRenditionPath as s, DEFAULT_BASE_PATH as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-renditions",
-  "version": "0.3.0",
+  "version": "0.5.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",