image-renditions 0.0.0-stage → 0.2.0

package/dist/recipe-BavgOq0b.mjs

@@ -0,0 +1,142 @@
+//#region src/assert.ts
+/** Throws a `RangeError` unless a value is an integer from `min` to `max`. */
+function assertInteger(name, value, min, max) {
+	if (!Number.isInteger(value) || value < min || value > max) throw new RangeError(`Invalid ${name} ${value}; expected an integer from ${min} to ${max}.`);
+}
+//#endregion
+//#region src/recipe.ts
+/** File extension of each output format, used in rendition URLs and storage keys. */
+const formatExtensions = {
+	avif: "avif",
+	webp: "webp",
+	jpeg: "jpg",
+	png: "png"
+};
+/** MIME type of each output format. */
+const formatContentTypes = {
+	avif: "image/avif",
+	webp: "image/webp",
+	jpeg: "image/jpeg",
+	png: "image/png"
+};
+/** Library-owned recipe version; bumping it regenerates every rendition of every application. */
+const RECIPE_ENGINE_VERSION = 1;
+/** Upper bound of a rendition side in physical pixels; WebP cannot encode larger sides. */
+const MAX_DIMENSION = 16383;
+const defaultSourcePolicy = {
+	svg: "rasterize",
+	orientation: "auto"
+};
+const animations = ["first-frame", "preserve"];
+const formats = [
+	"avif",
+	"webp",
+	"jpeg",
+	"png"
+];
+const fits = [
+	"cover",
+	"contain",
+	"fill",
+	"inside",
+	"outside"
+];
+const positions = [
+	"center",
+	"top",
+	"bottom",
+	"left",
+	"right",
+	"entropy",
+	"attention"
+];
+/** Encoder quality defaults; `png` is lossless and has no quality. */
+const defaultQuality = {
+	avif: 50,
+	webp: 80,
+	jpeg: 80
+};
+/** Accepted effort range and default per format; formats without an entry ignore effort. */
+const effortRange = {
+	avif: {
+		min: 0,
+		max: 9,
+		default: 4
+	},
+	webp: {
+		min: 0,
+		max: 6,
+		default: 4
+	}
+};
+/**
+* Builds the canonical recipe for transformation options at a density.
+*
+* @throws {RangeError} When an option is out of range or inconsistent.
+*/
+function normalizeRecipe({ options, density = 1, pipeline, policy, animation = "first-frame" }) {
+	assertInteger("pipeline", pipeline, 0, Number.MAX_SAFE_INTEGER);
+	if (!(Number.isFinite(density) && density > 0)) throw new RangeError(`Invalid density ${density}.`);
+	const format = options.format ?? "avif";
+	assertOneOf("format", format, formats);
+	assertOneOf("animation", animation, animations);
+	if (options.fit !== void 0) assertOneOf("fit", options.fit, fits);
+	if (options.position !== void 0) assertOneOf("position", options.position, positions);
+	const color = options.background === void 0 ? void 0 : normalizeColor(options.background);
+	if (options.quality !== void 0) assertInteger("quality", options.quality, 1, 100);
+	const range = effortRange[format];
+	if (options.effort !== void 0) assertInteger("effort", options.effort, range?.min ?? 0, range?.max ?? 9);
+	const width = scaleDimension("width", options.width, density);
+	const height = scaleDimension("height", options.height, density);
+	const resized = width !== void 0 || height !== void 0;
+	const fit = width !== void 0 && height !== void 0 ? options.fit ?? "cover" : void 0;
+	const position = fit === "cover" || fit === "contain" ? options.position ?? "center" : void 0;
+	if (fit === "contain" && (position === "entropy" || position === "attention")) throw new RangeError(`Position "${position}" applies to the "cover" fit only.`);
+	const flattened = format === "jpeg";
+	const background = fit === "contain" || flattened ? color ?? (flattened ? "#ffffffff" : "#00000000") : void 0;
+	return Object.freeze({
+		engine: 1,
+		pipeline,
+		width,
+		height,
+		fit,
+		position,
+		enlarge: resized ? options.enlarge ?? false : void 0,
+		background,
+		format,
+		quality: format === "png" ? void 0 : options.quality ?? defaultQuality[format],
+		effort: range ? options.effort ?? range.default : void 0,
+		svg: resolvePolicyValue("svg", policy, ["rasterize"]),
+		animation,
+		orientation: resolvePolicyValue("orientation", policy, ["auto"])
+	});
+}
+/** Serializes a recipe deterministically: sorted keys, no undefined fields, no whitespace. */
+function serializeRecipe(recipe) {
+	return JSON.stringify(Object.fromEntries(Object.entries(recipe).filter(([, value]) => value !== void 0).sort(([a], [b]) => a < b ? -1 : 1)));
+}
+function resolvePolicyValue(name, policy, allowed) {
+	const value = policy?.[name] ?? defaultSourcePolicy[name];
+	assertOneOf(name, value, allowed);
+	return value;
+}
+function scaleDimension(name, value, density) {
+	if (value === void 0) return;
+	assertInteger(name, value, 1, MAX_DIMENSION);
+	const scaled = Math.round(value * density);
+	assertInteger(`${name} at density ${density}`, scaled, 1, MAX_DIMENSION);
+	return scaled;
+}
+/** Expands a hex color to lowercase `#rrggbbaa`, so equivalent spellings hash equally. */
+function normalizeColor(color) {
+	const match = /^#([\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i.exec(color);
+	if (!match) throw new RangeError(`Invalid background color "${color}"; use a hex color.`);
+	const digits = match[1].toLowerCase();
+	const full = digits.length <= 4 ? [...digits].map((digit) => digit + digit).join("") : digits;
+	return `#${full.length === 6 ? `${full}ff` : full}`;
+}
+function assertOneOf(name, value, allowed) {
+	if (!allowed.includes(value)) throw new RangeError(`Invalid ${name} "${value}"; expected one of ${allowed.join(", ")}.`);
+}
+//#endregion
+export { normalizeRecipe as a, formatExtensions as i, RECIPE_ENGINE_VERSION as n, serializeRecipe as o, formatContentTypes as r, assertInteger as s, MAX_DIMENSION as t };

package/dist/s3.d.mts

@@ -0,0 +1,26 @@
+import { n as ResultStore, r as SourceStore } from "./stores-P-TUmax4.mjs";
+import { S3Client } from "@aws-sdk/client-s3";
+//#region src/stores/s3.d.ts
+/** Options of {@link createS3Source}. */
+export interface S3SourceOptions {
+  /** Client of AWS SDK v3, such as `S3Client` or the aggregated `S3`. */
+  client: Pick<S3Client, "send">;
+  bucket: string;
+  /** Largest source object, in bytes; larger sources fail as too large. */
+  maxBytes?: number;
+}
+/** Options of {@link createS3Results}. */
+export interface S3ResultsOptions {
+  /** Client of AWS SDK v3, such as `S3Client` or the aggregated `S3`. */
+  client: Pick<S3Client, "send">;
+  bucket: string;
+  /** Public URL of the bucket root, such as `https://storage.example.com/bucket`; objects must be publicly readable. */
+  publicUrl: string;
+  /** `Cache-Control` stored with each rendition; renditions never change, so they are immutable for a year by default. */
+  cacheControl?: string;
+}
+/** Creates a source store reading objects from an S3 bucket. */
+export declare function createS3Source({ client, bucket, maxBytes }: S3SourceOptions): SourceStore;
+/** Creates a result store writing objects to an S3 bucket that serves them publicly. */
+export declare function createS3Results({ client, bucket, publicUrl, cacheControl }: S3ResultsOptions): ResultStore;
+//#endregion

package/dist/s3.mjs

@@ -0,0 +1,81 @@
+import { t as encodePath } from "./path-hNFUjCbA.mjs";
+import { t as RenditionError } from "./error-DViVpVmH.mjs";
+import { GetObjectCommand, HeadObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
+//#region src/stores/s3.ts
+/** Longest S3 object key, in UTF-8 bytes. */
+const MAX_KEY_BYTES = 1024;
+const encoder = new TextEncoder();
+/** Creates a source store reading objects from an S3 bucket. */
+function createS3Source({ client, bucket, maxBytes = 52428800 }) {
+	return { async read(key, { signal }) {
+		if (!fitsKeyLimit(key)) return;
+		const controller = new AbortController();
+		const output = await client.send(new GetObjectCommand({
+			Bucket: bucket,
+			Key: key
+		}), { abortSignal: AbortSignal.any([signal, controller.signal]) }).catch(ignoreNotFound);
+		if (!output?.Body) return;
+		const tooLarge = new RenditionError("source-too-large", `The source ${key} exceeds ${maxBytes} bytes.`);
+		if ((output.ContentLength ?? 0) > maxBytes) {
+			controller.abort();
+			throw tooLarge;
+		}
+		const reader = output.Body.transformToWebStream().getReader();
+		const chunks = [];
+		let size = 0;
+		for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+			size += chunk.value.byteLength;
+			if (size > maxBytes) {
+				controller.abort();
+				reader.cancel().catch(() => {});
+				throw tooLarge;
+			}
+			chunks.push(chunk.value);
+		}
+		const data = new Uint8Array(size);
+		let offset = 0;
+		for (const chunk of chunks) {
+			data.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+		return data;
+	} };
+}
+/** Creates a result store writing objects to an S3 bucket that serves them publicly. */
+function createS3Results({ client, bucket, publicUrl, cacheControl = "public, max-age=31536000, immutable" }) {
+	return {
+		async exists(key, { signal }) {
+			assertKeyLimit(key);
+			return await client.send(new HeadObjectCommand({
+				Bucket: bucket,
+				Key: key
+			}), { abortSignal: signal }).catch(ignoreNotFound) !== void 0;
+		},
+		async write(key, { data, contentType }, { signal }) {
+			assertKeyLimit(key);
+			await client.send(new PutObjectCommand({
+				Bucket: bucket,
+				Key: key,
+				Body: data,
+				ContentType: contentType,
+				CacheControl: cacheControl
+			}), { abortSignal: signal });
+		},
+		url: (key) => `${publicUrl.replace(/\/$/, "")}/${encodePath(key)}`
+	};
+}
+/** Checks a key against the S3 limit, which counts UTF-8 bytes rather than characters. */
+function fitsKeyLimit(key) {
+	return encoder.encode(key).byteLength <= MAX_KEY_BYTES;
+}
+function assertKeyLimit(key) {
+	if (!fitsKeyLimit(key)) throw new RenditionError("invalid-request", `The key ${key} exceeds the S3 limit of ${MAX_KEY_BYTES} bytes.`);
+}
+function ignoreNotFound(error) {
+	const { name, $metadata } = error;
+	if (name === "NoSuchBucket") throw error;
+	if ($metadata?.httpStatusCode === 404 || name === "NoSuchKey" || name === "NotFound") return;
+	throw error;
+}
+//#endregion
+export { createS3Results, createS3Source };

package/dist/scopes-C1kzqQHz.mjs

@@ -0,0 +1,22 @@
+//#region src/scopes.ts
+/** Checks that a target has a scope the catalog declares; a catalog without scopes accepts any. */
+function isDeclaredScope(scopes, scope) {
+	return !scopes || scope !== void 0 && scopes.includes(scope);
+}
+/**
+* Throws a `RangeError` unless a target has a scope the catalog declares.
+*
+* @throws {RangeError} When the scope is missing or not declared.
+*/
+function assertDeclaredScope(scopes, scope) {
+	if (!isDeclaredScope(scopes, scope)) throw new RangeError(scope === void 0 ? "Missing rendition scope." : `Undeclared rendition scope "${scope}".`);
+}
+/** Target of a scope and a path, typed by the scopes of the catalog, or `undefined` when the catalog does not declare the scope. */
+function toDeclaredTarget(scopes, scope, path) {
+	return isDeclaredScope(scopes, scope) ? {
+		scope,
+		path
+	} : void 0;
+}
+//#endregion
+export { isDeclaredScope as n, toDeclaredTarget as r, assertDeclaredScope as t };

package/dist/server.d.mts

@@ -0,0 +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-9XP5SZhg.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 };

package/dist/server.mjs

@@ -0,0 +1,218 @@
+import { i as formatExtensions, s as assertInteger } from "./recipe-BavgOq0b.mjs";
+import { s as hashRecipe } from "./url-BAU5GYXC.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-CPJllrYi.mjs";
+//#region src/server/coordinator.ts
+/** Creates a coordinator that merges concurrent equal requests within the process. */
+function createLocalCoordinator() {
+	const running = /* @__PURE__ */ new Map();
+	return { run(key, task) {
+		const current = running.get(key);
+		if (current) return current;
+		const promise = task().finally(() => running.delete(key));
+		running.set(key, promise);
+		return promise;
+	} };
+}
+//#endregion
+//#region src/server/readiness.ts
+/**
+* Creates a process-local readiness index with least-recently-used eviction.
+*
+* @throws {RangeError} When `maxEntries` is not a non-negative integer.
+*/
+function createMemoryReadinessIndex({ maxEntries = 1e4 } = {}) {
+	assertInteger("maxEntries", maxEntries, 0, Number.MAX_SAFE_INTEGER);
+	const entries = /* @__PURE__ */ new Set();
+	return {
+		has(url) {
+			if (!entries.has(url)) return false;
+			entries.delete(url);
+			entries.add(url);
+			return true;
+		},
+		add(url) {
+			entries.delete(url);
+			entries.add(url);
+			if (entries.size > maxEntries) entries.delete(entries.values().next().value);
+		}
+	};
+}
+//#endregion
+//#region src/server/limiter.ts
+/** Creates a limiter with the given bounds. */
+function createLimiter({ concurrency, queueSize, queueTimeout }) {
+	let active = 0;
+	const waiting = [];
+	function release() {
+		const next = waiting.shift();
+		if (next) next();
+		else active--;
+	}
+	function acquire() {
+		if (active < concurrency) {
+			active++;
+			return Promise.resolve();
+		}
+		if (waiting.length >= queueSize) return Promise.reject(new RenditionError("overloaded", "The processing queue is full."));
+		return new Promise((resolve, reject) => {
+			const grant = () => {
+				clearTimeout(timer);
+				resolve();
+			};
+			const timer = setTimeout(() => {
+				waiting.splice(waiting.indexOf(grant), 1);
+				reject(new RenditionError("overloaded", "Timed out waiting for a processing slot."));
+			}, queueTimeout);
+			waiting.push(grant);
+		});
+	}
+	return { async run(task) {
+		await acquire();
+		try {
+			return await task();
+		} finally {
+			release();
+		}
+	} };
+}
+//#endregion
+//#region src/server/server.ts
+/** Longest delay of Node timers, in milliseconds. */
+const MAX_TIMEOUT = 2 ** 31 - 1;
+/**
+* Creates a rendition server over source and result stores.
+*
+* @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 memory = createMemoryReadinessIndex(options.readiness?.memory);
+	const shared = options.readiness?.shared;
+	const coordinator = options.coordinator ?? createLocalCoordinator();
+	const { concurrency = 2, queueSize = 100, queueTimeout = 3e4, storageTimeout = 15e3, indexTimeout = 1e3 } = options.limits ?? {};
+	assertInteger("limits.concurrency", concurrency, 1, Number.MAX_SAFE_INTEGER);
+	assertInteger("limits.queueSize", queueSize, 0, Number.MAX_SAFE_INTEGER);
+	assertInteger("limits.queueTimeout", queueTimeout, 1, MAX_TIMEOUT);
+	assertInteger("limits.storageTimeout", storageTimeout, 1, MAX_TIMEOUT);
+	assertInteger("limits.indexTimeout", indexTimeout, 1, MAX_TIMEOUT);
+	const limiter = createLimiter({
+		concurrency,
+		queueSize,
+		queueTimeout
+	});
+	for (const variant of catalog.allVariants) try {
+		processor.assertRecipe?.(variant.recipe);
+	} catch (error) {
+		throw error instanceof RangeError ? new RangeError(`The processor cannot render "${variant.label}": ${error.message}`, { cause: error }) : error;
+	}
+	async function resolve(target, context) {
+		if (!isDeclaredScope(catalog.scopes, target.scope)) throw new RenditionError("invalid-request", `The scope of the target ${describe(target)} is not declared.`);
+		const resolution = await resolveSource(target, context);
+		if (!resolution) throw new RenditionError("invalid-request", `The target ${describe(target)} is not served.`);
+		const { sourceKey } = resolution;
+		const resultPrefix = resolution.resultPrefix ?? sourceKey;
+		if (!isSafePath(sourceKey) || !isSafePath(resultPrefix)) throw createUnsafeKeyError(target);
+		return {
+			sourceKey,
+			resultPrefix
+		};
+	}
+	async function locate(hash, format, target, context) {
+		const { sourceKey, resultPrefix } = await resolve(target, context);
+		const key = `${resultPrefix}/${hash}.${formatExtensions[format]}`;
+		if (!isSafePath(key)) throw createUnsafeKeyError(target);
+		return {
+			sourceKey,
+			rendition: {
+				key,
+				url: results.url(key)
+			}
+		};
+	}
+	async function isIndexed(url) {
+		if (memory.has(url)) return true;
+		const found = await callShared((signal) => shared?.has(url, { signal }));
+		if (found) memory.add(url);
+		return found === true;
+	}
+	async function markPublished(url) {
+		memory.add(url);
+		await callShared((signal) => shared?.add(url, { signal }));
+	}
+	/** Calls the shared index, reporting its failures, synchronous ones and timeouts included, instead of failing the operation. */
+	async function callShared(call) {
+		if (!shared) return;
+		try {
+			return await withTimeout(indexTimeout, call);
+		} catch (error) {
+			report(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) => {
+			throw error instanceof RenditionError ? error : new RenditionError("processing-failed", `Processing failed: ${error}`, { cause: error });
+		});
+		await callStorage("storage-error", (signal) => results.write(key, image, { signal }));
+	}
+	return {
+		catalog,
+		async ensure(input, target, context) {
+			const recipe = Object.freeze({ ...input });
+			processor.assertRecipe?.(recipe);
+			const { sourceKey, rendition } = await locate(hashRecipe(recipe), recipe.format, target, context);
+			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));
+					await markPublished(rendition.url);
+				}
+				return rendition;
+			});
+		},
+		async findPublished(hash, format, target, context) {
+			const { rendition } = await locate(hash, format, target, context);
+			return await isIndexed(rendition.url) ? rendition : void 0;
+		},
+		resolve
+	};
+}
+/**
+* Runs a call with an abort signal that fires after the timeout.
+*
+* The call may ignore the signal, so the timeout also settles the result, keeping a hung call from holding the request or a processing slot.
+*/
+function withTimeout(timeout, call) {
+	const signal = AbortSignal.timeout(timeout);
+	const expired = new Promise((_, reject) => {
+		signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+	});
+	return Promise.race([new Promise((resolve) => resolve(call(signal))), expired]);
+}
+function resolveUnscoped({ scope, path }) {
+	return scope === void 0 ? { sourceKey: path } : void 0;
+}
+function describe({ scope, path }) {
+	return scope === void 0 ? path : `${scope}:${path}`;
+}
+function createUnsafeKeyError(target) {
+	return new RenditionError("invalid-request", `The target ${describe(target)} resolves to an unsafe key.`);
+}
+//#endregion
+export { RenditionError, createLocalCoordinator, createMemoryReadinessIndex, createRenditionHandler, createRenditionServer };

package/dist/sharp.d.mts

@@ -0,0 +1,22 @@
+import { t as Processor } from "./processor-DvyPs-OZ.mjs";
+//#region src/processors/sharp/processor.d.ts
+/** Options of {@link createSharpProcessor}. */
+export interface SharpProcessorOptions {
+  /** Largest decoded source, in pixels; larger sources fail as too large, and `0` removes the limit. */
+  maxInputPixels?: number;
+  /**
+   * Largest animation a recipe keeps, in pixels of all its frames at the larger of the source and the rendition size; `0` removes the limit.
+   *
+   * A larger animation renders its first frame.
+   */
+  maxAnimationPixels?: number;
+  /** Most frames of an animation a recipe keeps; an animation with more renders its first frame, and `0` removes the limit. */
+  maxFrames?: number;
+}
+/**
+ * Creates a processor backed by sharp and libvips.
+ *
+ * @throws {RangeError} When a limit is not a non-negative integer.
+ */
+export declare function createSharpProcessor({ maxInputPixels, maxAnimationPixels, maxFrames }?: SharpProcessorOptions): Processor;
+//#endregion