Having trouble understanding the Centralized Code Interface code example in the Ash Docs

Ash Forum Ash Questions / Help
1

I have been studying the the beta of the Ash Book and going through the docs, and I am having some difficulties grasping this code example from the docs

defmodule MyApp.Tweets do
  use Ash.Domain

  resources do
    resource MyApp.Tweets.Tweet do
      # define a function called `tweet` that uses
      # the `:create` action on MyApp.Tweets.Tweet
      define :tweet, action: :create, args: [:text]
    end

    resource MyApp.Tweets.Comment do
      # define a function called `comment` that uses
      # the `:create` action on MyApp.Tweets.Comment
      define :comment, action: :create, args: [:tweet_id, :text]
    end
  end
end

Which is supposed to allow:

tweet = MyApp.Tweets.tweet!("My first tweet!", actor: user1)
comment = MyApp.Tweets.comment!(tweet.id, "What a cool tweet!", actor: user2)

In my mind the define is operating nested inside a Resource definition and the tweet! and comment! functions should be defined at the Resource level and not at the Domain level.

Again in my mind the define “should” work something like:

define :tweet, module: :MyApp.Tweets.Tweet, action: :create, args: [:text]

Not sure if this is related to me trying to learn Elixir at the same time that I am learning Ash, for sure that is not helping and I have a deep dive on macros and alikes pending.

Thanks in advance on your guidance!

2

If you look closely at the syntax, you’ll notice that define is inside a given resource, so it is aware of the module context it’s in. :slight_smile:

If you want to do the interfaces on the resource, so the call would be MyApp.Tweets.Tweet.tweet, you can alternatively define them in a code_interface block inside the resource itself. It’s up to your preference on how you want to construct the interface.

1 Like
3

I understand, I think, that define has to have awareness of the Resources because it is operating, relying, on the actions defined there. This makes sense.

But it is weird to me the way in which it becomes aware of the Resource context, not sure if I’m explaining myself.

4

Imagine if you had a 100 interfaces for a resource (extreme example), in your example you would have to repeate same module/resource for each. The way it is now, you just put them in the resource block; or define them in the resource.

But I think I understand what you mean: it’s more intuitive to define it as an option. But in the case of defining an interface in a resource, what then? You wouldn’t mention the module? It would be less consistent.

3 Likes
5

Ya it’s funny—I think it does have to do with being new to Elixir because I see what OP means now that they’ve pointed it out but this never once occurred to me before!

@anibal maybe thinking of it as with_resource do would help but as mentioned, it’s really just about getting a clean way to define things. Macro-heavy DSLs can take some getting used to. It’s probably easier to not think of resources and resource as function calls but as a simplified language for creating data structures that are then fed into “real” functions. Incidentally, this is exactly what is happening behind the scenes!

For example, would the following be as surprising? (Note, this is a completely invented simplified example):

defmodule MyApp.Tweets do
  @behaviour Ash.Domain

  @impl true
  def domain do
    %{
      resources: [
        %{
          module: MyApp.Tweets.Tweet,
          define: [
            :tweet, action: :create, args: [:text]
          ]
        },
        %{
          module: MyApp.Tweets.Comment,
          define: [
            :comment, action: :create, args: [:tweet_id, :text]
          ]
        }
      ]
    }
  end
end

Ash could have been done in a manner like that, but the DSL is much nicer.

3 Likes
6

Extrema but useful, I get the convenience of having the block to operate within it.

Ummm, maybe something like:

defmodule Foo.Bar do
  use Ash.Resource, domain: Foo.Bar

  actions do
    ...
  end

  interface  do
     define ...
  end

That would be obvious to me, also to an LLM which my be an interesting consideration. Not saying this is the way it should be, I’m a newcomer still learning the basics.

7

Indeed! Thinking of it as with_resource do shines a different light on it, I am OK with DSL heavy syntax since ye old Rails days. I am comfortable with the “Ash way”, but this syntax in particular felt like the neddle skipping on vinyl. With you answer I will need now to research understand what else should fit under:

  resources do
    resource MyApp.Foo.Bar do
       ... 
    end

Thanks.

1 Like
8

You can do it that way, but it is code_interface.

That’s what I meant before by you get to choose whether to put it on the Domain or Resource.

As far as AI, Zach has put a lot of effort into informing AI, and all the official Ash libs have usage rules defined that you can plug into your LLM’s context. With that set up, it understands how to use domain interfaces pretty well.

9

Thanks for the pointer, completely missed the existence of code_interface !!! This is easier for me to understand.

10

By defining the interface on the domain, you get something more akin to a “service”. i.e

MyApp.Accounts.register_user!(...)

vs

MyApp.Accounts.User.register_user!()

Defining them on the domain for the most part decouples the caller from the resource in charge of registering said user.

3 Likes
11

Thanks for the hint, I started to review Domain Driven Design principles together with Ash to find a guide in such kind of decisions. Nice thing the framework provide the flexibility.