ecs_on_rails 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bef233f6d1933696953db3058563f4e4178c67aeb6d56f6d2f241f64f23b81f3
+  data.tar.gz: a7806e71e299991ae122dd30ce78a009bf181ed55c11d8b43444be2a2f6ef1d8
+SHA512:
+  metadata.gz: 7fd3624f55f3264bbaf3c84cb355a63cc5e0e5e66eabd43d04ad01c1d87bff202dd8d4e851d6006c66c383c742702da548115161ab33dd2ddc7d1f37b0e86295
+  data.tar.gz: 926baa1d0cfca36f1453d0cc4abb02d463a04d49b499b2a6eb72f54534a4486ccfe27e1452a6b0a2206f2589062cd4f53aa1b05ab07fed7b4479e19515b92ecd

data/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] — 2026-07-23
+
+First RubyGems release.
+
+### Changed
+
+- The gem is published as **`ecs_on_rails`**. Both `ecs-rails` and `ecs_rails`
+  are unavailable: an unrelated `ecs-rails` gem already exists, and RubyGems
+  treats `-`, `_` and case as equivalent when comparing names, so every spelling
+  of "ecs rails" collides with it.
+- **No API change.** The require path is still `ecs_rails`, the module is still
+  `EcsRails`, and the generators are still `ecs_rails:install`,
+  `ecs_rails:component` and `ecs_rails:relationship`. Only the name you put in
+  your Gemfile differs:
+
+  ```ruby
+  gem "ecs_on_rails"   # Gemfile
+  require "ecs_rails"  # everywhere else
+  ```
+
+  A `lib/ecs_on_rails.rb` shim requires `ecs_rails`, so a bare `gem
+  "ecs_on_rails"` works under `Bundler.require`.
+
+## [0.2.0] — 2026-07-22
+
+Adds cross-entity relationships. Demo-validated by the bulletin-board app.
+
+### Added
+
+- Relationship query & preload sugar (RFC-0013). `Entity.with_related(:author, user)` /
+  `without_related(:author)` / `includes_related(:author)` query and preload a
+  relationship by its declared name, so the backing component class never appears in
+  application code. Thin sugar over the component verbs.
+- Relationship DSL (RFC-0012). `relates_to :author, User` on an entity declares a
+  cross-entity link with no relationship component file — the DSL defines the
+  backing component dynamically. `post.author` / `post.author =` reach the target;
+  `rails g ecs_rails:relationship Post author:User` emits the migration. Deleting
+  the target nullifies the link; deleting the owner cascades.
+
+## [0.1.0] — 2026-07-20
+
+Feature-complete, demo-validated. Not yet published to RubyGems. See the
+[v0.1 retrospective](../docs/retrospective-v0.1.md).
+
+### Added
+
+- Component preloading (RFC-0011). `Entity.includes_components(*Components)` batches
+  component loads (all declared, or a named subset) so a list view issues a bounded
+  number of queries instead of one per component per row. A thin wrapper over
+  ActiveRecord's native `preload`, which already works with lazy components.
+- Component query DSL (RFC-0010). `Entity.with_component(Component, **conditions)` /
+  `Entity.without_component(Component)` query entities by which components they
+  have, compiling to correlated `EXISTS` / `NOT EXISTS` subqueries that apply the
+  entity-model scope automatically (a shared component can't leak across entity
+  types). Chainable with ordinary ActiveRecord. Avoids `.with` (AR's CTEs).
+- Component presence (RFC-0009). `entity.add(Component)` / `entity.has?(Component)` /
+  `entity.remove(Component)` and a generated `entity.<component>?` predicate, so
+  marker components (Moderator, Administrator) — which carry no state and so are
+  never persisted by the lazy save cascade — work.
+- Validation error merging (RFC-0007). `entity.valid?` reflects its touched
+  components' validity; component errors merge under `entity.errors[:"email.address"]`
+  and read naturally in a form. A non-dirty virtual component is not validated.
+- Method delegation (RFC-0005). Component methods and attribute accessors are
+  callable on the entity — `user.send_welcome_email`, `user.address = "x"`.
+  Name clashes between two components raise `DelegationConflict` at load time;
+  `except:`/`only:` are the escape hatch.
+- Lazy / virtual components (RFC-0006). `entity.email` always returns an
+  `Email`, never `nil` — a missing row yields an in-memory component with every
+  attribute at its database default. `entity.save` cascades to the components
+  you touched, inserting a row only for those that are dirty, in one
+  transaction. Reading a component costs a `SELECT` and nothing else.
+- The `component` DSL (RFC-0004). `component Name` on an entity declares what it
+  is composed from, generates the reader, and wires the `has_one`.
+- `ApplicationComponent` (RFC-0003) and entity subclass resolution — a loaded
+  entity comes back as its real subclass (`User`, not `ApplicationEntity`).
+- `ApplicationEntity` (RFC-0001) — immutable identity rows in one shared
+  `entities` table, discriminated by `model`.
+- The component registry (RFC-0002), reload-safe by keying on class name.
+- `ecs_rails:install` and `ecs_rails:component` generators (RFC-0008).
+- Gem scaffold, MIT licence, and RSpec + PostgreSQL test harness.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jason Hutchens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# ECS Rails
+
+An Entity–Component–System reimagining of ActiveRecord that stays idiomatic to
+Ruby on Rails.
+
+> The full API below is implemented and tested (534 examples on real
+> PostgreSQL). A companion bulletin-board app is built entirely on it and runs
+> live at **[ecs-rails.kranzky.com](https://ecs-rails.kranzky.com)**. See the
+> [v0.1 retrospective](https://github.com/kranzky/ecs_rails/blob/main/docs/retrospective-v0.1.md)
+> for the full story of how it was designed.
+
+## The idea
+
+Replace one-table-per-model with one-table-per-component. An entity is a
+lightweight identity row; all state and behaviour live in small, reusable
+components that are composed onto it.
+
+```ruby
+class User < ApplicationEntity
+  component Name
+  component Email
+  component Avatar
+  component Moderator          # a marker: no data, presence is the meaning
+end
+
+class Email < ApplicationComponent
+  validates :address, presence: true
+
+  def send_welcome_email
+    # self is the Email, never the User
+  end
+end
+```
+
+```ruby
+user = User.create!            # one row in `entities`, no component rows
+user.email                     # => #<Email> — virtual, not persisted
+user.email.address = "a@b.com"
+user.save!                     # now `emails` gets a row
+
+user.send_welcome_email        # delegated to the Email component
+user.errors[:"email.address"]  # component errors merge onto the entity
+```
+
+Every v0.1 capability, working today:
+
+```ruby
+# Lazy components — no row until a value differs from its default.
+user.avatar.persisted?                       # => false, costs no INSERT
+
+# Presence / markers — a user IS a moderator when the row exists.
+user.add(Moderator); user.moderator?         # => true
+user.remove(Moderator)
+
+# Query by composition — avoids AR's .with (CTEs); scopes to the entity model.
+Post.with_component(PublishState, state: "published")
+User.without_component(Avatar)
+
+# Preload to bound the query count on a list view.
+Post.with_component(PublishState).includes_components(Title, Body, Likes)
+```
+
+Components are shared by *type*, so `Likes` behaves identically on a `Post` and
+a `Comment` — reuse without STI and without polymorphic associations.
+
+## Getting started
+
+```ruby
+# Gemfile — note the packaging name differs from the require path (see Names)
+gem "ecs_on_rails"
+```
+
+```sh
+bundle install
+rails g ecs_rails:install
+rails g ecs_rails:component Email address:string verified:boolean
+```
+
+Entities go in `app/entities`, components in `app/entities/components`
+([configurable](https://github.com/kranzky/ecs_rails/blob/main/docs/adr/0010-entity-component-directory-layout.md)); the
+install generator wires the autoloading.
+
+## Documentation
+
+- **[Architecture](https://github.com/kranzky/ecs_rails/blob/main/docs/architecture.md)** — the invariants. Start here.
+- **[v0.1 retrospective](https://github.com/kranzky/ecs_rails/blob/main/docs/retrospective-v0.1.md)** — what was built, what
+  the demo found, what's next.
+- **[ADRs](https://github.com/kranzky/ecs_rails/tree/main/docs/adr)** — why the design is the way it is (14 decisions,
+  several amended by their own demo).
+- **[RFCs](https://github.com/kranzky/ecs_rails/tree/main/docs/rfc)** — the 13 features, each one commit.
+- **[Backlog](https://github.com/kranzky/ecs_rails/blob/main/docs/backlog.md)** — what deliberately isn't built yet.
+- **[Friction log](https://github.com/kranzky/ecs_rails/blob/main/docs/friction-log.md)** — the demo's running verdict on
+  the API.
+
+## Development
+
+Requires Ruby >= 3.2 and a running PostgreSQL.
+
+```sh
+createdb ecs_rails_test
+bundle install
+bundle exec rspec
+```
+
+Set `DATABASE_URL` to point the suite at a different database.
+
+## Names
+
+`ecs_rails` everywhere except the Gemfile — see
+[ADR-0007](https://github.com/kranzky/ecs_rails/blob/main/docs/adr/0007-monorepo-and-licensing.md#three-different-names).
+
+| | |
+|---|---|
+| GitHub repo | [`ecs_rails`](https://github.com/kranzky/ecs_rails) |
+| RubyGems gem | `ecs_on_rails` |
+| Ruby module | `EcsRails` |
+| `require` | `ecs_rails` |
+| Generators | `ecs_rails:install`, `:component`, `:relationship` |
+
+Only the published gem name differs. RubyGems collapses `-`, `_` and case when
+comparing names, so `ecs-rails`, `ecs_rails` and `ecsrails` are one name — and
+it belongs to an unrelated, still-maintained gem. `ecs_on_rails` keeps the
+`rails` keyword without the `rails-` prefix that convention reserves for Rails
+Core Team gems.
+
+## Licence
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/ecs_on_rails.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# The gem is published as "ecs_on_rails", but its canonical require path and
+# module are "ecs_rails" / EcsRails. Bundler requires a gem by its own name, so
+# `Bundler.require` (i.e. a bare `gem "ecs_on_rails"` in a Gemfile) attempts
+# `require "ecs_on_rails"` and would raise LoadError without this file.
+#
+# Requiring "ecs_rails" directly is equivalent and is what the documentation
+# uses throughout.
+require "ecs_rails"

data/lib/ecs_rails/component.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module EcsRails
+  # An ordinary ActiveRecord model that belongs to exactly one entity.
+  #
+  # Implements RFC-0003. See docs/architecture.md §1 for the invariants.
+  #
+  # Host apps subclass this once, as ApplicationComponent, then subclass that
+  # per component type:
+  #
+  #   class ApplicationComponent < EcsRails::Component
+  #     self.abstract_class = true
+  #   end
+  #
+  #   class Email < ApplicationComponent
+  #     validates :address, presence: true
+  #   end
+  #
+  #   Email.where(verified: false)  # queried directly; no join to entities
+  #   Email.first.entity            # => #<User> — the real subclass (ADR-0008)
+  #
+  # A component owns its own table and knows nothing about entity subclasses.
+  # Scopes, validations, callbacks and associations all work as normal: this is
+  # a plain AR model that happens to hang off an entity.
+  #
+  # The one sanctioned exception to "knows nothing about entity subclasses" is a
+  # relationship component's `class_name:` — see ADR-0006.
+  class Component < ActiveRecord::Base
+    self.abstract_class = true
+
+    # Lazy / virtual components (RFC-0006), from the component's side: what
+    # "dirty" means — the question that decides whether this component is worth
+    # a row — and the after_destroy that resets its entity's reader back to a
+    # virtual instance (architecture.md §3).
+    include Lazy::Component
+
+    # Every component belongs to exactly one entity (architecture.md §1).
+    #
+    # The association targets the abstract ApplicationEntity, which has no table
+    # of its own — but EcsRails::Entity sets table_name to "entities", so the
+    # generated query is an ordinary select against that table. The loaded row's
+    # `model` column then decides which subclass to instantiate, via
+    # Entity.discriminate_class_for_record. That is what makes `email.entity`
+    # return a User rather than an ApplicationEntity (RFC-0003, ADR-0008).
+    #
+    # `optional: false` is explicit rather than inherited from
+    # `belongs_to_required_by_default`. That config is applied by the Rails
+    # railtie via load_defaults, so its value depends on the host app's
+    # configured defaults and is not visible in bare ActiveRecord. RFC-0003
+    # requires entity_id to be required unconditionally, so we state it here
+    # rather than inherit a host's setting. (Same reasoning as RFC-0001's
+    # readonly guard in entity.rb.)
+    #
+    # Deliberately no `dependent:` option. Cascade is owned by the database:
+    # every component table has an ON DELETE CASCADE foreign key to
+    # entities(id), so entity.destroy removes the component rows
+    # (architecture.md §3). Declaring `dependent: :destroy` on this side would
+    # invert the ownership — destroying a component would destroy its entity,
+    # and with it every sibling component. That is the wrong direction and
+    # destructive; the DB layer already has the right one.
+    belongs_to :entity, class_name: "ApplicationEntity", optional: false
+
+    # The unique index on entity_id (ADR-0005) is the real enforcement, and a
+    # uniqueness validation here would cost a SELECT on every save while still
+    # racing. RFC-0003 asserts RecordNotUnique from the database, so the guard
+    # is left where it is enforced.
+  end
+end

data/lib/ecs_rails/config.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module EcsRails
+  # Generator configuration for the directory layout (ADR-0010).
+  #
+  # The gem RUNTIME never reads this: entities and components are keyed by class
+  # name (RFC-0002) and by the `model` discriminator (ADR-0002), so the registry
+  # does not care where a class file lives. This object exists purely so the
+  # generators (RFC-0008) know where to write, and so the initializer they emit
+  # can echo the chosen path.
+  #
+  # `entities_path` is the single knob. Components always live in a `components`
+  # subdirectory of it, which is why `components_path` is derived rather than
+  # separately settable — ADR-0010 deliberately exposes one path, not two.
+  class Config
+    # Entities land here; the default is the ADR-0010 layout. Set it to
+    # "app/models" to restore the pre-ADR-0010 single-directory layout.
+    attr_accessor :entities_path
+
+    def initialize
+      @entities_path = "app/entities"
+    end
+
+    # Components live in a `components` subdirectory of the entities path. The
+    # generated initializer collapses this directory so Zeitwerk treats the
+    # `components/` segment as transparent (ADR-0010 "How it works").
+    def components_path
+      "#{entities_path}/components"
+    end
+  end
+end