@zerotal/media 1.3.0

package/src/conversions/PerformConversionsJob.ts

@@ -0,0 +1,45 @@
+import { Job } from "@zerotal/queue";
+import { performConversions } from "./queueBridge.ts";
+import { mediaState } from "../state.ts";
+
+/**
+ * Generates a media item's conversions on a worker instead of in the request.
+ *
+ * Only reachable when `@zerotal/queue` is installed — `MediaProvider` imports
+ * this module lazily, inside the branch that has already found a `queue`
+ * binding. Apps without a queue generate every conversion inline and never load
+ * this file.
+ */
+export class PerformConversionsJob extends Job {
+  override readonly queue: string;
+
+  constructor(
+    readonly mediaId: number,
+    readonly conversions: string[],
+    queue?: string,
+  ) {
+    super();
+    this.queue = queue ?? mediaState().config.queue;
+  }
+
+  override payload(): Record<string, unknown> {
+    return { mediaId: this.mediaId, conversions: this.conversions, queue: this.queue };
+  }
+
+  static fromPayload(payload: Record<string, unknown>): PerformConversionsJob {
+    return new PerformConversionsJob(
+      Number(payload["mediaId"]),
+      (payload["conversions"] as string[] | undefined) ?? [],
+      payload["queue"] as string | undefined,
+    );
+  }
+
+  /**
+   * A media row deleted between dispatch and execution makes this a no-op, not a
+   * failure: retrying cannot bring the row back, so throwing would just burn
+   * every attempt before landing in the failed queue for no one to act on.
+   */
+  async handle(): Promise<void> {
+    await performConversions(this.mediaId, this.conversions);
+  }
+}

package/src/conversions/SharpImageDriver.ts

@@ -0,0 +1,174 @@
+import {
+  FORMAT_MIME,
+  type ImageDriver,
+  type ImageManipulation,
+  type ImageMetadata,
+  type ImageResult,
+} from "./ImageDriver.ts";
+import { MediaError } from "../errors.ts";
+import type { ConversionFormat } from "../types.ts";
+
+// ── Minimal structural view of sharp ──────────────────────────────────────────
+// `sharp` is an optional peer: apps that never crop never install it, so we
+// cannot import its types. This is only the slice this driver uses.
+
+interface SharpPipeline {
+  rotate(degrees?: number): SharpPipeline;
+  resize(options: {
+    width?: number;
+    height?: number;
+    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+    withoutEnlargement?: boolean;
+  }): SharpPipeline;
+  jpeg(options?: { quality?: number }): SharpPipeline;
+  png(options?: { quality?: number }): SharpPipeline;
+  webp(options?: { quality?: number }): SharpPipeline;
+  avif(options?: { quality?: number }): SharpPipeline;
+  heif(options?: { quality?: number; compression?: string }): SharpPipeline;
+  metadata(): Promise<{ width?: number; height?: number; format?: string }>;
+  toBuffer(options: { resolveWithObject: true }): Promise<{
+    data: Uint8Array;
+    info: { width: number; height: number };
+  }>;
+}
+
+type SharpFactory = (input: Uint8Array) => SharpPipeline;
+
+let _sharp: SharpFactory | null = null;
+
+/**
+ * Load `sharp` once, with an error that says what to install if it is absent.
+ *
+ * The specifier goes through a variable so the compiler does not try to resolve
+ * it: `sharp` is genuinely optional, and a literal `import("sharp")` would fail
+ * `tsc` in every app that has not installed it — including all the ones using
+ * the default driver, which is most of them.
+ */
+async function loadSharp(): Promise<SharpFactory> {
+  if (_sharp) return _sharp;
+  const specifier = "sharp";
+  try {
+    const module = (await import(specifier)) as {
+      default?: SharpFactory;
+    } & SharpFactory;
+    _sharp = module.default ?? module;
+    return _sharp;
+  } catch {
+    throw new MediaError(
+      'config/media.ts sets driver: "sharp" but the sharp package is not installed.\n' +
+        "Fix: `bun add sharp`, or switch back to the built-in driver with " +
+        'driver: "bun" (which cannot crop — see fit: "cover").',
+    );
+  }
+}
+
+/**
+ * Image processing on `sharp`, for apps that need what `Bun.Image` does not do —
+ * principally `fit: "cover"`, the centre-crop behind every square thumbnail.
+ *
+ * Opt in by installing `sharp` and setting `driver: "sharp"` in `config/media.ts`.
+ * `sharp` builds against Node-API v9, which Bun implements, so it runs here; it
+ * is a native module, so it does add an install step and a platform-specific
+ * binary, which is exactly why it is not the default.
+ */
+export class SharpImageDriver implements ImageDriver {
+  readonly name = "SharpImageDriver";
+  readonly supportsCrop = true;
+
+  async metadata(bytes: Uint8Array): Promise<ImageMetadata | null> {
+    try {
+      const sharp = await loadSharp();
+      const meta = await sharp(bytes).metadata();
+      if (meta.width === undefined || meta.height === undefined) return null;
+      return { width: meta.width, height: meta.height, format: meta.format ?? "unknown" };
+    } catch {
+      return null;
+    }
+  }
+
+  async convert(bytes: Uint8Array, manipulation: ImageManipulation): Promise<ImageResult> {
+    const { width, height, fit = "inside", format, quality, rotate } = manipulation;
+    const sharp = await loadSharp();
+
+    let pipeline = sharp(bytes);
+
+    if (rotate !== undefined && rotate !== 0) pipeline = pipeline.rotate(rotate);
+
+    if (width !== undefined || height !== undefined) {
+      pipeline = pipeline.resize({
+        ...(width !== undefined ? { width } : {}),
+        ...(height !== undefined ? { height } : {}),
+        fit,
+        withoutEnlargement: manipulation.withoutEnlargement ?? true,
+      });
+    }
+
+    pipeline = _applyFormat(pipeline, format, quality);
+
+    const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+
+    return {
+      bytes: data,
+      width: info.width,
+      height: info.height,
+      format,
+      mimeType: FORMAT_MIME[format],
+    };
+  }
+
+  async placeholder(bytes: Uint8Array): Promise<string | null> {
+    try {
+      const sharp = await loadSharp();
+      // No ThumbHash in sharp, so a tiny blurred WebP stands in. Larger than
+      // Bun.Image's placeholder, and still small enough to inline.
+      const { data } = await sharp(bytes)
+        .resize({ width: 32, fit: "inside" })
+        .webp({ quality: 40 })
+        .toBuffer({ resolveWithObject: true });
+      return `data:image/webp;base64,${Buffer.from(data).toString("base64")}`;
+    } catch {
+      return null;
+    }
+  }
+
+  async canEncode(format: ConversionFormat): Promise<boolean> {
+    try {
+      const sharp = await loadSharp();
+      await _applyFormat(sharp(_PROBE_PNG).resize({ width: 2 }), format, 60).toBuffer({
+        resolveWithObject: true,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+function _applyFormat(
+  pipeline: SharpPipeline,
+  format: ConversionFormat,
+  quality: number | undefined,
+): SharpPipeline {
+  const options = quality === undefined ? undefined : { quality };
+  switch (format) {
+    case "jpeg":
+      return pipeline.jpeg(options);
+    case "png":
+      return pipeline.png(options);
+    case "webp":
+      return pipeline.webp(options);
+    case "avif":
+      return pipeline.avif(options);
+    case "heic":
+      return pipeline.heif({ ...(options ?? {}), compression: "hevc" });
+  }
+}
+
+/** A valid 2×2 PNG, used to probe which encoders are available. */
+const _PROBE_PNG = Uint8Array.from(
+  atob(
+    "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAD0lEQVR4nGMsY2AoY0AGAA5uAO6e" +
+      "5/phAAAAAElFTkSuQmCC",
+  ),
+  (c) => c.charCodeAt(0),
+);

package/src/conversions/dispatch.ts

@@ -0,0 +1,38 @@
+/**
+ * Handles a set of conversions off the request path.
+ *
+ * @param mediaId - Row to convert.
+ * @param conversions - Names of the conversions to generate.
+ */
+export type ConversionDispatcher = (mediaId: number, conversions: string[]) => Promise<void>;
+
+let _dispatcher: ConversionDispatcher | null = null;
+
+/**
+ * Install the queue-backed dispatcher.
+ *
+ * `MediaProvider` calls this only when a `queue` binding exists, which is what
+ * keeps `@zerotal/media` free of a hard dependency on `@zerotal/queue`: an app
+ * that never queues never pulls the package in, and one that does gets deferred
+ * conversions with no extra wiring.
+ */
+export function setConversionDispatcher(dispatcher: ConversionDispatcher | null): void {
+  _dispatcher = dispatcher;
+}
+
+/** Whether conversions can currently be deferred. */
+export function isQueueAvailable(): boolean {
+  return _dispatcher !== null;
+}
+
+/**
+ * Hand conversions to the queue.
+ *
+ * A no-op when nothing is installed — callers check {@link isQueueAvailable}
+ * first and run inline instead, so this is only reached if a queue disappeared
+ * between the check and the dispatch.
+ */
+export async function dispatchConversions(mediaId: number, conversions: string[]): Promise<void> {
+  if (_dispatcher === null) return;
+  await _dispatcher(mediaId, conversions);
+}

package/src/conversions/queueBridge.ts

@@ -0,0 +1,82 @@
+import { modelByName } from "@zerotal/orm";
+import { MediaItem } from "../MediaItem.ts";
+import { ConversionRunner } from "./ConversionRunner.ts";
+import { resolveCollection, hasCollection, type CollectionHost } from "../collections/resolve.ts";
+import { mediaState } from "../state.ts";
+import type { ConversionMap } from "../types.ts";
+
+/**
+ * Work that a queued conversion job performs, plus the dispatch that puts it
+ * there.
+ *
+ * `@zerotal/queue` is imported dynamically and only from {@link dispatchConversionJob},
+ * which is itself only reached when the container already has a `queue` binding.
+ * That is what lets `@zerotal/media` list the queue as neither a dependency nor
+ * a peer.
+ */
+
+/** Regenerate a named set of conversions for one media row. */
+export async function performConversions(
+  mediaId: number,
+  conversions: string[],
+): Promise<{ generated: string[]; failed: Array<{ name: string; reason: string }> }> {
+  const empty = {
+    generated: [] as string[],
+    failed: [] as Array<{ name: string; reason: string }>,
+  };
+
+  const media = await MediaItem.find(mediaId);
+  if (media === null) return empty;
+
+  const ownerClass = ownerClassFor(media.modelType);
+  if (ownerClass === null || !hasCollection(ownerClass, media.collectionName)) return empty;
+
+  const declared = resolveCollection(ownerClass, media.collectionName).conversions ?? {};
+
+  const wanted: ConversionMap = {};
+  for (const name of conversions) {
+    const conversion = declared[name];
+    if (conversion !== undefined) wanted[name] = conversion;
+  }
+
+  const state = mediaState();
+  return new ConversionRunner(state.driver, state.config).run(media, wanted);
+}
+
+/**
+ * Queue a conversion job.
+ *
+ * If the dispatch itself fails — no queue driver, a Redis that just went away —
+ * the conversion runs inline instead. A thumbnail generated on the request
+ * thread is worse than one generated on a worker, and much better than one that
+ * never appears at all.
+ */
+export async function dispatchConversionJob(mediaId: number, conversions: string[]): Promise<void> {
+  try {
+    const [{ PerformConversionsJob }, { Queue, JobRegistry }] = await Promise.all([
+      import("./PerformConversionsJob.ts"),
+      import("@zerotal/queue"),
+    ]);
+
+    // The worker deserialises by class name, so the class has to be findable
+    // before the job is popped — not merely before it is pushed.
+    JobRegistry.register(PerformConversionsJob);
+
+    await Queue.dispatch(new PerformConversionsJob(mediaId, conversions));
+  } catch {
+    await performConversions(mediaId, conversions);
+  }
+}
+
+/**
+ * Look up a model class by the name stored in `model_type`.
+ *
+ * The ORM registry is populated by model discovery, so this resolves anything
+ * under `app/models/`. A type that is not registered — a model defined inline in
+ * a test, say — yields null and the job becomes a no-op, rather than a job that
+ * can never succeed retrying until it exhausts its attempts.
+ */
+export function ownerClassFor(modelType: string): CollectionHost | null {
+  const found = modelByName(modelType);
+  return (found as CollectionHost | undefined) ?? null;
+}

package/src/errors.ts

@@ -0,0 +1,114 @@
+import { ZerotalError } from "@zerotal/core";
+
+/** Base class for every error this package throws. */
+export class MediaError extends ZerotalError {
+  constructor(message: string, code = "E_MEDIA", status = 500, context?: Record<string, unknown>) {
+    super(message, code, status, context);
+  }
+}
+
+/** A collection was referenced that the model never declared. */
+export class UnknownCollectionError extends MediaError {
+  constructor(model: string, collection: string, known: string[]) {
+    const list = known.length > 0 ? known.map((c) => `"${c}"`).join(", ") : "none declared";
+    super(
+      `[Zerotal Media] ${model} has no media collection "${collection}". Declared: ${list}.\n` +
+        `Fix: add it to the static mediaCollections field on ${model}.`,
+      "E_MEDIA_UNKNOWN_COLLECTION",
+      500,
+      { model, collection, known },
+    );
+  }
+}
+
+/**
+ * The file's sniffed type is not in the collection's `accepts` list.
+ *
+ * A 422 rather than a 500: the upload was understood and refused, which is the
+ * client's problem to fix.
+ */
+export class DisallowedMimeTypeError extends MediaError {
+  constructor(collection: string, actual: string, allowed: string[]) {
+    super(
+      `[Zerotal Media] Collection "${collection}" does not accept ${actual}. ` +
+        `Allowed: ${allowed.join(", ")}.\n` +
+        "Note: the type is read from the file's own bytes, not from the upload's " +
+        "Content-Type header, so a renamed file is still rejected.",
+      "E_MEDIA_DISALLOWED_MIME_TYPE",
+      422,
+      { collection, actual, allowed },
+    );
+  }
+}
+
+/** The file is larger than the collection's `maxSize`. */
+export class FileTooLargeError extends MediaError {
+  constructor(collection: string, actual: number, max: number) {
+    super(
+      `[Zerotal Media] File is ${actual} bytes; collection "${collection}" allows at most ${max}.\n` +
+        "Fix: raise maxSize on the collection, or compress before uploading.",
+      "E_MEDIA_FILE_TOO_LARGE",
+      413,
+      { collection, actual, max },
+    );
+  }
+}
+
+/**
+ * A conversion asked for something the active image driver cannot do.
+ *
+ * Overwhelmingly this is `fit: "cover"` on the default `BunImageDriver`:
+ * `Bun.Image.resize()` accepts only `fit: 'fill' | 'inside'` and the class
+ * exposes no crop primitive, so a centre-cropped thumbnail is not expressible.
+ */
+export class UnsupportedManipulationError extends MediaError {
+  constructor(driver: string, what: string, fix: string) {
+    super(
+      `[Zerotal Media] ${driver} cannot ${what}.\nFix: ${fix}`,
+      "E_MEDIA_UNSUPPORTED_MANIPULATION",
+      500,
+      { driver },
+    );
+  }
+}
+
+/** The requested output format is not encodable on this host. */
+export class UnsupportedFormatError extends MediaError {
+  constructor(format: string, available: string[]) {
+    super(
+      `[Zerotal Media] This host cannot encode ${format}. Available: ${available.join(", ")}.\n` +
+        "Bun.Image encodes AVIF/HEIC/TIFF through OS codecs, which are absent here. " +
+        "Fix: use jpeg, png, or webp — or run on a host with the codec installed.",
+      "E_MEDIA_UNSUPPORTED_FORMAT",
+      500,
+      { format, available },
+    );
+  }
+}
+
+/** A file could not be read back from the disk it was recorded on. */
+export class MediaFileMissingError extends MediaError {
+  constructor(path: string, disk: string) {
+    super(
+      `[Zerotal Media] No file at "${path}" on disk "${disk}", but a media row points at it.\n` +
+        "Fix: run `bun zt media:clean` to reconcile rows against disks.",
+      "E_MEDIA_FILE_MISSING",
+      404,
+      { path, disk },
+    );
+  }
+}
+
+/** Media was added to a model that has not been saved yet. */
+export class UnsavedOwnerError extends MediaError {
+  constructor(model: string) {
+    super(
+      `[Zerotal Media] Cannot attach media to an unsaved ${model} — it has no id yet ` +
+        "to record in model_id.\n" +
+        `Fix: await ${model.toLowerCase()}.save() (or use .create()) before adding media.`,
+      "E_MEDIA_UNSAVED_OWNER",
+      500,
+      { model },
+    );
+  }
+}

package/src/facades/MediaLibrary.ts

@@ -0,0 +1,16 @@
+import { createFacade } from "@zerotal/core";
+
+/**
+ * Facade over the container's `media` binding.
+ *
+ * Named `MediaLibrary` rather than `Media` because {@link Media} is the model
+ * mixin, and an app importing both would otherwise have to rename one at every
+ * call site. The facade is the rarer of the two.
+ *
+ * @example
+ * import { MediaLibrary } from "@zerotal/media";
+ *
+ * await MediaLibrary.regenerate(media, Product, ["thumb"]);
+ * const report = await MediaLibrary.clean({ dryRun: false });
+ */
+export const MediaLibrary = createFacade("media");

package/src/index.ts

@@ -0,0 +1,94 @@
+// @zerotal/media — public API
+
+// Model + model mixin
+// `Media` is the mixin — it reads as `Model.using(Media)`. `MediaItem` is one
+// stored file: a row in the `media` table.
+export { Media } from "./Media.ts";
+export { MediaItem, pathGenerator, setPathGenerator } from "./MediaItem.ts";
+export { MediaAdder } from "./MediaAdder.ts";
+
+// Application-level operations
+export { MediaManager } from "./MediaManager.ts";
+export type { CleanReport } from "./MediaManager.ts";
+export { MediaLibrary } from "./facades/MediaLibrary.ts";
+export { MediaProvider } from "./provider/MediaProvider.ts";
+
+// Collections
+export { resolveCollection, hasCollection, collectionNames } from "./collections/resolve.ts";
+export type { CollectionHost } from "./collections/resolve.ts";
+export { applyRetentionRules } from "./collections/retention.ts";
+
+// Conversions
+export { ConversionRunner, partitionConversions } from "./conversions/ConversionRunner.ts";
+export { BunImageDriver } from "./conversions/BunImageDriver.ts";
+export { SharpImageDriver } from "./conversions/SharpImageDriver.ts";
+export {
+  FORMAT_EXTENSION,
+  FORMAT_MIME,
+  CONVERTIBLE_MIME_TYPES,
+  isConvertible,
+} from "./conversions/ImageDriver.ts";
+export type {
+  ImageDriver,
+  ImageManipulation,
+  ImageMetadata,
+  ImageResult,
+} from "./conversions/ImageDriver.ts";
+export {
+  setConversionDispatcher,
+  isQueueAvailable,
+  dispatchConversions,
+} from "./conversions/dispatch.ts";
+export type { ConversionDispatcher } from "./conversions/dispatch.ts";
+export { performConversions, ownerClassFor } from "./conversions/queueBridge.ts";
+
+// Paths
+export { DefaultPathGenerator } from "./paths/PathGenerator.ts";
+export type { PathGenerator } from "./paths/PathGenerator.ts";
+
+// Sources
+export { fromValue, fromUrl, fromDisk, fromPath } from "./sources.ts";
+export type { MediaSource, ResolvedSource, SourceResolver } from "./sources.ts";
+
+// Disk resolution (the seam tests use to skip building a container)
+export {
+  diskFor,
+  diskNameFor,
+  defaultDiskName,
+  setDiskResolver,
+  setDefaultDiskName,
+} from "./support/disks.ts";
+export type { DiskResolver } from "./support/disks.ts";
+
+// Schema provisioning
+export { mediaSchemaConcern } from "./mediaSchemaConcern.ts";
+
+// Config
+export { MediaConfig, mediaDefaults } from "./config.ts";
+export type { MediaConfigShape } from "./config.ts";
+
+// Shared state (mainly for tests and advanced wiring)
+export { mediaState, setMediaState, resetMediaState } from "./state.ts";
+export type { MediaState } from "./state.ts";
+
+// Testing
+export { MediaFake } from "./MediaFake.ts";
+
+// Types
+export type {
+  CollectionDefinition,
+  ConversionDefinition,
+  ConversionFit,
+  ConversionFormat,
+  ConversionMap,
+  GeneratedConversion,
+  MediaCollections,
+  MediaOwner,
+  PendingMediaMeta,
+  ResponsiveImage,
+  ResponsiveImageSet,
+  SafeConversionFormat,
+} from "./types.ts";
+
+// Errors
+export * from "./errors.ts";

package/src/mediaSchemaConcern.ts

@@ -0,0 +1,65 @@
+import type { ConcernDescriptor } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import { Schema } from "@zerotal/orm";
+
+/**
+ * Provisions the `media` table on boot — so apps don't write a migration for it.
+ *
+ * Runs once after model discovery (order 70), additively and idempotently: it
+ * creates the table only when it's missing. Skipped when `media.autoCreateTable`
+ * is off and in DB-less runtimes; any DDL/connection error is swallowed so boot
+ * never fails because of it.
+ *
+ * Mirrors `auditSchemaConcern`, and exists for the same reason: the alternative
+ * is an app that boots cleanly and then fails on its first upload, in production.
+ */
+export const mediaSchemaConcern: ConcernDescriptor = {
+  name: "media-schema",
+  order: 70,
+  envs: ["web", "worker", "test"],
+  async run(ctx) {
+    try {
+      const config = ctx.resolve<ConfigManager>("config");
+      if (config?.get<boolean>("media.autoCreateTable", true) === false) return;
+
+      const tableName = config?.get<string>("media.table", "media") ?? "media";
+      if (await Schema.hasTable(tableName)) return;
+
+      await Schema.create(tableName, (blueprint) => {
+        blueprint.increments("id");
+
+        // model_id is text, not an integer: apps with UUID primary keys are as
+        // entitled to attach media as apps with auto-increment ones.
+        blueprint.string("model_type");
+        blueprint.string("model_id");
+        blueprint.string("uuid").nullable();
+        blueprint.string("collection_name");
+        blueprint.string("name");
+        blueprint.string("file_name");
+        blueprint.string("mime_type").nullable();
+        blueprint.string("disk");
+        blueprint.string("conversions_disk").nullable();
+        blueprint.integer("size");
+
+        // Every JSON column defaults to an object, never a bare scalar — a bare
+        // scalar in a json column does not survive the round trip intact.
+        blueprint.text("manipulations").nullable();
+        blueprint.text("custom_properties").nullable();
+        blueprint.text("generated_conversions").nullable();
+        blueprint.text("responsive_images").nullable();
+
+        blueprint.integer("order_column").nullable();
+        blueprint.timestamp("created_at").nullable();
+        blueprint.timestamp("updated_at").nullable();
+
+        // The query every read makes: "this model's items in this collection,
+        // in order".
+        blueprint.index(["model_type", "model_id", "collection_name"], "media_owner_index");
+        blueprint.index(["order_column"], "media_order_index");
+        blueprint.unique(["uuid"], "media_uuid_unique");
+      });
+    } catch {
+      // No database (or DDL not permitted) in this runtime — skip silently.
+    }
+  },
+};

package/src/paths/PathGenerator.ts

@@ -0,0 +1,47 @@
+import type { MediaItem } from "../MediaItem.ts";
+
+/**
+ * Decides where a media item's files live on disk.
+ *
+ * Every media item gets its own directory. That is what makes deleting one item
+ * safe: removing its directory can never take a sibling's file with it, however
+ * the two were named.
+ */
+export interface PathGenerator {
+  /** Directory for the original, relative to the disk root. No trailing slash. */
+  forOriginal(media: MediaItem): string;
+  /** Directory for generated conversions. */
+  forConversions(media: MediaItem): string;
+  /** Directory for responsive image variants. */
+  forResponsiveImages(media: MediaItem): string;
+}
+
+/**
+ * The default layout:
+ *
+ * ```text
+ * media/<uuid>/original.jpg
+ * media/<uuid>/conversions/thumb.webp
+ * media/<uuid>/responsive/640.webp
+ * ```
+ *
+ * Keyed on `uuid` rather than the numeric `id` that Laravel's media library
+ * uses. These paths end up in public URLs, and a sequential id in a public URL
+ * discloses how many rows the table has — plus it lets anyone walk the range.
+ * The uuid costs nothing and leaks nothing.
+ */
+export class DefaultPathGenerator implements PathGenerator {
+  constructor(private readonly prefix: string = "media") {}
+
+  forOriginal(media: MediaItem): string {
+    return `${this.prefix}/${media.uuid}`;
+  }
+
+  forConversions(media: MediaItem): string {
+    return `${this.forOriginal(media)}/conversions`;
+  }
+
+  forResponsiveImages(media: MediaItem): string {
+    return `${this.forOriginal(media)}/responsive`;
+  }
+}