object_forge 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13df90e0eb14f3fb52c1b9be5706a3b2da6c844369005f0500fe31f67ced6091
+  data.tar.gz: 6ce301c70ae87b0e46662482cd46af63d8e282aca65f92e220dc02e4a6b3e2b6
+SHA512:
+  metadata.gz: b75f0d0ddacd4f102a02bbb74bd0189e8b2759eb4e9a4f3f62de84a028356800908d3313ec5361299078e49a2101abcedda91358601cfc03cf76ac2bb3fb05b7
+  data.tar.gz: 76231dd798153526c679874b3528d120a7f3562c8dfc540001be54465b46f53a50afa46f04d17f8bc2ddfcb152708d9003e417fd4d8c6d220890c62597930104

data/lib/object_forge/crucible.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "un_basic_object"
+
+module ObjectForge
+  # Melting pot for the forged object's attributes.
+  #
+  # @note This class is not intended to be used directly,
+  #   but it's not a private API.
+  #
+  # @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)) }
+
+    # @param attributes [Hash{Symbol => Proc, Any}] initial attributes
+    def initialize(attributes)
+      super()
+      @attributes = attributes
+      @resolved_attributes = ::Set.new
+    end
+
+    # Resolve all attributes by calling their +Proc+s,
+    # using +self+ as the evaluation context.
+    #
+    # Attributes can freely refer to each other inside +Proc+s
+    # through bareword names or +#[]+.
+    # However, make sure to avoid cyclic dependencies:
+    # they aren't specially detected or handled, and will cause +SystemStackError+.
+    #
+    # @note This method destructively modifies initial attributes.
+    #
+    # @return [Hash{Symbol => Any}] resolved attributes
+    def resolve!
+      @attributes.each_key { |name| method_missing(name) }
+      @attributes
+    end
+
+    private
+
+    # Get the value of the attribute +name+.
+    #
+    # To prevent problems with calling methods which may be defined,
+    # +#[]+ can be used instead.
+    #
+    # @example
+    #   attrs = {
+    #     name: -> { "Name" },
+    #     description: -> { name.downcase },
+    #     duration: -> { rand(1000) }
+    #   }
+    #   Crucible.new(attrs).resolve!
+    #   # => { name: "Name", description: "name", duration: 123 }
+    # @example using conflicting and reserved names
+    #   attrs = {
+    #     "[]": -> { "Brackets" },
+    #     "[]=": -> { "#{self[:[]]} are brackets" },
+    #     "!": -> { "#{self[:[]=]}!" }
+    #   }
+    #   Crucible.new(attrs).resolve!
+    #   # => { "[]": "Brackets", "[]=": "Brackets are brackets", "!": "Brackets are brackets!" }
+    #
+    # @param name [Symbol]
+    # @return [Any]
+    def method_missing(name)
+      if @attributes.key?(name)
+        if @resolved_attributes.include?(name) || !(::Proc === @attributes[name])
+          @attributes[name]
+        else
+          @resolved_attributes << name
+          @attributes[name] = instance_exec(&@attributes[name])
+        end
+      else
+        super
+      end
+    end
+
+    alias [] method_missing
+
+    def respond_to_missing?(name, _include_all)
+      @attributes.key?(name)
+    end
+  end
+end

data/lib/object_forge/forge.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "crucible"
+require_relative "forge_dsl"
+
+module ObjectForge
+  # Object instantitation forge.
+  #
+  # @since 0.1.0
+  class Forge
+    # Interface for forge parameters.
+    # It is not used internally, but can be useful for defining forges
+    # through means other than {ForgeDSL}.
+    #
+    # @!attribute [r] attributes
+    #   Non-trait values of the attributes.
+    #   @return [Hash{Symbol => Any}]
+    #
+    # @!attribute [r] traits
+    #   Attributes belonging to traits.
+    #   @return [Hash{Symbol => Hash{Symbol => Any}}]
+    Parameters = Struct.new(:attributes, :traits, keyword_init: true)
+
+    # 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 name [Symbol, nil] forge name
+    # @yieldparam f [ForgeDSL]
+    # @yieldreturn [void]
+    # @return [Forge] forge
+    def self.define(forged, name: nil, &)
+      new(forged, ForgeDSL.new(&), name:)
+    end
+
+    # @return [Symbol, nil] forge name
+    attr_reader :name
+
+    # @return [Class] class to forge
+    attr_reader :forged
+
+    # @return [Parameters, ForgeDSL] forge parameters
+    attr_reader :parameters
+
+    # @param forged [Class] class 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
+    end
+
+    # Forge a new instance.
+    #
+    # @overload forge(*traits, **overrides)
+    # @overload forge(traits, overrides)
+    #
+    # Positional arguments are taken as trait names, keyword arguments as attribute overrides,
+    # unless there are exactly two positional arguments: an array and a hash.
+    #
+    # All traits and overrides are applied in argument order,
+    # with overrides always applied after traits.
+    #
+    # @thread_safety Forging is thread-safe if {#parameters},
+    #    +traits+ and +overrides+ are thread-safe.
+    #
+    # @param traits [Array<Symbol>] traits to apply
+    # @param overrides [Hash{Symbol => Any}] attribute overrides
+    # @return [Any] built instance
+    def forge(*traits, **overrides)
+      # @type var traits: Array[(Array[Symbol] | Hash[Symbol, untyped])]
+      traits, overrides = check_traits_and_overrides(traits, overrides)
+      attributes = @parameters.attributes.merge(*@parameters.traits.values_at(*traits), overrides)
+      attributes = Crucible.new(attributes).resolve!
+
+      forged.new(attributes)
+    end
+
+    alias build forge
+    alias [] forge
+
+    private
+
+    def check_traits_and_overrides(traits, overrides)
+      unless traits.size == 2 && overrides.empty?
+        # @type var traits: Array[Symbol]
+        # @type var overrides: Hash[Symbol, untyped]
+        return [traits, overrides]
+      end
+
+      case traits
+      in [Array => real_traits, Hash => real_overrides]
+        [real_traits, real_overrides]
+      else
+        [traits, overrides]
+      end
+    end
+  end
+end

data/lib/object_forge/forge_dsl.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require_relative "sequence"
+require_relative "un_basic_object"
+
+module ObjectForge
+  # DSL for defining a forge.
+  #
+  # @note This class is not intended to be used directly,
+  #   but it's not a private API.
+  #
+  # @thread_safety DSL is not thread-safe.
+  #   Take care not to introduce side effects,
+  #   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
+    attr_reader :attributes
+
+    # @return [Hash{Symbol => Sequence}] used sequences
+    attr_reader :sequences
+
+    # @return [Hash{Symbol => Hash{Symbol => Proc}}] trait definitions
+    attr_reader :traits
+
+    # Define forge's parameters through DSL.
+    #
+    # If the block has a parameter, an object will be yielded,
+    # and +self+ context will be preserved.
+    # Otherwise, DSL will change +self+ context inside the block,
+    # without ability to call methods available outside.
+    #
+    # @example with block parameter
+    #   ForgeDSL.new do |f|
+    #     f.attribute(:name) { "Name" }
+    #     f[:description] { name.upcase }
+    #     f.duration { rand(1000) }
+    #   end
+    #
+    # @example without block parameter
+    #   ForgeDSL.new do
+    #     attribute(:name) { "Name" }
+    #     self[:description] { name.upcase }
+    #     duration { rand(1000) }
+    #   end
+    #
+    # @yieldparam f [ForgeDSL] self
+    # @yieldreturn [void]
+    def initialize(&dsl)
+      super
+      @attributes = {}
+      @sequences = {}
+      @traits = {}
+
+      dsl.arity.zero? ? instance_exec(&dsl) : yield(self)
+
+      freeze
+    end
+
+    # Freezes the instance, including +attributes+, +sequences+ and +traits+.
+    # Prevents further responses through +#method_missing+.
+    #
+    # @note Called automatically in {#initialize}.
+    #
+    # @return [self]
+    def freeze
+      ::Object.instance_method(:freeze).bind_call(self)
+      @attributes.freeze
+      @sequences.freeze
+      @traits.freeze
+      self
+    end
+
+    # Define an attribute, possibly transient.
+    #
+    # DSL does not know or care what attributes the forged class has,
+    # so the only difference between "real" and "transient" attributes
+    # is how the class itself treats them.
+    #
+    # It is also possible to define attributes using +method_missing+ shortcut,
+    # except for conflicting or reserved names.
+    #
+    # You can refer to any other attribute inside the attribute definition block.
+    # +self[:name]+ can be used to refer to an attribute with a conflicting or reserved name.
+    #
+    # @example
+    #   f.attribute(:name) { "Name" }
+    #   f[:description] { name.downcase }
+    #   f.duration { rand(1000) }
+    # @example using conflicting and reserved names
+    #   f.attribute(:[]) { "Brackets" }
+    #   f.attribute(:[]=) { "#{self[:[]]} are brackets" }
+    #   f.attribute(:!) { "#{self[:[]=]}!" }
+    #
+    # @param name [Symbol] attribute name
+    # @yieldreturn [Any] attribute value
+    # @return [Symbol] attribute name
+    #
+    # @raise [ArgumentError] if +name+ is not a Symbol
+    # @raise [DSLError] if no block is given
+    def attribute(name, &definition)
+      unless ::Symbol === name
+        raise ::ArgumentError,
+              "attribute name must be a Symbol, #{name.class} given (in #{name.inspect})"
+      end
+      unless block_given?
+        raise DSLError, "attribute definition requires a block (in #{name.inspect})"
+      end
+
+      if @current_trait
+        @traits[@current_trait][name] = definition
+      else
+        @attributes[name] = definition
+      end
+
+      name
+    end
+
+    alias [] attribute
+
+    # Define an attribute, using a sequence.
+    #
+    # +name+ is used for both attribute and sequence, for the whole forge.
+    # If the name was used for a sequence previously,
+    # the sequence will not be redefined on subsequent calls.
+    #
+    # @example
+    #   f.sequence(:date, Date.today)
+    #   f.sequence(:id) { _1.to_s }
+    #   f.sequence(:dated_id, 10) { |n| "#{Date.today}/#{n}-#{id}" }
+    # @example using external sequence
+    #   seq = Sequence.new(1)
+    #   f.sequence(:global_id, seq)
+    # @example sequence reuse
+    #   f.sequence(:id, "a") # => "a", "b", ...
+    #   f.trait :new_id do
+    #     f.sequence(:id) { |n| n * 2 } # => "aa", "bb", ...
+    #   end
+    #
+    # @param name [Symbol] attribute name
+    # @param initial [Sequence, #succ] existing sequence, or initial value for a new sequence
+    # @yieldparam value [#succ] current value of the sequence to calculate attribute value
+    # @yieldreturn [Any] attribute value
+    # @return [Symbol] attribute name
+    #
+    # @raise [ArgumentError] if +name+ is not a Symbol
+    # @raise [DSLError] if +initial+ does not respond to #succ and is not a {Sequence}
+    def sequence(name, initial = 1, **nil, &)
+      unless ::Symbol === name
+        raise ::ArgumentError,
+              "sequence name must be a Symbol, #{name.class} given (in #{name.inspect})"
+      end
+
+      seq = @sequences[name] ||= Sequence.new(initial)
+
+      if block_given?
+        attribute(name) { instance_exec(seq.next, &) }
+      else
+        attribute(name) { seq.next }
+      end
+
+      name
+    end
+
+    # Define a trait — a group of attributes with non-default values.
+    #
+    # DSL yields itself to the block, in case you need to refer to it.
+    # This can be used to define traits using a block coming from outside of DSL.
+    #
+    # @example
+    #   f.trait :special do
+    #     f.name { "***xXxSPECIALxXx***" }
+    #     f.sequence(:special_id) { "~~~ SpEcIaL #{_1} ~~~" }
+    #   end
+    # @example externally defined trait
+    #   # Variable defined outside of DSL:
+    #   success_trait = ->(ft) do
+    #     ft.status { :success }
+    #     ft.error_code { 0 }
+    #   end
+    #   # Inside the DSL:
+    #   f.trait(:success, &success_trait)
+    #
+    # @note Traits can not be defined inside of traits.
+    #
+    # @param name [Symbol] trait name
+    # @yield block for trait definition
+    # @yieldparam f [ForgeDSL] self
+    # @yieldreturn [void]
+    # @return [Symbol] trait name
+    #
+    # @raise [ArgumentError] if +name+ is not a Symbol
+    # @raise [DSLError] if no block is given
+    # @raise [DSLError] if called inside of another trait definition
+    def trait(name, **nil)
+      unless ::Symbol === name
+        raise ::ArgumentError,
+              "trait name must be a Symbol, #{name.class} given (in #{name.inspect})"
+      end
+      if @current_trait
+        raise DSLError, "can not define trait inside of another trait (in #{name.inspect})"
+      end
+      raise DSLError, "trait definition requires a block (in #{name.inspect})" unless block_given?
+
+      @current_trait = name
+      @traits[name] = {}
+      yield self
+      @traits[name].freeze
+      @current_trait = nil
+
+      name
+    end
+
+    # Return a string containing a human-readable representation of the definition.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name}:#{__id__} " \
+        "attributes=#{@attributes.keys.inspect} " \
+        "sequences=#{@sequences.keys.inspect} " \
+        "traits={#{@traits.map { |k, v| "#{k.inspect}=#{v.keys.inspect}" }.join(", ")}}>"
+    end
+
+    private
+
+    # Define an attribute using a shorthand.
+    #
+    # Can not be used to define attributes with reserved names.
+    # Trying to use a conflicting name will lead to usual issues
+    # with calling random methods.
+    # When in doubt, use {#attribute} or {#[]} instead.
+    #
+    # Reserved names are:
+    # - all names ending in +?+, +!+ or +=+
+    # - all names starting with a non-word ASCII character
+    #   (operators, +`+, +[]+, +[]=+)
+    # - +rand+
+    #
+    # @param name [Symbol] attribute name
+    # @yieldreturn [Any] attribute value
+    # @return [Symbol] attribute name
+    #
+    # @raise [DSLError] if a reserved +name+ is used
+    def method_missing(name, **nil, &)
+      return super if frozen?
+      return attribute(name, &) if respond_to_missing?(name, false)
+
+      raise DSLError, "#{name.inspect} is a reserved name (in #{name.inspect})"
+    end
+
+    def respond_to_missing?(name, _include_all)
+      return false if frozen?
+
+      !name.end_with?("?", "!", "=") && !name.match?(/\A(?=\p{ASCII})\P{Word}/) && name != :rand
+    end
+  end
+end

data/lib/object_forge/forgeyard.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+
+module ObjectForge
+  # A registry for forges, making them accessible by name.
+  #
+  # @since 0.1.0
+  class Forgeyard
+    # @return [Concurrent::Map{Symbol => Forge}] registered forges
+    attr_reader :forges
+
+    def initialize
+      @forges = Concurrent::Map.new
+    end
+
+    # Define and register a forge in one go.
+    #
+    # @see #register
+    # @see Forge.define
+    #
+    # @param name [Symbol] name to register forge under
+    # @param forged [Class] class to forge
+    # @yieldparam f [ForgeDSL]
+    # @yieldreturn [void]
+    # @return [Forge] forge
+    def define(name, forged, &)
+      register(name, Forge.define(forged, name: name, &))
+    end
+
+    # Add a forge under a specified name.
+    #
+    # If +name+ was already taken, new +forge+ will be ignored
+    # and existing forge will be returned.
+    #
+    # @thread_safety Registration is thread-safe, i.e. first one always wins.
+    #
+    # @param name [Symbol] name to register forge under
+    # @param forge [Forge] forge to register
+    # @return [Forge] actually registered forge
+    def register(name, forge)
+      # `put_if_absent` returns `nil` if there was no previous value, hence the `||`.
+      @forges.put_if_absent(name, forge) || forge
+    end
+
+    # Build an instance using a forge.
+    #
+    # @see Forge#forge
+    #
+    # @param name [Symbol] name of the forge
+    # @param traits [Array<Symbol>] traits to apply
+    # @param overrides [Hash{Symbol => Any}] attribute overrides
+    # @return [Any] built instance
+    #
+    # @raise [KeyError] if forge with the specified name is not registered
+    def forge(name, *traits, **overrides)
+      @forges.fetch(name)[traits, overrides]
+    end
+
+    alias build forge
+    alias [] forge
+  end
+end

data/lib/object_forge/sequence.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "concurrent/mvar"
+
+module ObjectForge
+  # A thread-safe representation of a sequence of values.
+  #
+  # @since 0.1.0
+  class Sequence
+    # Return a new sequence, or +initial+ if it's already a sequence.
+    #
+    # @param initial [#succ, Sequence]
+    # @return [Sequence]
+    def self.new(initial, ...)
+      return initial if initial.is_a?(Sequence)
+
+      super
+    end
+
+    # @return [#succ] initial value for the sequence
+    attr_reader :initial
+
+    # @note Initial value must not be modified after the sequence is created,
+    #   or the results will be unpredicatable. Consider always passing a frozen value.
+    #
+    # @param initial [#succ] initial value for the sequence
+    #
+    # @raise [ArgumentError] if +initial+ does not respond to #succ
+    def initialize(initial)
+      unless initial.respond_to?(:succ)
+        raise ArgumentError, "initial value must respond to #succ, #{initial.class} given"
+      end
+
+      @initial = initial
+      @container = Concurrent::MVar.new(initial)
+    end
+
+    # Get the next value in the sequence, starting with the initial value.
+    #
+    # @thread_safety Sequence traversal is synchronized,
+    #   so no duplicate values will be returned.
+    #
+    # @return [#succ] next value
+    def next
+      @container.modify(&:succ)
+    end
+
+    # Reset the sequence to its {#initial} value.
+    #
+    # @thread_safety Reset is synchronized with {#next}.
+    #
+    # @return [#succ] whatever value would be returned by {#next} before reset
+    def reset
+      @container.modify { @initial }
+    end
+
+    alias rewind reset
+  end
+end

data/lib/object_forge/un_basic_object.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ObjectForge
+  # BasicObject with a few common methods copied from Object.
+  #
+  # @api private
+  #
+  # @since 0.1.0
+  class UnBasicObject < ::BasicObject
+    # @!group Instance methods copied from Object
+    # @!method class
+    #   @see Kernel#class
+    #   @return [Class]
+    # @!method eql?(other)
+    #   @see Object#eql?
+    #   @return [Boolean]
+    # @!method freeze
+    #   @see Kernel#freeze
+    #   @return [self]
+    # @!method frozen?
+    #   @see Kernel#frozen?
+    #   @return [Boolean]
+    # @!method hash
+    #   @see Object#hash
+    #   @return [Integer]
+    # @!method inspect
+    #   @see Object#inspect
+    #   @return [String]
+    # @!method is_a?(class)
+    #   @see Kernel#is_a?
+    #   @return [Boolean]
+    # @!method respond_to?(symbol [, include_private])
+    #   @see Object#respond_to?
+    #   @return [Boolean]
+    # @!method to_s
+    #   @see Object#to_s
+    #   @return [String]
+    %i[class eql? freeze frozen? hash inspect is_a? respond_to? to_s].each do |m|
+      define_method(m, ::Object.instance_method(m))
+    end
+    alias kind_of? is_a?
+    # @!endgroup
+
+    %i[block_given? raise].each { |m| private define_method(m, ::Object.instance_method(m)) }
+
+    # @!macro pp_support
+    #   Support for +pp+ (and IRB).
+    #
+    #   @note This method dynamically calls UnboundMethod#bind_call, making it fairly slow.
+    #
+    #   @api public
+    def pretty_print(...)
+      # We have to do it this way, instead of defining methods,
+      # because Object#pretty_print does not exist without requiring "pp".
+      ::Object.instance_method(:pretty_print).bind_call(self, ...)
+    end
+
+    # @!macro pp_support
+    def pretty_print_cycle(...)
+      # See comment for #pretty_print.
+      # :nocov:
+      ::Object.instance_method(:pretty_print_cycle).bind_call(self, ...)
+      # :nocov:
+    end
+  end
+end

data/lib/object_forge/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ObjectForge
+  # Current version
+  VERSION = "0.1.0"
+end

data/lib/object_forge.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+Dir["#{__dir__}/object_forge/**/*.rb"].each { require _1 }
+
+# A simple all-purpose factory library with minimal assumptions.
+#
+# These are the main classes you should be aware of:
+# - {Forgeyard} is a registry of named related Forges.
+#   A Forgeyard allows to {Forgeyard#define} a Forge,
+#   and {Forgeyard#forge} a new object using a defined Forge.
+# - {Forge} is a factory for objects.
+#   Usually created through {Forgeyard#define}/{Forge.define} in a manner similar to FactoryBot,
+#   Forges can be used standalone, or as a part of a Forgeyard.
+# - {Sequence} is a representation of a sequence of values.
+#   They are usually used implicitly through {ForgeDSL#sequence},
+#   but can be created explicitly to be shared (or used outside of ObjectForge).
+#
+# Additionally, successful use may depend on understanding these:
+# - {ForgeDSL} is a block-based DSL inspired by FactoryBot and ROM::Factory.
+#   It allows defining arbitrary attributes (possibly using sequences),
+#   with support for traits (collections of attributes with non-default values).
+# - {Crucible} is used to resolve attributes.
+#
+# @example Quick example
+#   Frobinator = Struct.new(:frob, :inator, keyword_init: true)
+#   # Forge's name and forged class are completely independent.
+#   ObjectForge.define(:frobber, Frobinator) do |f|
+#     f.frob { "Frob" + inator.call }
+#     f.inator { -> { "inator" } }
+#     f.trait :static do |tf|
+#       tf.frob { "Static" }
+#     end
+#   end
+#   # These methods are aliases:
+#   ObjectForge.forge(:frobber)
+#   # => #<struct Frobinator frob="Frobinator", inator=#<Proc:...>>
+#   ObjectForge.build(:frobber, frob: -> { "Frob" + inator }, inator: "orn")
+#   # => #<struct Frobinator frob="Froborn", inator="orn">
+#   ObjectForge[:frobber, :static, inator: "Value"]
+#   # => #<struct Frobinator frob="Static", inator="Value">
+module ObjectForge
+  # Base error class for ObjectForge.
+  # @since 0.1.0
+  class Error < StandardError; end
+  # Error raised when a mistake is made in using DSL.
+  # @since 0.1.0
+  class DSLError < Error; end
+
+  # Default {Forgeyard} that is used by {.define} and {.forge}.
+  #
+  # @!macro default_forgeyard
+  #   @note
+  #     Default forgeyard is intended to be useful for non-shareable code,
+  #     like simple application tests and specs.
+  #     It should not be used in application code, and never in gems.
+  # @since 0.1.0
+  DEFAULT_YARD = Forgeyard.new
+
+  # @overload sequence(initial)
+  # Create a sequence, to be used wherever it needs to be.
+  #
+  # @see Sequence.new
+  # @since 0.1.0
+  #
+  # @param initial [#succ, Sequence]
+  # @return [Sequence]
+  def self.sequence(...)
+    Sequence.new(...)
+  end
+
+  # @overload define(name, forged, &)
+  # Define and create a forge in {DEFAULT_YARD}.
+  #
+  # @!macro default_forgeyard
+  # @see Forgeyard#define
+  # @since 0.1.0
+  #
+  # @param name [Symbol] forge name
+  # @param forged [Class] class to forge
+  # @yieldparam f [ForgeDSL]
+  # @yieldreturn [void]
+  # @return [Forge] forge
+  def self.define(...)
+    DEFAULT_YARD.define(...)
+  end
+
+  # @overload forge(name, *traits, **overrides)
+  # Build an instance using a forge from {DEFAULT_YARD}.
+  #
+  # @!macro default_forgeyard
+  # @see Forgeyard#forge
+  # @since 0.1.0
+  #
+  # @param name [Symbol] name of the forge
+  # @param traits [Array<Symbol>] traits to apply
+  # @param overrides [Hash{Symbol => Any}] attribute overrides
+  # @return [Any] built instance
+  def self.forge(...)
+    DEFAULT_YARD.forge(...)
+  end
+
+  class << self
+    # @since 0.1.0
+    alias build forge
+    # @since 0.1.0
+    alias [] forge
+  end
+end

data/sig/object_forge.rbs

@@ -0,0 +1,186 @@
+module ObjectForge
+  class Error < StandardError
+  end
+  class DSLError < Error
+  end
+
+  interface _Sequenceable
+    def succ: -> self
+    def respond_to?: (Symbol name, ?bool include_private) -> bool
+    def class: -> Class
+  end
+  interface _Forgable
+    def new: (Hash[Symbol, untyped]) -> self
+  end
+  interface _ForgeParameters
+    def attributes: () -> Hash[Symbol, untyped]
+    def traits: () -> Hash[Symbol, Hash[Symbol, untyped]]
+  end
+
+  VERSION: String
+  DEFAULT_YARD: ObjectForge::Forgeyard
+
+  def self.sequence
+    : (?(ObjectForge::_Sequenceable | ObjectForge::Sequence) initial) -> ObjectForge::Sequence
+
+  def self.define
+    : (Symbol name, ObjectForge::_Forgable forged) { (ObjectForge::ForgeDSL) -> void } -> ObjectForge::Forge
+    | (Symbol name, ObjectForge::_Forgable forged) { [self: ObjectForge::ForgeDSL] -> void } -> ObjectForge::Forge
+
+  def self.forge
+    : (Symbol name, *Symbol traits, **untyped overrides) -> ObjectForge::_Forgable
+end
+
+class ObjectForge::Sequence
+  def self.new
+    : (?(ObjectForge::_Sequenceable | ObjectForge::Sequence) initial) -> ObjectForge::Sequence
+  
+  attr_reader initial: ObjectForge::_Sequenceable
+  
+  def initialize: (ObjectForge::_Sequenceable initial) -> void
+
+  def next: -> ObjectForge::_Sequenceable
+
+  def reset: -> ObjectForge::_Sequenceable
+  alias rewind reset
+end
+  
+class ObjectForge::Forgeyard
+  attr_reader forges: Concurrent::Map[Symbol, ObjectForge::Forge]
+
+  def initialize
+    : () -> void
+
+  def define
+    : (Symbol name, ObjectForge::_Forgable forged) { (ObjectForge::ForgeDSL) -> void } -> ObjectForge::Forge
+    | (Symbol name, ObjectForge::_Forgable forged) { [self: ObjectForge::ForgeDSL] -> void } -> ObjectForge::Forge
+
+  def register
+    : (Symbol name, ObjectForge::Forge forge) -> ObjectForge::Forge
+
+  def forge
+    : (Symbol name, *Symbol traits, **untyped overrides) -> ObjectForge::_Forgable
+  alias build forge
+  alias [] forge
+end
+
+class ObjectForge::Forge
+  class Parameters
+    include ObjectForge::_ForgeParameters
+
+    def intitialize
+      : (attributes: Hash[Symbol, untyped], traits: Hash[Symbol, Hash[Symbol, untyped]]) -> void
+  end
+
+  attr_reader forged: ObjectForge::_Forgable
+  attr_reader name: Symbol
+
+  def self.define
+    : (ObjectForge::_Forgable forged, ?name: Symbol?) { (ObjectForge::ForgeDSL) -> void } -> ObjectForge::Forge
+    | (ObjectForge::_Forgable forged, ?name: Symbol?) { [self: ObjectForge::ForgeDSL] -> void } -> ObjectForge::Forge
+  
+  def initialize
+    : (ObjectForge::_Forgable forged, ObjectForge::_ForgeParameters parameters, ?name: Symbol?) -> void
+  
+  def forge
+    : (*Symbol traits, **untyped overrides) -> ObjectForge::_Forgable
+    | (Array[Symbol] traits, Hash[Symbol, untyped] overrides) -> ObjectForge::_Forgable
+  alias build forge
+  alias [] forge
+
+  private
+
+  def check_traits_and_overrides
+    : (Array[Symbol] traits, Hash[Symbol, untyped] overrides) -> [Array[Symbol], Hash[Symbol, untyped]]
+   | (Array[(Array[Symbol] | Hash[Symbol, untyped])], Hash[Symbol, untyped]) -> [Array[Symbol], Hash[Symbol, untyped]]
+end
+
+class ObjectForge::ForgeDSL < ObjectForge::UnBasicObject
+  include ObjectForge::_ForgeParameters
+  attr_reader sequences: Hash[Symbol, ObjectForge::Sequence]
+
+  @attributes: Hash[Symbol, Proc]
+  @sequences: Hash[Symbol, ObjectForge::Sequence]
+  @traits: Hash[Symbol, Hash[Symbol, Proc]]
+
+  def initialize
+    : () { (ObjectForge::ForgeDSL) -> void } -> void
+    | () { [self: ObjectForge::ForgeDSL] -> void } -> void
+
+  def freeze: -> self
+
+  def attribute
+    : (Symbol name) { -> untyped } -> Symbol
+    | (Symbol name) { (ObjectForge::_Sequenceable) -> untyped } -> Symbol
+  alias [] attribute
+
+  def sequence
+    : (Symbol name, ?(ObjectForge::_Sequenceable | ObjectForge::Sequence) initial) { (ObjectForge::_Sequenceable) -> untyped } -> Symbol
+
+  def trait
+    : (Symbol name) { (self) -> void } -> Symbol
+
+  def inspect: -> String
+  
+  private
+
+  def method_missing
+    : (Symbol name) { -> untyped } -> Symbol
+    # After freezing:
+    | (Symbol name) { -> untyped } -> void
+
+  def respond_to_missing?
+    : (Symbol name, bool include_all) -> bool
+
+  def rand: [T] (?(Float | Integer | Range[T])) -> (Float | Integer | T)
+end
+
+class ObjectForge::Crucible < ObjectForge::UnBasicObject
+  @attributes: Hash[Symbol, untyped]
+  @resolved_attributes: Set[Symbol]
+
+  def initialize
+    : (Hash[Symbol, untyped] attributes) -> void
+
+  def resolve!
+    : -> Hash[Symbol, untyped]
+
+  private
+
+  def method_missing
+    : (Symbol name) -> untyped
+  alias [] method_missing
+
+  def respond_to_missing?
+    : (Symbol name, bool include_all) -> bool
+end
+
+class ObjectForge::UnBasicObject < BasicObject
+  def class: -> Class
+  
+  def eql?: (untyped other) -> bool
+
+  def freeze: -> self
+
+  def frozen?: -> bool
+
+  def hash: -> Integer
+
+  def inspect: -> String
+
+  def is_a?: (Module klass) -> bool
+
+  def respond_to?: (Symbol name, ?bool include_private) -> bool
+
+  def to_s: -> String
+
+  def pretty_print: (untyped) -> void
+
+  def pretty_print_cycle: (untyped) -> void
+  
+  private
+
+  def block_given?: -> bool
+
+  def raise: (_Exception exception, ?String message) -> void
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: object_forge
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexandr Bulancov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-07-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: |
+  ObjectForge provides a familiar way to build objects in any context
+  with minimal assumptions about usage environment.
+  It has no connection to any framework and, indeed, has nothing to do with a database.
+  To use, just define some factories and call them wherever you need,
+  be it in tests, console, or application code.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/object_forge.rb
+- lib/object_forge/crucible.rb
+- lib/object_forge/forge.rb
+- lib/object_forge/forge_dsl.rb
+- lib/object_forge/forgeyard.rb
+- lib/object_forge/sequence.rb
+- lib/object_forge/un_basic_object.rb
+- lib/object_forge/version.rb
+- sig/object_forge.rbs
+homepage: https://github.com/trinistr/object_forge
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/trinistr/object_forge
+  bug_tracker_uri: https://github.com/trinistr/object_forge/issues
+  documentation_uri: https://rubydoc.info/gems/object_forge/0.1.0
+  source_code_uri: https://github.com/trinistr/object_forge/tree/v0.1.0
+  changelog_uri: https://github.com/trinistr/object_forge/blob/v0.1.0/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options:
+- "--tag"
+- thread_safety:Thread safety
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: A simple factory for objects with minimal assumptions.
+test_files: []