ambassadors 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b0c2c3ab1c86761e0943b3f7d04f22064c61fab01d79d09f46de1949989205d
+  data.tar.gz: fd23cf3f92d981992d09b8d68c66edd9dfd3a3e9f68dd10b4155ba6eef4083c9
+SHA512:
+  metadata.gz: 94dfadc228c1e01b94654564ba821fd7026e2eca4f906b6e9101985b35cb81fd4b2caaa0d6e5ef45fc953711b6e396251ee630a1c865647a8ba7a7e427bfb095
+  data.tar.gz: 7d0fe8f56f03ff0b86ae654df50f4ec4a6b87f6e34b0bacfdda7c88421244a794923585bd6e0b4fcb3d6c69393fd029cb7f7d35686854886ecc996692683048b

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-23
+
+Initial public release.
+
+- `Ambassador` base class with the `expose` DSL for read-only, frozen properties.
+- `AmbassadorCollection` for enumerating entities as ambassadors, with batched iteration for `ActiveRecord::Relation`.
+- `ambassador_options:` for passing keyword arguments through to each ambassador's constructor.
+- `cursor:` and `order:` options to control batched iteration.
+- `Ambassador#to_ambassador` for polymorphic casting.
+- Optional Rails integration that includes `ActiveModel::Serialization` in `Ambassador` when available.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"ambassadors" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["gavin@gavinmorrice.com"](mailto:"gavin@gavinmorrice.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 CleoAI Ltd.
+
+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,237 @@
+[![Ruby](https://github.com/meetcleo/ambassadors/actions/workflows/main.yml/badge.svg)](https://github.com/meetcleo/ambassadors/actions/workflows/main.yml)
+
+# Ambassadors
+
+Immutable, read-only wrappers for your domain entities, designed for modular monoliths with explicit domain interfaces.
+
+The core of this gem is the `Ambassador` class, with `AmbassadorCollection` as a supporting abstraction for iterating safely over many ambassadors.
+
+- `Ambassador` - a frozen, read-only, stable façade over a domain entity.
+- `AmbassadorCollection` - an `Enumerable` that always yields ambassador instances, with optional batching for heavy data sources (such as large ActiveRecord collections).
+
+---
+
+## Motivation
+
+In a modular monolith, domain boundaries should be explicit.
+
+Passing raw ORM models or deeply coupled objects across those boundaries makes refactors risky and leaks internal concerns everywhere.
+
+**Ambassadors** are:
+
+- Read-only views over your domain entities
+- Explicit about what they expose
+- Immutable once constructed
+
+They are a safe value to return from **domain interface methods** to the outside world (other domains, adapters, controllers, etc.).
+
+`AmbassadorCollection` then gives you a consistent way to work with many such ambassadors, regardless of the underlying source (e.g. `Array`, `ActiveRecord::Relation`, remote API results).
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ambassadors"
+```
+
+Then:
+
+```sh
+bundle install
+```
+
+The Ruby namespace is `Ambassadors`.
+For ergonomics, `Ambassador` and `AmbassadorCollection` are also defined as top-level constants.
+
+## Defining an Ambassador
+
+```ruby
+class UserAmbassador < Ambassador
+  expose :id, :email, :created_at
+end
+```
+
+```ruby
+user = User.find(...)
+ambassador = UserAmbassador.new(user)
+ambassador.id         # => 123
+ambassador.email      # => "user@example.com"
+ambassador.created_at # => 2025-01-01 12:34:56 UTC
+```
+
+### Key properties
+
+- The ambassador instance is frozen in the constructor.
+- Only methods declared with `expose` are generated and forwarded to the entity.
+- Values returned from exposed properties are frozen.
+- Property names ending in `!` or `=` cannot be exposed, and raise `Ambassadors::InvalidPropertyError`.
+
+### `expose` DSL
+
+```ruby
+class CardAmbassador < Ambassador
+  expose :id, :last4, :status
+end
+```
+
+### Custom methods
+
+Ambassador subclasses are ordinary Ruby classes, so you can define your own methods alongside exposed properties.
+The wrapped entity is available via `entity`.
+
+```ruby
+class UserAmbassador < Ambassador
+  expose :id, :first_name, :last_name
+
+  def full_name
+    "#{entity.first_name} #{entity.last_name}"
+  end
+end
+```
+
+### `#to_ambassador`
+
+Every `Ambassador` responds to `#to_ambassador` and returns itself.
+Entities may also implement `#to_ambassador` to control how they are cast (see [Ambassador casting](#ambassador-casting)).
+
+## AmbassadorCollection
+
+`AmbassadorCollection` is a thin wrapper that:
+
+- Includes `Enumerable`
+- Iterates using a strategy (plain `each`, `find_each`, etc.)
+- Always yields ambassador instances
+
+### Basic usage
+
+```ruby
+users = [User.new(name: "user A"), User.new(name: "user B")] # users is an Array of User objects
+collection = AmbassadorCollection.new(users, ambassador_class: UserAmbassador)
+
+collection.each do |ambassador|
+  puts ambassador.email
+end
+```
+
+### With ActiveRecord
+
+Will safely iterate over `ActiveRecord::Relation` objects, without exposing dangerous methods (e.g. `delete_all`) or loading too many results at once.
+
+```ruby
+users = User.where(active: true) # users is an ActiveRecord::Relation
+collection = AmbassadorCollection.new(users, ambassador_class: UserAmbassador)
+
+collection.each do |ambassador| # loads in batches of 1000 by default
+  puts ambassador.email
+end
+```
+
+Specify an optional `batch_size:`:
+
+```ruby
+users = User.where(active: true)
+collection = AmbassadorCollection.new(users, ambassador_class: UserAmbassador, batch_size: 50)
+
+collection.each do |ambassador| # loads in batches of 50
+  puts ambassador.email
+end
+```
+
+Batches are loaded with `find_each`, ordered by the primary key ascending by default.
+Pass `cursor:` and `order:` to batch on a different column or direction.
+See the [ActiveRecord::Batches documentation](https://api.rubyonrails.org/classes/ActiveRecord/Batches.html#method-i-find_each) for the constraints on cursor columns.
+
+```ruby
+users = User.where(active: true)
+collection = AmbassadorCollection.new(
+  users,
+  ambassador_class: UserAmbassador,
+  cursor: :created_at,
+  order: :desc
+)
+```
+
+### Passing options to ambassadors
+
+If your ambassador's constructor accepts keyword arguments, pass them to every ambassador in the collection with `ambassador_options:`.
+
+```ruby
+class UserAmbassador < Ambassador
+  expose :id, :email
+
+  def initialize(entity, include_profile: false)
+    @include_profile = include_profile
+    super(entity)
+  end
+end
+
+collection = AmbassadorCollection.new(
+  users,
+  ambassador_class: UserAmbassador,
+  ambassador_options: { include_profile: true }
+)
+```
+
+### Collection helpers
+
+Alongside the `Enumerable` methods, `AmbassadorCollection` provides:
+
+- `#length`, `#size`, `#count` - the number of items in the underlying collection
+- `#empty?` - whether the underlying collection has no items
+- `#take` - the first ambassador, or the first `n` ambassadors when given a count
+- `#all` - returns the collection itself
+
+## Ambassador casting
+
+Ambassadors will be cast based on the following strategies, in the order listed:
+
+- Call `#to_ambassador` on the entity in the current iteration (if it responds to it).
+- Use the provided `ambassador_class` to initialize a new ambassador for the entity.
+- Infer the ambassador class name from the entity's class name (e.g. `User` => `UserAmbassador`).
+
+If no strategy succeeds, the collection will raise `Ambassadors::UresolvedAmbassadorError`.
+
+## Rails integration
+
+When loaded inside a Rails application, the gem registers a Railtie that includes `ActiveModel::Serialization` in `Ambassador` once ActiveModel has loaded.
+Ambassador subclasses that define an `attributes` method can then be serialised with the standard ActiveModel API (`serializable_hash`, `as_json`, and so on).
+
+---
+
+## Development
+
+Run tests:
+
+```sh
+bundle exec rake test
+```
+
+Run guard:
+
+```sh
+bundle exec guard
+```
+
+Lint:
+
+```sh
+bundle exec rubocop
+```
+
+Run everything (tests and lint):
+
+```sh
+bundle exec rake
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/meetcleo/ambassadors.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE.txt) for details.

data/Rakefile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.options = ["--yardopts", ".yardopts"] # optional, YARD uses this by default
+  end
+rescue LoadError
+  puts "Ignoring YARD doc task. Yard not installed."
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/ambassadors/ambassador.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  ##
+  # Read-only wrapper around a domain entity.
+  #
+  # An Ambassador forms a stable, immutable interface that exposes selected
+  # attributes of an entity to the outside world. Domain interface methods
+  # return Ambassadors instead of the underlying entities, so internal models
+  # are protected from direct access and can evolve safely.
+  #
+  # @note Although this class is defined under the {Ambassadors} namespace,
+  # it defines the top-level constant {::Ambassador} for ergonomics.
+  #
+  # @example Defining a user ambassador
+  #   class UserAmbassador < Ambassador
+  #     expose :id, :email, :created_at
+  #   end
+  #
+  #   user = User.find(...)
+  #   ambassador = UserAmbassador.new(user)
+  #   ambassador.email # => "user@example.com" (frozen)
+  #   ambassador.payment_cards # => NoMethodError
+  class ::Ambassador
+    require "ambassadors/freezer"
+    require "ambassadors/property_name_checker"
+
+    class << self
+      # Declares one or more methods that should be publicly exposed as read-only properties
+      # Values returned from these methods are frozen.
+      #
+      # @param properties [Array<Symbol>] list of method names to expose
+      # @return [void]
+      #
+      # @example
+      #   class CardAmbassador < Ambassador
+      #     expose :id, :email
+      #   end
+      def expose(*properties)
+        properties = properties.map(&:to_sym)
+        # Remove any methods that are already defined from the set of properties
+        (properties - instance_methods).each do |property_name|
+          check_property_name_is_exposable!(property_name)
+          exposed_property_names.add(property_name)
+
+          define_method(:"#{property_name}") do
+            Freezer.new(entity.public_send(property_name)).value
+          end
+        end
+      end
+
+      private :instance_eval, :instance_exec
+
+      private
+
+      # @return [Set<Symbol>] the set of all exposed property names
+      def exposed_property_names
+        @exposed_property_names ||= Set.new
+      end
+
+      # @param property_name [Symbol]
+      # @raise [InvalidPropertyError]
+      # @return [void]
+      def check_property_name_is_exposable!(property_name)
+        PropertyNameChecker.new(property_name).check!
+      end
+    end
+
+    # @param entity [Object] the internal domain object being wrapped
+    def initialize(entity)
+      @__entity__ = entity
+      freeze
+    end
+
+    # @return [Object] the wrapped domain entity
+    def entity
+      @__entity__
+    end
+
+    def ==(other)
+      other.respond_to?(:entity) && entity == other.entity
+    end
+
+    # String representation showing exposed fields and their values.
+    #
+    # @return [String]
+    def inspect
+      "<#{self.class.name} #{exposed_properties.map { |k, v| "#{k}=#{v.inspect}" }.join(", ").strip}>"
+    end
+
+    ##
+    # Returns this Ambassador. (Used for polymorphic consistency)
+    # @return [Ambassador]
+    def to_ambassador
+      self
+    end
+
+    private
+
+    def exposed_properties
+      hash = {}
+      self.class.send(:exposed_property_names).each do |name|
+        hash[name] = public_send(name)
+      end
+      hash
+    end
+  end
+end

data/lib/ambassadors/ambassador_collection.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  ##
+  # Collection wrapper for objects that can be represented as {Ambassadors::Ambassador}
+  # instances.
+  #
+  # @note Although this class is defined under the {Ambassadors} namespace,
+  # it reopens the top-level constant {::AmbassadorCollection}.
+  #
+  # @note The +#each+ method will use batch loading behind the scenes when
+  # enumerable is an ActiveRecord::Relation. This is to protect the database
+  # against loading enormous queries.
+  #
+  # @example Wrap an Array of models
+  #   collection = AmbassadorCollection.new(users, ambassador_class: UserAmbassador)
+  #   collection.each do |ambassador|
+  #     puts ambassador.id
+  #   end
+  #
+  # @example Use with an ActiveRecord::Relation
+  #   relation   = User.where(active: true)
+  #   collection = AmbassadorCollection.new(relation, ambassador_class: UserAmbassador)
+  #   collection.map(&:id)
+  #
+  # @example Enumerate lazily via Enumerator
+  #   collection = AmbassadorCollection.new(users, ambassador_class: UserAmbassador)
+  #   enum = collection.each
+  #   first_two = [enum.next, enum.next]
+  #
+  class ::AmbassadorCollection
+    require_relative "iterators"
+    require "ambassadors/ambassador_factory"
+
+    include Enumerable
+
+    ##
+    # If a batching strategy is used, load this number of records per batch
+    # @return [Integer]
+    DEFAULT_BATCH_SIZE = 1_000
+
+    ##
+    # Wraps an enumerable collection of entities in Ambassadors
+    # @param enumerable [Enumerable]
+    # @param ambassador_class [nil, Class]
+    # @param ambassador_options [Hash]
+    # @param batch_size [Integer] The number of records to load per batch (if not loading from memory)
+    # @param iterator [Ambassadors::Iterators::IterationStrategy] Determines how to iterate over each item
+    # @param cursor [Symbol] The cursor to order batches on (@see https://api.rubyonrails.org/classes/ActiveRecord/Batches.html#method-i-find_each)
+    # @param order [Symbol<asc|desc>] The order by direction for batching (@see https://api.rubyonrails.org/classes/ActiveRecord/Batches.html#method-i-find_each)
+    def initialize(enumerable,
+                   ambassador_class: nil,
+                   ambassador_options: {},
+                   batch_size: DEFAULT_BATCH_SIZE,
+                   iterator: Ambassadors::Iterators.resolve(
+                     enumerable:
+                   ),
+                   **)
+      @enumerable = enumerable
+      @iterator = iterator.new(
+        enumerable: @enumerable,
+        batch_size: batch_size,
+        **
+      )
+      @ambassador_factory = AmbassadorFactory.new(
+        default_ambassador_class: ambassador_class,
+        ambassador_options: ambassador_options
+      )
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      @iterator.to_enum.each do |item|
+        yield(@ambassador_factory.cast(item))
+      end
+    end
+
+    ##
+    # The number of items in the current collection
+    # @return [Integer]
+    def length
+      @enumerable.length
+    end
+
+    alias size length
+    alias count length
+
+    ##
+    # Whether the current collection has no items
+    # @return [Boolean]
+    def empty?
+      @enumerable.empty?
+    end
+
+    ##
+    # The entire collection. Returns self.
+    # @return [self]
+    def all
+      # TODO: Revisit this decision?
+      # This makes sense in terms of the entire collection _is_ the collection,
+      # but it might not be the best implementation
+      self
+    end
+
+    def take(index = nil)
+      if index.nil?
+        @enumerable.take(1)[0]
+      else
+        super
+      end
+    end
+  end
+end

data/lib/ambassadors/ambassador_factory.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  class AmbassadorFactory # :nodoc:
+    def initialize(default_ambassador_class: nil, ambassador_options: {})
+      @default_ambassador_class = default_ambassador_class
+      @ambassador_options = ambassador_options
+    end
+
+    ##
+    # Cast the given entity with the most appropriate Ambassador class.
+    # Will prioritise in the following order:
+    #   - +#to_ambassador+ called on the entity
+    #   - +@ambassador_class+ if defined
+    #   - Infer based on the class name (e.g. +User+ => +UserAmbassador+)
+    # @return [Ambassador] Instance of an Ambassador class for this entity
+    # @raise [UresolvedAmbassadorError]
+    def cast(entity)
+      return entity.to_ambassador if entity.respond_to?(:to_ambassador)
+
+      return @default_ambassador_class.new(entity, **@ambassador_options) if @default_ambassador_class
+
+      raise UresolvedAmbassadorError, "Cannot infer ambassador for #{entity}" unless entity.class.name
+
+      inferred_ambassador_class_for_entity(entity)
+    end
+
+    protected
+
+    def inferred_ambassador_class_for_entity(entity)
+      inferred_ambassador_class_name = "#{entity.class.name}Ambassador"
+
+      unless Module.const_defined?(inferred_ambassador_class_name)
+        raise UresolvedAmbassadorError, "Cannot infer ambassador for #{entity}"
+      end
+
+      Module.const_get(inferred_ambassador_class_name)
+    end
+  end
+end

data/lib/ambassadors/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  class Error < StandardError; end
+
+  ##
+  # Raised when we are unable to determine which +Ambassador+ class to load
+  class UresolvedAmbassadorError < Error; end
+
+  ##
+  # Raised when trying to expose an unsafe property
+  class InvalidPropertyError < Error
+    # @param property_name [String, Symbol]
+    def initialize(property_name)
+      super
+      @property_name = property_name
+    end
+
+    # @return [String]
+    def message
+      "Cannot define a read-only property named #{@property_name}"
+    end
+  end
+end

data/lib/ambassadors/freezer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  ##
+  # Ensures any value returned from the entity is deeply frozen.
+  # @abstract
+  # @private
+  class Freezer
+    # @return [Object] the frozen value
+    attr_reader :value
+
+    # @param value [Object] the object to freeze
+    def initialize(value)
+      @value = value.frozen? ? value : value.dup.freeze
+      freeze
+    end
+  end
+
+  private_constant :Freezer
+end

data/lib/ambassadors/iterators/each_iterator.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  module Iterators
+    ##
+    # Strategy to use in +AmbassadorCollection+ when it's safe to
+    # iterate over each item in the set.
+    class EachIterator < Iterator
+    end
+  end
+end

data/lib/ambassadors/iterators/find_each_iterator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  module Iterators
+    ##
+    # Strategy to use in +AmbassadorCollection+ when it's safer to paginate
+    # over batches of the data.
+    class FindEachIterator < Iterator
+      def initialize(batch_size:, cursor: nil, order: nil, **)
+        super(**)
+        @batch_size = batch_size
+        @cursor = cursor || @enumerable.primary_key
+        @order = order || :asc
+      end
+
+      def each(&)
+        return enum_for(:each) unless block_given?
+
+        @enumerable.find_each(batch_size: @batch_size, cursor: @cursor, order: @order, &)
+      end
+    end
+  end
+end

data/lib/ambassadors/iterators/iterator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  module Iterators
+    ##
+    # Base class for custom iteration strategies.
+    # Pass in the enumerable collection to iterate. Subclasses should define a
+    # custom implementation of +#each+.
+    #
+    class Iterator
+      ##
+      # @param enumerable [Enumerable<Object>]
+      def initialize(enumerable:, **_kwargs)
+        @enumerable = enumerable
+      end
+
+      def each(&)
+        return enum_for(:each) unless block_given?
+
+        @enumerable.each(&)
+      end
+    end
+  end
+end

data/lib/ambassadors/iterators/iterator_resolver.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  module Iterators
+    class IteratorResolver # :nodoc:
+      def self.resolve(...)
+        new(...).iterator_class
+      end
+
+      def initialize(enumerable:)
+        @enumerable = enumerable
+      end
+
+      ##
+      # @return [Iterator]
+      def iterator_class
+        if defined?(ActiveRecord::Relation) && @enumerable.is_a?(ActiveRecord::Relation)
+          FindEachIterator
+        else
+          EachIterator
+        end
+      end
+    end
+  end
+end

data/lib/ambassadors/iterators.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  ##
+  # Iteration strategies are used to allow an +AmbassadorCollection+ to define
+  # how it should iterate over its enumerable. This might include
+  # setting limits on how many records are loaded from a DB at a time, or
+  # how to safely paginate records on a 3rd party API.
+  module Iterators # :nodoc:
+    require_relative "iterators/iterator"
+    require_relative "iterators/each_iterator"
+    require_relative "iterators/find_each_iterator"
+    require_relative "iterators/iterator_resolver"
+
+    def self.resolve(enumerable:)
+      IteratorResolver.resolve(enumerable: enumerable)
+    end
+  end
+end

data/lib/ambassadors/property_name_checker.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  ##
+  # Validates that exposed property names are safe
+  class PropertyNameChecker
+    # @return [Symbol]
+    attr_reader :property_name
+
+    # @param property_name [Symbol]
+    def initialize(property_name)
+      @property_name = property_name
+    end
+
+    # @raise [InvalidPropertyError] if method is not something we want to expose
+    # @return [void]
+    def check!
+      raise Ambassadors::InvalidPropertyError, property_name if property_name_is_bang?
+      raise Ambassadors::InvalidPropertyError, property_name if property_name_is_setter?
+    end
+
+    private
+
+    def property_name_is_bang?
+      property_name.to_s.end_with?("!")
+    end
+
+    def property_name_is_setter?
+      property_name.to_s.end_with?("=")
+    end
+  end
+
+  private_constant :PropertyNameChecker
+end

data/lib/ambassadors/railtie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Ambassadors
+  ##
+  # Hooks into the Rails boot process when the gem is loaded inside a Rails application.
+  # @see https://api.rubyonrails.org/classes/Rails/Railtie.html
+  class Railtie < Rails::Railtie
+    ##
+    # Includes +ActiveModel::Serialization+ in {::Ambassador} when ActiveModel is
+    # available, so exposed properties can be serialised.
+    initializer "ambassadors.active_model_serialization" do
+      ActiveSupport.on_load(:active_model) do
+        if defined?(::Ambassador) && defined?(::ActiveModel::Serialization)
+          ::Ambassador.include(ActiveModel::Serialization)
+        end
+      end
+    end
+  end
+end

data/lib/ambassadors/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ambassadors
+  VERSION = "0.1.0"
+end

data/lib/ambassadors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+##
+# Root module for Ambassadors behaviour.
+# @note That two of the public classes defined in this module are actually
+# cast to the top-level-namespace. This is purely for ergonomics.
+# @see README.md for more information.
+module Ambassadors
+  require_relative "ambassadors/version"
+  require_relative "ambassadors/ambassador"
+  require_relative "ambassadors/ambassador_collection"
+  require_relative "ambassadors/errors"
+  require_relative "ambassadors/railtie" if defined?(Rails)
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: ambassadors
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gavin Morrice
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Ambassadors are frozen, read-only wrappers around domain entities, providing a stable interface
+  that is safe to pass across domain boundaries in a modular monolith.
+email:
+- gavin@gavinmorrice.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ambassadors.rb
+- lib/ambassadors/ambassador.rb
+- lib/ambassadors/ambassador_collection.rb
+- lib/ambassadors/ambassador_factory.rb
+- lib/ambassadors/errors.rb
+- lib/ambassadors/freezer.rb
+- lib/ambassadors/iterators.rb
+- lib/ambassadors/iterators/each_iterator.rb
+- lib/ambassadors/iterators/find_each_iterator.rb
+- lib/ambassadors/iterators/iterator.rb
+- lib/ambassadors/iterators/iterator_resolver.rb
+- lib/ambassadors/property_name_checker.rb
+- lib/ambassadors/railtie.rb
+- lib/ambassadors/version.rb
+homepage: https://github.com/meetcleo/ambassadors
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/meetcleo/ambassadors
+  changelog_uri: https://github.com/meetcleo/ambassadors/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/meetcleo/ambassadors/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.13
+specification_version: 4
+summary: Immutable, read-only wrappers for domain entities.
+test_files: []