ash-project/ash
1
0
Fork 0
mirror of https://github.com/ash-project/ash.git synced 2024-09-20 05:23:03 +12:00
Code Issues Projects Releases Packages Wiki Activity

docs: sanitize things for docs

Browse source
This commit is contained in:
Zach Daniel 2022-08-30 16:45:55 -06:00
parent 00433e648a
commit c380cc1a14
13 changed files with 23 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

0
documentation/how_to/store-context-in-process.md
View file

0
documentation/how_to/structure_a_project.md
View file

31
documentation/topics/attributes.md
View file

@ -1,31 +0,0 @@
# taken from `attribute.always_select?`
Useful if fields are used in read action preparations consistently.
A primary key attribute *cannot be deselected*, so this option will have no effect.
Generally, you should favor selecting the field that you need while running your preparation. For example:
```elixir
defmodule MyApp.QueryPreparation.Thing do
use Ash.Resource.Preparation
def prepare(query, _, _) do
query
# we use `ensure_selected` here because we don't want
# to limit the fields being selected to only this attribute, rather
# rather we want to make sure this field is definitely selected.
|> Ash.Query.ensure_selected(:attribute_i_need)
|> Ash.Query.after_action(fn query, results ->
{:ok, Enum.map(results, fn result ->
do_something_with_attribute_i_need(result)
end)}
end)
end
end
```
This will prevent unnecessary fields from being selected.
# Taken from `attribute.generated?`
If it is, the data layer will know to read the value back after writing.

2
documentation/tutorials/get-started.md
View file

@ -524,8 +524,6 @@ Creating and using changesets can be verbose. Check out the {{link:ash:guide:Cod
See {{link:ash_postgres:guide:Get Started With Postgres:AshPostgres}} to see how to back your resources with postgres. This is highly recommended, as the postgres data layer provides tons of advanced capabilities.
See the {{link:ash:guide:Data Layers}} guide on how you might write your own data layer.
#### Add an API
Check out the AshJsonApi and AshGraphql extensions to effortlessly build APIs around your resources

6
documentation/tutorials/philosophy.md
View file

@ -1,10 +1,10 @@
# Philosophy
The philosophy behind Ash allows us to build an extremely flexible and powerful set of tools, without locking users into specific choices at any level. The framework acts as a spinal cord for your application, with extension points at every level to allow for custom behavior. What are follows are the core tenets behind Ash Framework.
The philosophy behind Ash allows us to build an extremely flexible and powerful set of tools, without locking users into specific choices at any level. The framework acts as a spinal cord for your application, with extension points at every level to allow for custom behavior. What follows are the core tenets behind Ash Framework.
## Anything, not Everything
"Anything, not Everything" means building a framework capable of doing anything, not providing a framework that already does everything. The first is possible, the second is not. Our primary goal is to provide a framework that *unlocks* potential, and frees developers to work on the things that makes their application special. To this end, there are many prebuilt extensions to use, but there is also a rich suite of tools to build your *own* extensions. In this way, you can make the framework work for you, instead of struggling to fit your application to a strictly proscribed pattern. Use as much of Ash as you can, and leverage the amazing Elixir ecosystem for everything else.
"Anything, not Everything" means building a framework capable of doing anything, not providing a framework that already does everything. The first is possible, the second is not. Our primary goal is to provide a framework that *unlocks* potential, and frees developers to work on the things that make their application special. To this end, there are many prebuilt extensions to use, but there is also a rich suite of tools to build your *own* extensions. In this way, you can make the framework work for you, instead of struggling to fit your application to a strictly proscribed pattern. Use as much of Ash as you can, and leverage the amazing Elixir ecosystem for everything else.
## Declarative, Introspectable, Derivable
@ -12,7 +12,7 @@ The real superpower behind Ash is the declarative design pattern. All behavior i
## Pragmatism First
While Ash does have lofty goals and a roadmap, the priority for development is always what the *current* users of Ash need or are having trouble with. We focus on simple, pragmatic, and integrated solutions that meld well with the rest of the framework. A high priority is placed on ensuring that our users don't experience feature whip-lash due to poorly thought out implementations, and that any breaking changes(a fairly rare occurrence) have a clean and simple upgrade path. This is something made much easier by the declarative pattern,.
While Ash does have lofty goals and a roadmap, the priority for development is always what the *current* users of Ash need or are having trouble with. We focus on simple, pragmatic, and integrated solutions that meld well with the rest of the framework. A high priority is placed on ensuring that our users don't experience feature whip-lash due to poorly thought out implementations, and that any breaking changes(a fairly rare occurrence) have a clean and simple upgrade path. This is something made much easier by the declarative pattern.
## Community

8
lib/ash/changeset/changeset.ex
View file

@ -1761,7 +1761,7 @@ defmodule Ash.Changeset do
* `:create` - the records are created using the destination's primary create action
* `{:create, :action_name}` - the records are created using the specified action on the destination resource
* `{:create, :action_name, :join_table_action_name, [:list, :of, :join_table, :params]}` - Same as `{:create, :action_name}` but takes
the list of params specified out and applies them when creating the join table row, with the provided join_table_action_name.
the list of params specified out and applies them when creating the join record, with the provided join_table_action_name.
* `:error` - an eror is returned indicating that a record would have been created
* If `on_lookup` is set, and the data contained a primary key or identity, then the error is a `NotFound` error
* Otherwise, an `InvalidRelationship` error is returned
@ -1816,7 +1816,7 @@ defmodule Ash.Changeset do
* belongs_to - an update action on the source resource
* `{:relate_and_update, :action_name, :read_action_name}` - Same as the above, but customizes the read action called to search for matches.
* `{:relate_and_update, :action_name, :read_action_name, [:list, :of, :join_table, :params]}` - Same as the above, but uses the provided list of parameters when creating
the join row (only relevant for many to many relationships). Use `:all` to *only* update the join table row, and pass all parameters to its action
the join row (only relevant for many to many relationships). Use `:all` to *only* update the join record, and pass all parameters to its action
"""
],
on_match: [
@ -1828,9 +1828,9 @@ defmodule Ash.Changeset do
* `:update` - the record is updated using the destination's primary update action
* `{:update, :action_name}` - the record is updated using the specified action on the destination resource
* `{:update, :action_name, :join_table_action_name, [:list, :of, :params]}` - Same as `{:update, :action_name}` but takes
the list of params specified out and applies them as an update to the join table row (only valid for many to many).
the list of params specified out and applies them as an update to the join record (only valid for many to many).
* `{:destroy, :action_name}` - the record is destroyed using the specified action on the destination resource. The action should be:
* many_to_many - a destroy action on the join table
* many_to_many - a destroy action on the join record
* has_many - a destroy action on the destination resource
* has_one - a destroy action on the destination resource
* belongs_to - a destroy action on the destination resource

18
lib/ash/resource/dsl.ex
View file

@ -4,11 +4,7 @@ defmodule Ash.Resource.Dsl do
describe: """
Declares an attribute on the resource.
""",
links: [
guides: [
"ash:guide:Attributes"
]
],
links: [],
examples: [
"""
attribute :name, :string do
@ -102,11 +98,7 @@ defmodule Ash.Resource.Dsl do
describe: """
A section for declaring attributes on the resource.
""",
links: [
guides: [
"ash:guide:Attributes"
]
],
links: [],
examples: [
"""
attributes do
@ -204,9 +196,9 @@ defmodule Ash.Resource.Dsl do
@many_to_many %Spark.Dsl.Entity{
name: :many_to_many,
describe: """
Declares a many_to_many relationship. Many to many relationships require a join table.
Declares a many_to_many relationship. Many to many relationships require a join resource.
A join table is typically a table who's primary key consists of one foreign key to each resource.
A join resource is a resource that consists of a relationship to the source and destination of the many to many.
""",
links: [
guides: [
@ -224,7 +216,7 @@ defmodule Ash.Resource.Dsl do
destination_attribute_on_join_resource :book_id
end
# And in `BookWord` (the resource that defines the join table)
# And in `BookWord` (the join resource)
belongs_to :book, Book, primary_key?: true, required?: true
belongs_to :word, Word, primary_key?: true, required?: true
"""

19
lib/ash/resource/relationships/belongs_to.ex
View file

@ -61,9 +61,7 @@ defmodule Ash.Resource.Relationships.BelongsTo do
[
primary_key?: [
type: :boolean,
links: [
guides: ["ash:guide:Attributes"]
],
links: [],
default: false,
doc:
"Whether the generated attribute is, or is part of, the primary key of a resource."
@ -71,18 +69,14 @@ defmodule Ash.Resource.Relationships.BelongsTo do
required?: [
type: :boolean,
default: false,
links: [
guides: ["ash:guide:Attributes"]
],
links: [],
doc:
"Whether this relationship must always be present, e.g: must be included on creation, and never removed (it may be modified). The generated attribute will not allow nil values."
],
attribute_writable?: [
type: :boolean,
default: false,
links: [
guides: ["ash:guide:Attributes"]
],
links: [],
doc: """
Whether the generated attribute will be marked as public & writable.
"""
@ -90,9 +84,7 @@ defmodule Ash.Resource.Relationships.BelongsTo do
define_attribute?: [
type: :boolean,
default: true,
links: [
guides: ["ash:guide:Attributes"]
],
links: [],
doc:
"If set to `false` an attribute is not created on the resource for this relationship, and one must be manually added in `attributes`, invalidating many other options."
],
@ -101,8 +93,7 @@ defmodule Ash.Resource.Relationships.BelongsTo do
links: [
modules: [
"ash:module:Ash.Type"
],
guides: ["ash:guide:Attributes"]
]
],
default: :uuid,
doc: "The type of the generated created attribute."

2
lib/ash/resource/relationships/many_to_many.ex
View file

@ -86,7 +86,7 @@ defmodule Ash.Resource.Relationships.ManyToMany do
type: :atom,
links: [],
doc:
"The has_many relationship to the join table. Defaults to <relationship_name>_join_assoc"
"The has_many relationship to the join resource. Defaults to <relationship_name>_join_assoc"
]
],
@global_opts,

4
lib/ash/resource/transformers/validate_relationship_attributes.ex
View file

@ -46,14 +46,14 @@ defmodule Ash.Resource.Transformers.ValidateRelationshipAttributes do
raise Spark.Error.DslError,
path: [:relationships, relationship.name],
message:
"Relationship `#{relationship.name}` expects source field on join table `#{relationship.source_attribute_on_join_resource}` to be defined on #{inspect(relationship.through)}"
"Relationship `#{relationship.name}` expects source attribute on resource `#{relationship.source_attribute_on_join_resource}` to be defined on #{inspect(relationship.through)}"
end
unless relationship.destination_attribute_on_join_resource in through_attributes do
raise Spark.Error.DslError,
path: [:relationships, relationship.name],
message:
"Relationship `#{relationship.name}` expects destination field on join table `#{relationship.destination_attribute_on_join_resource}` to be defined on #{inspect(relationship.through)}"
"Relationship `#{relationship.name}` expects destination attribute on join resource `#{relationship.destination_attribute_on_join_resource}` to be defined on #{inspect(relationship.through)}"
end
end
end

2
mix.exs
View file

@ -7,7 +7,7 @@ defmodule Ash.MixProject do
designed to be used by multiple front ends.
"""
@version "2.0.0-pre.8"
@version "2.0.0-rc.0"
def project do
[

2
test/actions/create_test.exs
View file

@ -534,7 +534,7 @@ defmodule Ash.Test.Actions.CreateTest do
|> Api.create!()
end
test "it updates the join table properly" do
test "it updates the join resource properly" do
post2 =
Post
|> new()

2
test/actions/update_test.exs
View file

@ -388,7 +388,7 @@ defmodule Ash.Test.Actions.UpdateTest do
Post |> Ash.Query.sort(:title) |> Api.read!() |> Enum.map(& &1.title)
end
test "it updates the join table properly" do
test "it updates the join resource properly" do
post =
Post
|> new(%{title: "title"})