# `PhoenixKit.Modules.Storage.FileInstance`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.87/lib/modules/storage/schemas/file_instance.ex#L1)

Schema for file variants (thumbnails, resizes, video qualities).

Each file can have multiple instances representing different versions:
- **original** - The unchanged uploaded file
- **thumbnail** - Small preview (150x150)
- **small** - Small variant (300x300)
- **medium** - Medium variant (800x600)
- **large** - Large variant (1920x1080)
- **360p** - Video quality variant (640x360)
- **720p** - Video quality variant (1280x720)
- **1080p** - Video quality variant (1920x1080)
- **video_thumbnail** - Thumbnail extracted from video (640x360)

All instances are stored next to the original file in the same directory.

## Processing Status

- `pending` - Instance not yet processed
- `processing` - Currently being generated
- `completed` - Successfully generated
- `failed` - Generation failed

## Fields

- `variant_name` - Name of the variant (original, thumbnail, medium, etc.)
- `file_name` - System filename (uuid_v7-variant.ext)
- `mime_type` - MIME type of this variant
- `ext` - File extension
- `checksum` - Hash for integrity verification
- `size` - Variant file size in bytes
- `width` - Width in pixels (nullable)
- `height` - Height in pixels (nullable)
- `processing_status` - Current processing state
- `file_uuid` - Parent file reference

## Examples

    # Original instance
    %FileInstance{
      variant_name: "original",
      file_name: "018e3c4a-9f6b-7890-original.jpg",
      mime_type: "image/jpeg",
      ext: "jpg",
      checksum: "abc123...",
      size: 524_288,
      width: 2000,
      height: 2000,
      processing_status: "completed",
      file_uuid: "018e3c4a-9f6b-7890-abcd-ef1234567890"
    }

    # Thumbnail instance
    %FileInstance{
      variant_name: "thumbnail",
      file_name: "018e3c4a-9f6b-7890-thumbnail.jpg",
      mime_type: "image/jpeg",
      ext: "jpg",
      checksum: "def456...",
      size: 8_192,  # 8 KB
      width: 150,
      height: 150,
      processing_status: "completed",
      file_uuid: "018e3c4a-9f6b-7890-abcd-ef1234567890"
    }

    # Video quality variant
    %FileInstance{
      variant_name: "720p",
      file_name: "018e3c4a-9f6b-7890-720p.mp4",
      mime_type: "video/mp4",
      ext: "mp4",
      size: 5_242_880,  # 5 MB
      width: 1280,
      height: 720,
      processing_status: "processing"
    }

# `t`

```elixir
@type t() :: %PhoenixKit.Modules.Storage.FileInstance{
  __meta__: term(),
  checksum: String.t(),
  ext: String.t(),
  file: PhoenixKit.Modules.Storage.File.t() | Ecto.Association.NotLoaded.t(),
  file_name: String.t(),
  file_uuid: UUIDv7.t() | nil,
  height: integer() | nil,
  inserted_at: DateTime.t() | nil,
  locations:
    [PhoenixKit.Modules.Storage.FileLocation.t()]
    | Ecto.Association.NotLoaded.t(),
  mime_type: String.t(),
  processing_status: String.t(),
  size: integer(),
  updated_at: DateTime.t() | nil,
  uuid: UUIDv7.t() | nil,
  variant_name: String.t(),
  width: integer() | nil
}
```

# `changeset`

Changeset for creating or updating a file instance.

## Required Fields

- `variant_name`
- `file_name`
- `mime_type`
- `ext`
- `checksum`
- `size`
- `file_uuid`

## Validation Rules

- Processing status must be valid (pending, processing, completed, failed)
- Size must be positive
- Width/height must be positive (if provided)
- Unique variant_name per file

# `completed?`

Returns whether this instance has been successfully processed.

# `failed?`

Returns whether this instance failed processing.

# `original?`

Returns whether this is the original file instance.

# `pending?`

Returns whether this instance is pending processing.

# `processing?`

Returns whether this instance is currently being processed.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
