@zerotal/media 1.4.0 → 1.5.0

package/src/index.ts

@@ -1,4 +1,9 @@
 // @zerotal/media — public API
+//
+// Test and advanced-wiring seams (state swapping, disk resolver overrides,
+// queue-bridge internals) live at `@zerotal/media/testing`. They are
+// deliberately not re-exported here: this entry point is what the package's
+// stability guarantee covers, and it should stay small enough to keep.
 
 // Model + model mixin
 // `Media` is the mixin — it reads as `Model.using(Media)`. `MediaItem` is one
@@ -19,7 +24,7 @@ export type { CollectionHost } from "./collections/resolve.ts";
 export { applyRetentionRules } from "./collections/retention.ts";
 
 // Conversions
-export { ConversionRunner, partitionConversions } from "./conversions/ConversionRunner.ts";
+export { ConversionRunner } from "./conversions/ConversionRunner.ts";
 export { BunImageDriver } from "./conversions/BunImageDriver.ts";
 export { SharpImageDriver } from "./conversions/SharpImageDriver.ts";
 export {
@@ -34,13 +39,7 @@ export type {
   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";
+export { isQueueAvailable, dispatchConversions } from "./conversions/dispatch.ts";
 
 // Paths
 export { DefaultPathGenerator } from "./paths/PathGenerator.ts";
@@ -50,15 +49,8 @@ export type { PathGenerator } from "./paths/PathGenerator.ts";
 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";
+// Disk resolution
+export { diskFor, defaultDiskName } from "./support/disks.ts";
 
 // Schema provisioning
 export { mediaSchemaConcern } from "./mediaSchemaConcern.ts";
@@ -67,10 +59,6 @@ export { mediaSchemaConcern } from "./mediaSchemaConcern.ts";
 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";
 

package/src/mediaSchemaConcern.ts

@@ -12,6 +12,8 @@ import { Schema } from "@zerotal/orm";
  *
  * 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.
+ *
+ * @internal — registered by MediaProvider so the `media` table provisions itself.
  */
 export const mediaSchemaConcern: ConcernDescriptor = {
   name: "media-schema",

package/src/paths/PathGenerator.ts

@@ -25,7 +25,7 @@ export interface PathGenerator {
  * media/<uuid>/responsive/640.webp
  * ```
  *
- * Keyed on `uuid` rather than the numeric `id` that Laravel's media library
+ * Keyed on `uuid` rather than the numeric `id` a media library normally
  * 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.

package/src/sources.ts

@@ -3,6 +3,7 @@ import { MediaError } from "./errors.ts";
 import { diskFor } from "./support/disks.ts";
 
 /** A file's bytes plus the name it arrived under. */
+/** @internal — source-resolution plumbing. */
 export interface ResolvedSource {
   bytes: Uint8Array;
   /** Original filename, used to derive the default media name. */
@@ -10,6 +11,7 @@ export interface ResolvedSource {
 }
 
 /** Anything that can be resolved to bytes on demand. */
+/** @internal — source-resolution plumbing. */
 export type SourceResolver = () => Promise<ResolvedSource>;
 
 /** Things `addMedia()` accepts directly. */
@@ -21,6 +23,8 @@ export type MediaSource = UploadedFile | File | Blob | Uint8Array | ArrayBuffer;
  * Resolution is deferred so a rule that can reject on metadata alone — a
  * collection that accepts only PDFs, say — does not have to buffer the file
  * first.
+ *
+ * @internal — source resolution; apps pass a `MediaSource` to `addMedia*`.
  */
 export function fromValue(source: MediaSource, fileName?: string): SourceResolver {
   if (source instanceof UploadedFile) {
@@ -66,6 +70,8 @@ export function fromValue(source: MediaSource, fileName?: string): SourceResolve
  *   often enough that downloading whatever arrives is how one request exhausts the
  *   heap; the limit is checked against `Content-Length` first and again against
  *   what actually arrived, since the header is a claim.
+ *
+ * @internal — source resolution; apps pass a `MediaSource` to `addMedia*`.
  */
 export function fromUrl(url: string, maxBytes: number): SourceResolver {
   return async () => {
@@ -108,6 +114,7 @@ export function fromUrl(url: string, maxBytes: number): SourceResolver {
 }
 
 /** Read a file already sitting on one of the app's storage disks. */
+/** @internal — source resolution; apps pass a `MediaSource` to `addMedia*`. */
 export function fromDisk(path: string, disk?: string): SourceResolver {
   return async () => {
     const bytes = await diskFor(disk).getBuffer(path);
@@ -119,6 +126,7 @@ export function fromDisk(path: string, disk?: string): SourceResolver {
 }
 
 /** Read a file from the local filesystem. */
+/** @internal — source resolution; apps pass a `MediaSource` to `addMedia*`. */
 export function fromPath(path: string): SourceResolver {
   return async () => {
     const file = Bun.file(path);

package/src/support/disks.ts

@@ -33,6 +33,8 @@ export function setDiskResolver(resolver: DiskResolver | null): void {
  * empty string is looked up literally and throws `DiskNotConfiguredError`. Media
  * config uses `""` to mean "inherit the default", so every lookup goes through
  * here rather than reaching for `Storage.disk()` directly.
+ *
+ * @internal — disk resolution.
  */
 export function diskFor(name?: string | null): StorageDriver {
   const trimmed = name?.trim();
@@ -65,6 +67,8 @@ export function setDefaultDiskName(name: string | null): void {
  *
  * Falls back to `""` when there is no app or no storage config to ask — the read
  * path treats that as "the default", which is the best answer available.
+ *
+ * @internal — disk resolution.
  */
 export function defaultDiskName(): string {
   if (_defaultName !== null) return _defaultName;

package/src/testing.ts

@@ -0,0 +1,35 @@
+/**
+ * Test and advanced-wiring seams for `@zerotal/media`.
+ *
+ * These let a test drive the package without standing up a container: swap the
+ * disk resolver, plant a config/driver pair, reset it afterwards. They are the
+ * package's own internals, exposed because testing media without them is
+ * genuinely awkward — not because they are part of the API.
+ *
+ * They live behind `@zerotal/media/testing` so the main entry point can be
+ * frozen while these stay free to change:
+ *
+ * ```ts
+ * import { setDiskResolver, resetMediaState } from "@zerotal/media/testing";
+ * ```
+ *
+ * Nothing here is covered by the package's stability guarantee. If you find
+ * yourself needing one of these in application code, that is a gap in the real
+ * API worth reporting.
+ */
+
+// Shared state — the config and driver every operation reads.
+export { mediaState, setMediaState, resetMediaState } from "./state.ts";
+export type { MediaState } from "./state.ts";
+
+// Disk resolution — the seam that lets tests skip building a container.
+export { setDiskResolver, setDefaultDiskName, diskNameFor } from "./support/disks.ts";
+export type { DiskResolver } from "./support/disks.ts";
+
+// Conversion dispatch — swap the queue for a spy, or force the inline path.
+export { setConversionDispatcher } from "./conversions/dispatch.ts";
+export type { ConversionDispatcher } from "./conversions/dispatch.ts";
+
+// Queue-bridge internals, reachable for tests that assert on job behaviour.
+export { performConversions, ownerClassFor } from "./conversions/queueBridge.ts";
+export { partitionConversions } from "./conversions/ConversionRunner.ts";

package/src/types.ts

@@ -24,8 +24,13 @@ export type ConversionFormat = SafeConversionFormat | "avif" | "heic";
  *   ratio. The result may be smaller than the box in one dimension.
  * - `fill` — stretch to exactly `width` × `height`, ignoring aspect ratio.
  * - `cover` — scale and centre-crop to exactly fill the box, preserving aspect
- *   ratio. **Requires an image driver that can crop**; the default
- *   `BunImageDriver` cannot, and says so with a named error.
+ *   ratio. Needs both `width` and `height`: given one, there is nothing to crop
+ *   away and it behaves as `inside`.
+ *
+ * With `withoutEnlargement` (the default), a source too small to fill the box is
+ * never scaled up — `cover` then yields the largest centre window the source can
+ * supply, which may not have the requested aspect ratio. A 300×500 source asked
+ * to cover 400×400 gives 300×400.
  */
 export type ConversionFit = "inside" | "fill" | "cover";
 
@@ -43,6 +48,15 @@ export interface ConversionDefinition {
   quality?: number;
   /** Clockwise rotation in degrees applied before resizing. */
   rotate?: number;
+  /**
+   * Allow scaling a source *up* to meet the target box. Default: `false`.
+   *
+   * Off by default because upscaling produces a larger file that looks worse.
+   * Turn it on when the exact box matters more than fidelity — a `cover`
+   * thumbnail for a fixed-size grid slot, say, which would otherwise come back
+   * undersized (and off-aspect) for small sources.
+   */
+  allowEnlargement?: boolean;
   /** Generate this conversion on the queue instead of inline. Default: `false`. */
   queued?: boolean;
 }