Implement mold system (#8)

* Add settings molds through DSL

* Change object building to use molds

* Provide essential molds out-of-the-box

* Add support for Struct, Data, Hash out-of-the-box

Author: trinistr

.ruby-version

@@ -1 +1 @@
-3.2.9
+3.3.9

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Next]
 
+This update brings a huge and necessary enhancement: ability to change how objects are built.
+This is achieved with the *mold* (builder) system. You can now precisely control (or abuse) the process,
+making it possible to consume attributes in any way you want.
+
+**Added**
+- Add setting the mold for a Forge through the `ForgeDSL#mold=` method, using any object (or class) with a `#call` method.
+- Add `Molds::SingleArgumentMold` as a default mold, mimicing previous behavior, and `Molds::KeywordsMold` as an alternative.
+- Add `Molds::HashMold` and `Molds::StructMold` to support Hashes and Structs out-of-the-box.
+- Add `Molds::WrappedMold` to support complex user-provided molds.
+
+**Changed**
+- [Breaking] `Forge::Parameters` interface now includes `#mold`.
+- `Forge` will automatically use `Molds::MoldMold` to determine the mold if none is provided.
+
 [Compare v0.1.1...main](https://github.com/trinistr/object_forge/compare/v0.1.1...main)
 
 ## [v0.1.1]

README.md

@@ -23,8 +23,8 @@ However, such gems make a lot of assumptions about why, how and what for they wi
 - assuming that streamlined object generation is only useful for testing;
 - (related to the previous point) assuming that there will never be a need to
   have more than one configuration of a library in the same project
-  (I believe, this anti-pattern was popularised by Rails);
-- (and related again) assuming that adding global methods or objects is a good idea.
+  (I believe this anti-pattern was popularised by Rails);
+- assuming that adding global methods or objects is a good idea.
 
 I notice that there is also a problem of thinking that Rails's "convention-over-configuration" approach is always appropriate, but then making configuration convoluted, instead of making it easy for the user to do the things they want in the way they want in the first place.
 
@@ -196,12 +196,10 @@ kanban
     [Default global forgeyard]
     [Thread-safe behavior]
     [Tapping into built objects for post-processing]
+    [Custom builders (molds)]
+    [Built-in Hash, Struct, Data builders (molds)]
   [⚗️ To do]
     [Ability to replace resolver]
-    [Custom builders]
-    [Struct builder]
-    [Data builder]
-    [Hash builder]
     [After-build hook]
   [❔Under consideration]
     [Calling traits from traits]

lib/object_forge.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-Dir["#{__dir__}/object_forge/**/*.rb"].each { require _1 }
+require_relative "object_forge/forgeyard"
+require_relative "object_forge/sequence"
+require_relative "object_forge/version"
 
 # A simple all-purpose factory library with minimal assumptions.
 #
@@ -76,7 +78,7 @@ def self.sequence(...)
   # @since 0.1.0
   #
   # @param name [Symbol] forge name
-  # @param forged [Class] class to forge
+  # @param forged [Class, Any] class or object to forge
   # @yieldparam f [ForgeDSL]
   # @yieldreturn [void]
   # @return [Forge] forge

lib/object_forge/crucible.rb

@@ -12,7 +12,6 @@ module ObjectForge
   #
   # @thread_safety Attribute resolution is idempotent,
   #   but modifies instance variables, making it unsafe to share the Crucible
-  #
   # @since 0.1.0
   class Crucible < UnBasicObject
     %i[rand].each { |m| private define_method(m, ::Object.instance_method(m)) }

lib/object_forge/forge.rb

@@ -2,6 +2,7 @@
 
 require_relative "crucible"
 require_relative "forge_dsl"
+require_relative "molds"
 
 module ObjectForge
   # Object instantitation forge.
@@ -19,14 +20,22 @@ class Forge
     # @!attribute [r] traits
     #   Attributes belonging to traits.
     #   @return [Hash{Symbol => Hash{Symbol => Any}}]
-    Parameters = Struct.new(:attributes, :traits, keyword_init: true)
+    #
+    # @!attribute [r] mold
+    #   An object that knows how to build the instance.
+    #   Must have a +call+ method that takes a class and a hash of attributes.
+    #   @since 0.2.0
+    #   @return [#call, nil]
+    Parameters = Struct.new(:attributes, :traits, :mold, keyword_init: true)
+
+    MOLD_MOLD = Molds::MoldMold.new.freeze
 
     # Define (and create) a forge using DSL.
     #
     # @see ForgeDSL
     # @thread_safety Thread-safe if DSL definition is thread-safe.
     #
-    # @param forged [Class] class to forge
+    # @param forged [Class, Any] class or object to forge
     # @param name [Symbol, nil] forge name
     # @yieldparam f [ForgeDSL]
     # @yieldreturn [void]
@@ -38,19 +47,20 @@ def self.define(forged, name: nil, &)
     # @return [Symbol, nil] forge name
     attr_reader :name
 
-    # @return [Class] class to forge
+    # @return [Class, Any] class or object to forge
     attr_reader :forged
 
     # @return [Parameters, ForgeDSL] forge parameters
     attr_reader :parameters
 
-    # @param forged [Class] class to forge
+    # @param forged [Class, Any] class or object to forge
     # @param parameters [Parameters, ForgeDSL] forge parameters
     # @param name [Symbol, nil] forge name
     def initialize(forged, parameters, name: nil)
       @name = name
       @forged = forged
       @parameters = parameters
+      @mold = parameters.mold || MOLD_MOLD.call(forged: forged)
     end
 
     # Forge a new instance.
@@ -67,7 +77,7 @@ def initialize(forged, parameters, name: nil)
     # If a block is given, forged instance is yielded to it after being built.
     #
     # @thread_safety Forging is thread-safe if {#parameters},
-    #    +traits+ and +overrides+ are thread-safe.
+    #   +traits+ and +overrides+ are thread-safe.
     #
     # @param traits [Array<Symbol>] traits to apply
     # @param overrides [Hash{Symbol => Any}] attribute overrides
@@ -76,7 +86,7 @@ def initialize(forged, parameters, name: nil)
     # @return [Any] built instance
     def forge(*traits, **overrides)
       resolved_attributes = resolve_attributes(traits, overrides)
-      instance = build_instance(resolved_attributes)
+      instance = @mold.call(forged: @forged, attributes: resolved_attributes)
       yield instance if block_given?
       instance
     end
@@ -90,9 +100,5 @@ def resolve_attributes(traits, overrides)
       attributes = @parameters.attributes.merge(*@parameters.traits.values_at(*traits), overrides)
       Crucible.new(attributes).resolve!
     end
-
-    def build_instance(attributes)
-      forged.new(attributes)
-    end
   end
 end

lib/object_forge/forge_dsl.rb

@@ -3,6 +3,8 @@
 require_relative "sequence"
 require_relative "un_basic_object"
 
+require_relative "molds/wrapped_mold"
+
 module ObjectForge
   # DSL for defining a forge.
   #
@@ -14,7 +16,6 @@ module ObjectForge
   #   especially in attribute definitions.
   #   The instance itself is frozen after initialization,
   #   so it should be safe to share.
-  #
   # @since 0.1.0
   class ForgeDSL < UnBasicObject
     # @return [Hash{Symbol => Proc}] attribute definitions
@@ -26,6 +27,9 @@ class ForgeDSL < UnBasicObject
     # @return [Hash{Symbol => Hash{Symbol => Proc}}] trait definitions
     attr_reader :traits
 
+    # @return [#call, nil] forge mold
+    attr_reader :mold
+
     # Define forge's parameters through DSL.
     #
     # If the block has a parameter, an object will be yielded,
@@ -71,9 +75,34 @@ def freeze
       @attributes.freeze
       @sequences.freeze
       @traits.freeze
+      @mold.freeze
       self
     end
 
+    # Set the forge mold.
+    #
+    # Mold is an object that knows how to take a hash of attributes
+    # and create an object from them.
+    # It can also be a class with +#call+, in which case a new mold will be instantiated
+    # automatically for each build. If a single instance is enough,
+    # please call +.new+ yourself once.
+    #
+    # @since 0.2.0
+    #
+    # @param mold [Class, #call, nil]
+    # @return [Class, #call, nil]
+    #
+    # @raise [DSLError] if +mold+ does not respond to or implement +#call+
+    def mold=(mold)
+      if nil == mold || mold.respond_to?(:call) # rubocop:disable Style/YodaCondition
+        @mold = mold
+      elsif ::Class === mold && mold.public_method_defined?(:call)
+        @mold = Molds::WrappedMold.new(mold)
+      else
+        raise DSLError, "mold must respond to or implement #call"
+      end
+    end
+
     # Define an attribute, possibly transient.
     #
     # DSL does not know or care what attributes the forged class has,

lib/object_forge/forgeyard.rb

@@ -2,6 +2,8 @@
 
 require "concurrent/map"
 
+require_relative "forge"
+
 module ObjectForge
   # A registry for forges, making them accessible by name.
   #
@@ -20,7 +22,7 @@ def initialize
     # @see Forge.define
     #
     # @param name [Symbol] name to register forge under
-    # @param forged [Class] class to forge
+    # @param forged [Class, Any] class or object to forge
     # @yieldparam f [ForgeDSL]
     # @yieldreturn [void]
     # @return [Forge] forge

lib/object_forge/molds.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module ObjectForge
+  # This module provides a collection of predefined molds to be used in common cases.
+  #
+  # Molds are +#call+able objects responsible for actually building objects produced by factories
+  # (or doing other, interesting things with them (truly, only the code review is the limit!)).
+  # They are supposed to be immutable, shareable, and persistent:
+  # initialize once, use for the whole runtime.
+  #
+  # A simple mold can easily be just a +Proc+.
+  # All molds must have the following +#call+ signature: +call(forged:, attributes:, **)+.
+  # The extra keywords are for future extensions.
+  #
+  # @example A very basic FactoryBot replacement
+  #   creator = ->(forged:, attributes:, **) do
+  #     instance = forged.new
+  #     attributes.each_pair { instance.public_send(:"#{_1}=", _2) }
+  #     instance.save!
+  #   end
+  #   creator.call(forged: User, attributes: { name: "John", age: 30 })
+  #     # => <User name="John" age=30>
+  # @example Using a mold to serialize collection of objects (contrivedly)
+  #   dumpy = ->(forged:, attributes:, **) do
+  #     Enumerator.new(attributes.size) do |y|
+  #       attributes.each_pair { y << forged.dump(_1 => _2) }
+  #     end
+  #   end
+  #   dumpy.call(forged: JSON, attributes: {a:1, b:2}).to_a
+  #     # => ["{\"a\":1}", "{\"b\":2}"]
+  #   dumpy.call(forged: YAML, attributes: {a:1, b:2}).to_a
+  #     # => ["---\n:a: 1\n", "---\n:b: 2\n"]
+  # @example Abstract factory pattern (kind of)
+  #   class FurnitureFactory
+  #     def call(forged:, attributes:, **)
+  #       concrete_factory = concrete_factory(forged)
+  #       attributes[:pieces].map do |piece|
+  #         concrete_factory.public_send(piece, attributes.dig(:color, piece))
+  #       end
+  #     end
+  #     private def concrete_factory(style)
+  #       case style
+  #       when :hitech
+  #         HiTechFactory.new
+  #       when :retro
+  #         RetroFactory.new
+  #       end
+  #     end
+  #   end
+  #   FurnitureFactory.new.call(forged: :hitech, attributes: {
+  #     pieces: [:chair, :table], color: { chair: :black, table: :white }
+  #   })
+  #     # => [<#HiTech::Chair color=:black>, <#HiTech::Table color=:white>]
+  # @example Abusing molds
+  #   printer = ->(forged:, attributes:, **) { PP.pp(attributes, forged) }
+  #   printer.call(forged: $stderr, attributes: {a:1, b:2})
+  #     # outputs "{:a=>1, :b=>2}" to $stderr
+  #
+  # @since 0.2.0
+  module Molds
+    Dir["#{__dir__}/molds/*.rb"].each { require_relative _1 }
+  end
+end

lib/object_forge/molds/hash_mold.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ObjectForge
+  module Molds
+    # Mold for constructing Hashes.
+    #
+    # @thread_safety Thread-safe on its own,
+    #   but using unshareable default value or block is not thread-safe.
+    #
+    # @since 0.2.0
+    class HashMold
+      # Default value to be assigned to each produced hash.
+      # @return [Any, nil]
+      attr_reader :default
+      # Default proc to be assigned to each produced hash.
+      # @return [Proc, nil]
+      attr_reader :default_proc
+
+      # Initialize new HashMold with default value or default proc
+      # to be assigned to each produced hash.
+      #
+      # The same exact objects are used for each hash.
+      # It is not advised to use mutable objects as default values.
+      # Be aware that using a default proc with assignment
+      # is inherently not safe, see this Ruby issue:
+      # https://bugs.ruby-lang.org/issues/19237.
+      #
+      # @see Hash.new
+      #
+      # @param default_value [Any]
+      # @yieldparam hash [Hash]
+      # @yieldparam key [Any]
+      # @yieldreturn [Any]
+      def initialize(default_value = nil, &default_proc)
+        @default = default_value
+        @default_proc = default_proc
+      end
+
+      # Build a new hash using +forged.[]+.
+      #
+      # @see Hash.[]
+      #
+      # @param forged [Class] Hash or a subclass of Hash
+      # @param attributes [Hash{Symbol => Any}]
+      # @return [Hash]
+      def call(forged:, attributes:, **_)
+        hash = forged[attributes]
+        hash.default = @default if @default
+        hash.default_proc = @default_proc if @default_proc
+        hash
+      end
+    end
+  end
+end