PhoenixAssets.Generated (PhoenixAssets v0.1.0)

View Source

Writes plugin-contributed TypeScript contracts to disk.

Walks the initialised plugins, collects every PhoenixAssets.GeneratedFile they contribute, and writes each one -- but only when its contents actually changed. This content-gated write is what keeps the Vite HMR graph quiet: a regeneration that produces byte-identical output performs no writes and triggers no hot update.

generate/2 with check: true performs the same collection but compares against disk without writing, returning {:error, {:stale, paths}} when the on-disk contracts drift from what the current Phoenix/Ash definitions would produce. This powers the mix phoenix_assets.gen --check CI gate.

Determinism

Generators must emit byte-identical output for identical inputs (stable ordering, no timestamps in the body). The engine relies on this: it is the contract that makes both the no-write fast path and the drift check meaningful.

See also

Summary

Types

generate_result()

Functions

clean(ctx)

Removes the files the configured plugins generate.

generate(ctx, opts \\ [])

Generates (or, with check: true, verifies) all frontend contracts.

stale?(ctx)

Returns true if the on-disk contracts differ from freshly generated output.

status(ctx)

Returns which generated files are fresh and which are stale, by relative path.

Types

generate_result()

@type generate_result() :: %{written: [Path.t()], unchanged: [Path.t()]}

Functions

clean(ctx)

@spec clean(PhoenixAssets.Context.t()) ::
  {:ok, %{removed: [Path.t()], kept: [Path.t()]}} | {:error, term()}

Removes the files the configured plugins generate.

Returns {:ok, %{removed: [...], kept: [...]}}, where kept lists paths that exist but whose contents differ from what the plugins would emit right now. Those are left alone: a host co-locating its own artifacts in the generated directory, or a contract someone edited by hand, should not be destroyed by a cleanup. Nothing outside the plugins' own file list is touched at all.

generate(ctx, opts \\ [])

@spec generate(
  PhoenixAssets.Context.t(),
  keyword()
) :: {:ok, generate_result()} | :ok | {:error, term()}

Generates (or, with check: true, verifies) all frontend contracts.

Returns {:ok, %{written: [...], unchanged: [...]}} on a write run, or :ok | {:error, {:stale, paths}} on a check run. Returns {:error, {plugin, reason}} if a plugin fails to initialise.

stale?(ctx)

@spec stale?(PhoenixAssets.Context.t()) :: boolean()

Returns true if the on-disk contracts differ from freshly generated output.

status(ctx)

@spec status(PhoenixAssets.Context.t()) ::
  %{fresh: [Path.t()], stale: [Path.t()]} | {:error, term()}

Returns which generated files are fresh and which are stale, by relative path.