feat: rebuild DSL inner workings for extensibility

README.md

@@ -1,16 +1,10 @@
-![Test Image 6](https://github.com/ash-project/ash/blob/master/logos/cropped-for-header.png)
+![Logo](https://github.com/ash-project/ash/blob/master/logos/cropped-for-header.png)
 
 ![Elixir CI](https://github.com/ash-project/ash/workflows/Elixir%20CI/badge.svg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Coverage Status](https://coveralls.io/repos/github/ash-project/ash/badge.svg?branch=master)](https://coveralls.io/github/ash-project/ash?branch=master)
 [![Hex version badge](https://img.shields.io/hexpm/v/ash.svg)](https://hex.pm/packages/ash)
 
-## Quick Links
-
-- [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)
-
 ## 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).

lib/ash.ex

@@ -1,9 +1,53 @@
 defmodule Ash do
   @moduledoc """
-  The primary interface for interrogating apis and resources.
 
-  These are tools for interrogating resources to derive behavior based on their
-  configuration. This is how all of the behavior of Ash is ultimately configured.
+  ![Logo](https://github.com/ash-project/ash/blob/master/logos/cropped-for-header.png?raw=true)
+
+  ## Quick Links
+
+  - [Resource Documentation](Ash.Resource.html)
+  - [DSL Documentation](Ash.Dsl.html)
+  - [Code API documentation](Ash.Api.Interface.html)
+
+  ## 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
+
+  ```elixir
+  defmodule Post do
+    use Ash.Resource
+
+    actions do
+      read :default
+
+      create :default
+    end
+
+    attributes do
+      attribute :name, :string
+    end
+
+    relationships do
+      belongs_to :author, Author
+    end
+  end
+  ```
+
+  For those looking to add ash extensions, see `Ash.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.
   """
   alias Ash.Resource.Actions.{Create, Destroy, Read, Update}
   alias Ash.Resource.Relationships.{BelongsTo, HasMany, HasOne, ManyToMany}
@@ -22,49 +66,42 @@ defmodule Ash do
   @type params :: Keyword.t()
   @type sort :: Keyword.t()
   @type side_loads :: Keyword.t()
-  @type attribute :: Ash.Resource.Attributes.Attribute.t()
+  @type attribute :: Ash.Resource.Attribute.t()
   @type action :: Create.t() | Read.t() | Update.t() | Destroy.t()
   @type query :: Ash.Query.t()
   @type actor :: Ash.record()
 
-  @doc "A short description of the resource, to be included in autogenerated documentation"
-  @spec describe(resource()) :: String.t()
-  def describe(resource) do
-    resource.describe()
-  end
+  require Ash.Dsl.Extension
+  alias Ash.Dsl.Extension
 
   @doc "A list of authorizers to be used when accessing the resource"
   @spec authorizers(resource()) :: [module]
   def authorizers(resource) do
-    resource.authorizers()
-  end
-
-  @doc "A list of resource modules for a given API"
-  @spec resources(api) :: list(resource())
-  def resources(api) do
-    api.resources()
+    :persistent_term.get({resource, :authorizers}, [])
   end
 
   @doc "A list of field names corresponding to the primary key of a resource"
   @spec primary_key(resource()) :: list(atom)
   def primary_key(resource) do
-    resource.primary_key()
+    :persistent_term.get({resource, :primary_key}, [])
+  end
+
+  def relationships(resource) do
+    Extension.get_entities(resource, [:relationships])
   end
 
   @doc "Gets a relationship by name from the resource"
   @spec relationship(resource(), atom() | String.t()) :: relationship() | nil
   def relationship(resource, relationship_name) when is_bitstring(relationship_name) do
-    Enum.find(resource.relationships(), &(to_string(&1.name) == relationship_name))
+    resource
+    |> relationships()
+    |> Enum.find(&(to_string(&1.name) == relationship_name))
   end
 
   def relationship(resource, relationship_name) do
-    Enum.find(resource.relationships(), &(&1.name == relationship_name))
-  end
-
-  @doc "A list of relationships on the resource"
-  @spec relationships(resource()) :: list(relationship())
-  def relationships(resource) do
-    resource.relationships()
+    resource
+    |> relationships()
+    |> Enum.find(&(&1.name == relationship_name))
   end
 
   @spec resource_module?(module) :: boolean
@@ -95,38 +132,44 @@ defmodule Ash do
     end
   end
 
+  def actions(resource) do
+    Extension.get_entities(resource, [:actions])
+  end
+
   @doc "Returns the action with the matching name and type on the resource"
   @spec action(resource(), atom(), atom()) :: action() | nil
   def action(resource, name, type) do
-    Enum.find(resource.actions(), &(&1.name == name && &1.type == type))
+    resource
+    |> actions()
+    |> Enum.find(&(&1.name == name && &1.type == type))
   end
 
-  @doc "A list of all actions on the resource"
-  @spec actions(resource()) :: list(action())
-  def actions(resource) do
-    resource.actions()
+  def attributes(resource) do
+    Extension.get_entities(resource, [:attributes])
+  end
+
+  def extensions(resource) do
+    :persistent_term.get({resource, :extensions}, [])
   end
 
   @doc "Get an attribute name from the resource"
   @spec attribute(resource(), String.t() | atom) :: attribute() | nil
   def attribute(resource, name) when is_bitstring(name) do
-    Enum.find(resource.attributes, &(to_string(&1.name) == name))
+    resource
+    |> attributes()
+    |> Enum.find(&(to_string(&1.name) == name))
   end
 
   def attribute(resource, name) do
-    Enum.find(resource.attributes, &(&1.name == name))
-  end
-
-  @doc "A list of all attributes on the resource"
-  @spec attributes(resource()) :: list(attribute())
-  def attributes(resource) do
-    resource.attributes()
+    resource
+    |> attributes()
+    |> Enum.find(&(&1.name == name))
   end
 
   @doc "The data layer of the resource, or nil if it does not have one"
   @spec data_layer(resource()) :: data_layer()
   def data_layer(resource) do
-    resource.data_layer()
+    :persistent_term.get({resource, :data_layer})
   end
 
   @doc false