@zerotal/media 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog — @zerotal/media
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `experimental`**
+
+## [Unreleased]
+
+## [1.3.0] — 2026-08-09
+
+### Added
+
+- Initial release. Attach files to models with the `Media` mixin —
+  `class Product extends Model.using(Media)` — declaring collections
+  declaratively on the model, and store originals on any configured disk. One
+  stored file is a `MediaItem`.
+- Media collections with `accepts` (checked against sniffed bytes), `maxSize`,
+  `single`, `onlyKeepLatest`, `fallbackUrl` / `fallbackPath`, and per-collection
+  disk overrides.
+- Image conversions on `Bun.Image` — no native module required. `fit: "cover"`
+  is unavailable on the default driver and raises `UnsupportedManipulationError`
+  naming the fix; install `sharp` and set `driver: "sharp"` for cropping.
+- Responsive image ladders with `srcset()` and a ThumbHash inline placeholder.
+- Arbitrary per-item metadata via `withCustomProperties()` on the adder and
+  `getCustomProperty()` / `setCustomProperty()` / `forgetCustomProperty()` on the
+  item, round-tripped through the row's JSON column. Reading without a fallback
+  yields `unknown` (narrow it yourself); reading with one yields the fallback's
+  type and never `undefined`.
+- Queued conversions through `@zerotal/queue` when it is registered, falling
+  back to inline generation when it is not.
+- `media` table provisioned at boot by `mediaSchemaConcern`, so apps write no
+  migration.
+- `MediaFake` assertions, `media:clean` and `media:regenerate` commands.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+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

@@ -0,0 +1,90 @@
+# @zerotal/media
+
+> Attach files to models — collections, image conversions, responsive images, and ordering.
+
+Associate uploads with any model, store them on any disk, and generate derived
+images without installing a native module. Zerotal's answer to
+`spatie/laravel-medialibrary`.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/media
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts` — alongside `StorageProvider`,
+which media writes through:
+
+```ts
+import { StorageProvider } from "@zerotal/core/storage";
+import { MediaProvider } from "@zerotal/media";
+
+export default [DatabaseProvider, StorageProvider, MediaProvider];
+```
+
+No migration is needed: the `media` table is provisioned at boot, once, only
+when missing.
+
+## Usage
+
+Compose `Media` and declare the collections a model owns:
+
+```ts
+import { Model, column } from "@zerotal/orm";
+import { Media, type MediaCollections } from "@zerotal/media";
+
+export class Product extends Model.using(Media) {
+  @column() name!: string;
+
+  static override mediaCollections: MediaCollections = {
+    images: {
+      accepts: ["image/jpeg", "image/png"],
+      conversions: { thumb: { width: 200, height: 200, format: "webp" } },
+      responsive: true,
+    },
+  };
+}
+```
+
+Then add and read files:
+
+```ts
+await product.addMedia(await ctx.file("photo")).toCollection("images");
+
+await product.getFirstMediaUrl("images", "thumb");
+await product.getMedia("images");
+await product.clearMediaCollection("images");
+```
+
+## Notable behaviour
+
+- **Types come from bytes.** `accepts` is checked against the type sniffed from
+  the file's own contents, never the filename or the upload's `Content-Type`.
+- **No native dependency.** Conversions run on `Bun.Image`, built into the
+  runtime. JPEG, PNG and WebP work on every host.
+- **`Bun.Image` cannot crop.** `fit: "cover"` throws rather than silently
+  returning a stretched image. Install `sharp` and set `driver: "sharp"` if you
+  need centre-cropped thumbnails.
+- **Deleting a model deletes its files** — unless it soft-deletes, in which case
+  they wait for `forceDelete()`.
+- **Paths are keyed on uuid,** not the numeric id, so a public URL discloses
+  nothing about row counts.
+
+## Commands
+
+```bash
+bun zt media:clean [--force]
+bun zt media:regenerate [--model=Product] [--only=thumb,hero]
+```
+
+## Documentation
+
+Full guide: [Media Library](https://zerotal.dev/docs/media).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@zerotal/media",
+  "version": "1.3.0",
+  "license": "MIT",
+  "maturity": "experimental",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./commands": "./src/commands/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.3.0",
+    "@zerotal/orm": "1.3.0"
+  },
+  "peerDependencies": {
+    "@zerotal/queue": "^1.0.0",
+    "sharp": "^0.33 || ^0.34"
+  },
+  "peerDependenciesMeta": {
+    "@zerotal/queue": {
+      "optional": true
+    },
+    "sharp": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@zerotal/queue": "1.3.0",
+    "typescript": "^5.8.0"
+  },
+  "description": "Attach files to models: media collections, image conversions, responsive images, and ordering — on any Zerotal storage disk.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "media",
+    "uploads",
+    "images"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/media"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/media#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/Media.ts

@@ -0,0 +1,278 @@
+import type { Constructor, ModelQueryBuilder } from "@zerotal/orm";
+import { MediaItem } from "./MediaItem.ts";
+import { MediaAdder } from "./MediaAdder.ts";
+import { resolveCollection, type CollectionHost } from "./collections/resolve.ts";
+import { mediaState } from "./state.ts";
+import { fromDisk, fromPath, fromUrl, fromValue, type MediaSource } from "./sources.ts";
+import type { MediaCollections, MediaOwner } from "./types.ts";
+
+/**
+ * What the mixin needs from whatever it is composed onto.
+ *
+ * Declaring the shape here — rather than casting `this` at each use — is what
+ * keeps this file free of escape-hatch casts. `constructor` is typed as the
+ * concrete class so `mediaCollections` and `name` are reachable directly;
+ * `softDeletes` is whatever the `SoftDeletes` mixin set, if it is in the chain.
+ */
+interface MediaHost extends MediaOwner {
+  id: number | string;
+  readonly constructor: CollectionHost & { softDeletes?: boolean };
+}
+
+// Helpers live at module scope rather than as private methods: a mixin returns an
+// anonymous class type, and TypeScript refuses to emit declarations for one that
+// carries private members (TS4094). Every ORM mixin has the same shape.
+
+/** Every media row this model owns, before any collection filter. */
+function ownedQuery(self: MediaHost): ModelQueryBuilder<MediaItem> {
+  return MediaItem.query()
+    .where("model_type", self.constructor.name)
+    .where("model_id", String(self.id));
+}
+
+/**
+ * Adds media handling to a model.
+ *
+ * Compose it with `Model.using(...)` and declare the collections the model
+ * owns in a static `mediaCollections` field. Zerotal's equivalent of Laravel's
+ * `HasMedia` interface plus `InteractsWithMedia` trait, in one piece — named for
+ * how it reads at the call site: `Model.using(Media)`.
+ *
+ * ## Deleting
+ *
+ * Hard-deleting a model deletes every file attached to it — without that, an
+ * upload outlives the only row that knew where it was, and you keep paying for
+ * storage nothing can reach. **Soft deletes are left alone**: restoring a model
+ * whose images had already been destroyed would be worse than an orphaned file,
+ * so a `SoftDeletes` model keeps its media until `forceDelete()`.
+ *
+ * @example
+ * ```ts
+ * export class Product extends Model.using(Media) {
+ *   \@column() name!: string;
+ *
+ *   static override mediaCollections: MediaCollections = {
+ *     images: {
+ *       accepts: ["image/jpeg", "image/png"],
+ *       conversions: { thumb: { width: 200, height: 200 } },
+ *     },
+ *   };
+ * }
+ *
+ * const product = await Product.create({ name: "Kettle" });
+ * await product.addMedia(await ctx.file("photo")).toCollection("images");
+ * await product.getFirstMediaUrl("images", "thumb");
+ * ```
+ */
+export function Media<TBase extends Constructor>(Base: TBase) {
+  class MediaModel extends Base {
+    /**
+     * The collections this model owns. Override in the subclass.
+     *
+     * A collection must be declared before anything can be added to it: an
+     * undeclared name is nearly always a typo, and silently accepting one would
+     * hide the mistake until someone noticed an empty gallery.
+     */
+    static mediaCollections: MediaCollections = {};
+
+    /** Primary key, supplied by the model this is composed onto. */
+    declare id: number | string;
+
+    /**
+     * The concrete subclass, typed so its statics are reachable.
+     *
+     * `Object.prototype.constructor` is `Function`, which knows nothing of
+     * `mediaCollections`. Re-declaring it here is what lets every method below
+     * read the model's collections without a cast at each use.
+     */
+    declare readonly ["constructor"]: CollectionHost & { softDeletes?: boolean };
+
+    // ── Adding ───────────────────────────────────────────────────────────────
+
+    /**
+     * Attach a file. Nothing is read or written until `.toCollection(name)` is
+     * awaited.
+     *
+     * @param source - An `UploadedFile`, `File`, `Blob`, `Uint8Array` or `ArrayBuffer`.
+     * @param fileName - Overrides the name the source reports.
+     */
+    addMedia(source: MediaSource, fileName?: string): MediaAdder {
+      return new MediaAdder(this, this.constructor, fromValue(source, fileName));
+    }
+
+    /** Attach a file fetched over http(s). */
+    addMediaFromUrl(url: string): MediaAdder {
+      return new MediaAdder(
+        this,
+        this.constructor,
+        fromUrl(url, mediaState().config.maxConversionInputSize),
+      );
+    }
+
+    /** Attach a file already stored on one of the app's disks. */
+    addMediaFromDisk(path: string, disk?: string): MediaAdder {
+      return new MediaAdder(this, this.constructor, fromDisk(path, disk));
+    }
+
+    /** Attach a file from the local filesystem. */
+    addMediaFromPath(path: string): MediaAdder {
+      return new MediaAdder(this, this.constructor, fromPath(path));
+    }
+
+    /**
+     * Copy an existing media item onto this model.
+     *
+     * The bytes are re-read and re-stored under a fresh uuid, so the two items
+     * are fully independent — deleting either leaves the other's file intact.
+     * Name and custom properties carry over; chain the builder's methods to
+     * change them.
+     *
+     * @example
+     * await draft.copyMedia(original).toCollection("images");
+     */
+    copyMedia(media: MediaItem): MediaAdder {
+      return new MediaAdder(this, this.constructor, async () => ({
+        bytes: await media.bytes(),
+        originalName: media.fileName,
+      }))
+        .usingName(media.name)
+        .withCustomProperties(media.customProperties ?? {});
+    }
+
+    // ── Reading ──────────────────────────────────────────────────────────────
+
+    /** Every item in a collection, in order. */
+    async getMedia(collection = "default"): Promise<MediaItem[]> {
+      return ownedQuery(this)
+        .where("collection_name", collection)
+        .orderBy("order_column", "asc")
+        .orderBy("id", "asc")
+        .get();
+    }
+
+    /** The first item in a collection, or `null`. */
+    async getFirstMedia(collection = "default"): Promise<MediaItem | null> {
+      const all = await this.getMedia(collection);
+      return all[0] ?? null;
+    }
+
+    /**
+     * URL of the first item, or the collection's `fallbackUrl` when it is empty.
+     *
+     * Returns `""` when there is neither, so it can go straight into `src`
+     * without a null check.
+     *
+     * A conversion that has not been generated yet — a queued one, most likely —
+     * falls back to the original rather than to nothing, so a gallery is never
+     * blank while the queue catches up.
+     */
+    async getFirstMediaUrl(collection = "default", conversion?: string): Promise<string> {
+      const media = await this.getFirstMedia(collection);
+      if (media === null) return resolveCollection(this.constructor, collection).fallbackUrl ?? "";
+
+      const url = media.getUrl(conversion);
+      if (url === "" && conversion !== undefined) return media.getUrl();
+      return url;
+    }
+
+    /** Path of the first item, or the collection's `fallbackPath`. */
+    async getFirstMediaPath(collection = "default", conversion?: string): Promise<string> {
+      const media = await this.getFirstMedia(collection);
+      if (media === null) return resolveCollection(this.constructor, collection).fallbackPath ?? "";
+      return media.getPath(conversion);
+    }
+
+    /** Whether a collection holds anything. */
+    async hasMedia(collection = "default"): Promise<boolean> {
+      const rows = await ownedQuery(this).where("collection_name", collection).limit(1).get();
+      return rows.length > 0;
+    }
+
+    /** How many items a collection holds. */
+    async mediaCount(collection = "default"): Promise<number> {
+      const rows = await ownedQuery(this).where("collection_name", collection).get();
+      return rows.length;
+    }
+
+    // ── Removing ─────────────────────────────────────────────────────────────
+
+    /**
+     * Delete every item in a collection, files included.
+     *
+     * @returns How many items were removed.
+     */
+    async clearMediaCollection(collection = "default"): Promise<number> {
+      const all = await this.getMedia(collection);
+      for (const media of all) await media.delete();
+      return all.length;
+    }
+
+    /** Delete every item this model owns, across every collection. */
+    async clearAllMedia(): Promise<number> {
+      const all = await ownedQuery(this).get();
+      for (const media of all) await media.delete();
+      return all.length;
+    }
+
+    // ── Ordering ─────────────────────────────────────────────────────────────
+
+    /**
+     * Reorder a collection to match the given media ids.
+     *
+     * Ids missing from the list keep their relative order *after* the ones
+     * present, so handing in only the three items a drag-and-drop UI moved does
+     * what it looks like rather than silently discarding the rest.
+     */
+    async setMediaOrder(ids: Array<number | string>, collection = "default"): Promise<void> {
+      const all = await this.getMedia(collection);
+      const wanted = ids.map(String);
+
+      const ranked = [...all].sort((a, b) => {
+        const ai = wanted.indexOf(String(a.id));
+        const bi = wanted.indexOf(String(b.id));
+        if (ai !== -1 && bi !== -1) return ai - bi;
+        if (ai !== -1) return -1;
+        if (bi !== -1) return 1;
+        return 0;
+      });
+
+      for (const [index, media] of ranked.entries()) {
+        if (media.orderColumn === index) continue;
+        media.orderColumn = index;
+        await media.save();
+      }
+    }
+
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+
+    /**
+     * Delete the model, cascading to its files on a hard delete.
+     *
+     * A soft-deleting model keeps its media: `restore()` is supposed to give
+     * back the model you had, and it cannot do that if the images were destroyed
+     * on the way out. Those files go on `forceDelete()` instead.
+     */
+    async delete(): Promise<void> {
+      if (this.constructor.softDeletes !== true) await this.clearAllMedia();
+
+      // Reached through the base prototype rather than `super` because the mixin
+      // is generic over a bare constructor — the same reason every ORM mixin is.
+      const base = Base.prototype as { delete?: () => Promise<void> };
+      await base.delete?.call(this);
+    }
+
+    /**
+     * Permanently delete a soft-deleting model, taking its files with it.
+     *
+     * A no-op passthrough when `SoftDeletes` is not composed in — there is no
+     * `forceDelete` to extend, and `delete()` has already done the cascade.
+     */
+    async forceDelete(): Promise<void> {
+      await this.clearAllMedia();
+      const base = Base.prototype as { forceDelete?: () => Promise<void> };
+      await base.forceDelete?.call(this);
+    }
+  }
+
+  return MediaModel;
+}

package/src/MediaAdder.ts

@@ -0,0 +1,185 @@
+import { sniffContentType } from "@zerotal/core/http";
+import { MediaItem, pathGenerator } from "./MediaItem.ts";
+import { resolveCollection, type CollectionHost } from "./collections/resolve.ts";
+import { applyRetentionRules } from "./collections/retention.ts";
+import { ConversionRunner, partitionConversions } from "./conversions/ConversionRunner.ts";
+import { dispatchConversions, isQueueAvailable } from "./conversions/dispatch.ts";
+import { DisallowedMimeTypeError, FileTooLargeError, UnsavedOwnerError } from "./errors.ts";
+import { mediaState } from "./state.ts";
+import { defaultDiskName, diskFor, diskNameFor } from "./support/disks.ts";
+import type { SourceResolver } from "./sources.ts";
+import type { CollectionDefinition, MediaOwner, PendingMediaMeta } from "./types.ts";
+
+/**
+ * The pending file returned by `model.addMedia(...)`, awaiting a collection.
+ *
+ * Nothing is read, validated or written until {@link toCollection} runs — the
+ * builder just records intent, so the collection's own rules decide what is
+ * allowed before any bytes are buffered.
+ *
+ * @example
+ * await product
+ *   .addMedia(await ctx.file("photo"))
+ *   .usingName("Front view")
+ *   .withCustomProperties({ alt: "Front view of the kettle" })
+ *   .toCollection("images");
+ */
+export class MediaAdder {
+  #meta: PendingMediaMeta = {};
+  #fileName: string | undefined;
+
+  constructor(
+    private readonly owner: MediaOwner,
+    private readonly ownerClass: CollectionHost,
+    private readonly resolve: SourceResolver,
+  ) {}
+
+  /** Set the human-facing label. Defaults to the filename without its extension. */
+  usingName(name: string): this {
+    this.#meta.name = name;
+    return this;
+  }
+
+  /**
+   * Override the name written to disk.
+   *
+   * The extension is still taken from the file's own bytes: a name you chose is
+   * yours to get right, but the stored `Content-Type` is a security boundary and
+   * is never client-derived.
+   */
+  usingFileName(fileName: string): this {
+    this.#fileName = fileName;
+    return this;
+  }
+
+  /** Attach arbitrary JSON to the media row. */
+  withCustomProperties(properties: Record<string, unknown>): this {
+    this.#meta.customProperties = { ...(this.#meta.customProperties ?? {}), ...properties };
+    return this;
+  }
+
+  /** Set an explicit sort position. Defaults to the end of the collection. */
+  withOrder(order: number): this {
+    this.#meta.order = order;
+    return this;
+  }
+
+  /** Override the collection's disk for this one file. */
+  toDisk(disk: string): this {
+    this.#meta.disk = disk;
+    return this;
+  }
+
+  /**
+   * Store the file, create its row, and generate whatever the collection asks for.
+   *
+   * @param collection - Name of a collection the model declares.
+   * @returns The saved {@link MediaItem}, with inline conversions already generated.
+   * @throws {UnknownCollectionError} when the model declares no such collection.
+   * @throws {DisallowedMimeTypeError} when the sniffed type is not accepted.
+   * @throws {FileTooLargeError} when the file exceeds the collection's `maxSize`.
+   */
+  async toCollection(collection = "default"): Promise<MediaItem> {
+    if (this.owner.id === undefined || this.owner.id === null || this.owner.id === "") {
+      throw new UnsavedOwnerError(this.ownerClass.name);
+    }
+
+    const definition = resolveCollection(this.ownerClass, collection);
+    const { bytes, originalName } = await this.resolve();
+
+    const sniffed = sniffContentType(bytes);
+    this.guard(definition, collection, sniffed.contentType, bytes.byteLength);
+
+    const config = mediaState().config;
+    const diskName = diskNameFor(
+      this.#meta.disk ?? definition.disk,
+      diskNameFor(config.disk, defaultDiskName()),
+    );
+    const conversionsDiskName = definition.conversionsDisk ?? config.conversionsDisk;
+
+    const media = new MediaItem();
+    media.modelType = this.ownerClass.name;
+    media.modelId = String(this.owner.id);
+    media.uuid = crypto.randomUUID();
+    media.collectionName = collection;
+    media.name = this.#meta.name ?? _stripExtension(originalName);
+    media.fileName = this.#fileName ?? `original.${sniffed.extension}`;
+    media.mimeType = sniffed.contentType;
+    media.disk = diskName;
+    media.conversionsDisk = conversionsDiskName === "" ? null : conversionsDiskName;
+    media.size = bytes.byteLength;
+    media.manipulations = {};
+    media.customProperties = this.#meta.customProperties ?? {};
+    media.generatedConversions = {};
+    media.responsiveImages = {};
+    media.orderColumn = this.#meta.order ?? (await _nextOrder(this.ownerClass.name, this.owner.id));
+
+    // The row is saved before the bytes land so the uuid — which the path is
+    // built from — is fixed and unique before anything is written under it.
+    await media.save();
+
+    const path = `${pathGenerator().forOriginal(media)}/${media.fileName}`;
+    await diskFor(diskName).put(path, bytes, { contentType: sniffed.contentType });
+
+    await this.generate(media, definition);
+    await applyRetentionRules(this.ownerClass.name, this.owner.id, collection, definition, media);
+
+    return media;
+  }
+
+  /** Enforce the collection's admission rules against the sniffed type. */
+  private guard(
+    definition: CollectionDefinition,
+    collection: string,
+    contentType: string,
+    size: number,
+  ): void {
+    if (definition.accepts !== undefined && !definition.accepts.includes(contentType)) {
+      throw new DisallowedMimeTypeError(collection, contentType, definition.accepts);
+    }
+    if (definition.maxSize !== undefined && size > definition.maxSize) {
+      throw new FileTooLargeError(collection, size, definition.maxSize);
+    }
+  }
+
+  /** Run inline conversions now and hand the rest to the queue. */
+  private async generate(media: MediaItem, definition: CollectionDefinition): Promise<void> {
+    const state = mediaState();
+    const { inline, queued } = partitionConversions(
+      definition.conversions,
+      isQueueAvailable() && state.config.queueConversions,
+    );
+
+    const runner = new ConversionRunner(state.driver, state.config);
+    await runner.run(media, inline);
+
+    if (definition.responsive !== undefined && definition.responsive !== false) {
+      const widths = Array.isArray(definition.responsive)
+        ? definition.responsive
+        : state.config.responsiveWidths;
+      await runner.runResponsive(media, widths);
+    }
+
+    if (Object.keys(queued).length > 0) {
+      await dispatchConversions(media.id as number, Object.keys(queued));
+    }
+  }
+}
+
+/** Position one past the current end of the collection. */
+async function _nextOrder(modelType: string, modelId: number | string): Promise<number> {
+  const rows = await MediaItem.query()
+    .where("model_type", modelType)
+    .where("model_id", String(modelId))
+    .orderBy("order_column", "desc")
+    .limit(1)
+    .get();
+
+  const highest = rows[0]?.orderColumn;
+  return typeof highest === "number" ? highest + 1 : 0;
+}
+
+function _stripExtension(fileName: string): string {
+  const index = fileName.lastIndexOf(".");
+  return index > 0 ? fileName.slice(0, index) : fileName;
+}