NativeElixirPdfUtilities.Diagnostics (native_elixir_pdf_utilities v1.1.0)

View Source

Builds consistent diagnostics for public API errors.

Public operations return diagnostic errors as {:error, {reason, diagnostic}} when the library can explain why an operation cannot continue. The diagnostic map always includes :stage, :reason, and :message, and may include actionable context such as :operation, :module, :line, :column, or :source.

The shared shape lets callers use one error handler across the library. The outer reason supports programmatic decisions, while the diagnostic provides context for logs and investigation.

Summary

Functions

Builds a diagnostic map for a public API failure.

Builds a standard {:error, {reason, diagnostic}} result.

Adds operation, module, or source context to an existing diagnostic map.

Types

context_option()

@type context_option() ::
  {:operation, atom()} | {:module, module()} | {:source, String.t() | nil}

detailed_error()

@type detailed_error() :: {atom(), diagnostic()}

diagnostic()

@type diagnostic() :: %{
  :stage => atom(),
  :reason => atom(),
  :message => String.t(),
  optional(:operation) => atom(),
  optional(:module) => module(),
  optional(:line) => pos_integer(),
  optional(:column) => pos_integer(),
  optional(:source) => String.t()
}

diagnostic_option()

@type diagnostic_option() ::
  context_option() | {:line, pos_integer()} | {:column, pos_integer()}

Functions

diagnostic(stage, reason, message, opts \\ [])

@spec diagnostic(atom(), atom(), String.t(), [diagnostic_option()]) :: diagnostic()

Builds a diagnostic map for a public API failure.

error(stage, reason, message, opts \\ [])

@spec error(atom(), atom(), String.t(), [diagnostic_option()]) ::
  {:error, detailed_error()}

Builds a standard {:error, {reason, diagnostic}} result.

with_context(diagnostic, opts \\ [])

@spec with_context(diagnostic(), [context_option()]) :: diagnostic()

Adds operation, module, or source context to an existing diagnostic map.