Documentation

All documentation is contained in the generated hex documentation located here. Head there for installation and usage information. What follows is only a brief introduction to Ash.

Is the project still in beta?

Ash is quite stable, but is technically still in beta. It is being used in production and has had many success stories along the way. 2.0.0 is coming very soon which will bring the project out of beta, and may contain some small breaking changes. The primary thing holding back the next release is an overhaul of the documentation, currently happening at https://www.ash-hq.org. For a funny story about why the package is in 1.0.0+ version but still in beta, see below.

Dependency

def deps do
  [
    {:ash, "~> 1.53.3"}
  ]
end

Links

Guides

• Getting Started Tutorial
• Resource DSL Documentation
• API DSL Documentation
• API interface documentation
• Query Documentation
• Changeset Documentation
• Example Application

Extensions

APIs

• AshJsonApi
• AshGraphql (beta)

Authorizers

• Ash.Policy.Authorizer (builtin)

Datalayers

• AshPostgres
• AshCsv
• Ets (built-in) - Only used for testing/prototyping
• Mnesia (built-in) - Only used for testing/prototyping

Introduction

Traditional MVC Frameworks (Rails, Django, .Net, Phoenix, etc) leave it up to the user to build the glue between requests for data (HTTP requests in various forms as well as server-side domain logic) and their respective ORMs. In that space, there is an incredible amount of boilerplate code that must get written from scratch for each application (authentication, authorization, sorting, filtering, sideloading relationships, serialization, etc).

Ash is an opinionated yet configurable framework designed to reduce boilerplate in an Elixir application. Ash does this by providing a layer of abstraction over your system's data layer(s) with Resources. It is designed to be used in conjunction with a phoenix application, or on its own.

To riff on a famous JRR Tolkien quote, a Resource is "One Interface to rule them all, One Interface to find them" and will become an indispensable place to define contracts for interacting with data throughout your application.

To start using Ash, first declare your Resources using the Ash Resource DSL. You could technically stop there, and just leverage the Ash Elixir API to avoid writing boilerplate. More likely, you would use extensions like Ash.JsonApi or Ash.GraphQL with Phoenix to add external interfaces to those resources without having to write any extra code at all.

Ash is an open-source project and draws inspiration from similar ideas in other frameworks and concepts. The goal of Ash is to lower the barrier to adopting and using Elixir and Phoenix, and in doing so help these amazing communities attract new developers, projects, and companies.

Example Resource

defmodule Post do
  use Ash.Resource

  actions do
    read :read

    create :create
  end

  attributes do
    attribute :name, :string
  end

  relationships do
    belongs_to :author, Author
  end
end

See the Getting Started Tutorial for more information.

For those looking to add Ash extensions:

• see Spark.Dsl.Extension for adding configuration.
• If you are looking to write a new data source, also see the Ash.DataLayer documentation.
• If you are looking to write a new authorizer, see Ash.Authorizer
• If you are looking to write a "front end", something powered by Ash resources, a guide on building those kinds of tools is in the works.

Creating a new release of Ash

• check out the repository locally
• run mix git_ops.release (see git_ops documentation for more information)
• check the changelog/new release number
• push (with tags) and CI will automatically deploy the hex package

1.0.0 Beta

The package version is 1.0.0+ which typically does not mean beta, but there is a funny story behind it. The 1.0.0 version was accidentally released to hex.pm very early on (before anyone was really using Ash), and we had no way to revert it since it wasn't noticed until the 24 hour period had passed and the hex team were (rightfully) sticklers about breaking the rules around removing packages. Deprecating the package version didn't solve the problem because it was still shown as the latest available version for the package, so we decided to just roll forward with 1.0.0.

Contributors

Ash is made possible by its excellent community!