image-renditions 0.4.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.
@@ -518,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.

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-P49xsp3S.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-P49xsp3S.d.mts → handler-BhkqhlYb.d.mts}

@@ -1,5 +1,5 @@
 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 { r as Processor, t as Degradation } from "./processor-Dd3jqaOW.mjs";

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/server.d.mts

@@ -1,4 +1,4 @@
-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-P49xsp3S.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 { 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() {

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.4.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",