ash/README.md

56 lines
2.9 KiB
Markdown
Raw Normal View History

2020-06-04 08:19:12 +12:00
![Test Image 6](https://github.com/ash-project/ash/blob/master/logos/cropped-for-header.png)
2020-06-02 15:23:33 +12:00
2020-06-02 14:10:32 +12:00
![Elixir CI](https://github.com/ash-project/ash/workflows/Elixir%20CI/badge.svg)
2020-06-03 01:41:05 +12:00
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
2020-06-03 00:44:11 +12:00
[![Coverage Status](https://coveralls.io/repos/github/ash-project/ash/badge.svg?branch=master)](https://coveralls.io/github/ash-project/ash?branch=master)
2020-06-03 01:40:33 +12:00
[![Hex version badge](https://img.shields.io/hexpm/v/ash.svg)](https://hex.pm/packages/ash)
2019-10-03 16:08:36 +13:00
2019-12-06 14:56:01 +13:00
## Quick Links
2020-04-05 22:24:56 +12:00
- [Resource Documentation](https://hexdocs.pm/ash/Ash.Resource.html)
- [DSL Documentation](https://hexdocs.pm/ash/Ash.Resource.DSL.html)
- [Code API documentation](https://hexdocs.pm/ash/Ash.Api.Interface.html)
2019-12-06 14:56:01 +13:00
## 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).
2019-10-05 16:16:28 +13:00
2020-06-04 08:21:48 +12:00
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.
2019-10-05 16:16:28 +13:00
2019-12-12 10:21:59 +13:00
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.
2019-12-06 09:46:21 +13:00
2020-06-04 08:22:44 +12:00
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.
2019-10-05 16:16:28 +13:00
2019-12-12 10:21:59 +13:00
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.
2019-10-03 16:08:36 +13:00
2019-12-09 08:48:49 +13:00
## Example Resource
2020-04-05 22:24:56 +12:00
2019-12-09 08:48:49 +13:00
```elixir
defmodule Post do
2020-06-05 14:43:30 +12:00
use Ash.Resource
2019-12-09 08:48:49 +13:00
use AshJsonApi.JsonApiResource
use Ash.DataLayer.Postgres
actions do
2020-05-21 10:59:58 +12:00
read :default
2020-04-05 22:24:56 +12:00
2020-05-21 10:59:58 +12:00
create :default
2019-12-09 08:48:49 +13:00
end
attributes do
attribute :name, :string
end
relationships do
belongs_to :author, Author
end
end
```
2020-06-03 03:47:34 +12:00
## 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