ecs_on_rails 0.2.2 → 0.3.0

data/lib/ecs_rails/markers.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module EcsRails
+  # The class-level DSL for markers: `marker`.
+  #
+  # Implements ADR-0018 §4 (RFC-0016), which amends ADR-0009's rejection of a
+  # `marker` keyword. Extended into EcsRails::Entity after {DSL}, {Relationships}
+  # and {Querying}, all of which it is built on.
+  #
+  #   class User < ApplicationEntity
+  #     marker :moderator
+  #     marker :administrator
+  #   end
+  #
+  #   user.add(:moderator)            # a row in markers, slot "moderator"
+  #   user.moderator?                 # => true — the row exists
+  #   user.moderator = false          # remove; `= true` adds
+  #   user.remove(:moderator)
+  #   User.with_marker(:moderator)    # entities that have the row
+  #   User.without_marker(:moderator)
+  #
+  # ## How a marker is stored (ADR-0018 §4)
+  #
+  # `marker :moderator` is
+  #
+  #   component Marker, prefix: :moderator, delegate: false
+  #
+  # — a labelled component (RFC-0014) with no attributes, whose slot is the
+  # marker name, on the one `markers` table created at install. The reader is
+  # `moderator_marker`; presence semantics are exactly ADR-0009's: a user *is* a
+  # moderator when the `(entity_id, "moderator")` row exists, `add` writes it
+  # now (the save cascade never would — a marker is never dirty), `remove`
+  # destroys it.
+  #
+  # What the declaration adds over a bare `component` is the ergonomics
+  # prefixing takes away: the predicate is `moderator?`, not
+  # `moderator_marker?`; `add`/`has?`/`remove` take the Symbol; and
+  # `moderator=` accepts a Boolean so a form checkbox routes through flat mass
+  # assignment. The `Marker` class is the host app's one-line catalogue
+  # component (EcsRails::Catalogue::Marker), found by name through
+  # {EcsRails::Config#marker_class_name}.
+  module Markers
+    # Declares a marker named `name`.
+    #
+    # @example
+    #   class User < ApplicationEntity
+    #     marker :moderator
+    #   end
+    #
+    #   user.add(:moderator)
+    #   user.moderator?            # => true
+    #   user.moderator = false     # removes the row
+    #
+    # @param name [Symbol, String] the marker name; becomes the slot, the
+    #   `name?` predicate, the `name=` writer, and the `name_marker` reader
+    # @return [EcsRails::Registry::Declaration] the Marker declaration
+    # @raise [EcsRails::DelegationConflict] if `name?` or `name=` is already a
+    #   method the entity answers
+    # @raise [ArgumentError] if `name` is not a valid slot label
+    # @raise [NameError] if the app has no `Marker` component (run
+    #   `rails g ecs_rails:install`, or set {EcsRails::Config#marker_class_name})
+    # @see EcsRails::Presence::Entity#add
+    # @see #with_marker
+    def marker(name)
+      name = name.to_sym
+      detect_marker_collision!(name)
+
+      declaration = component(ecs_marker_class, prefix: name, delegate: false)
+      define_marker_accessors(name)
+      ecs_own_markers << name unless ecs_own_markers.include?(name)
+
+      declaration
+    end
+
+    # The declared marker names for this entity, ancestry included.
+    #
+    # @example
+    #   User.marker_names  # => [:moderator, :administrator]
+    #
+    # @return [Array<Symbol>]
+    def marker_names
+      entity_ancestry.flat_map { |klass| klass.instance_variable_get(:@ecs_markers) || [] }.uniq
+    end
+
+    # Is `name` a marker this entity declares?
+    #
+    # @param name [Symbol, String]
+    # @return [Boolean]
+    def marker?(name)
+      marker_names.include?(name.to_sym)
+    end
+
+    # Entities that HAVE the marker (RFC-0010 sugar, ADR-0018 §4).
+    #
+    # @example
+    #   User.with_marker(:moderator)
+    #
+    # @param name [Symbol, String] a declared marker
+    # @return [ActiveRecord::Relation] chainable, entity-model scoped
+    # @raise [EcsRails::InvalidComponent] if `name` is not a declared marker
+    # @see #without_marker
+    def with_marker(name)
+      with_component(ecs_marker_class, prefix: ecs_resolve_marker!(name))
+    end
+
+    # Entities that do NOT have the marker.
+    #
+    # @example
+    #   User.without_marker(:administrator)
+    #
+    # @param name [Symbol, String] a declared marker
+    # @return [ActiveRecord::Relation] chainable, entity-model scoped
+    # @raise [EcsRails::InvalidComponent] if `name` is not a declared marker
+    # @see #with_marker
+    def without_marker(name)
+      without_component(ecs_marker_class, prefix: ecs_resolve_marker!(name))
+    end
+
+    private
+
+    # The host app's Marker component (EcsRails::Catalogue::Marker), resolved
+    # by name on every call so a reloaded constant is picked up.
+    def ecs_marker_class
+      EcsRails.config.marker_class_name.constantize
+    rescue NameError => e
+      raise NameError,
+            "EcsRails: `marker` needs the #{EcsRails.config.marker_class_name} component " \
+            "(#{e.message}). Run `rails g ecs_rails:install`, which writes it, or set " \
+            "EcsRails.config.marker_class_name to your class that includes " \
+            "EcsRails::Catalogue::Marker.", e.backtrace
+    end
+
+    # The bare predicate and the Boolean writer, into the same module the
+    # readers live in (ADR-0004: an entity-defined method still wins). Both are
+    # sugar over Presence: `moderator?` is `has?(:moderator)`, `moderator = x`
+    # is `add`/`remove`. The writer is what lets a checkbox param route through
+    # flat mass assignment (`User.update(moderator: "1")`); it takes anything
+    # ActiveModel would cast as a Boolean.
+    def define_marker_accessors(name)
+      mod = generated_component_methods
+
+      mod.define_method(:"#{name}?") { has?(name) }
+      mod.define_method(:"#{name}=") do |value|
+        ActiveModel::Type::Boolean.new.cast(value) ? add(name) : remove(name)
+      end
+    end
+
+    # The names a marker reserves on the entity, for the DSL's conflict checks
+    # (EcsRails::DSL#ecs_reserved_names). Extends whatever Relationships (and
+    # the DSL) reserved.
+    def ecs_reserved_names
+      marker_names.each_with_object(super) do |name, reserved|
+        [:"#{name}?", :"#{name}="].each { |method| reserved[method] ||= "marker :#{name}" }
+      end
+    end
+
+    def ecs_own_markers
+      @ecs_markers ||= []
+    end
+
+    # A marker name resolves to its slot, or raises the fail-loud
+    # InvalidComponent naming the declared markers — the same stance as
+    # relationships (RFC-0013).
+    def ecs_resolve_marker!(name)
+      return name.to_sym if marker?(name)
+
+      declared = marker_names
+      known = declared.empty? ? "none" : declared.map { |n| ":#{n}" }.join(", ")
+      raise InvalidComponent,
+            "#{self.name} has no marker named :#{name}. #{self.name} marks: #{known}."
+    end
+
+    # ADR-0004: the predicate and writer a marker generates must not be names
+    # the entity already answers — a component reader's `email?` predicate, a
+    # delegated `verified=`, a relationship's writer, another marker. The reader
+    # (`moderator_marker`) is checked by `component` itself a moment later.
+    def detect_marker_collision!(name)
+      # The same marker twice is a DuplicateComponent, which `component` raises
+      # a moment later with the slot named; reporting it here as a collision
+      # with its own predicate would be the less useful message.
+      return if marker_names.include?(name)
+
+      taken = component_declarations.flat_map do |declaration|
+        [declaration.reader_name, :"#{declaration.reader_name}?"] + delegation_map_for(declaration).keys
+      end
+      taken += ecs_reserved_names.keys
+
+      clash = [:"#{name}?", :"#{name}="].find { |method| taken.include?(method) }
+      return unless clash
+
+      raise DelegationConflict,
+            "marker :#{name} on #{self.name} collides with an existing ##{clash} method — " \
+            "a component, a relationship or another marker already owns that name. " \
+            "Choose a different marker name."
+    end
+  end
+end

data/lib/ecs_rails/preloading.rb

@@ -53,6 +53,10 @@ module EcsRails
     # @example A named subset, chained onto a component filter
     #   Post.with_component(PublishState).includes_components(Title, Body)
     #
+    # A component declared under several slots (RFC-0014) preloads every slot's
+    # has_one: `includes_components(PostalAddress)` batches `postal_address` and
+    # `business_address` alike, one query each.
+    #
     # @param component_classes [Array<Class<EcsRails::Component>>] components to
     #   preload; empty preloads every component the entity declares
     # @return [ActiveRecord::Relation] chainable, entity-model scoped
@@ -61,19 +65,26 @@ module EcsRails
     #   which accepts any concrete component
     # @see EcsRails::Relationships#includes_related for relationships
     def includes_components(*component_classes)
-      declared = components
-      targets = component_classes.empty? ? declared : component_classes
-      targets.each { |component_class| ecs_validate_declared_component!(component_class, declared) }
+      declarations = component_declarations
+      targets =
+        if component_classes.empty?
+          declarations
+        else
+          component_classes.flat_map { |component_class| ecs_declarations_of!(component_class, declarations) }
+        end
 
-      all.preload(*targets.map { |component_class| ecs_component_association_name(component_class) })
+      all.preload(*targets.map(&:reader_name))
     end
 
     private
 
-    # The has_one name for a component — the same derivation the DSL uses when it
-    # defines the association (EcsRails::DSL#define_component_association).
-    def ecs_component_association_name(component_class)
-      component_class.model_name.singular.to_sym
+    # Every declaration of `component_class` on this entity — one per slot
+    # (RFC-0014). Each reader name is the has_one the DSL defined, so preloading
+    # by reader name is the same derivation the DSL used
+    # (EcsRails::DSL#define_component_association).
+    def ecs_declarations_of!(component_class, declarations)
+      ecs_validate_declared_component!(component_class, declarations.map(&:component_class).uniq)
+      declarations.select { |declaration| declaration.component_class_name == component_class.name }
     end
 
     # A preloadable component is one this entity *declares* — unlike the query DSL

data/lib/ecs_rails/presence.rb

@@ -27,6 +27,15 @@ module EcsRails
   # This module is the entity side. The `<reader>?` predicate is generated per
   # component by the DSL, into generated_component_methods (see
   # EcsRails::DSL#define_component_predicate); it is just `has?(ThatComponent)`.
+  #
+  # Labelled slots (RFC-0014) add an optional `prefix:` to all three verbs —
+  # `add(PostalAddress, prefix: :business)` — and the per-slot predicate
+  # `user.business_address?`. Omitted, `prefix:` means the default slot, so
+  # every singular call reads exactly as before.
+  #
+  # Markers (ADR-0018 §4) add a Symbol form: `add(:moderator)` / `has?` /
+  # `remove` name a marker declared with `marker :moderator`, which is the
+  # `Marker` component in slot "moderator". `user.moderator?` is that `has?`.
   module Presence
     # The entity side of presence: `add` / `has?` / `remove`.
     #
@@ -59,16 +68,27 @@ module EcsRails
       # @example Validation still applies
       #   user.add(Email)         # raises: Email#address is required
       #
-      # @param component_class [Class<EcsRails::Component>] a component this
-      #   entity declares
+      # @example A labelled slot (RFC-0014)
+      #   user.add(PostalAddress, prefix: :business)
+      #   user.business_address?  # => true
+      #
+      # @example A marker, by name (ADR-0018 §4)
+      #   user.add(:moderator)
+      #   user.moderator?         # => true
+      #
+      # @param component_class [Class<EcsRails::Component>, Symbol] a component
+      #   this entity declares, or the name of a marker it declares
+      # @param prefix [Symbol, String, nil] the slot label; nil for the default
+      #   slot. Not accepted with a marker name.
       # @return [EcsRails::Component] the persisted component instance
-      # @raise [EcsRails::InvalidComponent] if the entity does not declare it
+      # @raise [EcsRails::InvalidComponent] if the entity does not declare it in
+      #   that slot
       # @raise [ActiveRecord::RecordInvalid] if the component is invalid — you
       #   cannot add an empty required component (ADR-0009)
       # @see #has?
       # @see #remove
-      def add(component_class)
-        name = ecs_presence_reader(component_class)
+      def add(component_class, prefix: nil)
+        name = ecs_presence_declaration(component_class, prefix).reader_name
 
         # The reader goes through RFC-0006's memo. When no row exists on this
         # instance it loads one (a SELECT) or builds a virtual; when a row does
@@ -102,27 +122,40 @@ module EcsRails
       #   user.has?(Moderator)  # => true
       #   user.moderator?       # => the same question, generated per component
       #
-      # @param component_class [Class<EcsRails::Component>] a component this
-      #   entity declares
-      # @return [Boolean] whether a persisted row exists
-      # @raise [EcsRails::InvalidComponent] if the entity does not declare it
+      # @param component_class [Class<EcsRails::Component>, Symbol] a component
+      #   this entity declares, or the name of a marker it declares
+      # @param prefix [Symbol, String, nil] the slot label; nil for the default slot
+      # @return [Boolean] whether a persisted row exists in that slot
+      # @raise [EcsRails::InvalidComponent] if the entity does not declare it in
+      #   that slot
       # @see #add
       # @see #remove
-      def has?(component_class)
-        name = ecs_presence_reader(component_class)
+      def has?(component_class, prefix: nil)
+        declaration = ecs_presence_declaration(component_class, prefix)
+        name = declaration.reader_name
 
         # Memo first: if this instance already loaded (and persisted) the
-        # component, the answer is known without touching the database. A merely
-        # virtual memo entry is *not* proof of absence — a row could have been
-        # written elsewhere — so it falls through to the existence check rather
-        # than answering false from memory.
+        # component, the answer is known without touching the database.
         cached = @ecs_components&.[](name)
         return true if cached&.persisted?
 
+        # Then the has_one itself. Once ActiveRecord has loaded it — by a
+        # preload (`includes_components(Marker)` on a list view) or by an earlier
+        # read through the reader — its target is authoritative for this
+        # instance, present or absent, exactly as any association cache is; a
+        # row written elsewhere since is stale until `reload`, as it would be
+        # for `user.email`. This is what makes a page of marker badges cost no
+        # queries after one preload (RFC-0016). A virtual memo entry alone does
+        # not decide it: `remove` on an absent marker leaves one behind without
+        # loading anything, and the association says so.
+        association = association(name)
+        return association.target&.persisted? || false if association.loaded?
+
         # Bare existence check: no row is instantiated, so nothing is loaded and
         # nothing is dirtied. One query per component, as everywhere else in the
-        # gem (architecture.md §7 non-goal: query optimisation).
-        component_class.where(entity_id: id).exists?
+        # gem (architecture.md §7 non-goal: query optimisation). Slot-scoped, so
+        # a `business_address` row does not answer for `postal_address`.
+        declaration.component_class.where(entity_id: id, slot: declaration.slot).exists?
       end
 
       # Destroys the row for `component_class` if present, and resets the reader
@@ -133,14 +166,16 @@ module EcsRails
       #   user.remove(Moderator)  # DELETEs the row; no-op if there was none
       #   user.moderator          # => #<Moderator> — virtual again, not nil
       #
-      # @param component_class [Class<EcsRails::Component>] a component this
-      #   entity declares
+      # @param component_class [Class<EcsRails::Component>, Symbol] a component
+      #   this entity declares, or the name of a marker it declares
+      # @param prefix [Symbol, String, nil] the slot label; nil for the default slot
       # @return [self] the entity, for chaining
-      # @raise [EcsRails::InvalidComponent] if the entity does not declare it
+      # @raise [EcsRails::InvalidComponent] if the entity does not declare it in
+      #   that slot
       # @see #add
       # @see #has?
-      def remove(component_class)
-        name = ecs_presence_reader(component_class)
+      def remove(component_class, prefix: nil)
+        name = ecs_presence_declaration(component_class, prefix).reader_name
 
         # Reach the component through the reader so a present row is loaded with
         # its callbacks intact. `component.destroy` fires Lazy::Component's
@@ -155,21 +190,39 @@ module EcsRails
 
       private
 
-      # Resolves a declared component class to its reader name, or raises.
+      # Resolves a declared (component, slot) — or a marker name — to its
+      # declaration, or raises.
       #
       # `add`/`has?`/`remove` accept only a component the entity actually
-      # declares (RFC-0009); anything else — an undeclared component, or a class
+      # declares (RFC-0009), in a slot it declares it under (RFC-0014), or the
+      # Symbol name of a marker it declares (ADR-0018 §4); anything else — an
+      # undeclared component, an undeclared slot, an unknown marker, or a class
       # that is not a component at all — is InvalidComponent, checked before any
-      # database work. The declared set already accounts for inheritance
-      # (DSL#components walks the ancestry), so a subclass sees its parents'
+      # database work. The lookup already accounts for inheritance
+      # (DSL#declaration_for walks the ancestry), so a subclass sees its parents'
       # components too.
-      def ecs_presence_reader(component_class)
-        unless self.class.components.include?(component_class)
+      def ecs_presence_declaration(component_class, prefix)
+        if component_class.is_a?(Symbol) || component_class.is_a?(String)
+          raise ArgumentError, "a marker name takes no prefix: (got #{prefix.inspect})" unless prefix.nil?
+
+          declaration = self.class.marker?(component_class) &&
+                        self.class.declaration_for(EcsRails.config.marker_class_name.constantize,
+                                                   prefix: component_class)
+          return declaration if declaration
+
+          known = self.class.marker_names
           raise InvalidComponent,
-                "#{component_class.inspect} is not a component of #{self.class.name}"
+                ":#{component_class} is not a marker of #{self.class.name}. #{self.class.name} marks: " \
+                "#{known.empty? ? 'none' : known.map { |n| ":#{n}" }.join(', ')}."
         end
 
-        component_class.model_name.singular.to_sym
+        declaration =
+          component_class.is_a?(Class) && self.class.declaration_for(component_class, prefix: prefix)
+        return declaration if declaration
+
+        where = prefix.nil? ? "" : " in slot #{prefix.to_s.inspect} (prefix: :#{prefix})"
+        raise InvalidComponent,
+              "#{component_class.inspect} is not a component of #{self.class.name}#{where}"
       end
     end
   end

data/lib/ecs_rails/querying.rb

@@ -13,6 +13,10 @@ module EcsRails
   #   User.without_component(Avatar)                         # users with NO avatar
   #   Post.with_component(Name).with_component(Avatar)       # AND — chainable
   #
+  #   Product.with_component(Money, prefix: :price) { where("amount_cents < ?", 5000) }
+  #   Product.with_component(Rating, "stars >= ?", 4)         # beyond equality (RFC-0018)
+  #   Product.order_by_component(Money, :amount_cents, prefix: :price)   # cheapest first
+  #
   # Extended into EcsRails::Entity, so these are class methods on every entity
   # class. ActiveRecord delegates class methods to relations (via `scoping`), so
   # `Post.where(...).with_component(...)` chains too: the method runs with `all`
@@ -34,6 +38,15 @@ module EcsRails
   # is Post's own default-scoped relation (`model = 'posts'`, ADR-0002). The DSL
   # only appends the `EXISTS` clause. Building from `unscoped` or from
   # `ApplicationEntity` would drop that scope and leak — so we build from `all`.
+  #
+  # ## Ordering is a different mechanism (RFC-0018)
+  #
+  # `EXISTS` is a boolean: it can filter on a component's value but cannot sort
+  # by it. `order_by_component` adds a correlated **scalar** subquery to
+  # `ORDER BY` — `(SELECT amount_cents FROM monies WHERE entity_id = entities.id
+  # AND slot = 'price' LIMIT 1)` — which needs no join, no table alias, cannot
+  # duplicate rows, and composes with every filter above. Entities without the
+  # row sort last.
   module Querying
     # Entities that HAVE a row for `component_class` (RFC-0010). With
     # `conditions`, the row must also match them (hash equality, like `where`).
@@ -43,7 +56,7 @@ module EcsRails
     # ActiveRecord and treated as data, never SQL (ADR-0011).
     #
     # The component need *not* be declared on this entity: querying a component
-    # the entity never declares is a valid, always-empty query, not an error.
+    # the entity never declares is valid and matches any stored rows (RFC-0010).
     #
     # @example Filtering by a component's attributes
     #   Post.with_component(PublishState, state: "published")
@@ -51,16 +64,95 @@ module EcsRails
     # @example Chaining — each call ANDs
     #   Post.with_component(Title).with_component(Body).order(created_at: :desc)
     #
+    # @example Filtering by slot (RFC-0014) — `prefix:` is sugar for `slot:`
+    #   User.with_component(Address, prefix: :business, region: "WA")
+    #   User.with_component(Address)   # any slot
+    #
+    # @example Beyond equality (RFC-0018): a block, run as the component's scope
+    #   Product.with_component(Money, prefix: :price) { where("amount_cents < ?", 5000) }
+    #   Post.with_component(Tags, prefix: :topics) { tagged("ruby") }        # a component scope
+    #   Post.with_component(SearchVector) { matching("composable") }
+    #
+    # @example Beyond equality: `where`-style positional conditions
+    #   Product.with_component(Rating, "stars >= ?", 4)
+    #   Product.with_component(Rating, ["stars >= ?", 4])
+    #
     # @param component_class [Class<EcsRails::Component>] a concrete component
+    # @param where_args [Array] optional `where`-style conditions — a SQL
+    #   fragment with binds, or an array of them — applied to the component row
+    # @param prefix [Symbol, String, nil] a slot label, as the DSL spells it;
+    #   equivalent to `slot: "label"`. Omitted: any slot.
     # @param conditions [Hash] optional attribute equality the row must match
+    # @yield the component's relation, as `self` — call `where`, `where.not`,
+    #   any of the component's own scopes; must return a relation
     # @return [ActiveRecord::Relation] chainable, and still scoped to this
     #   entity's own `model` discriminator (ADR-0002)
     # @raise [EcsRails::InvalidComponent] if `component_class` is not a concrete
     #   component, or is abstract and so owns no table
+    # @raise [ArgumentError] if the block returns something other than a
+    #   relation of the component
     # @see #without_component
+    # @see #order_by_component
     # @see EcsRails::Relationships#with_related the relationship-name equivalent
-    def with_component(component_class, **conditions)
-      all.where(ecs_component_exists_sql(component_class, conditions, negate: false))
+    def with_component(component_class, *where_args, prefix: nil, **conditions, &block)
+      conditions = ecs_slot_conditions(prefix).merge(conditions)
+      all.where(ecs_component_exists_sql(component_class, conditions, negate: false,
+                                                          where_args: where_args, refine: block))
+    end
+
+    # Orders entities by a component's column, via a correlated scalar subquery
+    # in `ORDER BY` (RFC-0018). Entities without the row sort last, whatever the
+    # direction, unless `nulls: :first`.
+    #
+    # Composes with `with_component` and the rest of ActiveRecord; several calls
+    # order by several components in turn; `reorder` clears earlier orders as
+    # usual. The entity-model scope is untouched: the subquery correlates on
+    # this relation's rows and nothing else.
+    #
+    # @example Cheapest first, then top-rated
+    #   Product.listed.order_by_component(Money, :amount_cents, prefix: :price)
+    #   Product.listed.order_by_component(Rating, :stars, :desc)
+    #
+    # @example By a primary attribute — the column may be omitted
+    #   Post.published.order_by_component(Counter, prefix: :likes, direction: :desc)
+    #   Post.order_by_component(Text, prefix: :title)   # alphabetical by title
+    #
+    # @param component_class [Class<EcsRails::Component>] a concrete component
+    # @param column [Symbol, String, nil] one of the component's columns; omit
+    #   for the component's primary attribute
+    # @param positional_direction [Symbol] `:asc` or `:desc`; also accepted as
+    #   `direction:`, which wins when both are given
+    # @param direction [Symbol, nil] the keyword spelling of the direction
+    # @param prefix [Symbol, String, nil] a slot label; omitted means the
+    #   default slot `""` — ordering needs ONE row per entity, so "any slot" is
+    #   not an option here
+    # @param nulls [Symbol] `:last` (default) or `:first` — where entities with
+    #   no row go
+    # @return [ActiveRecord::Relation] chainable, entity-model scoped
+    # @raise [EcsRails::InvalidComponent] if `component_class` is not a concrete
+    #   component, or is abstract and so owns no table
+    # @raise [ArgumentError] for an unknown column, a missing column on a
+    #   component with no primary attribute, or a bad direction / nulls
+    # @see #with_component
+    def order_by_component(component_class, column = nil, positional_direction = :asc,
+                           direction: nil, prefix: nil, nulls: :last)
+      ecs_validate_queryable_component!(component_class)
+      direction = (direction || positional_direction).to_sym
+      column = ecs_order_column!(component_class, column)
+      unless %i[asc desc].include?(direction)
+        raise ArgumentError, "order_by_component: direction must be :asc or :desc, got #{direction.inspect}"
+      end
+      unless %i[first last].include?(nulls)
+        raise ArgumentError, "order_by_component: nulls: must be :first or :last, got #{nulls.inspect}"
+      end
+
+      subquery = component_class
+                 .where(slot: prefix.to_s)
+                 .where(component_class.arel_table[:entity_id].eq(arel_table[primary_key]))
+                 .select(component_class.arel_table[column])
+                 .limit(1)
+
+      all.order(Arel.sql("(#{subquery.to_sql}) #{direction.to_s.upcase} NULLS #{nulls.to_s.upcase}"))
     end
 
     # Entities that have NO row for `component_class` (RFC-0010).
@@ -75,17 +167,29 @@ module EcsRails
     # @example
     #   User.without_component(Avatar)
     #
+    # @example No row in one slot (RFC-0014)
+    #   User.without_component(PostalAddress, prefix: :business)
+    #
     # @param component_class [Class<EcsRails::Component>] a concrete component
+    # @param prefix [Symbol, String, nil] a slot label; omitted means no row in
+    #   any slot
     # @return [ActiveRecord::Relation] chainable, entity-model scoped
     # @raise [EcsRails::InvalidComponent] if `component_class` is not a concrete
     #   component, or is abstract and so owns no table
     # @see #with_component
-    def without_component(component_class)
-      all.where(ecs_component_exists_sql(component_class, {}, negate: true))
+    def without_component(component_class, prefix: nil)
+      all.where(ecs_component_exists_sql(component_class, ecs_slot_conditions(prefix), negate: true))
     end
 
     private
 
+    # RFC-0014: `prefix: :business` reads as the DSL does and means
+    # `slot: "business"`. The slot is an ordinary column, so this is the only
+    # query surface slots need — pure spelling.
+    def ecs_slot_conditions(prefix)
+      prefix.nil? ? {} : { slot: prefix.to_s }
+    end
+
     # Builds the `EXISTS (...)` / `NOT EXISTS (...)` fragment for one component.
     #
     # The subquery is built from `component_class.where(conditions)` so that
@@ -95,14 +199,23 @@ module EcsRails
     # as properly quoted identifiers against the OUTER entities table — never a
     # hand-built string.
     #
+    # `where_args` (RFC-0018) go through the component relation's own `where`,
+    # so binds are sanitised exactly as in any `where("x > ?", n)`. `refine` is
+    # the block form: instance_exec'd on the component relation so `where`,
+    # `where.not` and the component's scopes read naturally, and checked to
+    # return a relation of the component — anything else is a mistake that
+    # would otherwise silently drop the refinement.
+    #
     # `arel_table` here is the entity class's own table (`entities`); the outer
     # query the fragment is appended to selects from that same table, so `id`
     # correlates to each candidate entity row.
-    def ecs_component_exists_sql(component_class, conditions, negate:)
+    def ecs_component_exists_sql(component_class, conditions, negate:, where_args: [], refine: nil)
       ecs_validate_queryable_component!(component_class)
 
-      subquery = component_class
-                 .where(conditions)
+      subquery = component_class.where(conditions)
+      subquery = subquery.where(*where_args) unless where_args.empty?
+      subquery = ecs_refine_component_scope(component_class, subquery, refine) if refine
+      subquery = subquery
                  .where(component_class.arel_table[:entity_id].eq(arel_table[primary_key]))
                  .select("1")
 
@@ -110,12 +223,45 @@ module EcsRails
       "#{keyword} (#{subquery.to_sql})"
     end
 
+    # The block form of `with_component`: run as the component's relation, and
+    # its result checked, because a block that returns e.g. an Integer or some
+    # other class's relation would otherwise be dropped on the floor.
+    def ecs_refine_component_scope(component_class, scope, block)
+      refined = scope.instance_exec(&block)
+      unless refined.is_a?(ActiveRecord::Relation) && refined.klass == component_class
+        raise ArgumentError,
+              "with_component(#{component_class.name}) { ... } must return a relation of " \
+              "#{component_class.name} (got #{refined.class}); call where/scopes on the block's self"
+      end
+
+      refined
+    end
+
+    # The column to order by: the one given, validated against the component's
+    # real columns (it is interpolated into SQL, so only a known column may pass),
+    # or the component's primary attribute when none is given.
+    def ecs_order_column!(component_class, column)
+      column = column.nil? ? component_class.primary : column.to_sym
+      if column.nil?
+        raise ArgumentError,
+              "order_by_component(#{component_class.name}): name a column — #{component_class.name} " \
+              "declares no primary attribute"
+      end
+      unless component_class.column_names.include?(column.to_s)
+        raise ArgumentError,
+              "order_by_component: #{component_class.name} has no column #{column.inspect} " \
+              "(columns: #{component_class.column_names.join(', ')})"
+      end
+
+      column
+    end
+
     # A queryable component is any concrete EcsRails::Component. Unlike the
     # presence API (RFC-0009), it need NOT be declared on this entity: querying
-    # `Post.with_component(Avatar)` when Post has no Avatar is a valid,
-    # always-empty query, not an error (RFC-0010) — and keeps the DSL from
-    # needing the registry. Anything that is not a concrete component raises
-    # InvalidComponent, before any database work.
+    # `Post.with_component(Avatar)` is valid even without that declaration. It
+    # matches stored rows, if any (RFC-0010), without consulting the registry.
+    # Anything that is not a concrete component raises InvalidComponent before
+    # any database work.
     def ecs_validate_queryable_component!(component_class)
       unless component_class.is_a?(Class) && component_class < EcsRails::Component
         raise InvalidComponent,