Simple API for manual nesting?

[jrochkind]

I am working with alba to see if I can easily do what I need with it.

I had an idea, what if alba could have simple API for doing "manual" nesting?

Imagine Employee with name, address_street, address_country.

class EmployeeResource
  include Alba::Resource
 
  attributes :name
 
  nested :address
     attribute :street, &:address_street
     attribute  :country, &:address_country
  end
end

To result in:

{
  name: "some name"
  address: {
    street: "some street",
    country: "some country"
  }
}

nested would just create a nested hash with that name -- inside the block, you are still in the same context as ever, and can call attributes and attribute that just work as usual on the "top" object.

(I am not sure nested is exactly the right name for this method).

This would get at the use case in #211. There you suggested using Rails composed_of, but I don't want to add functionality to my model that is really related to the "shape" I want to serialize in a specific context.

There you also found another way using addiitonal "resource" classes. This is possible, but can get inconvenient when you have a lot of nesting.

For instance, this feature maybe also could be used for implementing Json:Api actually -- in a flexible way that lets someone build Json:Api or something similar that isn't exactly Json:Api , fairly simply:

class EmployeeResource
    include Alba::Resource

   nested :data do
      attribute :type do
         "article"
      end
      attribute :id 

      nested :attributes do
         attributes :foo, :baz. 

         # I actually want to treat this as an attribute, which is totally legal in
         # json:api, an attribute whose value is complex json. This is something
         # your existing json:api draft I don't think lets me easily do
        many :departments do
             attributes :name, :type
         end
      end

      nested :relationships do
         many :something do
             nested :data do
                attributes :id 
                attribute: type do
                    "something"
                end 
         end
      end  
 
      nested :links do
          attribute :self, &:something
      end
   end
end

{
    data: {
       type: "article",
       id: "1",
       attributes: {
          # ....
       },
      relationships: {
       # etc

I don't think this will get all the way to json:api -- For instance, not sure how to use it to handle json:api collections, and relationships are still too fiddly. But maybe it is helpful in defining json:api in simpler terms?

And it lets you do a variety of flexible things that are just similar to json:api in some ways. A simple additional alba API that makes easier a whole category of things you might want to do to "shape" your output.

This is just an idea right now for discussion, I'm not completely positive if it's a great idea.

[okuramasafumi]

Thank you for the suggestion. Basically I'd like the "model" layer to expose nested data structure (in this example, address), but yes, as you said it's flexible, and if it's optional feature we won't feel like we'd like to remove it anyway.
One thing we need to consider is a name, nested is too abstract, but other names, such as hash, don't sound right.
This nested thing is called object in JSON spec (ref: https://www.crockford.com/mckeeman.html) but object is already taken for underlying object.

[okuramasafumi]

I'm convinced that serializers are responsible for nesting and creating proxy object for this purpose is not a good idea. Let's add this feature to Alba.

I'd prefer nested_hash because nested is not clear about what it returns.

[trevorturk]

I think this looks like a great feature! I just wanted to chime in about the name, I think perhaps nested_hash is a bit odd, since you can return a Hash or a JSON object? I think nested could be fine. I looked for prior art and found this: procore-oss/blueprinter#239 -- to compare, I think Alba would do something like:

class EmployeeResource
  include Alba::Resource

  attribute :address do
     attribute :street, &:address_street
  end
end

I could also see using something like nested_attributes or perhaps the word wrapped could be considered. I noticed that Rails uses that term a bit, for example in: https://api.rubyonrails.org/v7.0.3/classes/ActionController/ParamsWrapper.html

Anyway, please feel free to ignore me. This looks like a lovely feature, I just couldn't resist sharing my bike-shedding comments, sorry! 😬

[okuramasafumi]

I also came up with the idea that we can simply call attribute within attribute, in other words, attribute is simply nestable.

If that's difficult we could pass nested: true option to attribute call, that solves naming issue.

[trevorturk]

This looks great, and I think the implementation in #237 seems pretty light weight, which is very nice. I think you'll find the right path within these good options. Excellent work, you two! Thank you! 💝

[jrochkind]

Simply calling attribute within attribute is a nice API, I agree, but since a block argument to attribute already exists with another purpose, I think the implementation might be complicated, to kind of let it do two things at once. Might not be worth it.