ecs_on_rails 0.2.2 → 0.3.0

data/lib/ecs_rails/catalogue/geolocation.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A WGS 84 coordinate, and when it was geocoded. Derived data: it exists to
+    # be filled by an entity-blind geocoding system, paired to an `Address` by
+    # sharing its slot (`component Address, prefix: :registered` +
+    # `component Geolocation, prefix: :registered`).
+    module Geolocation
+      extend Definition
+
+      table "geolocations"
+      schema do |t|
+        t.decimal  :lat,         default: nil, precision: 10, scale: 7
+        t.decimal  :lng,         default: nil, precision: 10, scale: 7
+        t.datetime :geocoded_at, default: nil
+      end
+
+      included do
+        validates :lat, numericality: { greater_than_or_equal_to: -90, less_than_or_equal_to: 90 }, allow_nil: true
+        validates :lng, numericality: { greater_than_or_equal_to: -180, less_than_or_equal_to: 180 }, allow_nil: true
+      end
+
+      # @return [Boolean] whether a coordinate has been set
+      def geocoded?
+        lat.present? && lng.present?
+      end
+
+      # @return [Array<BigDecimal>, nil] `[lat, lng]`, or nil when not geocoded
+      def coordinates
+        [lat, lng] if geocoded?
+      end
+
+      # Records a lookup's answer: sets the coordinate and stamps `geocoded_at`.
+      # A lookup that found nothing is recorded as `locate(nil, nil)` — the
+      # stamp still says the address was tried, so a system need not retry it
+      # until the address changes, and stale coordinates never outlive it.
+      #
+      # `at:` defaults to now. A geocoding system that decides staleness by
+      # comparing `geocoded_at` with the address's `updated_at` should pass
+      # the `updated_at` it read instead: an edit landing while the lookup runs
+      # is then still newer than the stamp, and the next run recomputes it.
+      #
+      # @param lat [Numeric, nil]
+      # @param lng [Numeric, nil]
+      # @param at [Time] the moment (or address version) the answer describes
+      # @return [void]
+      def locate(lat, lng, at: Time.current)
+        assign_attributes(lat: lat, lng: lng, geocoded_at: at)
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/identifier.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # An identifier: sku, order_number, invoice_number, slug, an external id
+    # (`stripe_customer`) — one slot each, **unique per slot** at the database.
+    module Identifier
+      extend Definition
+
+      table "identifiers"
+      primary_attribute :value
+      schema do |t|
+        t.string :value, default: nil
+        t.index %i[slot value], unique: true
+      end
+
+      # @return [String] the value, or ""
+      def to_s
+        value.to_s
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/image.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # An image by URL with alt text: avatar, logo — one slot each. When Active
+    # Storage is loaded in the application the class also gains
+    # `has_one_attached :file`, so an upload can back the URL.
+    module Image
+      extend Definition
+
+      table "images"
+      schema do |t|
+        t.string :url, default: nil
+        t.string :alt, default: nil
+      end
+
+      included do
+        validates :url, format: { with: %r{\Ahttps?://\S+\z}, allow_blank: true }
+        has_one_attached :file if respond_to?(:has_one_attached)
+      end
+
+      # @return [Boolean]
+      def present_url?
+        url.present?
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/link.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A URL with a label: website, github, webhook — one slot each.
+    module Link
+      extend Definition
+
+      table "links"
+      schema do |t|
+        t.string :url,   default: nil
+        t.string :label, default: nil
+      end
+
+      included do
+        validates :url, format: { with: %r{\Ahttps?://\S+\z}, allow_blank: true }
+      end
+
+      # @return [String, nil] the host part of the URL
+      def host
+        URI.parse(url).host if url.present?
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/marker.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # The one component every marker is a row of (ADR-0018 §4).
+    #
+    # A marker carries no state: an entity *is* a moderator exactly when the row
+    # exists (ADR-0009). Under ADR-0018 all markers in an application share one
+    # `markers` table — `(id, entity_id, slot, timestamps)`, `UNIQUE (entity_id,
+    # slot)` — and the slot is the marker name. Declaring a marker is pure Ruby:
+    #
+    #   class User < ApplicationEntity
+    #     marker :moderator          # slot "moderator" on the markers table
+    #   end
+    #
+    #   user.add(:moderator)         # a row
+    #   user.moderator?              # => true
+    #   user.remove(:moderator)
+    #
+    # The host application owns the constant and includes this concern, exactly
+    # as with {Relationship}:
+    #
+    #   class Marker < ApplicationComponent
+    #     include EcsRails::Catalogue::Marker
+    #   end
+    #
+    # There is nothing else to it. Presence is {EcsRails::Presence::Entity}'s;
+    # the `marker` declaration ({EcsRails::Markers#marker}) is sugar over
+    # `component Marker, prefix: :moderator, delegate: false` that restores the
+    # bare `moderator?` predicate prefixing would otherwise take away.
+    module Marker
+      extend Definition
+
+      table "markers"
+      schema { |_t| } # no attributes: presence is the whole meaning
+    end
+  end
+end

data/lib/ecs_rails/catalogue/money.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # An amount of money: integer minor units and an ISO 4217 currency code —
+    # never a float. In the `commerce` set.
+    #
+    #   product.price_money.amount_cents = 1999
+    #   product.price_money.to_s                    # => "USD 19.99"
+    #   total = line.price_money + other.price_money  # same currency, or CurrencyMismatch
+    module Money
+      extend Definition
+
+      # Raised by arithmetic across currencies.
+      class CurrencyMismatch < EcsRails::Error; end
+
+      table "monies"
+      set :commerce
+      schema do |t|
+        t.integer :amount_cents, default: 0, null: false
+        t.string  :currency,     default: "USD", null: false, limit: 3
+      end
+
+      included do
+        validates :currency, format: { with: /\A[A-Z]{3}\z/ }
+      end
+
+      # @return [BigDecimal] the amount in major units
+      def amount
+        BigDecimal(amount_cents) / 100
+      end
+
+      # @param value [Numeric] major units
+      # @return [Integer] the stored cents
+      def amount=(value)
+        self.amount_cents = (BigDecimal(value.to_s) * 100).round.to_i
+      end
+
+      # @return [Boolean]
+      def zero?
+        amount_cents.zero?
+      end
+
+      # A new, unsaved instance holding the sum; same currency required.
+      #
+      # @param other [Money]
+      # @return [ActiveRecord::Base]
+      # @raise [CurrencyMismatch]
+      def +(other)
+        ecs_same_currency!(other)
+        self.class.new(amount_cents: amount_cents + other.amount_cents, currency: currency)
+      end
+
+      # A new, unsaved instance holding the difference; same currency required.
+      #
+      # @param other [Money]
+      # @return [ActiveRecord::Base]
+      # @raise [CurrencyMismatch]
+      def -(other)
+        ecs_same_currency!(other)
+        self.class.new(amount_cents: amount_cents - other.amount_cents, currency: currency)
+      end
+
+      # A new, unsaved instance scaled by `factor`, rounded to a cent.
+      #
+      # @param factor [Numeric]
+      # @return [ActiveRecord::Base]
+      def *(factor)
+        self.class.new(amount_cents: (amount_cents * factor).round, currency: currency)
+      end
+
+      # @return [String] e.g. "USD 19.99"
+      def to_s
+        format("%s %.2f", currency, amount)
+      end
+
+      private
+
+      def ecs_same_currency!(other)
+        return if other.currency == currency
+
+        raise CurrencyMismatch, "cannot combine #{currency} with #{other.currency}"
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/name.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A person's name (schema.org `givenName` / `familyName` / `name`).
+    #
+    # `given` and `family` for names that split; `full` for the ones that do
+    # not — mononyms, or an order that is not given-then-family. An
+    # organisation's name is `Text` under slot `name`, not this.
+    #
+    #   user.name.given = "Ada"; user.name.family = "Lovelace"
+    #   user.name.to_s              # => "Ada Lovelace"
+    #   user.name.initials          # => "AL"
+    module Name
+      extend Definition
+
+      table "names"
+      schema do |t|
+        t.string :given,  default: nil
+        t.string :family, default: nil
+        t.string :full,   default: nil
+      end
+
+      # The display form: `full` when set, else given and family joined.
+      #
+      # @return [String]
+      def to_s
+        full.presence || [given, family].compact_blank.join(" ")
+      end
+
+      # @return [String] the first letters of given and family, e.g. "AL"
+      def initials
+        [given, family].compact_blank.map { |part| part[0] }.join.upcase
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/password.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A password digest, via `has_secure_password` (Rails 8's generated
+    # authentication, from the catalogue). Requires the `bcrypt` gem in the
+    # application, as `has_secure_password` always does.
+    #
+    #   user.password.password = "s3cret"; user.save!   # stores a digest
+    #   user.password.authenticate("s3cret")            # => the component, or false
+    #
+    # A `Session` entity is `Token` + `Timestamp` + `relates_to :user`.
+    module Password
+      extend Definition
+
+      table "passwords"
+      schema do |t|
+        t.string :password_digest, default: nil
+      end
+
+      # The one-line class install writes is loaded by every application that
+      # installs `core`, bcrypt or not — and under eager_load a raise here would
+      # stop the app booting for a component it may never use. So the
+      # dependency is checked when the class is *used*: with bcrypt present,
+      # `has_secure_password`; without it, the same methods raise a LoadError
+      # that says what to add.
+      included do
+        if EcsRails::Catalogue::Password.bcrypt_available?
+          has_secure_password
+        else
+          %i[password= password_confirmation= authenticate authenticate_password].each do |method|
+            define_method(method) do |*|
+              raise LoadError, "EcsRails::Catalogue::Password needs the bcrypt gem: add `gem \"bcrypt\"` " \
+                               "to your Gemfile and bundle"
+            end
+          end
+        end
+      end
+
+      # @return [Boolean] whether bcrypt can be required
+      # @api private
+      def self.bcrypt_available?
+        require "bcrypt"
+        true
+      rescue LoadError
+        false
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/period.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A span of time: an event, a booking, an availability window. `ends_at`
+    # may be nil for an open-ended period.
+    module Period
+      extend Definition
+
+      table "periods"
+      schema do |t|
+        t.datetime :starts_at, default: nil
+        t.datetime :ends_at,   default: nil
+        t.string   :time_zone, default: nil
+        t.boolean  :all_day,   default: false, null: false
+      end
+
+      included do
+        validate :ecs_ends_after_starts
+      end
+
+      # @return [Boolean] whether now falls inside the period
+      def current?(at = Time.current)
+        return false if starts_at.nil?
+
+        at >= starts_at && (ends_at.nil? || at < ends_at)
+      end
+
+      # @param other [Period, Range<Time>]
+      # @return [Boolean] whether the two periods share any instant
+      def overlaps?(other)
+        other_start, other_end = if other.respond_to?(:starts_at)
+          [other.starts_at, other.ends_at]
+        else
+          [other.begin, other.end]
+        end
+        return false if starts_at.nil? || other_start.nil?
+
+        (ends_at.nil? || other_start < ends_at) && (other_end.nil? || starts_at < other_end)
+      end
+
+      # @return [ActiveSupport::Duration, nil] the length to the second, or nil
+      #   when open-ended
+      def duration
+        (ends_at - starts_at).round.seconds if starts_at && ends_at
+      end
+
+      private
+
+      def ecs_ends_after_starts
+        return if starts_at.nil? || ends_at.nil? || ends_at >= starts_at
+
+        errors.add(:ends_at, "must not be before starts_at")
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/phone.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A phone number in E.164 (`+61412345678`), with an optional extension.
+    # Multi-role by nature: `component Phone, prefix: :mobile`, `prefix: :work`.
+    #
+    # Format is the E.164 shape (a plus, a non-zero digit, up to 14 more) — no
+    # country database, no dependency.
+    module Phone
+      extend Definition
+
+      table "phones"
+      schema do |t|
+        t.string :e164,      default: nil, limit: 16
+        t.string :extension, default: nil, limit: 8
+      end
+
+      included do
+        validates :e164, format: { with: /\A\+[1-9]\d{1,14}\z/, allow_blank: true }
+        validates :extension, format: { with: /\A\d+\z/, allow_blank: true }
+      end
+
+      # @return [String] the number with the extension, e.g. "+61812345678 x204"
+      def to_s
+        [e164, extension.presence && "x#{extension}"].compact.join(" ")
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/position.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # An ordering within a list — kanban columns, checklist items. One slot per
+    # list an entity can be ordered in.
+    module Position
+      extend Definition
+
+      table "positions"
+      primary_attribute :position
+      schema do |t|
+        t.integer :position, default: 0, null: false
+        t.index %i[slot position]
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/rating.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A rating of one to five stars.
+    module Rating
+      extend Definition
+
+      table "ratings"
+      primary_attribute :stars
+      schema do |t|
+        t.integer :stars, default: nil
+      end
+
+      included do
+        validates :stars, inclusion: { in: 1..5 }, allow_nil: true
+      end
+
+      # @return [Boolean]
+      def rated?
+        stars.present?
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/relationship.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module EcsRails
+  # The catalogue: standard components that ship in the gem as concerns
+  # (ADR-0018). A host application owns the constant and includes the concern:
+  #
+  #   class Relationship < ApplicationComponent
+  #     include EcsRails::Catalogue::Relationship
+  #   end
+  #
+  # `rails g ecs_rails:install` writes these one-line classes and the one
+  # migration that creates their tables. The rest of the catalogue arrives with
+  # Linear ECS-9; {Relationship} is the first entry, because ADR-0017 needs it.
+  module Catalogue
+    # The one component every `relates_to` is a row of (ADR-0017).
+    #
+    # A relationship is a labelled component (RFC-0014) whose single attribute is
+    # a target: the slot is the relationship name, `target_id` points at the
+    # other entity. All relationships in an application live in one
+    # `relationships` table, created at install, so declaring one is pure Ruby:
+    #
+    #   class Post < ApplicationEntity
+    #     relates_to :author, User        # a row with slot "author"
+    #   end
+    #
+    #   post.author = user                # post.author_relationship.target = user
+    #   post.author                       # => the User (ADR-0008 resolves the subclass)
+    #
+    # The table (architecture.md §2):
+    #
+    #   relationships (id, entity_id, slot, target_id, owner_model, exclusive, timestamps)
+    #   UNIQUE (entity_id, slot)                               -- one target per name
+    #   INDEX  (target_id, slot)                               -- inverse lookups (RFC-0015)
+    #   UNIQUE (target_id, slot, owner_model) WHERE exclusive  -- has_one, DB-enforced
+    #   FK entity_id -> entities ON DELETE CASCADE
+    #   FK target_id -> entities ON DELETE NULLIFY
+    #
+    # `owner_model` is a denormalised copy of the owner's `entities.model`, so
+    # the exclusivity index is per owner type (an Invoice and an OrderItem both
+    # pointing at an Order under slot `order` must not collide) and the inverse
+    # `has_many` of RFC-0015 has a cheap scope. `exclusive` is what
+    # `relates_to :order, Order, unique: true` writes; the partial unique index
+    # then rejects a second owner of the same model pointing at the same target
+    # under the same slot — at most one Invoice per Order — with no index of its
+    # own. Both are stamped before save from the owning entity and the slot's
+    # declaration, never set by hand.
+    #
+    # The declared target class travels with the declaration as the slot option
+    # `target_class_name` (RFC-0014), and {#target=} checks assignments against
+    # it: `post.author = company` raises {EcsRails::InvalidRelationship}. The
+    # database never enforced target *type* — the foreign key points at
+    # `entities`, not at a per-type table — so this Ruby check is the type
+    # system, and it is mandatory (ADR-0017). Validation checks ID assignments
+    # too, including saves made directly through this component (RFC-0012).
+    module Relationship
+      extend Definition
+
+      table "relationships"
+      schema do |t|
+        t.uuid    :target_id,   default: nil
+        t.string  :owner_model, null: false
+        t.boolean :exclusive,   default: false, null: false
+        t.index %i[target_id slot]
+        t.index %i[target_id slot owner_model], unique: true, where: "exclusive", name: "index_relationships_exclusive"
+        t.foreign_key :target_id, on_delete: :nullify
+      end
+
+      included do
+        # The pointed-at entity. The association targets the abstract entity
+        # base, exactly as Component's `belongs_to :entity` does, and the loaded
+        # row's `model` decides the subclass (ADR-0008) — so `post.author` is a
+        # User. Optional: an unset relationship is a valid row-less virtual, and
+        # a nullified one (target destroyed) is a valid row (ADR-0003 / ADR-0013).
+        # Explicitly assigned new targets participate in the same transaction
+        # as the link. Autosave also validates them before the owner can commit
+        # (RFC-0012, ECS-25 amendment), preserving the save/save! contract.
+        belongs_to :target, class_name: "ApplicationEntity", optional: true, autosave: true
+
+        # RFC-0014 slot options, set by `relates_to` on the declaration: the
+        # target type this slot points at, and whether the link is exclusive.
+        slot_option :target_class_name
+        slot_option :unique, default: false
+
+        validate :ecs_validate_target
+        before_save :ecs_stamp_owner
+      end
+
+      # The entity class this relationship's slot was declared to point at.
+      #
+      # @return [Class<EcsRails::Entity>, nil] nil for a row whose owner no longer
+      #   declares the slot
+      def target_class
+        target_class_name&.constantize
+      end
+
+      # Assigns the target, checking it against the declared target class first.
+      #
+      # @param value [EcsRails::Entity, nil]
+      # @return [EcsRails::Entity, nil]
+      # @raise [EcsRails::InvalidRelationship] if `value` is not an instance of
+      #   the declared target class (or a subclass of it)
+      def target=(value)
+        expected = target_class
+        if value && expected && !value.is_a?(expected)
+          raise InvalidRelationship,
+                "relates_to :#{slot} on #{entity&.class&.name || owner_model} points at " \
+                "#{expected.name}; got #{value.class.name}"
+        end
+
+        super
+      end
+
+      # Whether the relationship has state waiting to be persisted.
+      # A new target has no UUID yet, but assigning it is a write. Without this
+      # check the lazy cascade skips the link before Rails can autosave its
+      # target. Only inspect an already loaded association: merely checking for
+      # pending state must not query an untouched target (RFC-0006 / RFC-0012).
+      #
+      # @return [Boolean]
+      def ecs_dirty?
+        return true if super
+        return false unless association(:target).loaded?
+
+        target&.new_record? || false
+      end
+
+      private
+
+      # ID writers bypass the object writer's type check. Validate through the
+      # association so preloaded/assigned targets are reused and a changed ID
+      # invalidates the old target using Rails' normal association behavior.
+      # The component error merges onto the owner through RFC-0007, preserving
+      # save/save! behavior even when the owner has not been inserted yet.
+      def ecs_validate_target
+        return if target_id.nil?
+
+        expected = target_class
+        value = target
+        if value.nil?
+          errors.add(:target, "must exist")
+        elsif expected && !value.is_a?(expected)
+          errors.add(:target, "must be a #{expected.name}")
+        end
+      end
+
+      # The owner's discriminator and the slot's exclusivity, copied onto the
+      # row so the database can enforce `unique: true` per owner type
+      # (ADR-0017). Stamped on every save rather than preset on the virtual: a
+      # preset would differ from the column default and make an untouched
+      # virtual look dirty (RFC-0006), and a save is the only time the values
+      # can matter.
+      def ecs_stamp_owner
+        owner = association(:entity).target || entity
+        self.owner_model = owner.model if owner
+        self.exclusive = unique ? true : false
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/role.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A role name: `member`, `owner`, `admin`. Data that belongs to a link, so
+    # it usually sits on a join entity (`Membership`, `Employment`).
+    module Role
+      extend Definition
+
+      table "roles"
+      primary_attribute :name
+      schema do |t|
+        t.string :name, default: nil
+      end
+
+      # @param value [String, Symbol]
+      # @return [Boolean]
+      def is?(value)
+        name == value.to_s
+      end
+    end
+  end
+end