easy_talk 1.0.4 → 3.0.0

data/easy_talk.gemspec

@@ -0,0 +1,39 @@
+# 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 with ActiveModel integration.'
+  spec.description = 'Generate json-schema from plain Ruby classes with ActiveModel integration for validations and serialization.'
+  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', '< 9.0']
+  spec.add_dependency 'activesupport', ['>= 7.0', '< 9.0']
+  spec.add_dependency 'js_regex', '~> 3.0'
+  spec.add_dependency 'sorbet-runtime', '~> 0.5'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

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
 

data/lib/easy_talk/builders/integer_builder.rb

@@ -7,6 +7,7 @@ module EasyTalk
     # Builder class for integer properties.
     class IntegerBuilder < BaseBuilder
       extend T::Sig
+
       VALID_OPTIONS = {
         minimum: { type: Integer, key: :minimum },
         maximum: { type: Integer, key: :maximum },

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
@@ -119,9 +119,7 @@ module EasyTalk
         return true if prop_options.dig(:constraints, :optional)
 
         # Check for nil_optional config to determine if nilable should also mean optional
-        if prop_options[:type].respond_to?(:nilable?) && prop_options[:type].nilable?
-          return EasyTalk.configuration.nilable_is_optional
-        end
+        return EasyTalk.configuration.nilable_is_optional if prop_options[:type].respond_to?(:nilable?) && prop_options[:type].nilable?
 
         false
       end
@@ -134,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/string_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base_builder'
+require 'js_regex' # Compile the ruby regex to JS regex
 require 'sorbet-runtime' # Add the import statement for the T module
 
 module EasyTalk
@@ -8,6 +9,7 @@ module EasyTalk
     # Builder class for string properties.
     class StringBuilder < BaseBuilder
       extend T::Sig
+
       VALID_OPTIONS = {
         format: { type: String, key: :format },
         pattern: { type: String, key: :pattern },
@@ -22,6 +24,13 @@ module EasyTalk
       def initialize(name, constraints = {})
         super(name, { type: 'string' }, constraints, VALID_OPTIONS)
       end
+
+      def build
+        super.tap do |schema|
+          pattern = schema[:pattern]
+          schema[:pattern] = JsRegex.new(pattern).source if pattern.is_a?(String)
+        end
+      end
     end
   end
 end

data/lib/easy_talk/configuration.rb

@@ -2,18 +2,12 @@
 
 module EasyTalk
   class Configuration
-    attr_accessor :exclude_foreign_keys, :exclude_associations, :excluded_columns,
-                  :exclude_primary_key, :exclude_timestamps, :default_additional_properties,
-                  :nilable_is_optional
+    attr_accessor :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
       @default_additional_properties = false
       @nilable_is_optional = false
+      @auto_validations = true
     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

@@ -9,7 +9,7 @@ require 'active_support/json'
 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.
@@ -35,22 +35,43 @@ module EasyTalk
   # @see SchemaDefinition
   module Model
     def self.included(base)
-      base.include ActiveModel::API # Include ActiveModel::API in the class including EasyTalk::Model
+      base.extend(ClassMethods)
+
+      base.include ActiveModel::API
       base.include ActiveModel::Validations
       base.extend ActiveModel::Callbacks
-      base.extend(ClassMethods)
       base.include(InstanceMethods)
-
-      # Apply ActiveRecord-specific functionality if appropriate
-      return unless defined?(ActiveRecord) && base.ancestors.include?(ActiveRecord::Base)
-
-      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
+        schema_def = self.class.schema_definition
+
+        # 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)
+          nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
+
+          next if nilable_type && current_value.nil?
+
+          defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
+
+          # 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 +98,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 +110,28 @@ module EasyTalk
       def as_json(_options = {})
         to_hash.merge(@additional_properties)
       end
+
+      # to_h includes both defined and additional properties
+      def to_h
+        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.
@@ -97,13 +141,8 @@ module EasyTalk
       # @return [Schema] The schema for the model.
       def schema
         @schema ||= if defined?(@schema_definition) && @schema_definition
-                      # Schema defined explicitly via define_schema
                       build_schema(@schema_definition)
-                    elsif respond_to?(:active_record_schema_definition)
-                      # ActiveRecord model without explicit schema definition
-                      build_schema(active_record_schema_definition)
                     else
-                      # Default case - empty schema
                       {}
                     end
       end
@@ -115,14 +154,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 +165,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 +204,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.
       #
@@ -164,34 +220,5 @@ module EasyTalk
         Builders::ObjectBuilder.new(schema_definition).build
       end
     end
-
-    # Module containing ActiveRecord-specific methods for schema generation
-    module ActiveRecordClassMethods
-      # Gets a SchemaDefinition that's built from the ActiveRecord database schema
-      #
-      # @return [SchemaDefinition] A schema definition built from the database
-      def active_record_schema_definition
-        @active_record_schema_definition ||= ActiveRecordSchemaBuilder.new(self).build_schema_definition
-      end
-
-      # Store enhancements to be applied to the schema
-      #
-      # @return [Hash] The schema enhancements
-      def schema_enhancements
-        @schema_enhancements ||= {}
-      end
-
-      # Enhance the generated schema with additional information
-      #
-      # @param enhancements [Hash] The schema enhancements
-      # @return [void]
-      def enhance_schema(enhancements)
-        @schema_enhancements = enhancements
-        # Clear cached values to force regeneration
-        @active_record_schema_definition = nil
-        @schema = nil
-        @json_schema = nil
-      end
-    end
   end
 end

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 = T::Utils::Nilable.get_underlying_type(type)
+
+      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