ecs_on_rails 0.2.1

data/lib/ecs_rails/presence.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module EcsRails
+  # Component presence as a first-class operation: add / has? / remove.
+  #
+  # Implements RFC-0009, decided by ADR-0009. Surfaced by the demo: a marker
+  # component (Moderator, Administrator) carries no state, so it is never
+  # `ecs_dirty?` (ADR-0003 excludes entity_id as identity), and RFC-0006's save
+  # cascade therefore never writes it. The natural path does nothing at all:
+  #
+  #   user.moderator            # a virtual Moderator
+  #   user.save!                # writes no moderators row — a marker is never dirty
+  #   user.moderator.persisted? # => false, forever
+  #
+  # Presence cannot be inferred from lazy state (reading must stay free, RFC-0006)
+  # and a marker has nothing to dirty, so presence is its own verb:
+  #
+  #   user.add(Moderator)     # persist the row now (idempotent, validated)
+  #   user.has?(Moderator)    # => true — a row exists
+  #   user.moderator?         # => the same question, per-component sugar (DSL)
+  #   user.remove(Moderator)  # destroy the row (idempotent)
+  #
+  # These are useful for *every* component — `has?(Email)`, `remove(Avatar)` —
+  # not just empty ones; a marker is simply the case where presence is the only
+  # state (ADR-0009). Mirrors Flecs' add/has/remove vocabulary.
+  #
+  # 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)`.
+  module Presence
+    module Entity
+      extend ActiveSupport::Concern
+
+      # Ensures a row exists for `component_class` on this entity and returns the
+      # now-persisted instance (RFC-0009).
+      #
+      # Immediate, not deferred to the next save: the whole reason `add` exists
+      # is that the save cascade never persists a marker. Idempotent: an existing
+      # row is returned untouched, never a second INSERT — the unique entity_id
+      # index (ADR-0005) would forbid one, and correctness should not depend on
+      # catching that. Validated: it uses `save!`, so `add(Email)` raises
+      # RecordInvalid (address is required) while `add(Moderator)` always
+      # succeeds. You cannot add an empty required component (ADR-0009).
+      def add(component_class)
+        name = ecs_presence_reader(component_class)
+
+        # 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
+        # exist — including one this instance already added — it is already the
+        # persisted instance, so we return it and no second INSERT is attempted.
+        component = public_send(name)
+        return component if component.persisted?
+
+        # A virtual instance: persist it. entity_id is restamped for the same
+        # reason the cascade does (RFC-0006) — on a freshly built virtual for a
+        # new entity it may not have been set yet. The memo now holds this same,
+        # persisted instance, so a later `entity.moderator` answers from it with
+        # no further query.
+        component.entity_id = id
+        component.save!
+        component
+      end
+
+      # True iff a row exists for `component_class` on this entity (RFC-0009).
+      #
+      # Side-effect-free, like `valid?` (RFC-0007): it never materialises,
+      # persists, or dirties anything. It consults RFC-0006's memo first — a
+      # component dirtied-and-saved on this instance is present without a fresh
+      # query — and otherwise issues a bare existence check (SELECT ... EXISTS),
+      # a load of nothing.
+      def has?(component_class)
+        name = ecs_presence_reader(component_class)
+
+        # 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.
+        cached = @ecs_components&.[](name)
+        return true if cached&.persisted?
+
+        # 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?
+      end
+
+      # Destroys the row for `component_class` if present, and resets the reader
+      # to a virtual default instance — exactly RFC-0006's `component.destroy`
+      # semantics. Idempotent when absent. Returns the entity (RFC-0009).
+      def remove(component_class)
+        name = ecs_presence_reader(component_class)
+
+        # Reach the component through the reader so a present row is loaded with
+        # its callbacks intact. `component.destroy` fires Lazy::Component's
+        # after_destroy, which calls #ecs_forget_component here — dropping the
+        # memo and nilling the association, so the next read rebuilds a virtual.
+        # When nothing is there to destroy the read leaves a virtual in the memo,
+        # which is already the reset state, so remove is idempotent.
+        component = public_send(name)
+        component.destroy if component.persisted?
+        self
+      end
+
+      private
+
+      # Resolves a declared component class to its reader name, or raises.
+      #
+      # `add`/`has?`/`remove` accept only a component the entity actually
+      # declares (RFC-0009); anything else — an undeclared component, 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'
+      # components too.
+      def ecs_presence_reader(component_class)
+        unless self.class.components.include?(component_class)
+          raise InvalidComponent,
+                "#{component_class.inspect} is not a component of #{self.class.name}"
+        end
+
+        component_class.model_name.singular.to_sym
+      end
+    end
+  end
+end

data/lib/ecs_rails/querying.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module EcsRails
+  # The class/relation-level query DSL: filter entities by which components they
+  # have.
+  #
+  # Implements RFC-0010, decided by ADR-0011. Surfaced by the demo, where every
+  # list view hand-rolled a cross-component subquery whose correctness silently
+  # rode the entity's default_scope.
+  #
+  #   Post.with_component(PublishState, state: "published")  # posts that HAVE a
+  #                                                          # matching row
+  #   User.without_component(Avatar)                         # users with NO avatar
+  #   Post.with_component(Name).with_component(Avatar)       # AND — chainable
+  #
+  # 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`
+  # returning the current relation, which already carries the entity-model scope.
+  #
+  # ## Why EXISTS, not JOIN (ADR-0011)
+  #
+  # Each call compiles to a correlated `EXISTS` / `NOT EXISTS` subquery rather
+  # than a join: EXISTS matches an entity once (no duplicate rows), N calls are N
+  # independent `AND EXISTS` clauses that compose without table aliasing, and
+  # `NOT EXISTS` is the natural, NULL-safe form of "without" (unlike `NOT IN` or a
+  # `LEFT JOIN ... IS NULL`).
+  #
+  # ## Why the entity-model scope is correct for free (ADR-0011)
+  #
+  # A component table is blind to entity type — `Name` has rows for Users *and*
+  # Posts. The scope that keeps `Post.with_component(Name)` from returning Users
+  # is NOT added by this DSL. It falls out of the method running on `all`, which
+  # 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`.
+  module Querying
+    # Entities that HAVE a row for `component_class` (RFC-0010). With
+    # `conditions`, the row must also match them (hash equality, like `where`).
+    #
+    # Returns an ActiveRecord::Relation, chainable with `where`, `order`, `limit`,
+    # and further `with_component` / `without_component` calls (which AND).
+    def with_component(component_class, **conditions)
+      all.where(ecs_component_exists_sql(component_class, conditions, negate: false))
+    end
+
+    # Entities that have NO row for `component_class` (RFC-0010). No conditions
+    # form — "without a *matching* row" is ambiguous and unneeded (see the RFC's
+    # Non-goals). A virtual/lazy component has no row, so it counts as absent,
+    # which is the intuitive reading of "without" (ADR-0009).
+    def without_component(component_class)
+      all.where(ecs_component_exists_sql(component_class, {}, negate: true))
+    end
+
+    private
+
+    # Builds the `EXISTS (...)` / `NOT EXISTS (...)` fragment for one component.
+    #
+    # The subquery is built from `component_class.where(conditions)` so that
+    # ActiveRecord sanitises the condition values — they are treated as data,
+    # never SQL, closing the injection hole (ADR-0011). The correlation is an
+    # Arel column comparison, `component.entity_id = entities.id`, so it renders
+    # as properly quoted identifiers against the OUTER entities table — never a
+    # hand-built string.
+    #
+    # `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:)
+      ecs_validate_queryable_component!(component_class)
+
+      subquery = component_class
+                 .where(conditions)
+                 .where(component_class.arel_table[:entity_id].eq(arel_table[primary_key]))
+                 .select("1")
+
+      keyword = negate ? "NOT EXISTS" : "EXISTS"
+      "#{keyword} (#{subquery.to_sql})"
+    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.
+    def ecs_validate_queryable_component!(component_class)
+      unless component_class.is_a?(Class) && component_class < EcsRails::Component
+        raise InvalidComponent,
+              "#{component_class.inspect} is not an EcsRails::Component subclass"
+      end
+
+      # An abstract component owns no table (architecture.md §1), so its EXISTS
+      # subquery could never resolve. Fail here rather than at the database.
+      return unless component_class.abstract_class?
+
+      raise InvalidComponent,
+            "#{component_class.name} is abstract and owns no table; " \
+            "query a concrete component"
+    end
+  end
+end

data/lib/ecs_rails/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module EcsRails
+  # Hooks the gem into a host Rails application.
+  class Railtie < ::Rails::Railtie
+    # The registry keys entries by class name and resolves lazily, so it
+    # survives development-mode reloading. See RFC-0002.
+    config.to_prepare do
+      EcsRails.registry.clear! if EcsRails.registry.respond_to?(:clear!)
+    end
+  end
+end

data/lib/ecs_rails/registry.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Required explicitly rather than relying on ActiveRecord having pulled them in:
+# #constantize is load-bearing for reload safety.
+require "active_support/core_ext/string/inflections"
+require "active_support/core_ext/string/filters"
+
+module EcsRails
+  # Records which components each entity declares. See RFC-0002.
+  #
+  # The registry is a process-wide singleton (`EcsRails.registry`) populated by the
+  # `component` DSL (RFC-0004) at class-load time, and read by generators,
+  # delegation and — later — systems.
+  #
+  # Reload safety is the whole design constraint. In development Rails does not
+  # mutate a reloaded class in place: it removes the constant and autoloads a
+  # brand-new Class object under the same name. A registry that held class
+  # objects would pin the old, orphaned constants forever, and every lookup
+  # would hand back classes the rest of the app has already forgotten. So
+  # nothing here stores a Class: entries are keyed by class *name*, and names are
+  # resolved back to live constants via #constantize at read time.
+  class Registry
+    # One `component Foo` declaration on one entity class.
+    #
+    # A value object over *names*. #entity_class / #component_class resolve on
+    # every call, so a Declaration handed out before a reload still resolves to
+    # the post-reload constants.
+    class Declaration
+      attr_reader :entity_class_name, :component_class_name, :options
+
+      def initialize(entity_class_name:, component_class_name:, options: {})
+        @entity_class_name = entity_class_name
+        @component_class_name = component_class_name
+        @options = options.dup.freeze
+        freeze
+      end
+
+      # Raises NameError if the constant has gone away. See #components_for.
+      def entity_class
+        entity_class_name.constantize
+      end
+
+      def component_class
+        component_class_name.constantize
+      end
+
+      def ==(other)
+        other.is_a?(Declaration) &&
+          entity_class_name == other.entity_class_name &&
+          component_class_name == other.component_class_name &&
+          options == other.options
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, entity_class_name, component_class_name, options].hash
+      end
+
+      def inspect
+        "#<#{self.class} #{entity_class_name} => #{component_class_name} #{options.inspect}>"
+      end
+    end
+
+    def initialize
+      clear!
+    end
+
+    # Records one declaration. Returns the Declaration.
+    #
+    # Raises DuplicateComponent if this entity already declares this component —
+    # per ADR-0005 a component appears at most once per entity, and RFC-0004
+    # relies on the raise to catch a doubled `component` line at class-load time.
+    def register(entity_class:, component_class:, options: {})
+      entity_name = name_for(entity_class)
+      component_name = name_for(component_class)
+
+      declarations = (@declarations[entity_name] ||= [])
+
+      if declarations.any? { |declaration| declaration.component_class_name == component_name }
+        raise DuplicateComponent,
+              "#{entity_name} already declares #{component_name}"
+      end
+
+      declaration = Declaration.new(
+        entity_class_name: entity_name,
+        component_class_name: component_name,
+        options: options
+      )
+      declarations << declaration
+      declaration
+    end
+
+    # The declarations for an entity, in declaration order.
+    #
+    # Resolution is lazy, so this never raises for a stale entry; asking the
+    # returned Declaration for #component_class does. That is deliberate: a
+    # dangling name means the registry has drifted out of sync with the app, and
+    # silently dropping the entry would make generators emit an incomplete schema
+    # and delegation quietly stop working. #clear! is the supported way to drop
+    # entries, and the Railtie calls it on every reload.
+    def components_for(entity_class)
+      declarations = @declarations[name_for(entity_class)]
+      declarations ? declarations.dup : []
+    end
+
+    # Every entity class declaring this component, as live class objects.
+    def entities_for(component_class)
+      component_name = name_for(component_class)
+
+      @declarations.each_value.with_object([]) do |declarations, entities|
+        declarations.each do |declaration|
+          entities << declaration.entity_class if declaration.component_class_name == component_name
+        end
+      end
+    end
+
+    # Resets the registry. Used between tests and by the Railtie's `to_prepare`.
+    def clear!
+      @declarations = {}
+      self
+    end
+
+    # An opaque snapshot of the current declarations, for save/restore around a
+    # block that mutates the registry — chiefly tests that `clear!` the
+    # process-wide singleton and would otherwise wipe declarations that
+    # host/app classes made at load time. `Declaration` is frozen and holds only
+    # strings, so a shallow dup of the arrays is a safe, cheap copy.
+    def snapshot
+      @declarations.transform_values(&:dup)
+    end
+
+    # Replaces the declarations with a previously taken #snapshot.
+    def restore(snapshot)
+      @declarations = snapshot.transform_values(&:dup)
+      self
+    end
+
+    private
+
+    # The one place a Class is turned into a String — and the only thing the
+    # registry ever retains.
+    def name_for(klass)
+      raise ArgumentError, "expected a Class, got #{klass.inspect}" unless klass.is_a?(Module)
+
+      klass.name || raise(ArgumentError, <<~MESSAGE.squish)
+        cannot register an anonymous class: the registry keys entries by class
+        name so they survive Rails reloading. Assign the class to a constant
+        before declaring components on it.
+      MESSAGE
+    end
+  end
+end