castkit 0.1.2 → 0.3.0

data/lib/castkit/types/collection.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../validators/collection_validator"
+
+module Castkit
+  module Types
+    # Type definition for `:array` attributes.
+    #
+    # Wraps any value in an array using `Array(value)` coercion. This ensures consistent array representation
+    # even if the input is a single value or nil.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `array :tags, of: :string`
+    class Collection < Base
+      # Deserializes the value into an array using `Array(value)`.
+      #
+      # @param value [Object]
+      # @return [::Array]
+      def deserialize(value)
+        Array(value)
+      end
+
+      # Validates the Array value.
+      #
+      # @param value [Object]
+      # @param options [Hash] validation options
+      # @param context [Symbol, String, nil] attribute context for error messages
+      # @return [void]
+      def validate!(value, options: {}, context: nil)
+        Castkit::Validators::CollectionValidator.call(value, options: options, context: context)
+      end
+    end
+  end
+end

data/lib/castkit/types/date.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "base"
+
+module Castkit
+  module Types
+    # Type definition for `:date` attributes.
+    #
+    # Handles deserialization from strings and other input into `Date` objects,
+    # and serializes `Date` values into ISO8601 strings.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `date :published_on`
+    class Date < Base
+      # Deserializes the input value to a `Date` instance.
+      #
+      # @param value [Object]
+      # @return [::Date]
+      # @raise [ArgumentError] if parsing fails
+      def deserialize(value)
+        ::Date.parse(value.to_s)
+      end
+
+      # Serializes a `Date` object to ISO8601 string format.
+      #
+      # @param value [::Date]
+      # @return [String]
+      def serialize(value)
+        value.iso8601
+      end
+    end
+  end
+end

data/lib/castkit/types/date_time.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "base"
+
+module Castkit
+  module Types
+    # Type definition for `:datetime` attributes.
+    #
+    # Handles deserialization from strings and other input into `DateTime` objects,
+    # and serializes `DateTime` values into ISO8601 strings.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `datetime :published_ad`
+    class DateTime < Base
+      # Deserializes the input value to a `DateTime` instance.
+      #
+      # @param value [Object]
+      # @return [::DateTime]
+      # @raise [ArgumentError] if parsing fails
+      def deserialize(value)
+        ::DateTime.parse(value.to_s)
+      end
+
+      # Serializes a `DateTime` object to ISO8601 string format.
+      #
+      # @param value [::DateTime]
+      # @return [String]
+      def serialize(value)
+        value.iso8601
+      end
+    end
+  end
+end

data/lib/castkit/types/float.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../validators/float_validator"
+
+module Castkit
+  module Types
+    # Type definition for `:integer` attributes.
+    #
+    # Handles deserialization from raw input (e.g., strings, floats) to Float,
+    # applies optional numeric validation rules (e.g., `min`, `max`), and returns
+    # the value unchanged during serialization.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `integer :count`
+    class Float < Base
+      # Deserializes the input value to an Float.
+      #
+      # @param value [Object]
+      # @return [Float]
+      def deserialize(value)
+        value.to_f
+      end
+
+      # Serializes the Float value.
+      #
+      # @param value [Float]
+      # @return [Float]
+      def serialize(value)
+        value
+      end
+
+      # Validates the Float value using Castkit's FloatValidator.
+      #
+      # Supports options like `min:` and `max:`.
+      #
+      # @param value [Object]
+      # @param options [Hash] validation options
+      # @param context [Symbol, String] attribute context for error messages
+      # @return [void]
+      def validate!(value, options: {}, context: {})
+        Castkit::Validators::FloatValidator.call(value, options: options, context: context)
+      end
+    end
+  end
+end

data/lib/castkit/types/integer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../validators/integer_validator"
+
+module Castkit
+  module Types
+    # Type definition for `:integer` attributes.
+    #
+    # Handles deserialization from raw input (e.g., strings, floats) to Integer,
+    # applies optional numeric validation rules (e.g., `min`, `max`), and returns
+    # the value unchanged during serialization.
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `integer :count`
+    class Integer < Base
+      # Deserializes the input value to an Integer.
+      #
+      # @param value [Object]
+      # @return [Integer]
+      def deserialize(value)
+        value.to_i
+      end
+
+      # Serializes the Integer value.
+      #
+      # @param value [Integer]
+      # @return [Integer]
+      def serialize(value)
+        value
+      end
+
+      # Validates the Integer value using Castkit's IntegerValidator.
+      #
+      # Supports options like `min:` and `max:`.
+      #
+      # @param value [Object]
+      # @param options [Hash] validation options
+      # @param context [Symbol, String] attribute context for error messages
+      # @return [void]
+      def validate!(value, options: {}, context: {})
+        Castkit::Validators::IntegerValidator.call(value, options: options, context: context)
+      end
+    end
+  end
+end

data/lib/castkit/types/string.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../validators/string_validator"
+
+module Castkit
+  module Types
+    # Type definition for `:string` attributes.
+    #
+    # Coerces any input to a string using `to_s`, and validates that the resulting value is a `String`.
+    # Supports optional format validation via a `:format` option (Regexp or Proc).
+    #
+    # This class is used internally by Castkit when an attribute is defined with:
+    #   `string :id`
+    class String < Base
+      # Deserializes the value by coercing it to a string using `to_s`.
+      #
+      # @param value [Object]
+      # @return [String]
+      def deserialize(value)
+        value.to_s
+      end
+
+      # Serializes the value as-is.
+      #
+      # @param value [String]
+      # @return [String]
+      def serialize(value)
+        value
+      end
+
+      # Validates the value is a `String` and optionally matches a format.
+      #
+      # @param value [Object]
+      # @param options [Hash] validation options (e.g., `format: /regex/`)
+      # @param context [Symbol, String]
+      # @raise [Castkit::AttributeError] if validation fails
+      # @return [void]
+      def validate!(value, options: {}, context: {})
+        Castkit::Validators::StringValidator.call(value, options: options, context: context)
+      end
+    end
+  end
+end

data/lib/castkit/types.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "types/base"
+require_relative "types/collection"
+require_relative "types/boolean"
+require_relative "types/date"
+require_relative "types/date_time"
+require_relative "types/float"
+require_relative "types/integer"
+require_relative "types/string"
+
+module Castkit
+  # Object types supported natively by Castkit.
+  module Types; end
+end

data/lib/castkit/validators/base.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Castkit
+  module Validators
+    # Abstract base class for all attribute validators.
+    #
+    # Validators are responsible for enforcing value constraints (e.g., type checks,
+    # format rules, numerical bounds). All validators must inherit from this base class
+    # and implement the `#call` instance method.
+    #
+    # Supports both instance-level and class-level invocation via `.call`.
+    #
+    # @abstract Subclasses must implement `#call`.
+    class Base
+      class << self
+        # Entry point for validating a value using the validator class.
+        #
+        # Instantiates the validator and invokes `#call` with the provided arguments.
+        #
+        # @param value [Object] the value to validate
+        # @param options [Hash] additional validation options (e.g., `min`, `max`, `format`)
+        # @param context [Symbol, String, Hash] context for the validation (usually the attribute name)
+        # @return [void]
+        # @raise [Castkit::AttributeError] if validation fails and `raise_type_errors` is true
+        def call(value, options:, context:)
+          new.call(value, options: options, context: context)
+        end
+      end
+
+      # Validates the value.
+      #
+      # @abstract
+      # @param value [Object] the value to validate
+      # @param options [Hash] validation options (e.g., min, max, format)
+      # @param context [Symbol, String, Hash] context for validation errors
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented in subclass
+      def call(value, options:, context:)
+        raise NotImplementedError, "#{self.class.name} must implement `#call`"
+      end
+
+      protected
+
+      # Emits or raises a type error depending on global configuration.
+      #
+      # @param type [Symbol] the expected type (e.g., `:integer`)
+      # @param value [Object, nil] the received value
+      # @param context [Symbol, String, nil] context to include in error messages
+      # @raise [Castkit::AttributeError] if `raise_type_errors` is enabled
+      # @return [void]
+      def type_error!(type, value, context: nil)
+        message = "#{context || "value"} must be a #{type}, got #{value}"
+        raise Castkit::AttributeError, message if Castkit.configuration.raise_type_errors
+
+        Castkit.warning "[Castkit] #{message}" if Castkit.configuration.enable_warnings
+      end
+    end
+  end
+end

data/lib/castkit/validators/boolean_validator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Castkit
+  module Validators
+    # Validator for boolean attributes.
+    #
+    # Accepts various representations of boolean values, including strings and integers.
+    # Converts common truthy/falsy string values into booleans, otherwise raises a type error.
+    #
+    # This validator is typically used internally by `Castkit::Types::Boolean`.
+    #
+    # @example
+    #   validator = Castkit::Validators::BooleanValidator.new
+    #   validator.call("true", _options: {}, context: :enabled) # => true
+    #   validator.call("0", _options: {}, context: :enabled)    # => false
+    #   validator.call("nope", _options: {}, context: :enabled) # raises Castkit::AttributeError
+    class BooleanValidator
+      # Validates the Boolean value.
+      #
+      # @param value [Object] the input to validate
+      # @param _options [Hash] unused, provided for consistency with other validators
+      # @param context [Symbol, String] the attribute name or path for error messages
+      # @return [Boolean]
+      # @raise [Castkit::AttributeError] if the value is not a recognizable boolean
+      def call(value, _options:, context:)
+        case value.to_s.downcase
+        when "true", "1"
+          true
+        when "false", "0"
+          false
+        else
+          type_error!(:boolean, value, context: context)
+        end
+      end
+    end
+  end
+end

data/lib/castkit/validators/collection_validator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../validators/base"
+
+module Castkit
+  module Validators
+    # Validator for array (collection) attributes.
+    #
+    # Ensures that the provided value is an instance of `Array`. This validator is
+    # typically used by `Castkit::Types::Collection` for attributes defined as arrays.
+    #
+    # @example
+    #   validator = Castkit::Validators::CollectionValidator.new
+    #   validator.call([1, 2, 3], _options: {}, context: :tags) # => passes
+    #   validator.call("foo", _options: {}, context: :tags)     # raises Castkit::AttributeError
+    class CollectionValidator < Castkit::Validators::Base
+      # Validates that the value is an Array.
+      #
+      # @param value [Object] the value to validate
+      # @param _options [Hash] unused, for interface consistency
+      # @param context [Symbol, String] the field or context for error messaging
+      # @return [void]
+      # @raise [Castkit::AttributeError] if value is not an Array
+      def call(value, _options:, context:)
+        type_error!(:array, value, context: context) unless value.is_a?(::Array)
+      end
+    end
+  end
+end

data/lib/castkit/validators/float_validator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "numeric_validator"
+
+module Castkit
+  module Validators
+    # Validator for Float attributes.
+    #
+    # Ensures the value is a `Float`, and applies any numeric bounds (`min`, `max`)
+    # defined in the attribute options. Inherits shared logic from `NumericValidator`.
+    #
+    # @example
+    #   validator = Castkit::Validators::FloatValidator.new
+    #   validator.call(3.14, options: { min: 0.0 }, context: :price) # => passes
+    #   validator.call(42, options: {}, context: :price)             # raises Castkit::AttributeError
+    class FloatValidator < Castkit::Validators::NumericValidator
+      # Validates that the value is a Float and within optional bounds.
+      #
+      # @param value [Object, nil] the value to validate
+      # @param options [Hash] validation options (e.g., `min`, `max`)
+      # @param context [Symbol, String] the attribute name or key for error messages
+      # @raise [Castkit::AttributeError] if value is not a Float or out of range
+      # @return [void]
+      def call(value, options:, context:)
+        return type_error!(:float, value, context: context) unless value.is_a?(::Float)
+
+        super
+      end
+    end
+  end
+end

data/lib/castkit/validators/integer_validator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "numeric_validator"
+
+module Castkit
+  module Validators
+    # Validator for Integer attributes.
+    #
+    # Ensures the value is an instance of `Integer` and optionally checks numerical constraints
+    # such as `min` and `max`, inherited from `Castkit::Validators::NumericValidator`.
+    #
+    # @example Validating an Integer attribute
+    #   IntegerValidator.call(42, options: { min: 10, max: 100 }, context: :count)
+    #
+    # @see Castkit::Validators::NumericValidator
+    class IntegerValidator < Castkit::Validators::NumericValidator
+      # Validates the Integer value.
+      #
+      # @param value [Object, nil] the value to validate
+      # @param options [Hash] validation options (e.g., `min`, `max`)
+      # @param context [Symbol, String] the attribute name or context for error messages
+      # @raise [Castkit::AttributeError] if the value is not an Integer or fails validation rules
+      # @return [void]
+      def call(value, options:, context:)
+        return type_error!(:integer, value, context: context) unless value.is_a?(::Integer)
+
+        super
+      end
+    end
+  end
+end

data/lib/castkit/validators/numeric_validator.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "../validator"
+require_relative "base"
 
 module Castkit
   module Validators
     # Validates that a numeric value falls within the allowed range.
     #
     # Supports `:min` and `:max` options to enforce bounds.
-    class NumericValidator < Castkit::Validator
+    class NumericValidator < Castkit::Validators::Base
       # Validates the numeric value.
       #
       # @param value [Numeric] the value to validate

data/lib/castkit/validators/string_validator.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "../validator"
+require_relative "base"
 
 module Castkit
   module Validators
     # Validates that a value is a String and optionally conforms to a format.
     #
     # Supports format validation using a Regexp or a custom Proc.
-    class StringValidator < Castkit::Validator
+    class StringValidator < Castkit::Validators::Base
       # Validates the string value.
       #
       # @param value [Object] the value to validate
@@ -16,8 +16,7 @@ module Castkit
       # @raise [Castkit::AttributeError] if value is not a string or fails format validation
       # @return [void]
       def call(value, options:, context:)
-        raise Castkit::AttributeError, "#{context} must be a String" unless value.is_a?(String)
-
+        return type_error!(:string, value, context: context) unless value.is_a?(::String)
         return unless options[:format]
 
         case options[:format]

data/lib/castkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Castkit
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/castkit.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "castkit/version"
+require_relative "castkit/attribute"
+require_relative "castkit/contract"
 require_relative "castkit/data_object"
 
 # Castkit is a lightweight, type-safe data object system for Ruby.

data/lib/generators/base.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "thor/group"
+require "castkit/inflector"
+
+module Castkit
+  module Generators
+    # Abstract base class for all Castkit generators.
+    #
+    # Provides standard behavior for generating a component and optional spec file from
+    # ERB templates. Subclasses must define a `component` (e.g., `:type`, `:contract`)
+    # and may override `config` or `default_values`.
+    #
+    # Template variables are injected using the `config` hash, which includes:
+    # - `:name`        – underscored version of the component name
+    # - `:class_name`  – PascalCase version of the component name
+    #
+    # @abstract
+    class Base < Thor::Group
+      include Thor::Actions
+
+      class << self
+        # Sets or retrieves the component type (e.g., :type, :data_object).
+        #
+        # @param value [Symbol, nil]
+        # @return [Symbol]
+        def component(value = nil)
+          value.nil? ? @component : (@component = value)
+        end
+
+        # @return [String] the root path to look for templates
+        def source_root
+          File.expand_path("templates", __dir__)
+        end
+      end
+
+      argument :name, desc: "The name of the component to generate"
+      class_option :spec, type: :boolean, default: true, desc: "Also generate a spec file"
+
+      # Creates the main component file using a template.
+      #
+      # Template: `component.rb.tt`
+      # Target: `lib/castkit/#{component}s/#{name}.rb`
+      #
+      # @return [void]
+      def create_component
+        template(
+          "#{self.class.component}.rb.tt",
+          "lib/castkit/#{self.class.component}s/#{config[:name]}.rb", **config
+        )
+      end
+
+      # Creates the associated spec file, if enabled.
+      #
+      # Template: `component_spec.rb.tt`
+      # Target: `spec/castkit/#{component}s/#{name}_spec.rb`
+      #
+      # @return [void]
+      def create_spec
+        return unless options[:spec]
+
+        template(
+          "#{self.class.component}_spec.rb.tt",
+          "spec/castkit/#{self.class.component}s/#{config[:name]}_spec.rb", **config
+        )
+      end
+
+      private
+
+      # Default values for test inputs based on type.
+      #
+      # These are used in spec templates to provide sample data.
+      #
+      # @return [Hash{Symbol => Object}]
+      def default_values
+        {
+          string: '"example"',
+          integer: 42,
+          float: 3.14,
+          boolean: true,
+          array: [],
+          hash: {}
+        }
+      end
+
+      # Returns the default config hash passed into templates.
+      #
+      # @return [Hash{Symbol => Object}]
+      def config
+        {
+          name: Castkit::Inflector.underscore(name),
+          class_name: Castkit::Inflector.pascalize(name)
+        }
+      end
+    end
+  end
+end

data/lib/generators/contract.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "thor/group"
+require "castkit/inflector"
+require_relative "base"
+
+module Castkit
+  module Generators
+    # Generator for creating Castkit contracts.
+    #
+    # Generates a contract class and optionally a corresponding spec file.
+    # Accepts an optional list of attribute definitions in the form `name:type`.
+    #
+    # Example:
+    #   $ castkit generate contract User name:string age:integer
+    #
+    # This will generate:
+    # - lib/castkit/contracts/user.rb
+    # - spec/castkit/contracts/user_spec.rb
+    #
+    # @see Castkit::Generators::Base
+    class Contract < Castkit::Generators::Base
+      component :contract
+
+      argument :fields, type: :array, default: [], desc: "Attribute definitions (e.g., name:string age:integer)"
+
+      private
+
+      # @return [Hash] configuration passed into templates
+      def config
+        super.merge(
+          attributes: parsed_fields,
+          default_values: default_values,
+          invalid_types: invalid_types
+        )
+      end
+
+      # Parses `name:type` fields into attribute definitions.
+      #
+      # @return [Array<Hash{Symbol => Object}>] list of parsed attribute hashes
+      def parsed_fields
+        fields.map do |field|
+          name, type = field.split(":")
+          { name: name, type: (type || "string").to_sym }
+        end
+      end
+
+      # Default "invalid" test values for each supported type.
+      #
+      # Used in generated specs to simulate bad input.
+      #
+      # @return [Hash{Symbol => Object}]
+      def invalid_types
+        {
+          string: true,
+          integer: '"invalid"',
+          float: '"bad"',
+          boolean: '"not_a_bool"',
+          date: 123,
+          datetime: [],
+          array: {},
+          hash: [],
+          uuid: 999
+        }
+      end
+    end
+  end
+end