@zerotal/media 1.3.0

package/src/MediaFake.ts

@@ -0,0 +1,99 @@
+import { MediaItem } from "./MediaItem.ts";
+
+/**
+ * Assertions over what a test attached to its models.
+ *
+ * Pairs with `Storage.fake()`, which handles the bytes: that one asserts a file
+ * landed on a disk, this one asserts a row points at it from the right
+ * collection. Both matter — a media row with no file and a file with no row are
+ * different bugs.
+ *
+ * @example
+ * const disk = Storage.fake();
+ * await product.addMedia(file).toCollection("images");
+ *
+ * await MediaFake.assertHas(product, "images");
+ * await MediaFake.assertCount(product, "images", 1);
+ * disk.assertExistsMatching(/^media\/[0-9a-f-]+\/original\.png$/);
+ */
+export const MediaFake = {
+  /** Every media row attached to a model. */
+  async all(owner: { id: number | string; constructor: { name: string } }): Promise<MediaItem[]> {
+    return MediaItem.query()
+      .where("model_type", owner.constructor.name)
+      .where("model_id", String(owner.id))
+      .orderBy("id", "asc")
+      .get();
+  },
+
+  /** Media rows in one of a model's collections. */
+  async inCollection(
+    owner: { id: number | string; constructor: { name: string } },
+    collection: string,
+  ): Promise<MediaItem[]> {
+    const all = await MediaFake.all(owner);
+    return all.filter((media) => media.collectionName === collection);
+  },
+
+  /** Fail unless the collection holds at least one item. */
+  async assertHas(
+    owner: { id: number | string; constructor: { name: string } },
+    collection: string,
+  ): Promise<void> {
+    const found = await MediaFake.inCollection(owner, collection);
+    if (found.length > 0) return;
+
+    const all = await MediaFake.all(owner);
+    const others = [...new Set(all.map((m) => m.collectionName))];
+    throw new Error(
+      `Expected ${owner.constructor.name}#${owner.id} to have media in "${collection}", ` +
+        `but it has none. Collections with media: ${others.length > 0 ? others.join(", ") : "none"}.`,
+    );
+  },
+
+  /** Fail unless the collection is empty. */
+  async assertMissing(
+    owner: { id: number | string; constructor: { name: string } },
+    collection: string,
+  ): Promise<void> {
+    const found = await MediaFake.inCollection(owner, collection);
+    if (found.length === 0) return;
+    throw new Error(
+      `Expected "${collection}" to be empty, but it holds ${found.length}: ` +
+        found.map((m) => m.fileName).join(", "),
+    );
+  },
+
+  /** Fail unless the collection holds exactly `count` items. */
+  async assertCount(
+    owner: { id: number | string; constructor: { name: string } },
+    collection: string,
+    count: number,
+  ): Promise<void> {
+    const found = await MediaFake.inCollection(owner, collection);
+    if (found.length === count) return;
+    throw new Error(
+      `Expected "${collection}" to hold ${count} item(s), found ${found.length}: ` +
+        (found.map((m) => m.fileName).join(", ") || "none"),
+    );
+  },
+
+  /** Fail unless a named conversion was generated for the collection's first item. */
+  async assertConversion(
+    owner: { id: number | string; constructor: { name: string } },
+    collection: string,
+    conversion: string,
+  ): Promise<void> {
+    const [first] = await MediaFake.inCollection(owner, collection);
+    if (first === undefined) {
+      throw new Error(`Expected a conversion "${conversion}", but "${collection}" is empty.`);
+    }
+    if (first.hasConversion(conversion)) return;
+
+    const generated = first.conversionNames();
+    throw new Error(
+      `Expected conversion "${conversion}" on ${first.fileName}, but it has ` +
+        `${generated.length > 0 ? generated.join(", ") : "none"}.`,
+    );
+  },
+};

package/src/MediaItem.ts

@@ -0,0 +1,282 @@
+import { BaseModel, column, table } from "@zerotal/orm";
+import type { StorageDriver } from "@zerotal/core/storage";
+import { diskFor } from "./support/disks.ts";
+import { DefaultPathGenerator, type PathGenerator } from "./paths/PathGenerator.ts";
+import { MediaFileMissingError } from "./errors.ts";
+import type { GeneratedConversion, ResponsiveImageSet } from "./types.ts";
+
+/** Swappable at the container level by `MediaProvider`. */
+let _pathGenerator: PathGenerator = new DefaultPathGenerator();
+
+/** Replace the global path generator. Called by `MediaProvider` from config. */
+export function setPathGenerator(generator: PathGenerator): void {
+  _pathGenerator = generator;
+}
+
+/** The path generator currently in force. */
+export function pathGenerator(): PathGenerator {
+  return _pathGenerator;
+}
+
+/**
+ * One stored file attached to a model.
+ *
+ * Rows are created by `model.addMedia(...)` rather than directly — the adder is
+ * what sniffs the file's type, enforces the collection's rules, writes the bytes
+ * and generates conversions. Constructing a `MediaItem` by hand gets you a row with
+ * no file behind it.
+ *
+ * @example
+ * const media = await product.addMedia(file).toCollection("images");
+ * media.getUrl();          // the original
+ * media.getUrl("thumb");   // a conversion, or "" when it has not been generated
+ * await media.delete();    // removes the row, the original, and every derivative
+ */
+@(table("media").withTimestamps())
+export class MediaItem extends BaseModel {
+  /** Owner discriminator — the owning model's class name. */
+  @column() modelType!: string;
+  /** Owner primary key. Stored as text so UUID keys work as well as integers. */
+  @column() modelId!: string;
+  /** Public identifier. Used in paths, so it never exposes the row count. */
+  @column() uuid!: string;
+  @column() collectionName!: string;
+  /** Human-facing label; defaults to the original filename without its extension. */
+  @column() name!: string;
+  /** Name on disk, e.g. `original.jpg`. */
+  @column() fileName!: string;
+  /** Sniffed from the file's own bytes — never the client-supplied header. */
+  @column() mimeType!: string | null;
+  @column() disk!: string;
+  @column() conversionsDisk!: string | null;
+  @column("number") size!: number;
+  @column("json") manipulations!: Record<string, unknown>;
+  @column("json") customProperties!: Record<string, unknown>;
+  @column("json") generatedConversions!: Record<string, GeneratedConversion>;
+  @column("json") responsiveImages!: ResponsiveImageSet | Record<string, never>;
+  @column("number") orderColumn!: number | null;
+
+  // ── Scopes ─────────────────────────────────────────────────────────────────
+
+  static forOwner = this.scope((q, type: string, id: string | number) =>
+    q.where("model_type", type).where("model_id", String(id)),
+  );
+
+  static inCollection = this.scope((q, collection: string) =>
+    q.where("collection_name", collection),
+  );
+
+  static ordered = this.scope((q) => q.orderBy("order_column", "asc").orderBy("id", "asc"));
+
+  // ── Disks ──────────────────────────────────────────────────────────────────
+
+  /** The disk holding the original. */
+  originalDisk(): StorageDriver {
+    return diskFor(this.disk);
+  }
+
+  /** The disk holding conversions — falls back to the original's disk. */
+  derivedDisk(): StorageDriver {
+    return diskFor(this.conversionsDisk ?? this.disk);
+  }
+
+  // ── Paths ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Path to the original, or to a named conversion.
+   *
+   * Returns `""` for a conversion that has not been generated — matching
+   * `getUrl()`, so a template can use either without a null check.
+   */
+  getPath(conversion?: string): string {
+    if (conversion === undefined) {
+      return `${pathGenerator().forOriginal(this)}/${this.fileName}`;
+    }
+    const generated = this.generatedConversions?.[conversion];
+    if (!generated) return "";
+    return `${pathGenerator().forConversions(this)}/${generated.fileName}`;
+  }
+
+  /** Path to one responsive variant by width, or `""` when absent. */
+  getResponsivePath(width: number): string {
+    const entry = this.responsiveSet().images.find((i) => i.width === width);
+    if (!entry) return "";
+    return `${pathGenerator().forResponsiveImages(this)}/${entry.fileName}`;
+  }
+
+  // ── URLs ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Public URL for the original, or for a named conversion.
+   *
+   * Returns `""` when the conversion does not exist, so `<img src="">` renders
+   * nothing rather than a broken path — check `hasConversion()` when you need to
+   * branch.
+   */
+  getUrl(conversion?: string): string {
+    const path = this.getPath(conversion);
+    if (path === "") return "";
+    const disk = conversion === undefined ? this.originalDisk() : this.derivedDisk();
+    return disk.url(path);
+  }
+
+  /**
+   * A signed, expiring URL — the way to expose a file on a private disk without
+   * making the disk public.
+   *
+   * @param expiresInSeconds - Lifetime of the link. Default 900 (15 minutes).
+   */
+  async getTemporaryUrl(expiresInSeconds = 900, conversion?: string): Promise<string> {
+    const path = this.getPath(conversion);
+    if (path === "") return "";
+    const disk = conversion === undefined ? this.originalDisk() : this.derivedDisk();
+    return disk.temporaryUrl(path, expiresInSeconds);
+  }
+
+  // ── Conversions ────────────────────────────────────────────────────────────
+
+  /** Whether a named conversion has been generated. */
+  hasConversion(name: string): boolean {
+    return Boolean(this.generatedConversions?.[name]);
+  }
+
+  /** Metadata for a generated conversion, or `null`. */
+  conversion(name: string): GeneratedConversion | null {
+    return this.generatedConversions?.[name] ?? null;
+  }
+
+  /** Names of every generated conversion. */
+  conversionNames(): string[] {
+    return Object.keys(this.generatedConversions ?? {});
+  }
+
+  // ── Responsive images ──────────────────────────────────────────────────────
+
+  /** The responsive set, normalised so callers never see `undefined`. */
+  responsiveSet(): ResponsiveImageSet {
+    const raw = this.responsiveImages as ResponsiveImageSet | undefined;
+    if (!raw || !Array.isArray(raw.images)) return { images: [] };
+    return raw;
+  }
+
+  /**
+   * A `srcset` attribute value for the responsive ladder, or `""` when none was
+   * generated.
+   *
+   * @example
+   * <img src={media.getUrl()} srcset={media.srcset()} sizes="(max-width: 768px) 100vw, 50vw" />
+   */
+  srcset(): string {
+    const set = this.responsiveSet();
+    if (set.images.length === 0) return "";
+    const disk = this.derivedDisk();
+    const dir = pathGenerator().forResponsiveImages(this);
+    return set.images
+      .map((image) => `${disk.url(`${dir}/${image.fileName}`)} ${image.width}w`)
+      .join(", ");
+  }
+
+  /**
+   * An inline `data:` URI of a tiny blurred version, for rendering while the
+   * real image loads. `null` when none was generated.
+   */
+  get placeholder(): string | null {
+    return this.responsiveSet().placeholder ?? null;
+  }
+
+  // ── Custom properties ──────────────────────────────────────────────────────
+
+  /**
+   * Read a custom property, with an optional fallback.
+   *
+   * Custom properties are an untyped JSON bag, so without a fallback the result is `unknown` —
+   * narrow it yourself (`as string`, or a type guard). With a fallback the result is the
+   * fallback's type and can never be `undefined`.
+   *
+   * The no-fallback overload is deliberately **non-generic**. A `<T = unknown>` parameter that
+   * appears only in the return type is inferred from the CALL SITE's context rather than falling
+   * back to its default, so `expect(item.getCustomProperty("alt"))` collapsed `T` to `undefined`
+   * and rejected every assertion against it. A concrete `unknown` cannot be hijacked that way.
+   */
+  getCustomProperty(key: string): unknown;
+  getCustomProperty<T>(key: string, fallback: T): T;
+  getCustomProperty<T>(key: string, fallback?: T): T | undefined {
+    const value = this.customProperties?.[key];
+    return (value as T | undefined) ?? fallback;
+  }
+
+  /** Set a custom property in memory. Call `save()` to persist. */
+  setCustomProperty(key: string, value: unknown): this {
+    this.customProperties = { ...(this.customProperties ?? {}), [key]: value };
+    return this;
+  }
+
+  /** Remove a custom property in memory. Call `save()` to persist. */
+  forgetCustomProperty(key: string): this {
+    const next = { ...(this.customProperties ?? {}) };
+    delete next[key];
+    this.customProperties = next;
+    return this;
+  }
+
+  // ── Contents ───────────────────────────────────────────────────────────────
+
+  /** Read the original's bytes. */
+  async bytes(): Promise<Uint8Array> {
+    const path = this.getPath();
+    const buffer = await this.originalDisk().getBuffer(path);
+    if (buffer === null) throw new MediaFileMissingError(path, this.disk);
+    return buffer;
+  }
+
+  /** Whether the original is actually present on its disk. */
+  async fileExists(): Promise<boolean> {
+    return this.originalDisk().exists(this.getPath());
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────────────────────
+
+  /**
+   * Delete the row and every file behind it — original, conversions, responsive
+   * variants.
+   *
+   * Files go first. A failure part-way then leaves a row pointing at a missing
+   * file, which `media:clean` can find and fix; the reverse order would leave an
+   * orphaned file that nothing references and nothing can find.
+   */
+  override async delete(): Promise<void> {
+    await this.deleteFiles();
+    await super.delete();
+  }
+
+  /** Remove every file for this item, leaving the row. */
+  async deleteFiles(): Promise<void> {
+    const original = this.originalDisk();
+    const derived = this.derivedDisk();
+
+    await _ignoreMissing(original.delete(this.getPath()));
+
+    const conversionDir = pathGenerator().forConversions(this);
+    for (const generated of Object.values(this.generatedConversions ?? {})) {
+      await _ignoreMissing(derived.delete(`${conversionDir}/${generated.fileName}`));
+    }
+
+    const responsiveDir = pathGenerator().forResponsiveImages(this);
+    for (const image of this.responsiveSet().images) {
+      await _ignoreMissing(derived.delete(`${responsiveDir}/${image.fileName}`));
+    }
+  }
+}
+
+/**
+ * Deleting a file that is already gone is the outcome we wanted. Anything else
+ * propagates.
+ */
+async function _ignoreMissing(operation: Promise<void>): Promise<void> {
+  try {
+    await operation;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!/not found|no such file|ENOENT|does not exist/i.test(message)) throw error;
+  }
+}

package/src/MediaManager.ts

@@ -0,0 +1,111 @@
+import { MediaItem } from "./MediaItem.ts";
+import { ConversionRunner } from "./conversions/ConversionRunner.ts";
+import { resolveCollection, type CollectionHost } from "./collections/resolve.ts";
+import { diskFor } from "./support/disks.ts";
+import type { MediaConfigShape } from "./config.ts";
+import type { ImageDriver } from "./conversions/ImageDriver.ts";
+import type { ConversionMap } from "./types.ts";
+
+/** Outcome of a {@link MediaManager.clean} pass. */
+export interface CleanReport {
+  /** Rows whose file is gone from its disk. */
+  orphanedRows: number[];
+  /** Rows deleted (empty when `dryRun`). */
+  deletedRows: number[];
+  /** Conversions recorded on a row whose file is missing. */
+  danglingConversions: Array<{ mediaId: number; conversion: string }>;
+}
+
+/**
+ * Application-level media operations — the thing behind the `MediaLibrary` facade.
+ *
+ * Per-model work lives on the {@link Media} mixin; this is for the jobs that
+ * cut across models: regenerating conversions after changing a definition, and
+ * reconciling rows against what is actually on disk.
+ */
+export class MediaManager {
+  constructor(
+    readonly config: MediaConfigShape,
+    readonly driver: ImageDriver,
+  ) {}
+
+  /** A runner bound to the configured driver. */
+  runner(): ConversionRunner {
+    return new ConversionRunner(this.driver, this.config);
+  }
+
+  /**
+   * Regenerate conversions for one media item.
+   *
+   * Reads the collection definition off the owning model class, so changing a
+   * conversion's width and re-running this is all it takes to reprocess.
+   *
+   * @param media - The item to reprocess.
+   * @param ownerClass - The owning model class, for its collection definitions.
+   * @param only - Limit to these conversion names; omit for all of them.
+   */
+  async regenerate(
+    media: MediaItem,
+    ownerClass: CollectionHost,
+    only?: string[],
+  ): Promise<string[]> {
+    const definition = resolveCollection(ownerClass, media.collectionName);
+    const all = definition.conversions ?? {};
+
+    const wanted: ConversionMap = {};
+    for (const [name, conversion] of Object.entries(all)) {
+      if (only === undefined || only.includes(name)) wanted[name] = conversion;
+    }
+
+    const { generated } = await this.runner().run(media, wanted);
+
+    if (definition.responsive !== undefined && definition.responsive !== false) {
+      const widths = Array.isArray(definition.responsive)
+        ? definition.responsive
+        : this.config.responsiveWidths;
+      await this.runner().runResponsive(media, widths);
+    }
+
+    return generated;
+  }
+
+  /**
+   * Find media rows whose files have gone missing, and optionally remove them.
+   *
+   * Rows are checked one at a time against their own disk rather than by listing
+   * the disk, because the two live on different sides of a network for S3 and a
+   * full listing of a large bucket is not something to do casually.
+   *
+   * @param options.dryRun - Report without deleting. Default `true`, because the
+   *   destructive reading of "clean" should never be the one you get by accident.
+   */
+  async clean(options: { dryRun?: boolean } = {}): Promise<CleanReport> {
+    const dryRun = options.dryRun ?? true;
+    const report: CleanReport = { orphanedRows: [], deletedRows: [], danglingConversions: [] };
+
+    const all = await MediaItem.query().get();
+
+    for (const media of all) {
+      const id = Number(media.id);
+
+      if (!(await media.fileExists())) {
+        report.orphanedRows.push(id);
+        if (!dryRun) {
+          await media.delete();
+          report.deletedRows.push(id);
+        }
+        continue;
+      }
+
+      const derived = diskFor(media.conversionsDisk ?? media.disk);
+      for (const name of media.conversionNames()) {
+        const path = media.getPath(name);
+        if (path !== "" && !(await derived.exists(path))) {
+          report.danglingConversions.push({ mediaId: id, conversion: name });
+        }
+      }
+    }
+
+    return report;
+  }
+}

package/src/collections/resolve.ts

@@ -0,0 +1,39 @@
+import { UnknownCollectionError } from "../errors.ts";
+import type { CollectionDefinition, MediaCollections } from "../types.ts";
+
+/** A model class that may declare media collections. */
+export interface CollectionHost {
+  name: string;
+  mediaCollections?: MediaCollections;
+}
+
+/**
+ * The collection definition a model declares under `name`.
+ *
+ * Values may be a plain object or a thunk; the thunk is called on every lookup
+ * rather than cached, because the reason to write one is a value that changes
+ * between calls (the current tenant's disk, say).
+ *
+ * @throws {UnknownCollectionError} when the model declares no such collection —
+ *   listing the ones it does declare, because the mistake is nearly always a typo.
+ */
+export function resolveCollection(host: CollectionHost, name: string): CollectionDefinition {
+  const declared = host.mediaCollections ?? {};
+  const entry = declared[name];
+
+  if (entry === undefined) {
+    throw new UnknownCollectionError(host.name, name, Object.keys(declared));
+  }
+
+  return typeof entry === "function" ? entry() : entry;
+}
+
+/** Whether a model declares a collection under `name`. */
+export function hasCollection(host: CollectionHost, name: string): boolean {
+  return (host.mediaCollections ?? {})[name] !== undefined;
+}
+
+/** Every collection name the model declares. */
+export function collectionNames(host: CollectionHost): string[] {
+  return Object.keys(host.mediaCollections ?? {});
+}

package/src/collections/retention.ts

@@ -0,0 +1,47 @@
+import { MediaItem } from "../MediaItem.ts";
+import type { CollectionDefinition } from "../types.ts";
+
+/**
+ * Trim a collection back to what its rules allow, after something was added.
+ *
+ * `single` is `onlyKeepLatest(1)` under a friendlier name — an avatar or a hero
+ * image, where a second upload replaces the first rather than joining it.
+ *
+ * Deletion goes through `MediaItem.delete()` on each row rather than a bulk query,
+ * so the files behind the rows go too. A bulk delete would leave every
+ * superseded avatar on disk forever, which is the bug this exists to avoid.
+ *
+ * @param justAdded - The item that triggered the trim; never removed, even if
+ *   its sort position would otherwise put it outside the window.
+ */
+export async function applyRetentionRules(
+  modelType: string,
+  modelId: number | string,
+  collection: string,
+  definition: CollectionDefinition,
+  justAdded: MediaItem,
+): Promise<void> {
+  const keep = definition.single === true ? 1 : definition.onlyKeepLatest;
+  if (keep === undefined || keep < 1) return;
+
+  // Newest first: highest order, then highest id as the tiebreak for items added
+  // within the same order slot.
+  const rows = await MediaItem.query()
+    .where("model_type", modelType)
+    .where("model_id", String(modelId))
+    .where("collection_name", collection)
+    .orderBy("order_column", "desc")
+    .orderBy("id", "desc")
+    .get();
+
+  const survivors = new Set<unknown>([justAdded.id]);
+  for (const row of rows) {
+    if (survivors.size >= keep) break;
+    survivors.add(row.id);
+  }
+
+  for (const row of rows) {
+    if (survivors.has(row.id)) continue;
+    await row.delete();
+  }
+}

package/src/commands/MediaCleanCommand.ts

@@ -0,0 +1,62 @@
+import { Command } from "@zerotal/core";
+import type { FlagDef } from "@zerotal/core";
+import { MediaLibrary } from "../facades/MediaLibrary.ts";
+
+/**
+ * Reconcile media rows against what is actually on disk.
+ *
+ * Reports by default; `--force` is what deletes. "Clean" reads as harmless, and
+ * a command that silently removes rows the first time someone runs it to see
+ * what it does is a bad trade.
+ *
+ * @example
+ * ```bash
+ * bun zt media:clean            # report only
+ * bun zt media:clean --force    # delete rows whose files are gone
+ * ```
+ */
+export class MediaCleanCommand extends Command {
+  static override commandName = "media:clean";
+  static override description =
+    "Find media rows whose files are missing, and optionally remove them";
+  static override needsApp = true;
+  static override flags: FlagDef[] = [
+    {
+      name: "force",
+      short: "f",
+      type: "boolean",
+      description: "Delete the orphaned rows instead of just listing them",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const force = this.flags["force"] === true;
+    const report = await MediaLibrary.clean({ dryRun: !force });
+
+    if (report.orphanedRows.length === 0 && report.danglingConversions.length === 0) {
+      this.info("Every media row has its file. Nothing to do.");
+      return;
+    }
+
+    if (report.orphanedRows.length > 0) {
+      this.warn(
+        `${report.orphanedRows.length} media row(s) point at a file that is gone: ` +
+          report.orphanedRows.join(", "),
+      );
+    }
+
+    if (report.danglingConversions.length > 0) {
+      this.warn(
+        `${report.danglingConversions.length} recorded conversion(s) are missing their file. ` +
+          "Run `bun zt media:regenerate` to rebuild them.",
+      );
+    }
+
+    if (force) {
+      this.info(`Deleted ${report.deletedRows.length} row(s).`);
+    } else {
+      this.info("Nothing was deleted. Re-run with --force to remove the orphaned rows.");
+    }
+  }
+}