@holo-js/media 0.3.28 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holo-JS contributors
+
+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/dist/.holo-build-fingerprint

@@ -0,0 +1 @@
+90fe1fb20b9e79de3879f0aadd27cc72d3e9fdb5b7a2bd18449eddda2c91dd49

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _holo_js_db from '@holo-js/db';
-import { Entity, TableDefinition, ModelRecord, RelationMap, DynamicRelationResolver, ModelQueryBuilder, ModelRelationPath, RelationConstraintDefinition, RelatedColumnNameForRelationPath, ModelCollection, EntityWithLoaded, PaginatedResult, SimplePaginatedResult, CursorPaginatedResult, ResolveEagerLoads } from '@holo-js/db';
+import { Entity, TableDefinition, ModelRecord, RelationMap, DynamicRelationResolver, ModelQueryBuilder, ModelRelationPath, ModelRelationName, RelationNameConstraintMapGuarded, RelatedColumnNameForRelationPath, AggregateRelationConstraintMap, AggregateRelatedColumnNameOfKeys, RelationConstraintFor, ResolveEagerLoads, ModelCollection, EntityWithLoaded, PaginatedResult, SimplePaginatedResult, CursorPaginatedResult, RelationConstraintMap } from '@holo-js/db';
 import { StorageContent } from '@holo-js/storage/runtime';
 export { HoloMediaConfig, defineMediaConfig, normalizeMediaConfig } from './projectConfig.js';
 import { QueueJobDefinition, QueueJsonValue } from '@holo-js/queue';
@@ -213,15 +213,21 @@ declare class MediaItem<TCollectionName extends string = string, TConversionName
 
 type MediaSourceInput = string | BinaryContent | {
     readonly path: string;
-} | {
-    readonly url: string;
-    readonly fileName?: string;
-    readonly name?: string;
 } | {
     readonly contents: BinaryContent;
     readonly fileName?: string;
     readonly name?: string;
 };
+declare class RemoteMediaSource {
+    readonly url: string;
+    constructor(url: string);
+}
+declare class StoredMediaSource {
+    readonly disk: string;
+    readonly path: string;
+    constructor(disk: string, path: string);
+}
+type MediaAdderSource = MediaSourceInput | RemoteMediaSource | StoredMediaSource;
 type MediaAddErrorCode = 'max_size_exceeded' | 'invalid_mime_type' | 'invalid_extension';
 type MediaAddError = {
     readonly code: MediaAddErrorCode;
@@ -244,7 +250,7 @@ declare class MediaAdder<TEntity extends Entity<TableDefinition> = Entity<TableD
     private readonly entity;
     private readonly source;
     private readonly state;
-    constructor(entity: TEntity, source: MediaSourceInput, state?: {
+    constructor(entity: TEntity, source: MediaAdderSource, state?: {
         readonly fileName?: string;
         readonly name?: string;
         readonly disk?: string;
@@ -262,6 +268,7 @@ type MediaEnabledEntity<TTable extends TableDefinition = TableDefinition, TColle
 type MediaEnabledEntityMethods<TCollectionName extends string, TConversionName extends string> = {
     addMedia(source: MediaSourceInput): MediaAdder<Entity<TableDefinition>, TCollectionName, TConversionName>;
     addMediaFromUrl(url: string): MediaAdder<Entity<TableDefinition>, TCollectionName, TConversionName>;
+    addMediaFromDisk(path: string, disk: string): MediaAdder<Entity<TableDefinition>, TCollectionName, TConversionName>;
     getMedia(collectionName?: TCollectionName): Promise<MediaItem<TCollectionName, TConversionName, Entity<TableDefinition>>[]>;
     getMediaUrls(collectionName?: TCollectionName, conversionName?: TConversionName): Promise<string[]>;
     getMediaPaths(collectionName?: TCollectionName, conversionName?: TConversionName): Promise<string[]>;
@@ -302,15 +309,16 @@ type MediaEnabledFunction<TFunction, TCollectionName extends string, TConversion
     (...args: TArgs1): MediaEnabledResult<TReturn1, TCollectionName, TConversionName>;
     (...args: TArgs2): MediaEnabledResult<TReturn2, TCollectionName, TConversionName>;
 } : TFunction extends (...args: infer TArgs) => infer TReturn ? (...args: TArgs) => MediaEnabledResult<TReturn, TCollectionName, TConversionName> : TFunction;
+type MediaRelationCallbackMethod = 'whereHas' | 'orWhereHas' | 'whereDoesntHave' | 'orWhereDoesntHave' | 'whereRelation' | 'orWhereRelation' | 'withWhereHas' | 'withCount' | 'withExists' | 'withSum' | 'withAvg' | 'withMin' | 'withMax';
 type MediaEnabledQueryBuilder<TBuilder, TCollectionName extends string, TConversionName extends string> = {
-    [K in keyof TBuilder]: K extends 'with' ? MediaEnabledQueryBuilderWith<TBuilder, TCollectionName, TConversionName> : K extends 'withCount' | 'withExists' ? MediaEnabledRelationAggregate<TBuilder, TCollectionName, TConversionName> : K extends 'withSum' | 'withAvg' | 'withMin' | 'withMax' ? MediaEnabledRelationColumnAggregate<TBuilder, TCollectionName, TConversionName> : MediaEnabledFunction<TBuilder[K], TCollectionName, TConversionName>;
+    [K in keyof TBuilder]: K extends 'with' ? MediaEnabledQueryBuilderWith<TBuilder, TCollectionName, TConversionName> : K extends 'withCount' | 'withExists' ? MediaEnabledRelationAggregate<TBuilder, TCollectionName, TConversionName> : K extends 'withSum' | 'withAvg' | 'withMin' | 'withMax' ? MediaEnabledRelationColumnAggregate<TBuilder, TCollectionName, TConversionName> : K extends 'whereHas' | 'orWhereHas' | 'whereDoesntHave' | 'orWhereDoesntHave' ? MediaEnabledRelationFilter<TBuilder, TCollectionName, TConversionName> : K extends 'whereRelation' | 'orWhereRelation' ? MediaEnabledRelationColumnFilter<TBuilder, TCollectionName, TConversionName> : K extends 'withWhereHas' ? MediaEnabledWithWhereHas<TBuilder, TCollectionName, TConversionName> : MediaEnabledFunction<TBuilder[K], TCollectionName, TConversionName>;
 };
 type MediaEnabledPaginatedResult<TResult, TPaginator, TCollectionName extends string, TConversionName extends string> = Omit<TResult, keyof TPaginator> & TPaginator & (TResult extends {
     readonly data: infer TData;
 } ? {
     readonly data: MediaEnabledResult<TData, TCollectionName, TConversionName>;
 } : Record<never, never>);
-type MediaEnabledResult<TValue, TCollectionName extends string, TConversionName extends string> = TValue extends Promise<infer TResult> ? Promise<MediaEnabledResult<TResult, TCollectionName, TConversionName>> : TValue extends AsyncGenerator<infer TYield, infer TReturn, infer TNext> ? AsyncGenerator<MediaEnabledResult<TYield, TCollectionName, TConversionName>, TReturn, TNext> : TValue extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded> ? MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded>, TCollectionName, TConversionName> : TValue extends ModelCollection<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TItem> ? TItem extends Entity<TTable, TRelations> ? ModelCollection<TTable, TRelations, MediaEnabledEntityResult<TItem, TCollectionName, TConversionName>> : TValue : TValue extends PaginatedResult<infer TItem> ? MediaEnabledPaginatedResult<TValue, PaginatedResult<MediaEnabledResult<TItem, TCollectionName, TConversionName>>, TCollectionName, TConversionName> : TValue extends SimplePaginatedResult<infer TItem> ? MediaEnabledPaginatedResult<TValue, SimplePaginatedResult<MediaEnabledResult<TItem, TCollectionName, TConversionName>>, TCollectionName, TConversionName> : TValue extends CursorPaginatedResult<infer TItem> ? MediaEnabledPaginatedResult<TValue, CursorPaginatedResult<MediaEnabledResult<TItem, TCollectionName, TConversionName>>, TCollectionName, TConversionName> : MediaEnabledEntityResult<TValue, TCollectionName, TConversionName>;
+type MediaEnabledResult<TValue, TCollectionName extends string, TConversionName extends string> = TValue extends Promise<infer TResult> ? Promise<MediaEnabledResult<TResult, TCollectionName, TConversionName>> : TValue extends AsyncGenerator<infer TYield, infer TReturn, infer TNext> ? AsyncGenerator<MediaEnabledResult<TYield, TCollectionName, TConversionName>, TReturn, TNext> : TValue extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded, infer TScopes extends Readonly<Record<string, unknown>>> ? MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName> : TValue extends ModelCollection<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TItem, infer TScopes extends Readonly<Record<string, unknown>>> ? TItem extends Entity<TTable, TRelations> ? ModelCollection<TTable, TRelations, MediaEnabledEntityResult<TItem, TCollectionName, TConversionName>, TScopes> : TValue : TValue extends PaginatedResult<infer TItem> ? MediaEnabledPaginatedResult<TValue, PaginatedResult<MediaEnabledResult<TItem, TCollectionName, TConversionName>>, TCollectionName, TConversionName> : TValue extends SimplePaginatedResult<infer TItem> ? MediaEnabledPaginatedResult<TValue, SimplePaginatedResult<MediaEnabledResult<TItem, TCollectionName, TConversionName>>, TCollectionName, TConversionName> : TValue extends CursorPaginatedResult<infer TItem> ? MediaEnabledPaginatedResult<TValue, CursorPaginatedResult<MediaEnabledResult<TItem, TCollectionName, TConversionName>>, TCollectionName, TConversionName> : MediaEnabledEntityResult<TValue, TCollectionName, TConversionName>;
 type MediaModelStatic = {
     readonly definition: {
         readonly name: string;
@@ -320,28 +328,39 @@ type MediaModelStatic = {
     readonly resolveRelationUsing: (name: string, resolver: DynamicRelationResolver) => unknown;
 };
 type MediaRelationPath<TRelations extends RelationMap> = ModelRelationPath<TRelations>;
-type MediaRelationConstraint<TTable extends TableDefinition, TRelations extends RelationMap> = RelationConstraintDefinition & ((query: ModelQueryBuilder<TTable, TRelations>) => unknown);
-type MediaRelationConstraintMap<TRelations extends RelationMap> = Readonly<Partial<Record<MediaRelationPath<TRelations>, MediaRelationConstraint<TableDefinition, TRelations>>>>;
-type MediaEnabledQueryBuilderWith<TBuilder, TCollectionName extends string, TConversionName extends string> = TBuilder extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded> ? {
-    <TPaths extends readonly MediaRelationPath<TRelations>[]>(...relations: TPaths): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded & ResolveEagerLoads<TRelations, TPaths>>, TCollectionName, TConversionName>;
-    <TPath extends MediaRelationPath<TRelations>>(relation: TPath, constraint: MediaRelationConstraint<TTable, TRelations>): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded & ResolveEagerLoads<TRelations, readonly [TPath]>>, TCollectionName, TConversionName>;
-    (relations: MediaRelationConstraintMap<TRelations>): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded>, TCollectionName, TConversionName>;
-    <TPaths extends readonly MediaRelationPath<TRelations>[]>(relations: TPaths): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded & ResolveEagerLoads<TRelations, TPaths>>, TCollectionName, TConversionName>;
+type MediaEnabledQueryBuilderWith<TBuilder, TCollectionName extends string, TConversionName extends string> = TBuilder extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded, infer TScopes extends Readonly<Record<string, unknown>>> ? {
+    <TPaths extends readonly MediaRelationPath<TRelations>[]>(...relations: TPaths): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded & ResolveEagerLoads<TRelations, TPaths>, TScopes>, TCollectionName, TConversionName>;
+    <TPath extends MediaRelationPath<TRelations>>(relation: TPath, constraint: RelationConstraintFor<TRelations, TPath>): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded & ResolveEagerLoads<TRelations, readonly [TPath]>, TScopes>, TCollectionName, TConversionName>;
+    (relations: RelationConstraintMap<TRelations>): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName>;
+    <TPaths extends readonly MediaRelationPath<TRelations>[]>(relations: TPaths): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded & ResolveEagerLoads<TRelations, TPaths>, TScopes>, TCollectionName, TConversionName>;
 } : TBuilder extends {
     with: infer TWith;
 } ? MediaEnabledFunction<TWith, TCollectionName, TConversionName> : never;
-type MediaEnabledRelationAggregate<TBuilder, TCollectionName extends string, TConversionName extends string> = TBuilder extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded> ? {
-    (...relations: readonly MediaRelationPath<TRelations>[]): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded>, TCollectionName, TConversionName>;
-    (relations: MediaRelationConstraintMap<TRelations>): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded>, TCollectionName, TConversionName>;
+type MediaEnabledRelationAggregate<TBuilder, TCollectionName extends string, TConversionName extends string> = TBuilder extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded, infer TScopes extends Readonly<Record<string, unknown>>> ? {
+    (first: ModelRelationName<TRelations>, ...rest: readonly ModelRelationName<TRelations>[]): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName>;
+    <TConstraints extends RelationNameConstraintMapGuarded<TRelations, TConstraints>>(relations: TConstraints): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName>;
 } : never;
-type MediaEnabledRelationColumnAggregate<TBuilder, TCollectionName extends string, TConversionName extends string> = TBuilder extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded> ? <TPath extends MediaRelationPath<TRelations>>(first: TPath | MediaRelationConstraintMap<TRelations>, column: RelatedColumnNameForRelationPath<TRelations, TPath>, ...rest: readonly MediaRelationPath<TRelations>[]) => MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded>, TCollectionName, TConversionName> : never;
+type DistributiveKeysOfObject<TConstraints> = TConstraints extends unknown ? keyof TConstraints : never;
+type AggregateKeysOfObject<TConstraints> = TConstraints extends unknown ? `${Extract<keyof TConstraints, string | number>}` : never;
+type MediaEnabledRelationColumnAggregate<TBuilder, TCollectionName extends string, TConversionName extends string> = TBuilder extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded, infer TScopes extends Readonly<Record<string, unknown>>> ? {
+    <TRelationName extends ModelRelationName<TRelations>>(first: TRelationName, column: RelatedColumnNameForRelationPath<TRelations, TRelationName>, ...rest: readonly ModelRelationName<TRelations>[]): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName>;
+    <TConstraints extends AggregateRelationConstraintMap<TRelations, Extract<keyof TConstraints, string>>, _TNoExplicitArgument extends never>(first: TConstraints, column: AggregateRelatedColumnNameOfKeys<TRelations, AggregateKeysOfObject<TConstraints>>, ...rest: readonly ModelRelationName<TRelations>[]): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName>;
+    <TKey extends string>(first: NoInfer<TKey> | AggregateRelationConstraintMap<TRelations, TKey>, column: AggregateRelatedColumnNameOfKeys<TRelations, TKey>, ...rest: readonly ModelRelationName<TRelations>[]): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName>;
+    <TConstraints extends RelationNameConstraintMapGuarded<TRelations, TConstraints> & ([DistributiveKeysOfObject<TConstraints>] extends [ModelRelationName<TRelations>] ? unknown : never), _TNoExplicitArgument extends never>(first: TConstraints, column: RelatedColumnNameForRelationPath<TRelations, ModelRelationName<TRelations>>, ...rest: readonly ModelRelationName<TRelations>[]): MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName>;
+} : never;
+type MediaEnabledRelationFilter<TBuilder, TCollectionName extends string, TConversionName extends string> = TBuilder extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded, infer TScopes extends Readonly<Record<string, unknown>>> ? <TPath extends MediaRelationPath<TRelations>>(relation: TPath, constraint?: RelationConstraintFor<TRelations, TPath>) => MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName> : never;
+type MediaEnabledRelationColumnFilter<TBuilder, TCollectionName extends string, TConversionName extends string> = TBuilder extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded, infer TScopes extends Readonly<Record<string, unknown>>> ? <TRelationPath extends MediaRelationPath<TRelations>>(relation: TRelationPath, column: RelatedColumnNameForRelationPath<TRelations, TRelationPath>, operator: unknown, value?: unknown) => MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded, TScopes>, TCollectionName, TConversionName> : never;
+type MediaEnabledWithWhereHas<TBuilder, TCollectionName extends string, TConversionName extends string> = TBuilder extends ModelQueryBuilder<infer TTable extends TableDefinition, infer TRelations extends RelationMap, infer TLoaded, infer TScopes extends Readonly<Record<string, unknown>>> ? <TPath extends MediaRelationPath<TRelations>>(relation: TPath, constraint?: RelationConstraintFor<TRelations, TPath>) => MediaEnabledQueryBuilder<ModelQueryBuilder<TTable, TRelations, TLoaded & ResolveEagerLoads<TRelations, readonly [TPath]>, TScopes>, TCollectionName, TConversionName> : never;
 type MediaEnabledStaticWith<TModel extends MediaModelStatic, TCollectionName extends string, TConversionName extends string> = TModel extends {
     query(): infer TBuilder;
 } ? MediaEnabledQueryBuilderWith<TBuilder, TCollectionName, TConversionName> : TModel extends {
     with: infer TWith;
 } ? MediaEnabledFunction<TWith, TCollectionName, TConversionName> : never;
+type MediaEnabledStaticRelationCallbackMethod<TModel, TKey extends keyof TModel, TCollectionName extends string, TConversionName extends string> = TModel extends {
+    query(): infer TBuilder;
+} ? TKey extends keyof TBuilder ? MediaEnabledQueryBuilder<TBuilder, TCollectionName, TConversionName>[TKey] : never : never;
 type MediaEnabledModel<TModel extends MediaModelStatic, TDefinition extends MediaDefinitionInput> = {
-    [K in keyof TModel]: K extends 'with' ? MediaEnabledStaticWith<TModel, MediaCollectionName<TDefinition>, MediaConversionName<TDefinition>> : MediaEnabledFunction<TModel[K], MediaCollectionName<TDefinition>, MediaConversionName<TDefinition>>;
+    [K in keyof TModel]: K extends 'with' ? MediaEnabledStaticWith<TModel, MediaCollectionName<TDefinition>, MediaConversionName<TDefinition>> : K extends MediaRelationCallbackMethod ? MediaEnabledStaticRelationCallbackMethod<TModel, K, MediaCollectionName<TDefinition>, MediaConversionName<TDefinition>> : MediaEnabledFunction<TModel[K], MediaCollectionName<TDefinition>, MediaConversionName<TDefinition>>;
 };
 declare function defineMediaModel<TModel extends MediaModelStatic, const TDefinition extends MediaDefinitionInput>(model: TModel, definition: TDefinition | MediaDefinitionFactory<TDefinition>): MediaEnabledModel<TModel, TDefinition>;
 
@@ -366,4 +385,5 @@ declare function dispatchQueuedMediaConversions(payload: MediaGenerateConversion
 declare function createDefaultMediaConversionExecutor(): MediaConversionExecutor;
 declare const defaultMediaConversionExecutor: MediaConversionExecutor;
 
-export { type CollectionNamesOf, type ConversionNamesOf, MEDIA_GENERATE_CONVERSIONS_JOB, Media, type MediaAddResult, MediaAdder, type MediaCollectionBuilder, type MediaCollectionDefinition, type MediaConversionBuilder, type MediaConversionDefinition, type MediaConversionExecutor, type MediaConversionExecutorInput, type MediaConversionExecutorResult, type MediaConversionExecutorSource, type MediaConversionFit, type MediaConversionFormat, type MediaConversionPathInput, type MediaDefinitionFactory, type MediaDefinitionHelpers, type MediaDefinitionInput, type MediaEnabledEntity, type MediaEnabledModel, type MediaGenerateConversionsPayload, type MediaGenerateConversionsResult, MediaItem, type MediaOriginalPathInput, type MediaPathGenerator, type MediaSourceInput, type NormalizedMediaCollectionDefinition, type NormalizedMediaConversionDefinition, type NormalizedMediaDefinition, type StoredMediaConversion, collection, conversion, createDefaultMediaConversionExecutor, defaultMediaConversionExecutor, defineMediaModel, dispatchQueuedMediaConversions, ensureMediaQueueJobRegistered, getMediaConversionExecutor, getMediaDefinition, getMediaDefinitionForMorphClass, getMediaPathGenerator, normalizeCollectionDefinitions, normalizeConversionDefinitions, normalizeMediaDefinition, registerMediaDefinition, requireMediaDefinition, requireMediaDefinitionForMorphClass, resetMediaPathGenerator, resetMediaRuntime, resolveMediaCollection, resolveMediaConversion, resolveMediaDefinition, runMediaGenerateConversionsJob, setMediaConversionExecutor, setMediaPathGenerator };
+export { MEDIA_GENERATE_CONVERSIONS_JOB, Media, MediaAdder, MediaItem, collection, conversion, createDefaultMediaConversionExecutor, defaultMediaConversionExecutor, defineMediaModel, dispatchQueuedMediaConversions, ensureMediaQueueJobRegistered, getMediaConversionExecutor, getMediaDefinition, getMediaDefinitionForMorphClass, getMediaPathGenerator, normalizeCollectionDefinitions, normalizeConversionDefinitions, normalizeMediaDefinition, registerMediaDefinition, requireMediaDefinition, requireMediaDefinitionForMorphClass, resetMediaPathGenerator, resetMediaRuntime, resolveMediaCollection, resolveMediaConversion, resolveMediaDefinition, runMediaGenerateConversionsJob, setMediaConversionExecutor, setMediaPathGenerator };
+export type { CollectionNamesOf, ConversionNamesOf, MediaAddResult, MediaCollectionBuilder, MediaCollectionDefinition, MediaConversionBuilder, MediaConversionDefinition, MediaConversionExecutor, MediaConversionExecutorInput, MediaConversionExecutorResult, MediaConversionExecutorSource, MediaConversionFit, MediaConversionFormat, MediaConversionPathInput, MediaDefinitionFactory, MediaDefinitionHelpers, MediaDefinitionInput, MediaEnabledEntity, MediaEnabledModel, MediaGenerateConversionsPayload, MediaGenerateConversionsResult, MediaOriginalPathInput, MediaPathGenerator, MediaSourceInput, NormalizedMediaCollectionDefinition, NormalizedMediaConversionDefinition, NormalizedMediaDefinition, StoredMediaConversion };

package/dist/index.mjs

@@ -11,6 +11,7 @@ import { Entity } from "@holo-js/db";
 
 // src/runtime/image.ts
 import { mimeTypeFromFileName } from "@holo-js/kernel/file-content";
+import { imageDecodingLimits } from "@holo-js/kernel/image-decoding";
 
 // src/runtime/binary.ts
 import { basename, extname } from "path";
@@ -102,10 +103,16 @@ function createDefaultMediaConversionExecutor() {
       const outputFormat = normalizeOutputFormat(source.extension, conversion2.format);
       try {
         const sharp = await loadSharp();
-        let pipeline = sharp(await toBuffer(source.contents), {
+        const image = sharp(await toBuffer(source.contents), {
           animated: true,
-          failOn: "warning"
-        }).rotate();
+          failOn: "warning",
+          limitInputPixels: imageDecodingLimits.maximumDecodedPixels
+        });
+        const metadata = await image.metadata();
+        if ((metadata.pages ?? 1) > imageDecodingLimits.maximumFrames) {
+          throw new Error(`The image has more than ${imageDecodingLimits.maximumFrames} frames.`);
+        }
+        let pipeline = image.rotate();
         if (conversion2.width || conversion2.height) {
           pipeline = pipeline.resize({
             width: conversion2.width,
@@ -150,7 +157,8 @@ function createDefaultMediaConversionExecutor() {
         };
       } catch (error) {
         throw new Error(
-          `[Holo Media] Failed to generate conversion "${conversion2.name}" for "${source.fileName}": ${error.message}`
+          `[Holo Media] Failed to generate conversion "${conversion2.name}" for "${source.fileName}": ${error.message}`,
+          { cause: error }
         );
       }
     }
@@ -346,8 +354,14 @@ import { BlockList, isIP } from "net";
 import { tmpdir } from "os";
 import { basename as basename2, resolve, sep } from "path";
 import { Readable } from "stream";
+import { config } from "@holo-js/config";
+import { localStoragePathInternals } from "@holo-js/kernel";
 import { inspectFileContent } from "@holo-js/kernel/file-content";
-import { Storage as Storage4 } from "@holo-js/storage/runtime";
+import {
+  Storage as Storage4,
+  StorageMetadataUnsupportedError,
+  StorageStreamingUnsupportedError
+} from "@holo-js/storage/runtime";
 
 // src/queue.ts
 import {
@@ -359,6 +373,7 @@ import {
 import { connectionAsyncContext } from "@holo-js/db";
 
 // src/model/conversions.ts
+import { randomBytes } from "crypto";
 import { mimeTypeFromFileName as mimeTypeFromFileName2 } from "@holo-js/kernel/file-content";
 import { Storage as Storage2 } from "@holo-js/storage/runtime";
 
@@ -366,21 +381,16 @@ import { Storage as Storage2 } from "@holo-js/storage/runtime";
 import { DB } from "@holo-js/db";
 import { Storage } from "@holo-js/storage/runtime";
 var MediaMutation = class {
-  written = [];
+  created = [];
   async put(disk, path, contents) {
-    const previous = await Storage.disk(disk).getBytes(path);
-    this.written.push({ disk, path, previous });
+    this.created.push({ disk, path });
     await Storage.disk(disk).put(path, contents);
   }
   async compensate() {
     const failures = [];
-    for (const file of this.written.splice(0).reverse()) {
+    for (const file of this.created.splice(0).reverse()) {
       try {
-        if (file.previous) {
-          await Storage.disk(file.disk).put(file.path, file.previous);
-        } else {
-          await Storage.disk(file.disk).delete(file.path);
-        }
+        await Storage.disk(file.disk).delete(file.path);
       } catch (error) {
         failures.push(error);
       }
@@ -389,41 +399,62 @@ var MediaMutation = class {
     if (failures.length > 1) throw new AggregateError(failures, "[Holo Media] File compensation failed.");
   }
 };
+async function compensateAfterFailure(mutation, error) {
+  try {
+    await mutation.compensate();
+  } catch (cleanupError) {
+    return new AggregateError([error, cleanupError], "[Holo Media] File compensation failed.");
+  }
+  return error;
+}
 async function runMediaMutation(options) {
   const mutation = new MediaMutation();
-  return await DB.writeTransaction(async (transaction) => {
-    transaction.afterRollback(async () => {
-      const failures = [];
-      try {
-        await mutation.compensate();
-      } catch (error) {
-        failures.push(error);
-      }
-      try {
-        await options.afterRollback?.();
-      } catch (error) {
-        failures.push(error);
-      }
-      if (failures.length === 1) throw failures[0];
-      if (failures.length > 1) throw new AggregateError(failures, "[Holo Media] Rollback restoration failed.");
-    });
-    const result = await options.operation(mutation);
-    transaction.afterCommit(async () => {
-      const failures = [];
-      for (const effect of options.afterCommit ?? []) {
+  let written;
+  try {
+    written = await options.write(mutation);
+  } catch (error) {
+    throw await compensateAfterFailure(mutation, error);
+  }
+  let transactionStarted = false;
+  try {
+    return await DB.writeTransaction(async (transaction) => {
+      transactionStarted = true;
+      transaction.afterRollback(async () => {
+        const failures = [];
         try {
-          await effect(result);
+          await mutation.compensate();
         } catch (error) {
           failures.push(error);
         }
-      }
-      options.afterEffects?.();
-      if (failures.length === 0) return;
-      const cause = failures.length === 1 ? failures[0] : new AggregateError(failures, "[Holo Media] Post-commit effects failed.");
-      throw new Error(options.committedMessage, { cause });
+        try {
+          await options.afterRollback?.();
+        } catch (error) {
+          failures.push(error);
+        }
+        if (failures.length === 1) throw failures[0];
+        if (failures.length > 1) throw new AggregateError(failures, "[Holo Media] Rollback restoration failed.");
+      });
+      const result = await options.operation(mutation, written);
+      transaction.afterCommit(async () => {
+        const failures = [];
+        for (const effect of options.afterCommit ?? []) {
+          try {
+            await effect(result);
+          } catch (error) {
+            failures.push(error);
+          }
+        }
+        options.afterEffects?.();
+        if (failures.length === 0) return;
+        const cause = failures.length === 1 ? failures[0] : new AggregateError(failures, "[Holo Media] Post-commit effects failed.");
+        throw new Error(options.committedMessage, { cause });
+      });
+      return result;
     });
-    return result;
-  });
+  } catch (error) {
+    if (transactionStarted) throw error;
+    throw await compensateAfterFailure(mutation, error);
+  }
 }
 async function removeStoredFiles(files, retained = []) {
   const failures = [];
@@ -451,6 +482,7 @@ async function deleteMediaItems(items, owner) {
   if (items.length === 0) return;
   await runMediaMutation({
     committedMessage: "[Holo Media] Deletion remains committed; post-commit file cleanup failed.",
+    write: async () => void 0,
     operation: async () => {
       for (const item of items) await item.getEntity().delete();
       owner?.forgetRelation("media");
@@ -531,7 +563,13 @@ function resolveQueuedConversionNames(options) {
     ).filter((conversion2) => conversion2.queued).map((conversion2) => conversion2.name)
   );
 }
-async function generateStoredConversions(options) {
+function withUniqueSuffix(path) {
+  const token = randomBytes(8).toString("hex");
+  const slash = path.lastIndexOf("/");
+  const dot = path.lastIndexOf(".");
+  return dot > slash + 1 ? `${path.slice(0, dot)}.${token}${path.slice(dot)}` : `${path}.${token}`;
+}
+async function writeStoredConversions(options) {
   const requested = normalizeRequestedConversions(options.requestedConversions);
   const matchingConversions = resolveMatchingConversions(
     options.definition,
@@ -539,9 +577,6 @@ async function generateStoredConversions(options) {
     requested,
     { includeQueued: options.includeQueued === true }
   );
-  if (matchingConversions.length === 0) {
-    return Object.freeze({});
-  }
   const generatedConversions = /* @__PURE__ */ Object.create(null);
   const executor = getMediaConversionExecutor();
   for (const conversion2 of matchingConversions) {
@@ -554,7 +589,7 @@ async function generateStoredConversions(options) {
       continue;
     }
     const generatedFileName = sanitizeFileName(generated.fileName ?? options.source.fileName);
-    const conversionPath = getMediaPathGenerator().conversionPath({
+    const plannedPath = getMediaPathGenerator().conversionPath({
       uuid: options.source.uuid,
       fileName: options.source.fileName,
       extension: options.source.extension,
@@ -562,27 +597,22 @@ async function generateStoredConversions(options) {
       conversion: conversion2,
       generatedFileName
     });
-    const targetDisk = generated.disk ?? options.conversionsDisk;
-    const conversionMimeType = generated.mimeType?.trim() || mimeTypeFromFileName2(generatedFileName) || void 0;
-    const conversionContents = await toBinaryContent(generated.contents);
-    await options.mutation.put(targetDisk, conversionPath, conversionContents);
+    const path = options.unique ? withUniqueSuffix(plannedPath) : plannedPath;
+    const disk = generated.disk ?? options.conversionsDisk;
+    const contents = await toBinaryContent(generated.contents);
+    await options.mutation.put(disk, path, contents);
     generatedConversions[conversion2.name] = Object.freeze({
-      path: conversionPath,
-      disk: targetDisk,
+      path,
+      disk,
       fileName: generatedFileName,
-      mimeType: conversionMimeType,
-      size: getContentSize(conversionContents)
+      mimeType: generated.mimeType?.trim() || mimeTypeFromFileName2(generatedFileName) || void 0,
+      size: getContentSize(contents)
     });
   }
   return Object.freeze(generatedConversions);
 }
-async function deleteObsoleteConversions(current, next, fallbackDisk, requested) {
-  const obsolete = Object.entries(current).filter(([name, conversion2]) => {
-    if (requested?.length && !requested.includes(name) || !conversion2?.path) return false;
-    const nextConversion = next[name];
-    return nextConversion?.path !== conversion2.path || (nextConversion.disk ?? fallbackDisk) !== (conversion2.disk ?? fallbackDisk);
-  }).map(([, conversion2]) => ({ disk: conversion2.disk ?? fallbackDisk, path: conversion2.path }));
-  await removeStoredFiles(obsolete);
+function obsoleteConversionFiles(current, next, fallbackDisk) {
+  return Object.entries(current).filter(([name, conversion2]) => conversion2?.path && next[name]?.path !== conversion2.path).map(([, conversion2]) => ({ disk: conversion2.disk ?? fallbackDisk, path: conversion2.path }));
 }
 async function regenerateMediaEntityConversions(options) {
   const media = options.media;
@@ -591,7 +621,6 @@ async function regenerateMediaEntityConversions(options) {
   const collectionName = String(media.get("collection_name"));
   const collection2 = resolveCollectionDefinition(definition, collectionName);
   const requested = normalizeRequestedConversions(options.conversions);
-  const current = media.get("generated_conversions") ?? {};
   const conversionsDisk = String(media.get("conversions_disk") ?? media.get("disk"));
   resolveMatchingConversions(definition, collectionName, requested, {
     includeQueued: options.includeQueued === true
@@ -602,46 +631,56 @@ async function regenerateMediaEntityConversions(options) {
       `[Holo Media] Cannot regenerate conversions for media "${media.get("uuid")}" because the original file is missing.`
     );
   }
-  const nextBase = requested?.length ? Object.fromEntries(
-    Object.entries(current).filter(([name]) => !requested.includes(name))
-  ) : {};
-  return await runMediaMutation({
+  const mediaId = media.get("id");
+  const result = await runMediaMutation({
     committedMessage: "[Holo Media] Regeneration remains committed; post-commit cleanup or conversion dispatch failed.",
     afterRollback: async () => {
       options.owner?.forgetRelation("media");
       await media.refresh();
     },
-    operation: async (mutation) => {
-      const regenerated = await generateStoredConversions({
-        definition,
-        collection: collection2,
-        conversionsDisk,
-        requestedConversions: requested,
-        includeQueued: options.includeQueued === true,
-        mutation,
-        source: {
-          uuid: String(media.get("uuid")),
-          fileName: String(media.get("file_name")),
-          extension: media.get("extension") ?? void 0,
-          mimeType: media.get("mime_type") ?? void 0,
-          size: sourceContents.byteLength,
-          contents: sourceContents
-        }
-      });
+    write: async (mutation) => await writeStoredConversions({
+      definition,
+      collection: collection2,
+      conversionsDisk,
+      requestedConversions: requested,
+      includeQueued: options.includeQueued === true,
+      unique: true,
+      mutation,
+      source: {
+        uuid: String(media.get("uuid")),
+        fileName: String(media.get("file_name")),
+        extension: media.get("extension") ?? void 0,
+        mimeType: media.get("mime_type") ?? void 0,
+        size: sourceContents.byteLength,
+        contents: sourceContents
+      }
+    }),
+    operation: async (_mutation, regenerated) => {
+      const locked = await Media.query().where("id", mediaId).lockForUpdate().first();
+      if (!locked) {
+        throw new Error(`[Holo Media] Cannot regenerate conversions for media "${media.get("uuid")}" because the media row no longer exists.`);
+      }
+      const current = locked.get("generated_conversions") ?? {};
+      const nextBase = requested?.length ? Object.fromEntries(
+        Object.entries(current).filter(([name]) => !requested.includes(name))
+      ) : {};
       const generatedConversions = Object.freeze({ ...nextBase, ...regenerated });
       media.forceFill({ generated_conversions: generatedConversions });
       await media.save();
       options.owner?.forgetRelation("media");
-      return generatedConversions;
+      return {
+        generatedConversions,
+        obsolete: obsoleteConversionFiles(current, generatedConversions, conversionsDisk)
+      };
     },
     afterCommit: [
-      async (generatedConversions) => {
-        await deleteObsoleteConversions(current, generatedConversions, conversionsDisk, requested);
+      async ({ obsolete }) => {
+        await removeStoredFiles(obsolete);
       },
       async () => {
         if (options.includeQueued) return;
         await dispatchQueuedMediaConversionsForModel({
-          mediaId: media.get("id"),
+          mediaId,
           conversionNames: resolveQueuedConversionNames({ definition, collectionName, requestedConversions: requested })
         }, async () => {
           await media.refresh();
@@ -652,6 +691,7 @@ async function regenerateMediaEntityConversions(options) {
       options.owner?.forgetRelation("media");
     }
   });
+  return result.generatedConversions;
 }
 
 // src/queue.ts
@@ -782,6 +822,8 @@ var MediaItem = class {
     this.entity = entity;
     this.owner = owner;
   }
+  entity;
+  owner;
   get record() {
     return this.entity.toAttributes();
   }
@@ -866,8 +908,34 @@ var MediaItem = class {
 };
 
 // src/model/adder.ts
+var RemoteMediaSource = class {
+  constructor(url) {
+    this.url = url;
+  }
+  url;
+};
+var StoredMediaSource = class {
+  constructor(disk, path) {
+    this.disk = disk;
+    this.path = path;
+  }
+  disk;
+  path;
+};
 var DEFAULT_REMOTE_MEDIA_MAX_SIZE = 10 * 1024 * 1024;
+var REMOTE_MEDIA_TIMEOUT_MS = 3e4;
+var DEFAULT_MEDIA_DISK = "public";
 var BLOCKED_REMOTE_MEDIA_ADDRESSES = createBlockedRemoteMediaAddresses();
+var GLOBALLY_REACHABLE_BLOCKED_IPV4_ADDRESSES = createGloballyReachableBlockedIPv4Addresses();
+var GLOBAL_UNICAST_IPV6_ADDRESSES = createGlobalUnicastIPv6Addresses();
+var IETF_PROTOCOL_ASSIGNMENTS = createIETFProtocolAssignmentsBlockList();
+var GLOBALLY_REACHABLE_IETF_PROTOCOL_ASSIGNMENTS = createGloballyReachableIETFProtocolAssignments();
+var NAT64_WELL_KNOWN_PREFIX = Buffer.concat([Buffer.from([0, 100, 255, 155]), Buffer.alloc(8)]);
+var SIX_TO_FOUR_PREFIX = Buffer.from([32, 2]);
+var IPV4_COMPATIBLE_PREFIX = Buffer.alloc(12);
+var TRANSLATED_IPV4_PREFIX = Buffer.from([0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 0, 0]);
+var IPV4_MAPPED_PREFIX = Buffer.from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255]);
+var TEREDO_PREFIX = Buffer.from([32, 1, 0, 0]);
 var LOCAL_MEDIA_SOURCE_ROOTS = Object.freeze([
   tmpdir(),
   resolve(process.cwd(), "storage")
@@ -877,9 +945,9 @@ var defaultRemoteMediaAddressResolver = async (hostname) => await lookup(hostnam
   verbatim: true
 });
 function createRemoteMediaDownloader(resolver, requester) {
-  return async (url) => {
+  return async (url, signal) => {
     const address = await resolveRemoteMediaAddress(url, resolver);
-    return await requester(url, address);
+    return await requester(url, address, signal);
   };
 }
 var defaultRemoteMediaDownloader = createRemoteMediaDownloader(defaultRemoteMediaAddressResolver, requestRemoteMedia);
@@ -893,19 +961,14 @@ var MediaAddValidationException = class extends Error {
     this.error = error;
   }
 };
-function resolveImplicitDiskName() {
-  const defaultDisk = Storage4.disk();
-  if (defaultDisk.visibility === "public") {
-    return defaultDisk.name;
-  }
+function resolveMediaDefaultDisk() {
+  let configuredDisk;
   try {
-    const publicDisk = Storage4.disk("public");
-    if (publicDisk.visibility === "public") {
-      return publicDisk.name;
-    }
+    configuredDisk = config("media.disk");
   } catch {
+    return DEFAULT_MEDIA_DISK;
   }
-  return defaultDisk.name;
+  return typeof configuredDisk === "string" && configuredDisk.trim() ? configuredDisk.trim() : DEFAULT_MEDIA_DISK;
 }
 function parseRemoteFileName(url) {
   const parsedUrl = new URL(url);
@@ -950,39 +1013,51 @@ function createMaxSizeError(fileName, collectionName, maxSize, actualSize) {
 async function readRemoteMediaContents(response, fileName, maxSize, collectionName) {
   const resolvedMaxSize = typeof maxSize === "number" ? maxSize : DEFAULT_REMOTE_MEDIA_MAX_SIZE;
   if (!response.body) {
-    const contents2 = new Uint8Array(await response.arrayBuffer());
-    if (contents2.byteLength > resolvedMaxSize) {
-      throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, contents2.byteLength);
+    const contents = new Uint8Array(await response.arrayBuffer());
+    if (contents.byteLength > resolvedMaxSize) {
+      throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, contents.byteLength);
     }
-    return contents2;
+    return contents;
   }
-  const reader = response.body.getReader();
-  const chunks = [];
-  let totalSize = 0;
+  return await readBoundedMediaContents(
+    readWebStreamChunks(response.body),
+    fileName,
+    resolvedMaxSize,
+    collectionName
+  );
+}
+async function* readWebStreamChunks(stream) {
+  const reader = stream.getReader();
   try {
     while (true) {
       const { done, value } = await reader.read();
       if (done) {
-        break;
+        return;
       }
-      if (!value) {
-        continue;
+      if (value) {
+        yield value;
       }
-      totalSize += value.byteLength;
-      if (totalSize > resolvedMaxSize) {
-        await reader.cancel().catch(() => void 0);
-        throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, totalSize);
-      }
-      chunks.push(value);
     }
   } finally {
+    await reader.cancel().catch(() => void 0);
     reader.releaseLock();
   }
+}
+async function readBoundedMediaContents(chunks, fileName, maxSize, collectionName) {
+  const parts = [];
+  let totalSize = 0;
+  for await (const chunk of chunks) {
+    totalSize += chunk.byteLength;
+    if (totalSize > maxSize) {
+      throw createMaxSizeError(fileName, collectionName, maxSize, totalSize);
+    }
+    parts.push(chunk);
+  }
   const contents = new Uint8Array(totalSize);
   let offset = 0;
-  for (const chunk of chunks) {
-    contents.set(chunk, offset);
-    offset += chunk.byteLength;
+  for (const part of parts) {
+    contents.set(part, offset);
+    offset += part.byteLength;
   }
   return contents;
 }
@@ -992,16 +1067,7 @@ async function resolveMediaSource(input, overrideFileName, overrideName, options
   return mimeType ? { ...source, mimeType } : source;
 }
 async function readMediaSource(input, overrideFileName, overrideName, options) {
-  if (typeof input === "string" && /^https?:\/\//i.test(input)) {
-    return resolveRemoteMediaSource(
-      { url: input },
-      overrideFileName,
-      overrideName,
-      options.maxSize,
-      options.collectionName
-    );
-  }
-  if (typeof input !== "string" && isUrlInput(input)) {
+  if (input instanceof RemoteMediaSource) {
     return resolveRemoteMediaSource(
       input,
       overrideFileName,
@@ -1010,6 +1076,12 @@ async function readMediaSource(input, overrideFileName, overrideName, options) {
       options.collectionName
     );
   }
+  if (input instanceof StoredMediaSource) {
+    return resolveStorageMediaSource(input, overrideFileName, overrideName, options);
+  }
+  if (typeof input === "string" && /^https?:\/\//i.test(input) || typeof input === "object" && input !== null && "url" in input) {
+    throw new Error("[@holo-js/media] addMedia() reads file paths and binary contents. Use addMediaFromUrl() to download a URL.");
+  }
   if (typeof input === "string" || isPathInput(input)) {
     const path = await resolveLocalMediaSourcePath(typeof input === "string" ? input : input.path);
     const contents2 = await readFile(path);
@@ -1050,43 +1122,130 @@ function getBinaryFileName(input) {
 function isPathInput(input) {
   return typeof input === "object" && input !== null && "path" in input;
 }
-function isUrlInput(input) {
-  return typeof input === "object" && input !== null && "url" in input;
-}
-async function resolveRemoteMediaSource(input, overrideFileName, overrideName, maxSize, collectionName) {
-  const remoteUrl = resolveRemoteMediaUrl(input.url);
-  const response = await remoteMediaDownloader(remoteUrl);
-  if (response.status >= 300 && response.status < 400) {
-    throw new Error("[@holo-js/media] Remote media downloads do not follow redirects.");
-  }
-  if (!response.ok) {
+async function resolveStorageMediaSource(input, overrideFileName, overrideName, options) {
+  const disk = Storage4.disk(input.disk);
+  const fileName = sanitizeFileName(overrideFileName ?? localStoragePathInternals.splitLocalStoragePath(input.path).at(-1) ?? "");
+  const maxSize = options.maxSize;
+  const metadataAvailable = typeof maxSize === "number" && await checkStoredFileSize(disk, input, fileName, maxSize, options.collectionName);
+  const chunks = await openStoredFileStream(disk, input);
+  if (chunks === null) {
+    throw missingStoredFileError(input);
+  }
+  let contents;
+  if (chunks) {
+    contents = await readBoundedMediaContents(chunks, fileName, maxSize ?? Number.POSITIVE_INFINITY, options.collectionName);
+  } else if (typeof maxSize !== "number") {
+    contents = await readWholeStoredFile(disk, input);
+  } else if (!metadataAvailable) {
     throw new Error(
-      `[Holo Media] Failed to download media from "${remoteUrl.toString()}" (${response.status} ${response.statusText}).`
+      `[@holo-js/media] Collection "${options.collectionName}" has a maxSize, so "${input.path}" on disk "${input.disk}" needs a disk that supports file metadata or streaming.`
     );
+  } else {
+    contents = await readWholeStoredFile(disk, input);
+    if (contents.byteLength > maxSize) {
+      throw createMaxSizeError(fileName, options.collectionName, maxSize, contents.byteLength);
+    }
   }
-  const fileName = sanitizeFileName(
-    overrideFileName ?? input.fileName ?? parseRemoteFileName(remoteUrl.toString())
-  );
-  const contentLengthHeader = response.headers.get("content-length");
-  const contentLength = contentLengthHeader?.trim() ? Number(contentLengthHeader) : Number.NaN;
-  const resolvedMaxSize = typeof maxSize === "number" ? maxSize : DEFAULT_REMOTE_MEDIA_MAX_SIZE;
-  if (Number.isFinite(contentLength) && contentLength > resolvedMaxSize) {
-    throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, contentLength);
-  }
-  const contents = await readRemoteMediaContents(
-    response,
-    fileName,
-    maxSize,
-    collectionName
-  );
   return {
     contents,
     fileName,
     extension: getExtension(fileName),
     size: contents.byteLength,
-    name: getDisplayName(fileName, overrideName ?? input.name)
+    name: getDisplayName(fileName, overrideName)
   };
 }
+async function checkStoredFileSize(disk, input, fileName, maxSize, collectionName) {
+  let metadata;
+  try {
+    metadata = await disk.stat(input.path);
+  } catch (error) {
+    if (error instanceof StorageMetadataUnsupportedError) {
+      return false;
+    }
+    throw error;
+  }
+  if (!metadata) {
+    throw missingStoredFileError(input);
+  }
+  if (metadata.size > maxSize) {
+    throw createMaxSizeError(fileName, collectionName, maxSize, metadata.size);
+  }
+  return true;
+}
+async function openStoredFileStream(disk, input) {
+  try {
+    return await disk.readStream(input.path);
+  } catch (error) {
+    if (error instanceof StorageStreamingUnsupportedError) {
+      return void 0;
+    }
+    throw error;
+  }
+}
+async function readWholeStoredFile(disk, input) {
+  const contents = await disk.getBytes(input.path);
+  if (!contents) {
+    throw missingStoredFileError(input);
+  }
+  return contents;
+}
+function missingStoredFileError(input) {
+  return new Error(`[@holo-js/media] File "${input.path}" was not found on disk "${input.disk}".`);
+}
+async function withRemoteMediaDeadline(download) {
+  const controller = new AbortController();
+  let timer;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      const error = new Error(
+        `[@holo-js/media] Remote media downloads must finish within ${REMOTE_MEDIA_TIMEOUT_MS / 1e3} seconds.`
+      );
+      controller.abort(error);
+      reject(error);
+    }, REMOTE_MEDIA_TIMEOUT_MS);
+  });
+  try {
+    return await Promise.race([download(controller.signal), deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function resolveRemoteMediaSource(input, overrideFileName, overrideName, maxSize, collectionName) {
+  const remoteUrl = resolveRemoteMediaUrl(input.url);
+  return await withRemoteMediaDeadline(async (signal) => {
+    const response = await remoteMediaDownloader(remoteUrl, signal);
+    if (response.status >= 300 && response.status < 400) {
+      throw new Error("[@holo-js/media] Remote media downloads do not follow redirects.");
+    }
+    if (!response.ok) {
+      throw new Error(
+        `[Holo Media] Failed to download media from "${remoteUrl.toString()}" (${response.status} ${response.statusText}).`
+      );
+    }
+    const fileName = sanitizeFileName(
+      overrideFileName ?? parseRemoteFileName(remoteUrl.toString())
+    );
+    const contentLengthHeader = response.headers.get("content-length");
+    const contentLength = contentLengthHeader?.trim() ? Number(contentLengthHeader) : Number.NaN;
+    const resolvedMaxSize = typeof maxSize === "number" ? maxSize : DEFAULT_REMOTE_MEDIA_MAX_SIZE;
+    if (Number.isFinite(contentLength) && contentLength > resolvedMaxSize) {
+      throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, contentLength);
+    }
+    const contents = await readRemoteMediaContents(
+      response,
+      fileName,
+      maxSize,
+      collectionName
+    );
+    return {
+      contents,
+      fileName,
+      extension: getExtension(fileName),
+      size: contents.byteLength,
+      name: getDisplayName(fileName, overrideName)
+    };
+  });
+}
 async function resolveLocalMediaSourcePath(path) {
   const resolvedPath = await realpath(path);
   const allowedRoots = await Promise.all(LOCAL_MEDIA_SOURCE_ROOTS.map(async (root) => await realpath(root).catch(() => null)));
@@ -1111,9 +1270,13 @@ function resolveRemoteMediaUrl(value) {
   if (url.username || url.password) {
     throw new Error("[@holo-js/media] Remote media URLs must not include credentials.");
   }
-  if (isBlockedRemoteMediaHost(url.hostname)) {
+  if (isLocalRemoteMediaName(url.hostname)) {
     throw new Error("[@holo-js/media] Remote media URLs must not target local or private hosts.");
   }
+  const literal = parseRemoteMediaIPLiteral(url.hostname);
+  if (literal) {
+    assertRemoteMediaAddressesAllowed([literal]);
+  }
   return url;
 }
 function createBlockedRemoteMediaAddresses() {
@@ -1127,42 +1290,167 @@ function createBlockedRemoteMediaAddresses() {
     ["172.16.0.0", 12],
     ["192.0.0.0", 24],
     ["192.0.2.0", 24],
+    ["192.88.99.2", 32],
     ["192.168.0.0", 16],
     ["198.18.0.0", 15],
     ["198.51.100.0", 24],
     ["203.0.113.0", 24],
-    ["224.0.0.0", 4]
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+    ["255.255.255.255", 32]
   ]) {
     blockList.addSubnet(network, prefix, "ipv4");
   }
   for (const [network, prefix] of [
     ["::", 128],
     ["::1", 128],
+    ["100::", 64],
+    ["100:0:0:1::", 64],
+    ["2001:db8::", 32],
+    ["3fff::", 20],
+    ["5f00::", 16],
     ["fc00::", 7],
     ["fe80::", 10],
+    ["fec0::", 10],
     ["ff00::", 8]
   ]) {
     blockList.addSubnet(network, prefix, "ipv6");
   }
   return blockList;
 }
+function createGloballyReachableBlockedIPv4Addresses() {
+  const blockList = new BlockList();
+  for (const [network, prefix] of [
+    ["192.0.0.9", 32],
+    ["192.0.0.10", 32]
+  ]) {
+    blockList.addSubnet(network, prefix, "ipv4");
+  }
+  return blockList;
+}
+function createGlobalUnicastIPv6Addresses() {
+  const blockList = new BlockList();
+  blockList.addSubnet("2000::", 3, "ipv6");
+  return blockList;
+}
+function createIETFProtocolAssignmentsBlockList() {
+  const blockList = new BlockList();
+  blockList.addSubnet("2001::", 23, "ipv6");
+  return blockList;
+}
+function createGloballyReachableIETFProtocolAssignments() {
+  const blockList = new BlockList();
+  for (const [network, prefix] of [
+    ["2001::", 32],
+    ["2001:1::1", 128],
+    ["2001:1::2", 128],
+    ["2001:1::3", 128],
+    ["2001:3::", 32],
+    ["2001:4:112::", 48],
+    ["2001:20::", 28],
+    ["2001:30::", 28]
+  ]) {
+    blockList.addSubnet(network, prefix, "ipv6");
+  }
+  return blockList;
+}
+function isBlockedRemoteMediaIPv4Address(address) {
+  return BLOCKED_REMOTE_MEDIA_ADDRESSES.check(address, "ipv4") && !GLOBALLY_REACHABLE_BLOCKED_IPV4_ADDRESSES.check(address, "ipv4");
+}
 function isBlockedRemoteMediaAddress(address) {
-  return BLOCKED_REMOTE_MEDIA_ADDRESSES.check(address.address, address.family === 4 ? "ipv4" : "ipv6");
+  if (address.family === 4) {
+    return isBlockedRemoteMediaIPv4Address(address.address);
+  }
+  return isBlockedRemoteMediaIPv6Address(address.address);
+}
+function isBlockedRemoteMediaIPv6Address(address) {
+  const bytes = findIPv6Bytes(address);
+  if (!bytes) {
+    return true;
+  }
+  if (!GLOBAL_UNICAST_IPV6_ADDRESSES.check(address, "ipv6")) {
+    const mappedAddress = findMappedIPv4Address(bytes);
+    return mappedAddress === null || isBlockedRemoteMediaIPv4Address(mappedAddress);
+  }
+  if (BLOCKED_REMOTE_MEDIA_ADDRESSES.check(address, "ipv6")) {
+    return true;
+  }
+  if (IETF_PROTOCOL_ASSIGNMENTS.check(address, "ipv6") && !GLOBALLY_REACHABLE_IETF_PROTOCOL_ASSIGNMENTS.check(address, "ipv6")) {
+    return true;
+  }
+  return findEmbeddedIPv4Addresses(bytes).some(isBlockedRemoteMediaIPv4Address);
+}
+function findMappedIPv4Address(bytes) {
+  const mappedPrefixes = [NAT64_WELL_KNOWN_PREFIX, IPV4_COMPATIBLE_PREFIX, IPV4_MAPPED_PREFIX, TRANSLATED_IPV4_PREFIX];
+  if (!mappedPrefixes.some((prefix) => bytes.subarray(0, 12).equals(prefix))) {
+    return null;
+  }
+  return formatIPv4Octets(bytes.subarray(12, 16));
+}
+function findEmbeddedIPv4Addresses(bytes) {
+  const embeddedAddresses = [];
+  if (bytes.subarray(0, 2).equals(SIX_TO_FOUR_PREFIX)) {
+    embeddedAddresses.push(formatIPv4Octets(bytes.subarray(2, 6)));
+  }
+  if (bytes.subarray(0, 4).equals(TEREDO_PREFIX)) {
+    embeddedAddresses.push(formatIPv4Octets(bytes.subarray(12, 16).map((octet) => octet ^ 255)));
+  }
+  const interfaceIdentifierPrefix = bytes.readUInt16BE(8);
+  if ((interfaceIdentifierPrefix === 0 || interfaceIdentifierPrefix === 512) && bytes.readUInt16BE(10) === 24318) {
+    embeddedAddresses.push(formatIPv4Octets(bytes.subarray(12, 16)));
+  }
+  return embeddedAddresses;
+}
+function findIPv6Bytes(address) {
+  let canonical;
+  try {
+    canonical = new URL(`http://[${address}]`).hostname.slice(1, -1);
+  } catch {
+    return null;
+  }
+  const halves = canonical.split("::");
+  const head = halves[0] ? halves[0].split(":") : [];
+  const tail = halves[1] ? halves[1].split(":") : [];
+  const zeroGroups = halves.length === 2 ? 8 - head.length - tail.length : 0;
+  const groups = [...head, ...Array(zeroGroups).fill("0"), ...tail];
+  if (groups.length !== 8) {
+    return null;
+  }
+  return Buffer.from(groups.flatMap((group) => {
+    const value = Number.parseInt(group, 16);
+    return [value >> 8, value & 255];
+  }));
+}
+function formatIPv4Octets(octets) {
+  return Array.from(octets).join(".");
 }
 async function resolveRemoteMediaAddress(url, resolver) {
-  const addresses = await resolver(url.hostname);
+  const addresses = await resolveRemoteMediaHostAddresses(url.hostname, resolver);
+  assertRemoteMediaAddressesAllowed(addresses);
+  return addresses[0];
+}
+function assertRemoteMediaAddressesAllowed(addresses) {
   if (addresses.length === 0 || addresses.some(isBlockedRemoteMediaAddress)) {
     throw new Error("[@holo-js/media] Remote media URLs must not resolve to local or private hosts.");
   }
-  return addresses[0];
 }
-function requestRemoteMedia(url, address) {
+async function resolveRemoteMediaHostAddresses(hostname, resolver) {
+  const literal = parseRemoteMediaIPLiteral(hostname);
+  return literal ? [literal] : await resolver(hostname);
+}
+function parseRemoteMediaIPLiteral(hostname) {
+  const address = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  const family = isIP(address);
+  return family === 0 ? null : { address, family };
+}
+function requestRemoteMedia(url, address, signal) {
   return new Promise((resolveResponse, reject) => {
     const request = resolveRemoteMediaRequest(url.protocol)(url, {
       headers: {
         host: url.host
       },
-      lookup: createPinnedRemoteMediaLookup(address)
+      lookup: createPinnedRemoteMediaLookup(address),
+      signal
     }, (response) => {
       const headers = new Headers();
       appendRemoteMediaHeaders(headers, response.headers);
@@ -1191,14 +1479,9 @@ function appendRemoteMediaHeaders(headers, source) {
 function resolveRemoteMediaRequest(protocol) {
   return protocol === "https:" ? requestHttps : requestHttp;
 }
-function isBlockedRemoteMediaHost(hostname) {
+function isLocalRemoteMediaName(hostname) {
   const lowerCaseHostname = hostname.toLowerCase();
-  const normalized = lowerCaseHostname.startsWith("[") && lowerCaseHostname.endsWith("]") ? lowerCaseHostname.slice(1, -1) : lowerCaseHostname;
-  if (normalized === "localhost" || normalized.endsWith(".localhost")) {
-    return true;
-  }
-  const family = isIP(normalized);
-  return family !== 0 && isBlockedRemoteMediaAddress({ address: normalized, family });
+  return lowerCaseHostname === "localhost" || lowerCaseHostname.endsWith(".localhost");
 }
 function validateSource(collection2, source) {
   if (typeof collection2.maxSize === "number" && source.size > collection2.maxSize) {
@@ -1234,6 +1517,9 @@ var MediaAdder = class _MediaAdder {
     this.source = source;
     this.state = state;
   }
+  entity;
+  source;
+  state;
   usingName(name) {
     return new _MediaAdder(this.entity, this.source, {
       ...this.state,
@@ -1295,7 +1581,7 @@ var MediaAdder = class _MediaAdder {
       collection: collection2,
       definition: mediaDefinition,
       source,
-      disk: this.state.disk ?? collection2.disk ?? resolveImplicitDiskName()
+      disk: this.state.disk ?? collection2.disk ?? resolveMediaDefaultDisk()
     });
   }
 };
@@ -1312,16 +1598,18 @@ async function attachMedia(options) {
     afterRollback: () => {
       owner.forgetRelation("media");
     },
-    operation: async (mutation) => {
-      const existing = collection2.singleFile ? await owner.getMedia(options.collectionName) : [];
+    write: async (mutation) => {
       await mutation.put(disk, path, source.contents);
-      const generatedConversions = await generateStoredConversions({
+      return await writeStoredConversions({
         definition: options.definition,
         collection: collection2,
         conversionsDisk,
         source: { ...source, uuid },
         mutation
       });
+    },
+    operation: async (_mutation, generatedConversions) => {
+      const existing = collection2.singleFile ? await owner.getMedia(options.collectionName) : [];
       const max = await Media.query().where("model_type", ownerDefinition.morphClass).where("model_id", ownerId).where("collection_name", options.collectionName).max("order_column");
       const media = await Media.create({
         uuid,
@@ -1420,7 +1708,10 @@ function installEntityMediaMethods() {
     return new MediaAdder(this, source);
   };
   prototype.addMediaFromUrl = function addMediaFromUrl(url) {
-    return new MediaAdder(this, { url });
+    return new MediaAdder(this, new RemoteMediaSource(url));
+  };
+  prototype.addMediaFromDisk = function addMediaFromDisk(path, disk) {
+    return new MediaAdder(this, new StoredMediaSource(disk, path));
   };
   prototype.getMedia = async function getMedia(collectionName) {
     const query = createQuery(this, collectionName);

package/dist/projectConfig.d.ts

@@ -1,4 +1,5 @@
 interface HoloMediaConfig {
+    readonly disk?: string;
     readonly [key: string]: unknown;
 }
 declare module '@holo-js/config' {
@@ -9,4 +10,5 @@ declare module '@holo-js/config' {
 declare function normalizeMediaConfig(config?: HoloMediaConfig): Readonly<HoloMediaConfig>;
 declare function defineMediaConfig<TConfig extends HoloMediaConfig>(config: TConfig): Readonly<TConfig>;
 
-export { type HoloMediaConfig, defineMediaConfig, normalizeMediaConfig };
+export { defineMediaConfig, normalizeMediaConfig };
+export type { HoloMediaConfig };

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@holo-js/media",
-  "version": "0.3.28",
+  "version": "0.4.0",
   "description": "Holo-JS Framework - media collections and conversions for Holo-JS models",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cobraprojects/holo-js.git",
+    "directory": "packages/media"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -19,7 +24,8 @@
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsup",
@@ -28,21 +34,20 @@
     "test": "vitest --run"
   },
   "dependencies": {
-    "@holo-js/config": "^0.3.28",
-    "@holo-js/db": "^0.3.28",
-    "@holo-js/kernel": "^0.3.28",
-    "@holo-js/queue": "^0.3.28",
-    "@holo-js/storage": "^0.3.28",
-    "file-type": "^22.2.0",
-    "sharp": "^0.35.4"
+    "@holo-js/config": "^0.4.0",
+    "@holo-js/db": "^0.4.0",
+    "@holo-js/kernel": "^0.4.0",
+    "@holo-js/queue": "^0.4.0",
+    "@holo-js/storage": "^0.4.0",
+    "sharp": "^0.35.5"
   },
   "devDependencies": {
-    "@holo-js/db-sqlite": "^0.3.28",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^4.1.5"
+    "@holo-js/db-sqlite": "^0.4.0",
+    "tsup": "^9.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.5"
   },
   "engines": {
-    "node": "^22.12.0 || ^24.0.0 || ^26.0.0"
+    "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
   }
 }