image-renditions 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Semenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,444 @@
-# Temporary Holding Version
+# image-renditions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Resize and re-encode uploaded images when a page first shows them, store each result in your S3 bucket or a directory, and serve it from there.
+
+```vue
+<RenditionImg preset="avatar" src="avatars/42.jpg" alt="" />
+```
+
+```html
+<img
+  src="/_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg"
+  srcset="
+    /_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg    1x,
+    /_renditions/v1/avatar@2x.b62b90cf6c3ed57e4c1c27da0c36d778.avif/avatars/42.jpg 2x
+  "
+  alt=""
+/>
+```
+
+- The first request for such a URL renders a 48×48 AVIF from `avatars/42.jpg`, writes it to storage, and redirects the browser to the stored file.
+- Later requests redirect at once, and your bucket or CDN serves the image.
+- Changing the `avatar` preset gives it new URLs, so no browser or CDN keeps showing the old version.
+
+With an S3 bucket, or a directory that outlives deploys and is shared by every replica, app servers keep no image files: renditions survive redeploys, and any replica serves any of them.
+
+The h3 handler supports h3 1.15 or newer and h3 2, and the Nuxt module requires Nuxt 4.
+
+## 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.
+
+## Quick start
+
+This example sets up image-renditions in a Nuxt app.
+
+```sh
+npm install image-renditions sharp
+```
+
+`sharp` is needed by the built-in [processor](#processing).
+
+Define presets in a catalog.
+Both the app and the server import it, so it must import nothing but `image-renditions`:
+
+```ts
+// shared/renditions.ts
+import { defineCatalog } from "image-renditions"
+
+export default defineCatalog({
+  presets: {
+    // 48×48 for regular screens and 96×96 for high-density ones.
+    avatar: { width: 48, height: 48, densities: [1, 2] },
+    cover: { width: 800, height: 200 },
+  },
+})
+```
+
+Create a handler for rendition URLs, for example one that reads uploads from the `uploads` bucket and writes renditions to the public `renditions` bucket:
+
+```ts
+// server/renditions.ts
+import { S3 } from "@aws-sdk/client-s3"
+import { defineRenditionEventHandler } from "image-renditions/h3"
+import { createS3Results, createS3Source } from "image-renditions/s3"
+import { createRenditionServer } from "image-renditions/server"
+import { createSharpProcessor } from "image-renditions/sharp"
+
+import catalog from "#shared/renditions"
+
+const client = new S3({ region: "us-east-1" })
+
+const server = createRenditionServer({
+  source: createS3Source({ client, bucket: "uploads" }),
+  results: createS3Results({
+    client,
+    bucket: "renditions",
+    publicUrl: "https://renditions.example.com",
+  }),
+  processor: createSharpProcessor(),
+})
+
+export default defineRenditionEventHandler({ catalog, server })
+```
+
+A rendition of `avatars/42.jpg` is stored in `renditions` at `avatars/42.jpg/<hash>.avif`, and `publicUrl` is where browsers load it from.
+
+Register the catalog and the handler:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["image-renditions/nuxt"],
+  renditions: {
+    catalog: "#shared/renditions",
+    handler: "~~/server/renditions",
+  },
+})
+```
+
+Show images:
+
+```vue
+<!-- app/components/UserAvatar.vue -->
+<template>
+  <RenditionImg preset="avatar" :src="user.avatarPath" alt="" />
+</template>
+```
+
+`user.avatarPath` is the key of the upload in its bucket, such as `avatars/42.jpg`.
+Preset names are type-checked against the catalog.
+
+## Presets
+
+Options of a preset, or of `defaults`, which every preset overrides field by field:
+
+- `width`, `height` — size in CSS pixels at density 1; with one side set, the other keeps the aspect ratio.
+- `fit` — how the image fills the box when both sides are set:
+  - `cover` (default) crops what overflows the box.
+  - `contain` letterboxes the image inside the box.
+  - `fill` stretches the image to the box.
+  - `inside` and `outside` keep the aspect ratio, so one side of the output is smaller or larger than the box.
+- `position` — `center` (default), `top`, `bottom`, `left`, `right`, or content-aware `entropy` and `attention` for `cover`.
+- `enlarge` — upscale sources smaller than the target; otherwise they keep their size.
+- `background` — hex color for `contain` letterboxing, transparent by default, and for flattening transparency into JPEG, white by default.
+- `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.
+
+Options of the catalog:
+
+- `basePath` — path the handler is mounted at, `/_renditions` by default.
+- `pipelineVersion` — bump it to render every image again, for example after switching to another processor.
+
+Changing an option that affects the output gives the images of the preset new URLs, and they are rendered again on their first request.
+Renaming a preset keeps its stored renditions.
+
+## Showing images
+
+`<RenditionImg>` renders `src`, and a `srcset` when the preset has several densities.
+
+- It also renders `width` and `height` when the image always has the preset size: with `contain`, or with `cover` and `fill` when `enlarge` is set.
+  Otherwise a small source keeps its own size, so size such images with CSS.
+- A `src` that is already a URL, such as `blob:` or `https:`, renders unchanged, for example a preview of a file being uploaded.
+- A path no rendition URL can address, such as one with a `..` segment, renders no `src` instead of breaking the page.
+
+`useRenditions()` builds the same URLs in code, prefixed with `app.baseURL`:
+
+```ts
+const renditions = useRenditions()
+
+renditions.url("cover", post.coverPath)
+renditions.url("avatar", path, { density: 2 })
+renditions.srcset("avatar", path)
+renditions.attrs("avatar", path) // attributes <RenditionImg> renders, for your own img element
+```
+
+Module options, under `renditions`:
+
+- `catalog` — module exporting the catalog by default; required.
+- `handler` — optional module exporting the h3 handler by default, mounted at the catalog base path.
+- `defaultScope` — optional [scope](#scopes) for `<RenditionImg>` and `useRenditions()`.
+
+> For users coming from `@nuxt/image`: this module is not an `@nuxt/image` provider, so instead of `<NuxtImg>` and `useImage()`, use `<RenditionImg>` and `useRenditions()` with catalog presets.
+
+## Scopes
+
+The path an app stores for an upload, such as `avatars/42.jpg`, is often not its storage key.
+Each tenant may keep its uploads under its own prefix, and some files may be shared by all tenants, so the same path can mean different files.
+
+Scopes and `resolveSource` let the server decide where a path lives:
+
+- The scope tells which space a path belongs to, such as `tenant` or `shared`.
+  One page may show images of several spaces, so each URL carries its scope.
+- The context holds what the request determines, such as the current tenant; `getContext` derives it from the request, so a client cannot change it by editing a URL.
+- `resolveSource` maps the scope, the path and the context to storage keys, or rejects them.
+
+Without `resolveSource`, an unscoped path is the key itself, and scoped paths are rejected.
+
+For example, with uploads of several tenants and files shared between them:
+
+```ts
+// server/renditions.ts
+const server = createRenditionServer<{ tenant: string }>({
+  // source, results and processor as in the quick start
+  resolveSource({ scope, path }, { tenant }) {
+    if (scope === "tenant") {
+      return { sourceKey: `tenants/${tenant}/${path}` }
+    }
+    if (scope === "shared") {
+      return { sourceKey: `shared/${path}` }
+    }
+    return undefined
+  },
+})
+
+export default defineRenditionEventHandler({
+  catalog,
+  server,
+  // findTenant() is your lookup, for example by host.
+  getContext: async event => ({ tenant: await findTenant(event) }),
+})
+```
+
+- If `resolveSource` returns `undefined`, the request fails with `404`.
+- `resolveSource` receives unscoped paths too, with an undefined `scope`.
+- Map different scopes to different keys even for equal paths.
+- A rendition is stored in the result store at `<sourceKey>/<hash>.<extension>`.
+  To keep renditions in the bucket of uploads, also return a `resultPrefix` that no source key starts with, such as `` `renditions/${sourceKey}` ``, to use instead of `sourceKey`.
+- S3 limits a key to 1024 bytes in UTF-8, and a rendition key adds up to 38 bytes to its result prefix.
+  If source keys can come that close to the limit, return a shorter `resultPrefix`, or their renditions fail as `invalid-request`.
+
+Derive the context from the URL only, host included, for example from the tenant's domain: browsers and CDNs cache the redirect to a rendition by its URL for a day.
+If the context depends on cookies or a session, pass `redirectCacheControl: "no-store"` to `defineRenditionEventHandler()`, or one tenant may get the rendition of another.
+
+With the Nuxt module, `defaultScope: "tenant"` makes `tenant` the scope of every image, and `scope` selects another one:
+
+```vue
+<RenditionImg preset="cover" :src="template.coverPath" scope="shared" alt="" />
+```
+
+## Storage
+
+The server reads sources from a source store and writes renditions to a result store, which may be of different kinds.
+Both source stores fail sources larger than 50 MiB as unsupported; pass `maxBytes` to `createS3Source()` or `createFileSystemSource()` to change the limit.
+
+### S3 storage
+
+To keep uploads and renditions in S3 buckets, use the stores of `image-renditions/s3`:
+
+```ts
+// server/renditions.ts
+import { S3 } from "@aws-sdk/client-s3"
+import { createS3Results, createS3Source } from "image-renditions/s3"
+
+const client = new S3({ region: "us-east-1" })
+
+const server = createRenditionServer({
+  source: createS3Source({ client, bucket: "uploads" }),
+  results: createS3Results({
+    client,
+    bucket: "renditions",
+    publicUrl: "https://renditions.example.com",
+  }),
+  processor: createSharpProcessor(),
+})
+```
+
+The stores take the aggregated `S3` client of AWS SDK v3 or any object with its `getObject`, `headObject` and `putObject` methods.
+`createS3Results()` writes renditions with `Cache-Control: public, max-age=31536000, immutable`; pass it `cacheControl` to change the header.
+The bucket of renditions must serve them publicly at `publicUrl`, directly or through a CDN.
+
+### File storage
+
+To keep uploads and renditions on a disk served by a web server, use the stores of `image-renditions/fs`:
+
+```ts
+// server/renditions.ts
+import { createFileSystemResults, createFileSystemSource } from "image-renditions/fs"
+
+const server = createRenditionServer({
+  source: createFileSystemSource({ root: "/data/uploads" }),
+  results: createFileSystemResults({ root: "/data/renditions", publicUrl: "/renditions" }),
+  processor: createSharpProcessor(),
+})
+```
+
+```nginx
+location /renditions/ {
+  alias /data/renditions/;
+  add_header Cache-Control "public, max-age=31536000, immutable";
+}
+```
+
+## Processing
+
+`createSharpProcessor()` from `image-renditions/sharp` processes images with [sharp](https://sharp.pixelplumbing.com).
+Sources over 100 megapixels fail as unsupported; pass `maxInputPixels` to `createSharpProcessor()` to change the limit.
+A source that a preset would scale beyond 16383 pixels on a side, such as a narrow strip enlarged to the preset width, is scaled less to stay within that limit, so its rendition is smaller than the preset sets.
+Under `cover`, such a source is cropped instead, and its rendition keeps the preset size.
+
+To process images with another library, implement the [`Processor`](#extending) interface and pass your implementation to `createRenditionServer()` as `processor`.
+
+## h3 and other frameworks
+
+The handler from the quick start is a regular h3 event handler.
+Mount it at `<basePath>/**`, `/_renditions/**` by default:
+
+```ts
+// server.ts
+import { H3, serve } from "h3"
+
+import renditions from "./renditions"
+
+serve(new H3().all("/_renditions/**", renditions))
+```
+
+With h3 v1, add it to a router: `createRouter().use("/_renditions/**", renditions)`.
+
+For other frameworks, use `createRenditionHandler()` from `image-renditions/server`.
+It takes the same options without `getContext` and returns a function from the request and a function returning the context to a `Response`, for example in a fetch handler:
+
+```ts
+// server.ts
+import { createRenditionHandler } from "image-renditions/server"
+
+const renditions = createRenditionHandler({ catalog, server })
+
+export default {
+  fetch(request: Request) {
+    const { pathname, search } = new URL(request.url)
+    // The second argument returns the context resolveSource receives, such as the current tenant.
+    return renditions({ method: request.method, path: pathname + search }, () => undefined)
+  },
+}
+```
+
+Build URLs in the app with the catalog, which is safe to import in browsers:
+
+```ts
+catalog.url("avatar", { path: "avatars/42.jpg" })
+// /_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg
+
+catalog.srcset("avatar", { scope: "tenant", path: "avatars/42.jpg" })
+```
+
+## Rendering outside requests
+
+`server.ensure()` publishes one density of a preset without a request, for example right after an upload:
+
+```ts
+for (const { recipe } of catalog.variants("avatar")) {
+  await server.ensure(recipe, { scope: "tenant", path: "avatars/42.jpg" }, { tenant: "acme" })
+}
+```
+
+It resolves to the key and public URL of the rendition after it is written or found in storage.
+
+## How a request is served
+
+```text
+/_renditions/v1/[<scope>/]<preset>.<hash>.<extension>/<path>
+```
+
+The hash identifies the preset options at one density, and the preset name only labels the URL.
+The handler looks up the hash in the catalog, resolves the source, and then:
+
+1. If the process or a shared readiness index remembers the rendition, it redirects right away.
+2. Otherwise it checks storage and redirects if the rendition is there.
+3. Otherwise it reads the source, renders it, writes the result, and redirects.
+
+Within a process, equal concurrent requests are rendered once.
+Replicas without a shared `coordinator` may each render the same rendition and write equal files under its key.
+
+The redirect is a `307` with `Cache-Control: public, max-age=86400`, so browsers and CDNs remember it for a day.
+It points to the storage URL built from `publicUrl`, and a cached redirect cannot be revoked: after you move renditions to another domain, clients follow the old redirects until they expire.
+If `publicUrl` never changes, pass a longer `redirectCacheControl` to `defineRenditionEventHandler()`.
+
+## Concurrency and timeouts
+
+Rendering takes the CPU and memory of the app process, so the `limits` option of `createRenditionServer()` bounds it per process:
+
+- `concurrency` — renditions processed at once, 2 by default.
+- `queueSize` — renditions waiting for a slot, 100 by default.
+- `queueTimeout` — milliseconds a rendition may wait for a slot, 30 seconds by default.
+- `storageTimeout` — milliseconds a storage call may take, 15 seconds by default.
+- `indexTimeout` — milliseconds a shared readiness index call may take, 1 second by default.
+
+Requests beyond the queue, or waiting too long, fail as `overloaded`.
+Processing itself has no timeout, because a timeout could not stop the processor and free its slot.
+
+These limits bound image processing, not HTTP request rates.
+Requests for renditions missing from the readiness indexes check result storage, even when the source does not exist.
+On a public site, rate-limit requests per client at the CDN or reverse proxy.
+
+## Errors
+
+The handler responds to a failure with the status of its reason:
+
+- `invalid-request` (404): malformed URL, `resolveSource` rejected the target, or a key is unsafe or too long for the store
+- `unknown-recipe` (404): hash neither in the catalog nor known as published
+- `source-not-found` (404): no source under the resolved key
+- `unsupported-source` (422): source cannot be decoded or rendered, or exceeds a size limit
+- `source-error` (502): reading the source failed
+- `processing-failed` (500): processing failed for a reason other than the source
+- `storage-error` (502): checking for or writing the rendition failed
+- `overloaded` (503): processing queue is full or the wait timed out
+
+### Outdated URLs
+
+A page rendered before a preset changed keeps requesting the old hash, which the catalog no longer has.
+The handler serves it while the process or a shared readiness index remembers its rendition.
+Otherwise the request fails as `unknown-recipe` without calling the stores, so made-up hashes cause no storage traffic either.
+
+### Custom responses
+
+`onFailure` can report a failure or replace the response, for example with the original image:
+
+```ts
+export default defineRenditionEventHandler({
+  catalog,
+  server,
+  getContext,
+  onFailure({ reason, error, address, context }) {
+    if (reason === "storage-error" || reason === "processing-failed") {
+      reportError(error)
+    }
+    if (reason === "unknown-recipe" && address) {
+      // originalUrl() is your absolute URL of the uploaded file at the scope and path of the address.
+      return Response.redirect(originalUrl(address, context), 302)
+    }
+    return undefined
+  },
+})
+```
+
+Returning `undefined` keeps the default response.
+Every failure response, including a replaced one, is sent with `Cache-Control: no-store`.
+
+## Extending
+
+Implement an interface from `image-renditions/server` and pass your implementation to `createRenditionServer()`:
+
+- 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`.
+- 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`.
+  Bound the wait for the lock, because the server sets no timeout on it.
+
+The built-in stores and processor implement the same interfaces and serve as examples.
+
+## Limitations
+
+- Renditions are public, and anyone who knows a path that `resolveSource` serves can get its renditions.
+  Keep private images out of what `resolveSource` maps, for example by serving only the folders of public images.
+- A source must never change under its key: renditions of a replaced source keep showing the old image.
+  Store new content under a new key.
+- Deleting a source leaves its renditions in storage under its result prefix.
+- Animated sources render their first frame, SVG sources are rasterized at the target size, and EXIF orientation is applied.
+- Source paths are limited to 1024 characters.

package/dist/catalog-CSnosQ1L.d.mts

@@ -0,0 +1,64 @@
+import { l as SourcePolicy, r as Recipe, s as RenditionOptions } from "./recipe-Je9DxqO1.mjs";
+//#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]`. */
+  densities?: readonly number[];
+}
+/** Shared configuration of renditions, imported by both the client and the server. */
+interface CatalogDefinition<Name extends string = string> {
+  /** Path the rendition handler is mounted at, `/_renditions` by default. */
+  basePath?: string;
+  /** Bumping it gives every variant a new hash, so every rendition is generated again. */
+  pipelineVersion?: number;
+  /** Options of every preset; a preset overrides them field by field. */
+  defaults?: PresetDefinition;
+  /** How special kinds of sources are rendered. */
+  sources?: Partial<SourcePolicy>;
+  presets: Record<Name, PresetDefinition>;
+}
+/** One density of a preset, which is a separate recipe with its own hash. */
+interface RenditionVariant {
+  readonly preset: string;
+  readonly density: number;
+  /** Readable URL label, such as `avatar` or `avatar@2x`. */
+  readonly label: string;
+  readonly recipe: Recipe;
+  readonly hash: string;
+}
+/** Source a rendition is made from. */
+interface RenditionTarget {
+  /** Application-defined space of the path, such as a tenant; omitted when the application has one space. */
+  scope?: string;
+  /** Logical source path inside the scope. */
+  path: string;
+}
+/** Validated catalog with its variants and URL builders. */
+interface Catalog<Name extends string = string> {
+  readonly basePath: string;
+  readonly presets: readonly Name[];
+  /** Variants of a preset ordered by density. */
+  variants(preset: Name): readonly RenditionVariant[];
+  /**
+   * Variant of a preset at a density, `1` by default.
+   *
+   * @throws {RangeError} When the preset does not declare the density.
+   */
+  variant(preset: Name, density?: number): RenditionVariant;
+  /** Variant with a recipe hash, if the catalog has one. */
+  findVariant(hash: string): RenditionVariant | undefined;
+  /** Root-relative URL of a rendition. */
+  url(preset: Name, target: RenditionTarget, density?: number): string;
+  /** `srcset` attribute value listing every density of a preset. */
+  srcset(preset: Name, target: RenditionTarget): string;
+}
+/**
+ * Validates a catalog and computes the recipe and hash of every preset density.
+ *
+ * Preset names are only labels: renaming a preset keeps its hashes and thus its stored renditions.
+ *
+ * @throws {RangeError} When the catalog is invalid.
+ */
+declare function defineCatalog<const Name extends string>(definition: CatalogDefinition<Name>): Catalog<Name>;
+//#endregion
+export { RenditionVariant as a, RenditionTarget as i, CatalogDefinition as n, defineCatalog as o, PresetDefinition as r, Catalog as t };

package/dist/error-DViVpVmH.mjs

@@ -0,0 +1,12 @@
+//#region src/server/error.ts
+/** Failure of a rendition operation, with a reason a failure policy can tell apart. */
+var RenditionError = class extends Error {
+	reason;
+	name = "RenditionError";
+	constructor(reason, message = reason, options) {
+		super(message, options);
+		this.reason = reason;
+	}
+};
+//#endregion
+export { RenditionError as t };

package/dist/fs.d.mts

@@ -0,0 +1,25 @@
+import { n as ResultStore, r as SourceStore } from "./stores-DFDRMZcC.mjs";
+//#region src/stores/fs.d.ts
+/** Options of {@link createFileSystemSource}. */
+export interface FileSystemSourceOptions {
+  /** Directory source keys are resolved in. */
+  root: string;
+  /** Largest source file, in bytes; larger sources are unsupported. */
+  maxBytes?: number;
+}
+/** Options of {@link createFileSystemResults}. */
+export interface FileSystemResultsOptions {
+  /** Directory renditions are written to. */
+  root: string;
+  /**
+   * URL the directory is served at, such as `https://cdn.example.com/renditions` or `/renditions`.
+   *
+   * The web server in front of it sets `Cache-Control`; renditions never change, so it can mark them immutable.
+   */
+  publicUrl: string;
+}
+/** Creates a source store reading files from a directory. */
+export declare function createFileSystemSource({ root, maxBytes }: FileSystemSourceOptions): SourceStore;
+/** Creates a result store writing files to a directory that a web server serves. */
+export declare function createFileSystemResults({ root, publicUrl }: FileSystemResultsOptions): ResultStore;
+//#endregion

package/dist/fs.mjs

@@ -0,0 +1,50 @@
+import { n as isSafePath, t as encodePath } from "./path-hNFUjCbA.mjs";
+import { t as RenditionError } from "./error-DViVpVmH.mjs";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+//#region src/stores/fs.ts
+/** Creates a source store reading files from a directory. */
+function createFileSystemSource({ root, maxBytes = 52428800 }) {
+	return { async read(key, { signal }) {
+		const path = resolvePath(root, key);
+		const stats = await stat(path).catch(ignoreMissing);
+		if (!stats?.isFile()) return;
+		if (stats.size > maxBytes) throw new RenditionError("unsupported-source", `The source ${key} exceeds ${maxBytes} bytes.`);
+		return new Uint8Array(await readFile(path, { signal }));
+	} };
+}
+/** Creates a result store writing files to a directory that a web server serves. */
+function createFileSystemResults({ root, publicUrl }) {
+	return {
+		async exists(key) {
+			return (await stat(resolvePath(root, key)).catch(ignoreMissing))?.isFile() ?? false;
+		},
+		async write(key, { data }, { signal }) {
+			const path = resolvePath(root, key);
+			await mkdir(dirname(path), { recursive: true });
+			const temporary = `${path}.${randomUUID()}.tmp`;
+			try {
+				await writeFile(temporary, data, { signal });
+				await rename(temporary, path);
+			} catch (error) {
+				await rm(temporary, { force: true });
+				throw error;
+			}
+		},
+		url: (key) => `${publicUrl.replace(/\/$/, "")}/${encodePath(key)}`
+	};
+}
+function resolvePath(root, key) {
+	const base = resolve(root);
+	const path = resolve(base, key);
+	const prefix = base.endsWith(sep) ? base : base + sep;
+	if (!isSafePath(key) || !path.startsWith(prefix)) throw new RenditionError("invalid-request", `Unsafe storage key ${key}.`);
+	return path;
+}
+function ignoreMissing(error) {
+	if (error.code === "ENOENT" || error.code === "ENOTDIR") return;
+	throw error;
+}
+//#endregion
+export { createFileSystemResults, createFileSystemSource };

package/dist/h3.d.mts

@@ -0,0 +1,27 @@
+import { r as RenditionHandlerOptions } from "./handler-BFV_vIr4.mjs";
+import { EventHandler, H3Event } from "h3";
+//#region src/h3.d.ts
+/** Source of the application context of a request. */
+interface ContextOptions<Context> {
+  /**
+   * Derives the application context, such as a tenant, from the request event.
+   *
+   * Caches reuse a redirect for every request of its URL, so derive the context from the URL and host only, or set `redirectCacheControl` to `no-store`.
+   * It is skipped for unsupported methods and for malformed URLs unless `onFailure` needs the context.
+   */
+  getContext(event: H3Event): Context | Promise<Context>;
+}
+/**
+ * Options of {@link defineRenditionEventHandler}.
+ *
+ * `getContext` may be omitted when the server accepts an `undefined` context.
+ */
+export type RenditionEventHandlerOptions<Context> = RenditionHandlerOptions<Context> & (undefined extends Context ? Partial<ContextOptions<Context>> : ContextOptions<Context>);
+/**
+ * Defines an h3 event handler serving rendition URLs, for h3 v1 and v2.
+ *
+ * Mount it at the catalog base path with a catch-all route, such as `/_renditions/**`.
+ */
+export declare function defineRenditionEventHandler<Context>(options: RenditionEventHandlerOptions<Context>): EventHandler;
+//#endregion
+export {};

package/dist/h3.mjs

@@ -0,0 +1,25 @@
+import { t as createRenditionHandler } from "./handler-BHMwNZnI.mjs";
+import { defineEventHandler } from "h3";
+//#region src/h3.ts
+/**
+* Defines an h3 event handler serving rendition URLs, for h3 v1 and v2.
+*
+* Mount it at the catalog base path with a catch-all route, such as `/_renditions/**`.
+*/
+function defineRenditionEventHandler(options) {
+	const handler = createRenditionHandler(options);
+	const getContext = options.getContext;
+	return defineEventHandler((event) => handler(readRequest(event), () => getContext?.(event)));
+}
+function readRequest(event) {
+	if (event.url instanceof URL) return {
+		method: event.req.method,
+		path: event.url.pathname + event.url.search
+	};
+	return {
+		method: event.method,
+		path: event.path
+	};
+}
+//#endregion
+export { defineRenditionEventHandler };