Skip to content

[BAC-2109] Discriminated entity unions with a typed tag - #28

Closed
HolyWalley wants to merge 1 commit into
masterfrom
feature/BAC-2109
Closed

HolyWalley wants to merge 1 commit into
masterfrom
feature/BAC-2109

Conversation

@HolyWalley

Copy link
Copy Markdown
Contributor

BAC-2109. Needed first by the Brain thread context (BAC-2091, backends), which is Admin | Whatsapp | Messenger | Instagram, and by other unions we keep working around.

What was missing. An :entity attribute, an :array of entities and karen's ActiveRecord::Type::Entity column all take exactly one class. The only polymorphism in the gem is the ActiveJob serializer's class-name tag, which constantizes from the open world. The usual workaround is a flat superset entity with nullable per-type fields.

What this adds. STI-style unions declared once on a base entity:

class ThreadContext
  include ActiveModel::Entity
  discriminated_by :type, admin: "ThreadContext::Admin", whatsapp: "ThreadContext::Whatsapp"
end
  • The tag is a short string from the closed mapping. Resolution picks from the mapping and never constantizes anything else. Missing or unknown tags raise an ArgumentError naming the base and the allowed tags.
  • new, from_json and represent on the base dispatch on the tag (string or symbol key, camelized in from_json). Calling on a subclass builds that subclass as before. Type::Entity, Type::Array and the column type need no change: class_name: 'ThreadContext' and of: 'ThreadContext' just work, and a subclass instance assigned to a base-typed attribute is kept.
  • Each subclass gets its tag as the attribute default, serialized by represent, and validates it; nested validation runs the real subclass.
  • JSON schema: the base emits oneOf of the subclass refs plus an OpenAPI discriminator with propertyName and mapping; a subclass's schema has the tag as a required string with a one-value enum. Inline form inlines the branches and drops the mapping. Client generators get a tagged union.
  • README section, version 0.17.0.

Not included. Attribute-level sugar like class_name: A | B. The base-class form covers it, and a set used in one place only can get an anonymous base later.

Known. spec/active_model/entity/inspect_spec.rb:45 fails on Ruby 3.4 because of the Hash#inspect spacing change; CI runs 3.3 and it passes there. Untouched here.

🤖 Generated with Claude Code

An :entity attribute, an :array of entities and a JSON column of entities
each take exactly one class. A base entity can now declare a tag attribute
and a closed mapping of tag => subclass:

  discriminated_by :type, admin: "ThreadContext::Admin", whatsapp: "ThreadContext::Whatsapp"

new, from_json and represent on the base dispatch on the tag, so every
existing site typed with the base works unchanged. A subclass carries its
tag as the attribute default and validates it. Resolution picks from the
mapping and never constantizes anything else; a missing or unknown tag
raises. The base's JSON schema is a oneOf of the subclasses with an OpenAPI
discriminator, each subclass marking its tag as a one-value enum, so
clients get a tagged union. Version 0.17.0.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@HolyWalley
HolyWalley requested review from taleh007 and yard October 22, 2026 08:55
@HolyWalley HolyWalley self-assigned this Oct 22, 2026
@HolyWalley

Copy link
Copy Markdown
Contributor Author

Superseded: karen keeps the thread context in an envelope entity (one slot per type) instead of a discriminated union, so the gem stays as it is. See 44-pixels/backends#2345.

@HolyWalley HolyWalley closed this Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant