ecs_on_rails 0.2.1

data/lib/generators/ecs_rails/install/install_generator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# active_record must be required explicitly: rails/generators/active_record/
+# migration references ActiveRecord::Migration and ActiveRecord::VERSION but
+# does not load them itself. A host Rails app happens to have ActiveRecord
+# loaded already, so omitting this only breaks in isolation — which is exactly
+# where it is hardest to notice.
+require "active_record"
+require "rails/generators/named_base"
+require "rails/generators/active_record/migration"
+
+# ADR-0010: the generator reads EcsRails.config to place its files and to fill in
+# the initializer. Require the library explicitly so the generator stands on its
+# own requires — a clean `rails g` process must reach EcsRails.config without
+# depending on some other file having loaded it first (see RFC-0008's isolation
+# note and spec/generators/generator_isolation_spec.rb).
+require "ecs_rails"
+
+module EcsRails
+  module Generators
+    # `rails g ecs_rails:install`
+    #
+    # Implements RFC-0008. Emits the `entities` migration and the two abstract
+    # base classes a host app subclasses from. The migration mirrors
+    # docs/architecture.md §2 exactly — if the two ever disagree, the
+    # architecture document wins.
+    #
+    # Inherits from Base rather than NamedBase: install takes no NAME argument.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the entities migration and the ApplicationEntity / " \
+           "ApplicationComponent base classes."
+
+      def create_migration_file
+        migration_template(
+          "migration.rb.tt",
+          File.join(db_migrate_path, "ecs_rails_create_entities.rb")
+        )
+      end
+
+      # ADR-0010: base classes land under the configured layout —
+      # ApplicationEntity at entities_path, ApplicationComponent at
+      # components_path (entities_path/components).
+      def create_base_models
+        template "application_entity.rb.tt",
+                 File.join(EcsRails.config.entities_path, "application_entity.rb")
+        template "application_component.rb.tt",
+                 File.join(EcsRails.config.components_path, "application_component.rb")
+      end
+
+      # ADR-0010: the generated initializer both records the chosen layout (so
+      # ecs_rails:component and the app agree on it) and collapses the nested
+      # components directory, so Zeitwerk maps app/entities/components/name.rb to
+      # the top-level `Name` rather than `Components::Name`.
+      #
+      # An initializer — not application.rb, not the gem's Railtie — is the right
+      # home for the collapse: it runs before eager_load under both lazy and
+      # eager modes, and it does not read entities_path before app initializers
+      # have had their chance to set it. See ADR-0010 "How it works".
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/ecs_rails.rb"
+      end
+
+      private
+
+      # The literal path written into the generated initializer's
+      # `entities_path =` line. Reflects whatever entities_path is at generation
+      # time, so a pre-configured layout carries through into the initializer.
+      def entities_path
+        EcsRails.config.entities_path
+      end
+
+      # The `ActiveRecord::Migration[x.y]` version stamp, tracking whatever
+      # ActiveRecord the host app is actually running.
+      def migration_version
+        "#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"
+      end
+    end
+  end
+end

data/lib/generators/ecs_rails/install/templates/application_component.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# The base class for every component in this application.
+#
+# A component is an ordinary ActiveRecord model that owns one table and belongs
+# to exactly one entity. It may hold behaviour as well as data, and it must
+# never reference an entity subclass.
+#
+# Generate one with:
+#
+#   rails g ecs_rails:component Email address:string verified:boolean
+#
+# See docs/architecture.md §1.
+class ApplicationComponent < EcsRails::Component
+  self.abstract_class = true
+end

data/lib/generators/ecs_rails/install/templates/application_entity.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# The base class for every entity in this application.
+#
+# An entity is an immutable identity row: a UUID and a `model` discriminator,
+# and nothing else. All state lives in components.
+#
+#   class User < ApplicationEntity
+#     component Email
+#   end
+#
+# See docs/architecture.md §1.
+class ApplicationEntity < EcsRails::Entity
+  self.abstract_class = true
+end

data/lib/generators/ecs_rails/install/templates/initializer.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# ECS Rails directory layout (ADR-0010).
+#
+# entities_path is the single knob: entities live here, components live in its
+# `components` subdirectory. Set it to "app/models" to restore the old
+# single-directory layout (no collapse is needed then, since nothing nests).
+EcsRails.configure do |config|
+  config.entities_path = "<%= entities_path %>"
+end
+
+# Rails auto-adds every immediate subdirectory of app/ as an autoload root, so
+# app/entities works for free. The nested components/ directory is the exception:
+# without this, Zeitwerk would namespace it as Components::Name. `collapse` makes
+# the components/ segment transparent, exactly as Rails does for app/models/
+# concerns — so app/entities/components/name.rb resolves to the top-level `Name`.
+Rails.autoloaders.main.collapse(
+  Rails.root.join(EcsRails.config.entities_path, "components")
+)

data/lib/generators/ecs_rails/install/templates/migration.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Creates the single `entities` table every ECS Rails entity shares.
+# See docs/architecture.md §2 and docs/adr/0002-single-entities-table.md.
+class EcsRailsCreateEntities < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    # gen_random_uuid() lives in pgcrypto on PostgreSQL < 13; enabling it is
+    # harmless on 13+, where the function is built in.
+    enable_extension "pgcrypto" unless extension_enabled?("pgcrypto")
+
+    create_table :entities, id: :uuid, default: -> { "gen_random_uuid()" } do |t|
+      # The entity subclass discriminator, e.g. "users". Indexed because
+      # User.all compiles to WHERE model = 'users'.
+      t.string :model, null: false, index: true
+      t.datetime :created_at, null: false
+      # No updated_at — an entity is written once and never changes.
+      # See RFC-0001 and docs/architecture.md §1.
+    end
+  end
+end

data/lib/generators/ecs_rails/relationship/relationship_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# See the note in component_generator.rb: rails/generators/active_record/migration
+# references ActiveRecord::Migration without loading it, so these are required
+# explicitly for load-isolation (generator_isolation_spec.rb).
+require "active_record"
+require "rails/generators/named_base"
+require "rails/generators/active_record/migration"
+
+# ADR-0010: the generator reads EcsRails.config. Require the library explicitly so
+# the generator stands on its own requires (RFC-0008's isolation note).
+require "ecs_rails"
+
+module EcsRails
+  module Generators
+    # `rails g ecs_rails:relationship OWNER name:Target`
+    #
+    #   rails g ecs_rails:relationship Post author:User
+    #
+    # Implements RFC-0012 / ADR-0013. Unlike the component generator, this emits
+    # ONLY a migration — `relates_to` defines the backing component dynamically,
+    # so there is no model file to write. It prints a reminder to add the
+    # `relates_to` line to the entity.
+    #
+    # The migration creates the owner-scoped backing table `post_authors`:
+    #   - uuid PK,
+    #   - entity_id: not-null, UNIQUE index, ON DELETE CASCADE FK to entities —
+    #     the owner side (a post has at most one author; destroying the post
+    #     destroys the link),
+    #   - author_id: indexed, ON DELETE **NULLIFY** FK to entities — the target
+    #     side (destroying the target nullifies, does not cascade to the owner),
+    #   - timestamps.
+    #
+    # The single `name:Target` argument does not fit Rails' GeneratedAttribute
+    # (there is no `:Target` column type), so it is parsed by hand — see
+    # #parse_relationship!.
+    class RelationshipGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :relationship, type: :string, banner: "name:Target"
+
+      desc "Creates the migration for a relationship's backing table (no model)."
+
+      def create_migration_file
+        parse_relationship!
+        migration_template(
+          "migration.rb.tt",
+          File.join(db_migrate_path, "create_#{backing_table_name}.rb")
+        )
+      end
+
+      # RFC-0012: no component file. The DSL defines the backing component; the
+      # developer only has to declare the relationship on the entity.
+      def print_relates_to_reminder
+        entity_path = File.join(EcsRails.config.entities_path, class_path, "#{file_name}.rb")
+        say "Add the relationship to #{entity_path}:", :green
+        say "    relates_to :#{relation_name}, #{target_class_name}"
+      end
+
+      private
+
+      # Splits the `name:Target` argument. `file_name` (from NamedBase) is the
+      # OWNER, e.g. "post"; `relationship` is "author:User".
+      def parse_relationship!
+        @relation_name, @target_class_name = relationship.split(":", 2)
+
+        return unless @relation_name.to_s.empty? || @target_class_name.to_s.empty?
+
+        raise Thor::Error,
+              "expected OWNER name:Target, e.g. " \
+              "`rails g ecs_rails:relationship Post author:User` (got #{relationship.inspect})"
+      end
+
+      attr_reader :relation_name, :target_class_name
+
+      # The owner-scoped backing table: #{owner.singular}_#{relation.plural} —
+      # `post_authors`. Mirrors the derivation in EcsRails::Relationships.
+      def backing_table_name
+        "#{singular_table_name}_#{relation_name.pluralize}"
+      end
+
+      # The target FK column: `author_id`. Mirrors EcsRails::Relationships.
+      def target_foreign_key
+        "#{relation_name}_id"
+      end
+
+      def migration_version
+        "#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"
+      end
+    end
+  end
+end

data/lib/generators/ecs_rails/relationship/templates/migration.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Creates the <%= backing_table_name %> relationship backing table
+# (RFC-0012 / ADR-0013). This is what `relates_to :<%= relation_name %>,
+# <%= target_class_name %>` reads; there is no relationship component file — the
+# DSL defines the backing component dynamically.
+#
+# The owner side (entity_id) and the target side (<%= target_foreign_key %>) are
+# deliberately asymmetric:
+#   - entity_id: not-null, UNIQUE (ADR-0005: at most one per owner), ON DELETE
+#     CASCADE — destroying the owner destroys the link.
+#   - <%= target_foreign_key %>: nullable, ON DELETE NULLIFY — destroying the
+#     TARGET nullifies the link, it does NOT cascade to the owner.
+class Create<%= backing_table_name.camelize %> < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    create_table :<%= backing_table_name %>, id: :uuid, default: -> { "gen_random_uuid()" } do |t|
+      t.uuid :entity_id, null: false
+      t.uuid :<%= target_foreign_key %>, default: nil
+      t.timestamps
+    end
+
+    # ADR-0005: at most one relationship row per owner entity.
+    add_index :<%= backing_table_name %>, :entity_id, unique: true
+
+    # Destroying the owner destroys the link, at the database level.
+    add_foreign_key :<%= backing_table_name %>, :entities, column: :entity_id, on_delete: :cascade
+
+    # Destroying the TARGET nullifies the link — it does not cascade to the owner.
+    add_index :<%= backing_table_name %>, :<%= target_foreign_key %>
+    add_foreign_key :<%= backing_table_name %>, :entities, column: :<%= target_foreign_key %>, on_delete: :nullify
+  end
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: ecs_on_rails
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Jason Hutchens
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: |
+  ECS Rails extends ActiveRecord with an Entity-Component-System persistence
+  architecture inspired by Flecs, while remaining idiomatic Rails. Entities
+  are lightweight identity records composed from reusable, lazily persisted
+  components that encapsulate both data and behaviour.
+email:
+- jasonhutchens@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ecs_on_rails.rb
+- lib/ecs_rails.rb
+- lib/ecs_rails/component.rb
+- lib/ecs_rails/config.rb
+- lib/ecs_rails/dsl.rb
+- lib/ecs_rails/entity.rb
+- lib/ecs_rails/errors.rb
+- lib/ecs_rails/lazy.rb
+- lib/ecs_rails/preloading.rb
+- lib/ecs_rails/presence.rb
+- lib/ecs_rails/querying.rb
+- lib/ecs_rails/railtie.rb
+- lib/ecs_rails/registry.rb
+- lib/ecs_rails/relationships.rb
+- lib/ecs_rails/validations.rb
+- lib/ecs_rails/version.rb
+- lib/generators/ecs_rails/component/component_generator.rb
+- lib/generators/ecs_rails/component/templates/component_spec.rb.tt
+- lib/generators/ecs_rails/component/templates/migration.rb.tt
+- lib/generators/ecs_rails/component/templates/model.rb.tt
+- lib/generators/ecs_rails/install/install_generator.rb
+- lib/generators/ecs_rails/install/templates/application_component.rb.tt
+- lib/generators/ecs_rails/install/templates/application_entity.rb.tt
+- lib/generators/ecs_rails/install/templates/initializer.rb.tt
+- lib/generators/ecs_rails/install/templates/migration.rb.tt
+- lib/generators/ecs_rails/relationship/relationship_generator.rb
+- lib/generators/ecs_rails/relationship/templates/migration.rb.tt
+homepage: https://github.com/kranzky/ecs_rails
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kranzky/ecs_rails
+  changelog_uri: https://github.com/kranzky/ecs_rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kranzky/ecs_rails/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.17
+specification_version: 4
+summary: An Entity-Component-System reimagining of ActiveRecord.
+test_files: []