easy_talk 1.0.4 → 2.0.0

data/lib/easy_talk/configuration.rb

@@ -4,16 +4,17 @@ module EasyTalk
   class Configuration
     attr_accessor :exclude_foreign_keys, :exclude_associations, :excluded_columns,
                   :exclude_primary_key, :exclude_timestamps, :default_additional_properties,
-                  :nilable_is_optional
+                  :nilable_is_optional, :auto_validations
 
     def initialize
       @exclude_foreign_keys = true
       @exclude_associations = true
       @excluded_columns = []
-      @exclude_primary_key = true  # New option, defaulting to true
-      @exclude_timestamps = true   # New option, defaulting to true
+      @exclude_primary_key = true
+      @exclude_timestamps = true
       @default_additional_properties = false
       @nilable_is_optional = false
+      @auto_validations = true # New option: enable validations by default
     end
   end
 

data/lib/easy_talk/errors_helper.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module EasyTalk
+  # Helper module for generating consistent error messages
   module ErrorHelper
     def self.raise_constraint_error(property_name:, constraint_name:, expected:, got:)
       message = "Error in property '#{property_name}': Constraint '#{constraint_name}' expects #{expected}, " \

data/lib/easy_talk/model.rb

@@ -10,6 +10,7 @@ require 'active_model'
 require_relative 'builders/object_builder'
 require_relative 'schema_definition'
 require_relative 'active_record_schema_builder'
+require_relative 'validation_builder'
 
 module EasyTalk
   # The `Model` module is a mixin that provides functionality for defining and accessing the schema of a model.
@@ -47,10 +48,35 @@ module EasyTalk
       base.extend(ActiveRecordClassMethods)
     end
 
+    # Instance methods mixed into models that include EasyTalk::Model
     module InstanceMethods
       def initialize(attributes = {})
         @additional_properties = {}
-        super
+        super # Perform initial mass assignment
+
+        # After initial assignment, instantiate nested EasyTalk::Model objects
+        # Get the appropriate schema definition based on model type
+        schema_def = if self.class.respond_to?(:active_record_schema_definition)
+                       self.class.active_record_schema_definition
+                     else
+                       self.class.schema_definition
+                     end
+
+        # Only proceed if we have a valid schema definition
+        return unless schema_def.respond_to?(:schema) && schema_def.schema.is_a?(Hash)
+
+        (schema_def.schema[:properties] || {}).each do |prop_name, prop_definition|
+          # Get the defined type and the currently assigned value
+          defined_type = prop_definition[:type]
+          current_value = public_send(prop_name)
+
+          # Check if the type is another EasyTalk::Model and the value is a Hash
+          next unless defined_type.is_a?(Class) && defined_type.include?(EasyTalk::Model) && current_value.is_a?(Hash)
+
+          # Instantiate the nested model and assign it back
+          nested_instance = defined_type.new(current_value)
+          public_send("#{prop_name}=", nested_instance)
+        end
       end
 
       def method_missing(method_name, *args)
@@ -77,9 +103,10 @@ module EasyTalk
 
       # Add to_hash method to convert defined properties to hash
       def to_hash
-        return {} unless self.class.properties
+        properties_to_include = (self.class.schema_definition.schema[:properties] || {}).keys
+        return {} if properties_to_include.empty?
 
-        self.class.properties.each_with_object({}) do |prop, hash|
+        properties_to_include.each_with_object({}) do |prop, hash|
           hash[prop.to_s] = send(prop)
         end
       end
@@ -88,6 +115,23 @@ module EasyTalk
       def as_json(_options = {})
         to_hash.merge(@additional_properties)
       end
+
+      # Allow comparison with hashes
+      def ==(other)
+        case other
+        when Hash
+          # Convert both to comparable format for comparison
+          self_hash = (self.class.schema_definition.schema[:properties] || {}).keys.each_with_object({}) do |prop, hash|
+            hash[prop] = send(prop)
+          end
+
+          # Handle both symbol and string keys in the other hash
+          other_normalized = other.transform_keys(&:to_sym)
+          self_hash == other_normalized
+        else
+          super
+        end
+      end
     end
 
     # Module containing class-level methods for defining and accessing the schema of a model.
@@ -115,14 +159,6 @@ module EasyTalk
         "#/$defs/#{name}"
       end
 
-      def properties
-        @properties ||= begin
-          return unless schema[:properties].present?
-
-          schema[:properties].keys.map(&:to_sym)
-        end
-      end
-
       # Returns the JSON schema for the model.
       #
       # @return [Hash] The JSON schema for the model.
@@ -134,12 +170,30 @@ module EasyTalk
       #
       # @yield The block to define the schema.
       # @raise [ArgumentError] If the class does not have a name.
-      def define_schema(&block)
+      def define_schema(&)
         raise ArgumentError, 'The class must have a name' unless name.present?
 
         @schema_definition = SchemaDefinition.new(name)
-        @schema_definition.instance_eval(&block)
-        attr_accessor(*properties)
+        @schema_definition.klass = self # Pass the model class to the schema definition
+        @schema_definition.instance_eval(&)
+
+        # Define accessors immediately based on schema_definition
+        defined_properties = (@schema_definition.schema[:properties] || {}).keys
+        attr_accessor(*defined_properties)
+
+        # Track which properties have had validations applied
+        @validated_properties ||= Set.new
+
+        # Apply auto-validations immediately after definition
+        if EasyTalk.configuration.auto_validations
+          (@schema_definition.schema[:properties] || {}).each do |prop_name, prop_def|
+            # Only apply validations if they haven't been applied yet
+            unless @validated_properties.include?(prop_name)
+              ValidationBuilder.build_validations(self, prop_name, prop_def[:type], prop_def[:constraints])
+              @validated_properties.add(prop_name)
+            end
+          end
+        end
 
         @schema_definition
       end
@@ -155,6 +209,13 @@ module EasyTalk
         @schema_definition&.schema&.fetch(:additional_properties, false)
       end
 
+      # Returns the property names defined in the schema
+      #
+      # @return [Array<Symbol>] Array of property names as symbols
+      def properties
+        (@schema_definition&.schema&.dig(:properties) || {}).keys
+      end
+
       # Builds the schema using the provided schema definition.
       # This is the convergence point for all schema generation.
       #

data/lib/easy_talk/property.rb

@@ -11,30 +11,51 @@ require_relative 'builders/composition_builder'
 require_relative 'builders/typed_array_builder'
 require_relative 'builders/union_builder'
 
-# frozen_string_literal: true
-
-# EasyTalk module provides classes for building JSON schema properties.
+# EasyTalk module provides a DSL for building JSON Schema definitions.
+#
+# This module contains classes and utilities for easily creating valid JSON Schema
+# documents with a Ruby-native syntax. The `Property` class serves as the main entry
+# point for defining schema properties.
 #
-# This module contains the `Property` class, which is used to build a JSON schema property.
-# It also defines a constant `TYPE_TO_BUILDER` which maps property types to their respective builders.
+# @example Basic property definition
+#   property = EasyTalk::Property.new(:name, String, minLength: 3, maxLength: 50)
+#   property.build  # => {"type"=>"string", "minLength"=>3, "maxLength"=>50}
 #
-# Example usage:
-#   property = EasyTalk::Property.new(:name, 'String', minLength: 3, maxLength: 50)
-#   property.build
+# @example Using with nilable types
+#   nilable_prop = EasyTalk::Property.new(:optional_field, T::Types::Union.new(String, NilClass))
+#   nilable_prop.build  # => {"type"=>["string", "null"]}
 #
 # @see EasyTalk::Property
+# @see https://json-schema.org/ JSON Schema Documentation
 module EasyTalk
   # Property class for building a JSON schema property.
+  #
+  # This class handles the conversion from Ruby types to JSON Schema property definitions,
+  # and provides support for common constraints like minimum/maximum values, string patterns,
+  # and custom validators.
   class Property
     extend T::Sig
-    attr_reader :name, :type, :constraints
 
+    # @return [Symbol] The name of the property
+    attr_reader :name
+
+    # @return [Object] The type definition of the property
+    attr_reader :type
+
+    # @return [Hash<Symbol, Object>] Additional constraints applied to the property
+    attr_reader :constraints
+
+    # Mapping of Ruby type names to their corresponding schema builder classes.
+    # Each builder knows how to convert a specific Ruby type to JSON Schema.
+    #
+    # @api private
     TYPE_TO_BUILDER = {
       'String' => Builders::StringBuilder,
       'Integer' => Builders::IntegerBuilder,
       'Float' => Builders::NumberBuilder,
       'BigDecimal' => Builders::NumberBuilder,
       'T::Boolean' => Builders::BooleanBuilder,
+      'TrueClass' => Builders::BooleanBuilder,
       'NilClass' => Builders::NullBuilder,
       'Date' => Builders::TemporalBuilder::DateBuilder,
       'DateTime' => Builders::TemporalBuilder::DatetimeBuilder,
@@ -47,10 +68,19 @@ module EasyTalk
     }.freeze
 
     # Initializes a new instance of the Property class.
-    # @param name [Symbol] The name of the property.
-    # @param type [Object] The type of the property.
-    # @param constraints [Hash] The property constraints.
-    # @raise [ArgumentError] If the property type is missing.
+    #
+    # @param name [Symbol] The name of the property
+    # @param type [Object] The type of the property (Ruby class, string name, or Sorbet type)
+    # @param constraints [Hash<Symbol, Object>] Additional constraints for the property
+    #   (e.g., minLength, pattern, format)
+    #
+    # @example String property with constraints
+    #   Property.new(:username, 'String', minLength: 3, maxLength: 20, pattern: '^[a-z0-9_]+$')
+    #
+    # @example Integer property with range
+    #   Property.new(:age, 'Integer', minimum: 0, maximum: 120)
+    #
+    # @raise [ArgumentError] If the property type is missing or empty
     sig do
       params(name: Symbol, type: T.any(String, Object),
              constraints: T::Hash[Symbol, T.untyped]).void
@@ -59,18 +89,31 @@ module EasyTalk
       @name = name
       @type = type
       @constraints = constraints
-      raise ArgumentError, 'property type is missing' if type.blank?
+      if type.nil? || (type.respond_to?(:empty?) && type.is_a?(String) && type.strip.empty?)
+        raise ArgumentError,
+              'property type is missing'
+      end
+      raise ArgumentError, 'property type is not supported' if type.is_a?(Array) && type.empty?
     end
 
-    # Builds the property based on the specified type, constraints, and builder.
+    # Builds the property schema based on its type and constraints.
     #
-    # If the type responds to the `schema` method, it returns the schema of the type.
-    # Otherwise, it returns 'object'.
+    # This method handles different types of properties:
+    # - Nilable types (can be null)
+    # - Types with dedicated builders
+    # - Types that implement their own schema method
+    # - Default fallback to 'object' type
     #
-    # If a builder is specified, it uses the builder to build the property.
-    # The arguments passed to the builder depend on whether the builder is a collection type or not.
+    # @return [Hash] The complete JSON Schema property definition
     #
-    # @return [Object] The built property.
+    # @example Simple string property
+    #   property = Property.new(:name, 'String')
+    #   property.build  # => {"type"=>"string"}
+    #
+    # @example Complex nested schema
+    #   address = Address.new  # A class with a .schema method
+    #   property = Property.new(:shipping_address, address, description: "Shipping address")
+    #   property.build  # => Address schema merged with the description constraint
     def build
       if nilable_type?
         build_nilable_schema
@@ -86,43 +129,76 @@ module EasyTalk
       end
     end
 
-    # Converts the object to a JSON representation.
+    # Converts the property definition to a JSON-compatible format.
+    #
+    # This method enables seamless integration with Ruby's JSON library.
+    #
+    # @param _args [Array] Optional arguments passed to #as_json (ignored)
+    # @return [Hash] The JSON-compatible representation of the property schema
     #
-    # @param _args [Array] Optional arguments
-    # @return [Hash] The JSON representation of the object
+    # @see #build
+    # @see https://ruby-doc.org/stdlib-2.7.2/libdoc/json/rdoc/JSON.html#as_json-method
     def as_json(*_args)
       build.as_json
     end
 
-    # Returns the builder associated with the property type.
+    # Returns the builder class associated with the property type.
     #
-    # The builder is responsible for constructing the property based on its type.
-    # It looks up the builder based on the type's class name or name.
+    # The builder is responsible for converting the Ruby type to a JSON Schema type.
     #
-    # @return [Builder] The builder associated with the property type.
+    # @return [Class, nil] The builder class for this property's type, or nil if no dedicated builder exists
+    # @see #find_builder_for_type
     def builder
-      @builder ||= TYPE_TO_BUILDER[type.class.name.to_s] || TYPE_TO_BUILDER[type.name.to_s]
+      @builder ||= find_builder_for_type
     end
 
     private
 
+    # Finds the appropriate builder for the current type.
+    #
+    # First checks if there's a builder for the class name, then falls back
+    # to checking if there's a builder for the type's name (if it responds to :name).
+    #
+    # @return [Class, nil] The builder class for this type, or nil if none matches
+    # @api private
+    def find_builder_for_type
+      TYPE_TO_BUILDER[type.class.name.to_s] ||
+        (type.respond_to?(:name) ? TYPE_TO_BUILDER[type.name.to_s] : nil)
+    end
+
+    # Determines if the type is nilable (can be nil).
+    #
+    # A type is nilable if it's a union type that includes NilClass.
+    # This is typically represented as T.nilable(Type) in Sorbet.
+    #
+    # @return [Boolean] true if the type is nilable, false otherwise
+    # @api private
     def nilable_type?
-      return unless type.respond_to?(:types)
-      return unless type.types.all? { |t| t.respond_to?(:raw_type) }
+      return false unless type.respond_to?(:types)
+      return false unless type.types.all? { |t| t.respond_to?(:raw_type) }
 
       type.types.any? { |t| t.raw_type == NilClass }
     end
 
+    # Builds a schema for a nilable type, which can be either the actual type or null.
+    #
+    # @return [Hash] A schema with both the actual type and null type
+    # @api private
+    # @example
+    #   # For a T.nilable(String) type:
+    #   {"type"=>["string", "null"]}
     def build_nilable_schema
       # Extract the non-nil type from the Union
-      actual_type = type.types.find { |t| t != NilClass }
+      actual_type = type.types.find { |t| t.raw_type != NilClass }
+
+      return { type: 'null' } unless actual_type
 
       # Create a property with the actual type
       non_nil_schema = Property.new(name, actual_type, constraints).build
 
       # Merge the types into an array
       non_nil_schema.merge(
-        type: [non_nil_schema[:type], 'null']
+        type: [non_nil_schema[:type], 'null'].compact
       )
     end
   end

data/lib/easy_talk/schema_definition.rb

@@ -2,6 +2,7 @@
 
 require_relative 'keywords'
 require_relative 'types/composer'
+require_relative 'validation_builder'
 
 module EasyTalk
   #
@@ -16,11 +17,13 @@ module EasyTalk
     extend T::AllOf
 
     attr_reader :name, :schema
+    attr_accessor :klass # Add accessor for the model class
 
     def initialize(name, schema = {})
       @schema = schema
       @schema[:additional_properties] = false unless schema.key?(:additional_properties)
       @name = name
+      @klass = nil # Initialize klass to nil
     end
 
     EasyTalk::KEYWORDS.each do |keyword|
@@ -34,32 +37,24 @@ module EasyTalk
       @schema[:subschemas] += subschemas
     end
 
-    sig do
-      params(name: T.any(Symbol, String), type: T.untyped, constraints: T.untyped, blk: T.nilable(T.proc.void)).void
-    end
-    def property(name, type, constraints = {}, &blk)
+    def property(name, type, constraints = {}, &)
       validate_property_name(name)
       @schema[:properties] ||= {}
 
       if block_given?
-        property_schema = SchemaDefinition.new(name)
-        property_schema.instance_eval(&blk)
-
-        @schema[:properties][name] = {
-          type:,
-          constraints:,
-          properties: property_schema
-        }
-      else
-        @schema[:properties][name] = { type:, constraints: }
+        raise ArgumentError,
+              'Block-style sub-schemas are no longer supported. Use class references as types instead.'
       end
+
+      @schema[:properties][name] = { type:, constraints: }
     end
 
     def validate_property_name(name)
       return if name.to_s.match?(/^[A-Za-z_][A-Za-z0-9_]*$/)
 
-      raise InvalidPropertyNameError,
-            "Invalid property name '#{name}'. Must start with letter/underscore and contain only letters, numbers, underscores"
+      message = "Invalid property name '#{name}'. Must start with letter/underscore " \
+                'and contain only letters, numbers, underscores'
+      raise InvalidPropertyNameError, message
     end
 
     def optional?
@@ -67,7 +62,7 @@ module EasyTalk
     end
 
     # Helper method for nullable and optional properties
-    def nullable_optional_property(name, type, constraints = {}, &blk)
+    def nullable_optional_property(name, type, constraints = {})
       # Ensure type is nilable
       nilable_type = if type.respond_to?(:nilable?) && type.nilable?
                        type
@@ -79,7 +74,7 @@ module EasyTalk
       constraints = constraints.merge(optional: true)
 
       # Call standard property method
-      property(name, nilable_type, constraints, &blk)
+      property(name, nilable_type, constraints)
     end
   end
 end

data/lib/easy_talk/types/composer.rb

@@ -54,13 +54,14 @@ end
 
 # Shorthand module for accessing the AllOf composer
 module T
+  # Provides composition logic for combining multiple schemas with AllOf semantics
   module AllOf
     # Creates a new instance of `EasyTalk::Types::Composer::AllOf` with the given arguments.
     #
     # @param args [Array] the list of arguments to be passed to the constructor
     # @return [EasyTalk::Types::Composer::AllOf] a new instance
-    def self.[](*args)
-      EasyTalk::Types::Composer::AllOf.new(*args)
+    def self.[](*)
+      EasyTalk::Types::Composer::AllOf.new(*)
     end
   end
 
@@ -70,8 +71,8 @@ module T
     #
     # @param args [Array] the list of arguments to be passed to the constructor
     # @return [EasyTalk::Types::Composer::AnyOf] a new instance
-    def self.[](*args)
-      EasyTalk::Types::Composer::AnyOf.new(*args)
+    def self.[](*)
+      EasyTalk::Types::Composer::AnyOf.new(*)
     end
   end
 
@@ -81,8 +82,8 @@ module T
     #
     # @param args [Array] the list of arguments to be passed to the constructor
     # @return [EasyTalk::Types::Composer::OneOf] a new instance
-    def self.[](*args)
-      EasyTalk::Types::Composer::OneOf.new(*args)
+    def self.[](*)
+      EasyTalk::Types::Composer::OneOf.new(*)
     end
   end
 end