@spec aspect_slots() :: [String.t()]

The standard slots that always keep the aspect ratio.

@spec bump_revision(term()) :: :ok

Bumps a set's revision: every file whose variants it made is stale.

@spec create_variant_set(map()) ::
  {:ok, PhoenixKit.Modules.Storage.VariantSet.t()}
  | {:error, Ecto.Changeset.t()}

Creates a set. It starts with a copy of the Default's standard slots, so it keeps the contract every set has.

@spec default?(term()) :: boolean()

Whether uuid is the Default set's.

@spec default_flag(:generate_variants | :generate_tiles, boolean()) :: boolean()

One of the Default set's flags (:generate_variants or :generate_tiles): what the storage_auto_generate_variants and storage_tile_generation_enabled settings were before variant sets. default when there is no Default set yet.

@spec default_uuid() :: String.t()

The uuid of the Default variant set, fixed on every install.

@spec default_variant_set() :: PhoenixKit.Modules.Storage.VariantSet.t() | nil

The Default set.

@spec delete_variant_set(PhoenixKit.Modules.Storage.VariantSet.t()) ::
  {:ok, PhoenixKit.Modules.Storage.VariantSet.t()}
  | {:error, :default | :in_use | Ecto.Changeset.t()}

Deletes a set and its sizes. The Default cannot be deleted ({:error, :default}), nor a set a library uses ({:error, :in_use}).

@spec for_file(PhoenixKit.Modules.Storage.File.t()) ::
  PhoenixKit.Modules.Storage.VariantSet.t() | nil

The set a file's library uses.

@spec for_library(PhoenixKit.Modules.Storage.Library.t() | term()) ::
  PhoenixKit.Modules.Storage.VariantSet.t() | nil

The set library uses; the Default when its own is gone.

@spec get_variant_set(term()) :: PhoenixKit.Modules.Storage.VariantSet.t() | nil

A set, or nil (also for anything not a uuid).

@spec libraries_using(term()) :: non_neg_integer()

How many libraries (trashed ones included) use set_uuid explicitly.

@spec list_dimensions(term()) :: [PhoenixKit.Modules.Storage.Dimension.t()]

A set's sizes, ordered as the admin arranged them.

@spec list_selectable() :: [PhoenixKit.Modules.Storage.VariantSet.t()]

The sets a user library may choose.

@spec list_variant_sets() :: [PhoenixKit.Modules.Storage.VariantSet.t()]

Every set, the Default first.

@spec missing_standard_slots(term()) :: [String.t()]

The standard slots set_uuid has no size for.

@spec record_variants(
  PhoenixKit.Modules.Storage.File.t(),
  boolean(),
  PhoenixKit.Modules.Storage.VariantSet.t() | nil | :current
) :: :ok

Records that file's variants were made by its library's set as it is now (complete?), or that some are missing (the file is stale for the reconciler: placed_variant_revision = 0).

@spec set_library_variant_set(PhoenixKit.Modules.Storage.Library.t(), term()) ::
  {:ok, PhoenixKit.Modules.Storage.Library.t()}
  | {:error, Ecto.Changeset.t() | :not_found | :not_selectable}

Points library at set_uuid (nil for the Default). A user library may only use a selectable set ({:error, :not_selectable}).

@spec set_uuid_for(PhoenixKit.Modules.Storage.Library.t() | term()) :: String.t()

The uuid of the set library uses: its own, or the Default. Takes a library, a library uuid, or nil (a file with no library is in Media).

@spec spec_hash(PhoenixKit.Modules.Storage.Dimension.t()) :: String.t()

The spec hash of the variant dimension makes in format (its own format when not given; nil keeps the original's). Only what changes the pixels counts: width, height, quality, format and whether the aspect ratio is kept. V205 stamped existing instances with the same text in SQL (PhoenixKit.Migrations.Postgres.V205.spec_hash_sql/1).

@spec stand_in(PhoenixKit.Modules.Storage.File.t(), String.t(), [struct()]) ::
  {:instance, struct()} | :placeholder | :original

What to serve in place of variant of file while it has not been made (G17), given the file's instances:

• {:instance, instance} — the nearest smaller size the file has;
• :placeholder — no smaller size exists, and the original is larger than the size asked for;
• :original — the original is no larger than the size, or variant is not an image size of the file's set (an unknown name, a video transcode), which is what was always served.

A thumbnail-class request never gets a full-size original: in a grid of thousands, a new or renamed size would otherwise send thousands of them.

@spec standard_slots() :: [String.t()]

The sizes every set has.

@spec tiles_among([term()]) :: MapSet.t(String.t())

Of library_uuids (nil is Media), the ones whose set makes tiles, as a set of strings: one query for a page of files.

@spec tiles_for?(PhoenixKit.Modules.Storage.File.t() | term()) :: boolean()

Whether the set of file's library makes zoomable tiles. Takes a file or a file uuid; false for an unknown file.

@spec update_variant_set(PhoenixKit.Modules.Storage.VariantSet.t(), map()) ::
  {:ok, PhoenixKit.Modules.Storage.VariantSet.t()}
  | {:error, Ecto.Changeset.t()}

Updates a set's name or flags. Turning variant or tile generation on or off bumps its revision; a rename or selectable does not.

@spec variant_for(PhoenixKit.Modules.Storage.File.t(), keyword()) :: String.t()

The name of the size of file's set that fits a purpose (G19), rather than a size picked by name: a set may make small a square crop, so a name alone promises nothing.

Options

• :min_width — the smallest width that will do (default 0);
• :aspect — :preserve (the aspect ratio is kept), :crop, or :any (the default);
• :output — :image (the default: a still, a video's poster included) or :video (a transcode, for a video file).

The narrowest enabled size of the file's kind that is at least :min_width wide; the widest one when none is; "original" when the set has none that fit.

@spec variants_for?(PhoenixKit.Modules.Storage.File.t()) :: boolean()

Whether the set of file's library makes sizes automatically.