Module: ROM::Components::DSL

Defined in:
lib/rom/components/dsl.rb,
lib/rom/components/dsl/core.rb,
lib/rom/components/dsl/view.rb,
lib/rom/components/dsl/mapper.rb,
lib/rom/components/dsl/schema.rb,
lib/rom/components/dsl/command.rb,
lib/rom/components/dsl/dataset.rb,
lib/rom/components/dsl/gateway.rb,
lib/rom/components/dsl/relation.rb,
lib/rom/components/dsl/association.rb,
lib/rom/compat/components/dsl/schema.rb

Defined Under Namespace

Classes: Association, Command, Core, Dataset, Gateway, Mapper, Relation, Schema, View

Instance Method Summary collapse

Instance Method Details

#associations(source: config.component.id, namespace: source, **options, &block) ⇒ Array<Components::Association>

Define associations for a relation

Examples:

class Users < ROM::Relation[:sql]
  associations do
    has_many :tasks
    has_many :posts
    has_many :posts, as: :priority_posts, view: :prioritized
    belongs_to :account
  end
end

class Posts < ROM::Relation[:sql]
  associations do
    belongs_to :users, as: :author
  end

  view(:prioritized) do
    where { priority <= 3 }
  end
end

Returns:



152
153
154
155
 
# File 'lib/rom/components/dsl.rb', line 152

def associations(source: config.component.id, namespace: source, **options, &block)
  __dsl__(DSL::Association, source: source, namespace: namespace, **options, &block)
  components.associations
end

#commands(namespace, **options, &block) ⇒ Object

Command definition DSL

Examples:

setup.commands(:users) do
  define(:create) do
    input NewUserParams
    result :one
  end

  define(:update) do
    input UserParams
    result :many
  end

  define(:delete) do
    result :many
  end
end


177
178
179
180
 
# File 'lib/rom/components/dsl.rb', line 177

def commands(namespace, **options, &block)
  __dsl__(DSL::Command, namespace: namespace, relation: namespace, **options, &block)
  components.commands
end

#dataset(id = nil, **options, &block) ⇒ Object

Set or get custom dataset block

This block will be evaluated when a relation is instantiated and registered in a relation registry.

Examples:

class Users < ROM::Relation[:memory]
  dataset { sort_by(:id) }
end


31
32
33
 
# File 'lib/rom/components/dsl.rb', line 31

def dataset(id = nil, **options, &block)
  __dsl__(DSL::Dataset, id: id, **options, &block)
end

#gateway(id, **options, &block) ⇒ Object 



231
232
233
 
# File 'lib/rom/components/dsl.rb', line 231

def gateway(id, **options, &block)
  __dsl__(DSL::Gateway, id: id, **options, &block)
end

#mappers(namespace = nil, **options, &block) ⇒ Object

Mapper definition DSL



185
186
187
188
 
# File 'lib/rom/components/dsl.rb', line 185

def mappers(namespace = nil, **options, &block)
  __dsl__(DSL::Mapper, namespace: namespace, relation: namespace, **options, &block)
  components.mappers
end

#plugin(*args, &block) ⇒ Plugin

Configures a plugin for a specific adapter to be enabled for all relations

Examples:

setup = ROM::Setup.new(:sql, 'sqlite::memory')

setup.plugin(:sql, relations: :instrumentation) do |p|
  p.notifications = MyNotificationsBackend
end

setup.plugin(:sql, relations: :pagination)

Parameters:

  • adapter (Symbol) —

    The adapter identifier

  • spec (Hash<Symbol=>Symbol>) —

    Component identifier => plugin identifier

Returns:



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/rom/components/dsl.rb', line 207

def plugin(*args, &block)
  case args.size
  when 2
    adapter, spec = args
    type, name = spec.flatten(1)

    # TODO: plugin types are singularized, so this is not consistent
    #       with the configuration DSL for plugins that uses plural
    #       names of the components - this should be unified
    plugin = ROM
      .plugins[Inflector.singularize(type)].adapter(adapter).fetch(name)
      .configure(&block)

    config.component.plugins << plugin

    plugin
  when 1
    plugin(self.adapter, *args)
  else
    raise ArgumentError, "+plugin+ accepts either 1 or 2 arguments (#{args.size} given)"
  end
end

#relation(id, dataset: id, **options, &block) ⇒ Object

Relation definition DSL

Examples:

setup.relation(:users) do
  def names
    project(:name)
  end
end


71
72
73
 
# File 'lib/rom/components/dsl.rb', line 71

def relation(id, dataset: id, **options, &block)
  __dsl__(DSL::Relation, id: id, dataset: dataset, **options, &block)
end

#schema(id = nil, **options, &block) ⇒ Schema

Specify a relation schema

With a schema defined commands will set up a type-safe input handler automatically

Examples:

class Users < ROM::Relation[:sql]
  schema do
    attribute :id, Types::Serial
    attribute :name, Types::String
  end
end

# access schema from a finalized relation
users.schema

Parameters:

  • dataset (Symbol) —

    An optional dataset name

  • infer (Boolean) —

    Whether to do an automatic schema inferring

  • view (Boolean, Symbol) —

    Whether this is a view schema

Returns:



57
58
59
 
# File 'lib/rom/components/dsl.rb', line 57

def schema(id = nil, **options, &block)
  __dsl__(DSL::Schema, id: id, dataset: id, **options, &block)
end

#view(name, schema, &block) ⇒ Symbol #view(name, &block) ⇒ Symbol

Define a relation view with a specific schema

This method should only be used in cases where a given adapter doesn't support automatic schema projection at run-time.

Overloads:

  • #view(name, schema, &block) ⇒ Symbol

    Examples:

    View with the canonical schema

    class Users < ROM::Relation[:sql]
  view(:listing, schema) do
    order(:name)
  end
end

    View with a projected schema

    class Users < ROM::Relation[:sql]
  view(:listing, schema.project(:id, :name)) do
    order(:name)
  end
end
  • #view(name, &block) ⇒ Symbol

    Examples:

    View with the canonical schema and arguments

    class Users < ROM::Relation[:sql]
  view(:by_name) do |name|
    where(name: name)
  end
end

    View with projected schema and arguments

    class Users < ROM::Relation[:sql]
  view(:by_name) do
    schema { project(:id, :name) }
    relation { |name| where(name: name) }
  end
end

    View with a schema extended with foreign attributes

    class Users < ROM::Relation[:sql]
  view(:index) do
    schema { append(relations[:tasks][:title]) }
    relation { |name| where(name: name) }
  end
end

Returns:

  • (Symbol) —

    view method name



122
123
124
125
 
# File 'lib/rom/components/dsl.rb', line 122

def view(id, *args, &block)
  __dsl__(DSL::View, id: id, args: args, &block)
  id
end