A utility to flatten a list, but preserve keyword list elements

Converts a term into an Ash Error.

The term could be a simple string, the second element in an {:error, error} tuple, an Ash Error, or a list of any of these. In most cases the returned error is an Ash.Error.Unknown.UnknownError.

A stacktrace is added to the error, and any existing stacktrace (i.e. when the term is an Ash Error) is preserved.

to_ash_error converts string(s) into UnknownError(s):

  iex(1)> Ash.Error.to_ash_error("whoops!", nil, error_context: "some context")
  %Ash.Error.Unknown.UnknownError{
    changeset: nil,
    class: :unknown,
    error: "whoops!",
    error_context: ["some context"],
    field: nil,
    path: [],
    query: nil,
    stacktrace: #Stacktrace<>,
    vars: []
  }

  iex(2)> Ash.Error.to_ash_error(["whoops!", "whoops, again!!"], nil, error_context: "some context")
  [
    %Ash.Error.Unknown.UnknownError{
      changeset: nil,
      class: :unknown,
      error: "whoops!",
      error_context: ["some context"],
      field: nil,
      path: [],
      query: nil,
      stacktrace: #Stacktrace<>,
      vars: []
    },
    %Ash.Error.Unknown.UnknownError{
      changeset: nil,
      class: :unknown,
      error: "whoops, again!!",
      error_context: ["some context"],
      field: nil,
      path: [],
      query: nil,
      stacktrace: #Stacktrace<>,
      vars: []
    }
  ]

to_ash_error can preserve error-like data from a keyword-list and accumulate context if called against an Ash Error:

  iex(1)> err = Ash.Error.to_ash_error([vars: [:some_var], message: "whoops!"], nil, error_context: " some context")
  %Ash.Error.Unknown.UnknownError{
    changeset: nil,
    class: :unknown,
    error: "whoops!",
    error_context: ["some context"],
    field: nil,
    path: [],
    query: nil,
    stacktrace: #Stacktrace<>,
    vars: [:some_var]
  }
  iex(2)> Ash.Error.to_ash_error(err, nil, error_context: "some higher context")
  %Ash.Error.Unknown.UnknownError{
    changeset: nil,
    class: :unknown,
    error: "whoops!",
    error_context: ["some higher context", "some context"],
    field: nil,
    path: [],
    query: nil,
    stacktrace: #Stacktrace<>,
    vars: [:some_var]
  }

Options:

• error_context: a sting message providing extra context around the error

Conforms a term into one of the built-in Ash Error classes.

The provided term would usually be an Ash Error or a list of Ash Errors.

If the term is:

• a map/struct/Ash Error with a key :class having a value :special,
• a list with a single map/struct/Ash Error element as above, or
• an Ash.Error.Invalid containing such a list in its :errors field

then the term is returned unchanged.

Example:

iex(1)> Ash.Error.to_error_class("oops", changeset: Ash.Changeset.new(%Post{}), error_context: "some context")
  %Ash.Error.Unknown{
    changeset: #Ash.Changeset<
      errors: [
        %Ash.Error.Unknown.UnknownError{
          changeset: nil,
          class: :unknown,
          error: "oops",
          error_context: ["some context"],
          field: nil,
          path: [],
          query: nil,
          stacktrace: #Stacktrace<>,
          vars: []
        }
      ],
      ...
    >,
    class: :unknown,
    error_context: ["some context"],
    errors: [
      %Ash.Error.Unknown.UnknownError{
        changeset: nil,
        class: :unknown,
        error: "oops",
        error_context: ["some context"],
        field: nil,
        path: [],
        query: nil,
        stacktrace: #Stacktrace<>,
        vars: []
      }
    ],
    stacktrace: #Stacktrace<>,
    stacktraces?: true,
    vars: []
  }

Example of nested errors:

  iex(1)> error1 = Ash.Error.to_ash_error("whoops!", nil, error_context: "some context")
  iex(2)> error2 = Ash.Error.to_ash_error("whoops, again!!", nil, error_context: "some other context")
  iex(3)> Ash.Error.to_error_class([error1, error2], error_context: "some higher context")
  %Ash.Error.Unknown{
    changeset: nil,
    class: :unknown,
    error_context: ["some higher context"],
    errors: [
      %Ash.Error.Unknown.UnknownError{
        changeset: nil,
        class: :unknown,
        error: "whoops!",
        error_context: ["some higher context", "some context"],
        field: nil,
        path: [],
        query: nil,
        stacktrace: #Stacktrace<>,
        vars: []
      },
      %Ash.Error.Unknown.UnknownError{
        changeset: nil,
        class: :unknown,
        error: "whoops, again!!",
        error_context: ["some higher context", "some other context"],
        field: nil,
        path: [],
        query: nil,
        stacktrace: #Stacktrace<>,
        vars: []
      }
    ],
    path: [],
    query: nil,
    stacktrace: #Stacktrace<>,
    stacktraces?: true,
    vars: []
  }

Options:

• changeset: a changeset related to the error
• query: a query related to the error
• error_context: a sting message providing extra context around the error