Ruby type representations

[ethnt]

Data objects

Data accessors

attr_reader with instance variables (or data store)

The simplest (but most verbose) way to implement these getters is using instance variables and attr_reader.

class Movie
    attr_reader :id, :title

	def initialize(id:, title:)
		@id = id
		@title = title
	end
end

m = Movie.new(id: 123, title: "Inception")
m.id = 123
m.title = "Inception"
m.something_else # => NoMethodError: undefined method `something_else' for an instance of Movie (NoMethodError)

attr_reader is syntactic sugar that simply acts as a getter for an instance variable — it's shorthand for this:

def title
  @title
end

This is explicit, but verbose. This is very easily typed with Sorbet or RBS, and easy to generate. Instance variables can very easily replaced with a Hash for the actual data — for example:

class Movie
	def initialize(**attributes)
		@attributes = attributes
	end
	
	def id
		@attributes[:id]
	end
	
	def name
		@attributes[:name]
	end
end

Metaprogramming with #method_missing

The #method_missing method in Ruby is heavily used for metaprogramming — when defined in a class, any method call to an object of that class that doesn't exist would then be forwarded to this method. For example:

class Foo
  def bar
    "foobar"
  end

  def method_missing(m, *args, &block)
    puts m
    puts args
  end
end

f = Foo.new
f.bar # => "foobar"
f.foobar(123, "hello")
# =>
#   :m
#   [123, "hello"]

Therefore, with an internal structure of a Hash, you could do something like this:

class Movie
  def initialize(attributes = {})
    @attributes = attributes
  end

  def method_missing(m, *args, &block)
    @attributes[m]
  end
end

m = Movie.new({id: 123, title: "Inception"})
m.id # => 123
m.title # => "Inception"
m.something_else # => nil

The downside here is that there is no autocomplete — since the methods are never defined (just used at runtime), inspecting the class with pry reveals only the #method_missing method.

pry(main)> ls Movie
Movie#methods: method_missing

You can define methods that don't exist in the actual code within RBI and RBS files, but the #method_missing method itself cannot be typed.

Metaprogramming with define_method

The other method of metaprogramming in Ruby is with .define_method, which, uh, defines a method on the class.

class Movie
	def initialize(attributes)
		@attributes = attributes

		self.class.instance_eval do
			attributes.keys.each do |k|
				define_method(k.to_sym) { @attributes[k] }
			end
		end
	end
end

This has the important benefit of being discoverable... kind of. These methods are defined on the class only after they're defined in the initializer.

[1] pry(main)> ls Movie

[2] pry(main)> m = Movie.new({id: 1, name: "foobar"})
=> #<Movie:0x0000000120af8798 @attributes={:id=>1, :name=>"foobar"}>
[3] pry(main)> m.id
=> 1
[4] pry(main)> m.name
=> "foobar"
[5] pry(main)> ls m
Movie#methods: id  name
instance variables: @attributes
[6] pry(main)> ls Movie
Movie#methods: id  name

Again, you can define methods that don't exist in the actual code within RBI and RBS files, but there is no #method_missing to type here. This is the approach that Stripe uses in the stripe-ruby gem.

Attribute properties

The simplest approach here is to have two different data structures:

1. A map between an attribute name and an attribute definition (including properties like type, if it's required, optional, etc)
2. A map between the attribute name and a value

The first can be stored within the class, using some sort of DSL. For example:

class Metadata < DataObject
	field :filetype, :str
end

class Movie < DataObject
	field :id, type: :int, required: true
	field :title, type: :string, required: true
	field :synopsis, type: :string
	field :metadata, type: Metadata
end

And the data about the fields would be stored like so:

@fields = {
	id: #<Field name=:id, type=:int, required=true, optional=false>,
	title: #<Field name=:title, type=:string, required=true, optional=false>,
	synopsis: #<Field name=:synopsis, type=:string, required=false, optional=false>,
	metadata: #<Field name=:metadata, type=Metadata, required=false, optional=false>,
}

This would also be fairly easy to extend into other classes as well with a DSL:

class Animal
  field :breed, type: :string
end

class Dog
  extends [Animal]

  field :bark_volume, type: :integer
end

class Cat
  extends [Animal]

  field :meow_volume, type: :integer
end

Validating input and serialization

Using the aforementioned attribute store, you can then use this to validate input and serialize/deserialize data.

Enums

Enums are not really common in Ruby — Sorbet has them (fairly useless without the runtime, I think), but the closest that RBS can get is a union of possible values. With OpenAPI's definition of enums, we can add on to the attributes just a regular array of possible values (or a Set, if you're worried about uniqueness). Serialization doesn't seem to be a huge problem here (since it's a set of possible values).

In terms of forward compatibility is more complex, I would defer to how Fern does that in other languages.

Literals

Literals (such as "admin") are generally defined using symbols (i.e., :admin).

Undiscriminated unions

Undiscriminated unions are easy to type in both Sorbet (T.any(String, Boolean)) and RBS (String | Boolean).

Discriminated unions

With RBS, this can be typed with unions:

type dog = { type: "dog", breed: String, bark: Boolean }
type cat = { type: "cat", breed: String, meow: Boolean }
type animal = dog | cat

With Sorbet, you'd need to use a mixture of shapes, with a T::Enum as the discriminator:

class AnimalType < T::Enum
	enums do
		Dog = new("dog")
		Cat = new("cat")
	end
end

Cat = T.type_alias { { type: AnimalType, meow: T::Boolean } }
Dog = T.type_alias { { type: AnimalType, bark: T::Boolean } }

Animal = T.any(Cat, Dog)

[ethnt]

I'm going to come back to this with a decision on how data objects should be handled — everything else is straightforward enough!