easy_talk 1.0.3 → 2.0.0

data/easy_talk.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'lib/easy_talk/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'easy_talk'
+  spec.version = EasyTalk::VERSION
+  spec.authors = ['Sergio Bayona']
+  spec.email = ['bayona.sergio@gmail.com']
+
+  spec.summary = 'Generate json-schema from Ruby classes.'
+  spec.description = 'Generate json-schema from plain Ruby classes.'
+  spec.homepage = 'https://github.com/sergiobayona/easy_talk'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = 'https://github.com/sergiobayona/easy_talk/blob/main/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ spec/ .git .github Gemfile])
+    end
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activemodel', '~> 7.0'
+  spec.add_dependency 'activesupport', '~> 7.0'
+  spec.add_dependency 'sorbet-runtime', '~> 0.5'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/easy_talk/active_record_schema_builder.rb

@@ -98,6 +98,9 @@ module EasyTalk
         # Map the database type to Ruby type
         ruby_type = COLUMN_TYPE_MAP.fetch(column.type, String)
 
+        # If the column is nullable, wrap the type in a Union with NilClass
+        ruby_type = T::Types::Union.new([ruby_type, NilClass]) if column.null
+
         # Build constraints hash for this column
         constraints = build_column_constraints(column, column_enhancements)
 
@@ -133,7 +136,11 @@ module EasyTalk
       end
 
       # Add default value if present and not a proc
-      constraints[:default] = column.default if column.default && !column.default.is_a?(Proc)
+      if column.default && !column.default.is_a?(Proc) && column.type == :boolean
+        constraints[:default] = ActiveModel::Type::Boolean.new.cast(column.default)
+      elsif column.default && !column.default.is_a?(Proc)
+        constraints[:default] = column.default
+      end
 
       # Remove nil values
       constraints.compact

data/lib/easy_talk/builders/composition_builder.rb

@@ -50,7 +50,18 @@ module EasyTalk
       # @return [Array<Hash>] The array of schemas.
       def schemas
         items.map do |type|
-          type.respond_to?(:schema) ? type.schema : { type: type.to_s.downcase }
+          if type.respond_to?(:schema)
+            type.schema
+          else
+            # Map Float type to 'number' in JSON Schema
+            json_type = case type.to_s
+                       when 'Float', 'BigDecimal'
+                         'number'
+                       else
+                         type.to_s.downcase
+                       end
+            { type: json_type }
+          end
         end
       end
 
@@ -60,6 +71,18 @@ module EasyTalk
       def items
         @type.items
       end
+
+      # Builder class for AllOf composition.
+      class AllOfBuilder < CompositionBuilder
+      end
+
+      # Builder class for AnyOf composition.
+      class AnyOfBuilder < CompositionBuilder
+      end
+
+      # Builder class for OneOf composition.
+      class OneOfBuilder < CompositionBuilder
+      end
     end
   end
 end

data/lib/easy_talk/builders/object_builder.rb

@@ -8,7 +8,7 @@ module EasyTalk
     # ObjectBuilder is responsible for turning a SchemaDefinition of an "object" type
     # into a validated JSON Schema hash. It:
     #
-    # 1) Recursively processes the schema’s :properties,
+    # 1) Recursively processes the schema's :properties,
     # 2) Determines which properties are required (unless optional),
     # 3) Handles sub-schema composition (allOf, anyOf, oneOf, not),
     # 4) Produces the final object-level schema hash.
@@ -55,7 +55,7 @@ module EasyTalk
 
       ##
       # Main aggregator: merges the top-level schema keys (like :properties, :subschemas)
-      # into a single hash that we’ll feed to BaseBuilder.
+      # into a single hash that we'll feed to BaseBuilder.
       def build_options_hash
         # Start with a copy of the raw schema
         merged = @original_schema.dup
@@ -118,6 +118,9 @@ module EasyTalk
         # Check constraints[:optional]
         return true if prop_options.dig(:constraints, :optional)
 
+        # Check for nil_optional config to determine if nilable should also mean optional
+        return EasyTalk.configuration.nilable_is_optional if prop_options[:type].respond_to?(:nilable?) && prop_options[:type].nilable?
+
         false
       end
 
@@ -129,24 +132,12 @@ module EasyTalk
         @property_cache ||= {}
 
         # Memoize so we only build each property once
-        @property_cache[prop_name] ||= if prop_options[:properties]
-                                         # This indicates block-style definition => nested schema
-                                         nested_schema_builder(prop_options)
-                                       else
-                                         # Remove optional constraints from the property
-                                         constraints = prop_options[:constraints].except(:optional)
-                                         # Normal property: e.g. { type: String, constraints: {...} }
-                                         Property.new(prop_name, prop_options[:type], constraints)
-                                       end
-      end
-
-      ##
-      # Build a child schema by calling another ObjectBuilder on the nested SchemaDefinition.
-      #
-      def nested_schema_builder(prop_options)
-        child_schema_def = prop_options[:properties]
-        # If user used T.nilable(...) with a block, unwrap the nilable
-        ObjectBuilder.new(child_schema_def).build
+        @property_cache[prop_name] ||= begin
+          # Remove optional constraints from the property
+          constraints = prop_options[:constraints].except(:optional)
+          # Normal property: e.g. { type: String, constraints: {...} }
+          Property.new(prop_name, prop_options[:type], constraints)
+        end
       end
 
       ##

data/lib/easy_talk/builders/temporal_builder.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'string_builder'
+
+module EasyTalk
+  module Builders
+    # Builder class for temporal properties (date, datetime, time).
+    class TemporalBuilder < StringBuilder
+      # Initializes a new instance of the TemporalBuilder class.
+      #
+      # @param property_name [Symbol] The name of the property.
+      # @param options [Hash] The options for the builder.
+      # @param format [String] The format of the temporal property (date, date-time, time).
+      def initialize(property_name, options = {}, format = nil)
+        super(property_name, options)
+        @format = format
+      end
+
+      # Modifies the schema to include the format constraint for a temporal property.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def schema
+        super.tap do |schema|
+          schema[:format] = @format if @format
+        end
+      end
+
+      # Builder class for date properties.
+      class DateBuilder < TemporalBuilder
+        def initialize(property_name, options = {})
+          super(property_name, options, 'date')
+        end
+      end
+
+      # Builder class for datetime properties.
+      class DatetimeBuilder < TemporalBuilder
+        def initialize(property_name, options = {})
+          super(property_name, options, 'date-time')
+        end
+      end
+
+      # Builder class for time properties.
+      class TimeBuilder < TemporalBuilder
+        def initialize(property_name, options = {})
+          super(property_name, options, 'time')
+        end
+      end
+    end
+  end
+end

data/lib/easy_talk/configuration.rb

@@ -3,15 +3,18 @@
 module EasyTalk
   class Configuration
     attr_accessor :exclude_foreign_keys, :exclude_associations, :excluded_columns,
-                  :exclude_primary_key, :exclude_timestamps, :default_additional_properties
+                  :exclude_primary_key, :exclude_timestamps, :default_additional_properties,
+                  :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

@@ -6,55 +6,81 @@ require_relative 'builders/number_builder'
 require_relative 'builders/boolean_builder'
 require_relative 'builders/null_builder'
 require_relative 'builders/string_builder'
-require_relative 'builders/date_builder'
-require_relative 'builders/datetime_builder'
-require_relative 'builders/time_builder'
-require_relative 'builders/any_of_builder'
-require_relative 'builders/all_of_builder'
-require_relative 'builders/one_of_builder'
+require_relative 'builders/temporal_builder'
+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::DateBuilder,
-      'DateTime' => Builders::DatetimeBuilder,
-      'Time' => Builders::TimeBuilder,
-      'anyOf' => Builders::AnyOfBuilder,
-      'allOf' => Builders::AllOfBuilder,
-      'oneOf' => Builders::OneOfBuilder,
+      'Date' => Builders::TemporalBuilder::DateBuilder,
+      'DateTime' => Builders::TemporalBuilder::DatetimeBuilder,
+      'Time' => Builders::TemporalBuilder::TimeBuilder,
+      'anyOf' => Builders::CompositionBuilder::AnyOfBuilder,
+      'allOf' => Builders::CompositionBuilder::AllOfBuilder,
+      'oneOf' => Builders::CompositionBuilder::OneOfBuilder,
       'T::Types::TypedArray' => Builders::TypedArrayBuilder,
       'T::Types::Union' => Builders::UnionBuilder
     }.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
@@ -63,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
@@ -90,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