castkit 0.1.2 → 0.3.0

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: castkit
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Nathan Lucas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-14 00:00:00.000000000 Z
+date: 2025-04-17 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -72,27 +86,72 @@ files:
 - castkit.gemspec
 - lib/castkit.rb
 - lib/castkit/attribute.rb
-- lib/castkit/attribute_extensions/access.rb
-- lib/castkit/attribute_extensions/casting.rb
-- lib/castkit/attribute_extensions/error_handling.rb
-- lib/castkit/attribute_extensions/options.rb
-- lib/castkit/attribute_extensions/serialization.rb
-- lib/castkit/attribute_extensions/validation.rb
 - lib/castkit/castkit.rb
+- lib/castkit/cli.rb
+- lib/castkit/cli/generate.rb
+- lib/castkit/cli/list.rb
+- lib/castkit/cli/main.rb
 - lib/castkit/configuration.rb
+- lib/castkit/contract.rb
+- lib/castkit/contract/base.rb
+- lib/castkit/contract/data_object.rb
+- lib/castkit/contract/result.rb
+- lib/castkit/contract/validator.rb
+- lib/castkit/core/attribute_types.rb
+- lib/castkit/core/attributes.rb
+- lib/castkit/core/config.rb
+- lib/castkit/core/registerable.rb
 - lib/castkit/data_object.rb
-- lib/castkit/data_object_extensions/attribute_types.rb
-- lib/castkit/data_object_extensions/attributes.rb
-- lib/castkit/data_object_extensions/config.rb
-- lib/castkit/data_object_extensions/deserialization.rb
-- lib/castkit/default_serializer.rb
 - lib/castkit/error.rb
-- lib/castkit/serializer.rb
+- lib/castkit/ext/attribute/access.rb
+- lib/castkit/ext/attribute/error_handling.rb
+- lib/castkit/ext/attribute/options.rb
+- lib/castkit/ext/attribute/validation.rb
+- lib/castkit/ext/data_object/contract.rb
+- lib/castkit/ext/data_object/deserialization.rb
+- lib/castkit/ext/data_object/plugins.rb
+- lib/castkit/ext/data_object/serialization.rb
+- lib/castkit/inflector.rb
+- lib/castkit/plugins.rb
+- lib/castkit/serializers/base.rb
+- lib/castkit/serializers/default_serializer.rb
+- lib/castkit/types.rb
+- lib/castkit/types/base.rb
+- lib/castkit/types/boolean.rb
+- lib/castkit/types/collection.rb
+- lib/castkit/types/date.rb
+- lib/castkit/types/date_time.rb
+- lib/castkit/types/float.rb
+- lib/castkit/types/integer.rb
+- lib/castkit/types/string.rb
 - lib/castkit/validator.rb
-- lib/castkit/validators.rb
+- lib/castkit/validators/base.rb
+- lib/castkit/validators/boolean_validator.rb
+- lib/castkit/validators/collection_validator.rb
+- lib/castkit/validators/float_validator.rb
+- lib/castkit/validators/integer_validator.rb
 - lib/castkit/validators/numeric_validator.rb
 - lib/castkit/validators/string_validator.rb
 - lib/castkit/version.rb
+- lib/generators/base.rb
+- lib/generators/contract.rb
+- lib/generators/data_object.rb
+- lib/generators/plugin.rb
+- lib/generators/serializer.rb
+- lib/generators/templates/contract.rb.tt
+- lib/generators/templates/contract_spec.rb.tt
+- lib/generators/templates/data_object.rb.tt
+- lib/generators/templates/data_object_spec.rb.tt
+- lib/generators/templates/plugin.rb.tt
+- lib/generators/templates/plugin_spec.rb.tt
+- lib/generators/templates/serializer.rb.tt
+- lib/generators/templates/serializer_spec.rb.tt
+- lib/generators/templates/type.rb.tt
+- lib/generators/templates/type_spec.rb.tt
+- lib/generators/templates/validator.rb.tt
+- lib/generators/templates/validator_spec.rb.tt
+- lib/generators/type.rb
+- lib/generators/validator.rb
 - sig/castkit.rbs
 homepage: https://github.com/bnlucas/castkit
 licenses:

data/lib/castkit/attribute_extensions/access.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-module Castkit
-  module AttributeExtensions
-    # Provides access control helpers for attributes.
-    #
-    # These helpers determine whether an attribute is readable, writeable,
-    # or should be included during serialization/deserialization based on the
-    # configured `:access` and `:ignore` options.
-    module Access
-      # Returns the normalized access modes for the attribute (e.g., [:read, :write]).
-      #
-      # @return [Array<Symbol>] list of access symbols
-      def access
-        Array(options[:access]).map(&:to_sym)
-      end
-
-      # Whether the attribute should be included during serialization.
-      #
-      # @return [Boolean]
-      def readable?
-        access.include?(:read)
-      end
-
-      # Whether the attribute should be accepted during deserialization.
-      #
-      # Composite attributes are excluded from writeability.
-      #
-      # @return [Boolean]
-      def writeable?
-        access.include?(:write) && !composite?
-      end
-
-      # Whether the attribute is both readable and writeable.
-      #
-      # @return [Boolean]
-      def full_access?
-        readable? && writeable?
-      end
-
-      # Whether the attribute should be skipped during serialization.
-      #
-      # This is true if it's not readable or is marked as ignored.
-      #
-      # @return [Boolean]
-      def skip_serialization?
-        !readable? || ignore?
-      end
-
-      # Whether the attribute should be skipped during deserialization.
-      #
-      # @return [Boolean]
-      def skip_deserialization?
-        !writeable?
-      end
-
-      # Whether the attribute is ignored completely.
-      #
-      # @return [Boolean]
-      def ignore?
-        options[:ignore]
-      end
-    end
-  end
-end

data/lib/castkit/attribute_extensions/casting.rb

@@ -1,147 +0,0 @@
-# frozen_string_literal: true
-
-require "date"
-require_relative "../data_object"
-require_relative "error_handling"
-
-module Castkit
-  module AttributeExtensions
-    # Provides typecasting logic for attributes based on their declared type.
-    #
-    # Supports primitive types, arrays, nested Castkit::DataObject types, and union types.
-    module Casting
-      include Castkit::AttributeExtensions::ErrorHandling
-
-      PRIMITIVE_CASTERS = {
-        integer: lambda(&:to_i),
-        float: lambda(&:to_f),
-        string: lambda(&:to_s),
-        hash: ->(v) { v },
-        array: ->(v) { Array(v) }
-      }.freeze
-
-      private
-
-      # Casts a value based on the attribute's declared type.
-      #
-      # @param value [Object] the input value to cast
-      # @return [Object, nil] the cast value
-      # @raise [Castkit::AttributeError] if the value cannot be cast
-      def cast(value)
-        handle_error(:array_of_type) if type == :array && options[:of].nil?
-        value = default if value.nil?
-        return if value.nil? && optional?
-
-        cast_value(value)
-      end
-
-      # Delegates casting logic based on the attribute's type.
-      #
-      # This method is invoked internally by `#cast` after nil handling and default fallback.
-      #
-      # - For union types (`Array` of types), attempts each in order.
-      # - For array types, maps over elements with `#cast_element`.
-      # - For nested data objects, delegates to `.cast`.
-      # - For primitive types, uses `#cast_primitive`.
-      #
-      # @param value [Object] the raw input value to cast
-      # @return [Object, nil] the cast value
-      # @raise [Castkit::AttributeError] if casting fails for all union types or invalid primitives
-      def cast_value(value)
-        if type.is_a?(Array)
-          try_union_cast(value)
-        elsif type == :array
-          Array(value).map { |v| cast_element(v) }
-        elsif dataobject?
-          type.cast(value)
-        else
-          cast_primitive(value)
-        end
-      end
-
-      # Attempts to cast the value against a union of possible types.
-      #
-      # @param value [Object]
-      # @return [Object] the first successful cast result
-      # @raise [Castkit::AttributeError] if no types match
-      def try_union_cast(value)
-        last_error = nil
-
-        type.each do |t|
-          return try_cast_type(value, t)
-        rescue Castkit::AttributeError => e
-          last_error = e
-        end
-
-        raise last_error || handle_error(:union, types: type)
-      end
-
-      # Tries to cast a value to a specific type.
-      #
-      # @param value [Object]
-      # @param type [Symbol, Class] the type to try
-      # @return [Object, nil]
-      def try_cast_type(value, type)
-        return type.cast(value) if Castkit.dataobject?(type)
-
-        cast_primitive(value, type: type)
-      end
-
-      # Casts an element of an array attribute.
-      #
-      # @param value [Object]
-      # @return [Object, nil]
-      def cast_element(value)
-        if Castkit.dataobject?(options[:of])
-          options[:of].cast(value)
-        else
-          validate_element_type!(value)
-          cast_primitive(value, type: options[:of])
-        end
-      end
-
-      # Casts a primitive value based on its type.
-      #
-      # @param value [Object]
-      # @param type [Symbol]
-      # @return [Object, nil]
-      # @raise [Castkit::AttributeError]
-      def cast_primitive(value, type: self.type)
-        return cast_boolean(value) if type == :boolean
-        return Date.parse(value.to_s) if type == :date
-        return DateTime.parse(value.to_s) if type == :datetime
-
-        PRIMITIVE_CASTERS.fetch(type) do
-          handle_error(:primitive, type: type)
-        end.call(value)
-      end
-
-      # Casts a value to boolean.
-      #
-      # @param value [Object]
-      # @return [Boolean, nil]
-      # @raise [Castkit::AttributeError]
-      def cast_boolean(value)
-        case value.to_s.downcase
-        when "true", "1"
-          true
-        when "false", "0"
-          false
-        else
-          handle_error(:boolean, value: value)
-        end
-      end
-
-      # Validates element type for arrays, if `enforce_array_of_type` is enabled.
-      #
-      # @param value [Object]
-      # @return [void]
-      def validate_element_type!(value)
-        return unless Castkit.configuration.enforce_array_of_type
-
-        validator = Castkit.configuration.validator_for(options[:of])
-        validator.call(value, options: options, context: "#{field}[]")
-      end
-    end
-  end
-end

data/lib/castkit/attribute_extensions/error_handling.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../castkit"
-
-module Castkit
-  module AttributeExtensions
-    # Provides centralized handling of attribute casting and validation errors.
-    #
-    # The behavior of each error is controlled by configuration flags in `Castkit.configuration`.
-    module ErrorHandling
-      # Maps known error types to their handling behavior.
-      #
-      # Each entry includes:
-      # - `:config` – the config flag that determines enforcement
-      # - `:message` – a lambda that generates an error message
-      # - `:error` – the error class to raise
-      #
-      # @return [Hash<Symbol, Hash>]
-      ERROR_OPTIONS = {
-        array_of_type: {
-          config: :enforce_array_of_type,
-          message: ->(*_) { "`of:` must be provided for array type" },
-          error: Castkit::AttributeError
-        },
-        primitive: {
-          config: :enforce_known_primitive_type,
-          message: ->(_attr, type:) { "unknown primitive type: #{type.inspect}" },
-          error: Castkit::AttributeError
-        },
-        boolean: {
-          config: :enforce_boolean_casting,
-          message: ->(_attr, value:) { "must be a boolean, got: #{value.inspect}" },
-          error: Castkit::AttributeError
-        },
-        union: {
-          config: :enforce_union_match,
-          message: ->(_attr, types:) { "could not be cast to any of #{types.inspect}" },
-          error: Castkit::AttributeError
-        },
-        access: {
-          config: :enforce_attribute_access,
-          message: ->(_attr, mode:) { "invalid access mode `#{mode}`" },
-          error: Castkit::AttributeError
-        },
-        unwrapped: {
-          config: :enforce_unwrapped_prefix,
-          message: ->(*_) { "prefix can only be used with unwrapped attribute" },
-          error: Castkit::AttributeError
-        },
-        array_options: {
-          config: :enforce_array_options,
-          message: ->(*_) { "array attribute must specify `of:` type" },
-          error: Castkit::AttributeError
-        }
-      }.freeze
-
-      private
-
-      # Handles a validation or casting error based on the provided error key and context.
-      #
-      # If the corresponding configuration flag is enabled, an exception is raised.
-      # Otherwise, a warning is logged and the method returns `nil`.
-      #
-      # @param key [Symbol] the type of error (must match a key in ERROR_OPTIONS)
-      # @param kwargs [Hash] additional values passed to the message lambda
-      # @option kwargs [Symbol] :context (optional) the attribute context (e.g., field name)
-      # @return [nil]
-      # @raise [Castkit::AttributeError] if enforcement is enabled for the given error type
-      def handle_error(key, **kwargs)
-        config_key = ERROR_OPTIONS.dig(key, :config)
-        message_fn = ERROR_OPTIONS.dig(key, :message)
-        error_class = ERROR_OPTIONS.dig(key, :error) || Castkit::Error
-
-        context = kwargs.delete(:context)
-        message = message_fn.call(self, **kwargs)
-        raise error_class.new(message, context: context) if Castkit.configuration.public_send(config_key)
-
-        Castkit.warning "[Castkit] #{message}"
-        nil
-      end
-    end
-  end
-end

data/lib/castkit/attribute_extensions/options.rb

@@ -1,131 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../data_object"
-
-module Castkit
-  module AttributeExtensions
-    # Provides access to normalized attribute options and helper predicates.
-    #
-    # These methods support Castkit attribute behavior such as default values,
-    # key mapping, optionality, and structural roles (e.g. composite or unwrapped).
-    module Options
-      # Default options for attributes.
-      #
-      # @return [Hash<Symbol, Object>]
-      DEFAULT_OPTIONS = {
-        required: true,
-        ignore_nil: false,
-        ignore_blank: false,
-        ignore: false,
-        composite: false,
-        unwrapped: false,
-        prefix: nil,
-        access: %i[read write]
-      }.freeze
-
-      # Returns the default value for the attribute.
-      #
-      # If the default is callable, it is invoked.
-      #
-      # @return [Object]
-      def default
-        val = @default
-        val.respond_to?(:call) ? val.call : val
-      end
-
-      # Returns the serialization/deserialization key.
-      #
-      # Falls back to the field name if `:key` is not specified.
-      #
-      # @return [Symbol, String]
-      def key
-        options[:key] || field
-      end
-
-      # Returns the key path for accessing nested keys.
-      #
-      # Optionally includes alias key paths if `with_aliases` is true.
-      #
-      # @param with_aliases [Boolean]
-      # @return [Array<Array<Symbol>>] nested key paths
-      def key_path(with_aliases: false)
-        path = key.to_s.split(".").map(&:to_sym) || []
-        return path unless with_aliases
-
-        [path] + alias_paths
-      end
-
-      # Returns all alias key paths as arrays of symbols.
-      #
-      # @return [Array<Array<Symbol>>]
-      def alias_paths
-        options[:aliases].map { |a| a.to_s.split(".").map(&:to_sym) }
-      end
-
-      # Whether the attribute is required for object construction.
-      #
-      # @return [Boolean]
-      def required?
-        options[:required]
-      end
-
-      # Whether the attribute is optional.
-      #
-      # @return [Boolean]
-      def optional?
-        !required?
-      end
-
-      # Whether to ignore `nil` values during serialization.
-      #
-      # @return [Boolean]
-      def ignore_nil?
-        options[:ignore_nil]
-      end
-
-      # Whether to ignore blank values (`[]`, `{}`, empty strings) during serialization.
-      #
-      # @return [Boolean]
-      def ignore_blank?
-        options[:ignore_blank]
-      end
-
-      # Whether the attribute is a nested Castkit::DataObject.
-      #
-      # @return [Boolean]
-      def dataobject?
-        Castkit.dataobject?(type)
-      end
-
-      # Whether the attribute is a collection of Castkit::DataObjects.
-      #
-      # @return [Boolean]
-      def dataobject_collection?
-        type == :array && Castkit.dataobject?(options[:of])
-      end
-
-      # Whether the attribute is considered composite (not exposed in serialized output).
-      #
-      # @return [Boolean]
-      def composite?
-        options[:composite]
-      end
-
-      # Whether the attribute is unwrapped into the parent object.
-      #
-      # Only applies to Castkit::DataObject types.
-      #
-      # @return [Boolean]
-      def unwrapped?
-        dataobject? && options[:unwrapped]
-      end
-
-      # Returns the prefix used for unwrapped attributes.
-      #
-      # @return [String, nil]
-      def prefix
-        options[:prefix]
-      end
-    end
-  end
-end

data/lib/castkit/attribute_extensions/serialization.rb

@@ -1,89 +0,0 @@
-# frozen_string_literal: true
-
-module Castkit
-  module AttributeExtensions
-    # Handles serialization (`dump`) and deserialization (`load`) of attribute values.
-    #
-    # Supports primitive types, arrays, and nested Castkit::DataObject instances.
-    module Serialization
-      # Serializes a value into a format suitable for output (e.g., JSON or Hash).
-      #
-      # If the value is a Castkit::DataObject, a custom serializer is used if configured.
-      #
-      # @param value [Object, nil] the value to serialize
-      # @param visited [Set, nil] used for circular reference detection
-      # @return [Object, nil] the serialized value
-      def dump(value, visited: nil)
-        return value if value.nil?
-
-        if type == :array
-          Array(value).map { |val| dump_element(val, visited: visited) }
-        else
-          dump_element(value, visited: visited)
-        end
-      end
-
-      # Deserializes and validates a value during object instantiation.
-      #
-      # Applies default value, casts, and runs validators.
-      #
-      # @param value [Object] the input value
-      # @param context [Symbol] the attribute name or context key
-      # @return [Object] the deserialized and validated value
-      # @raise [Castkit::AttributeError] if value is required but missing
-      def load(value, context:)
-        value = default if value.nil?
-        return raise_error!("#{field} is required for instantiation") if value.nil? && required?
-
-        value = cast(value)
-        validate_value!(value, context: context)
-
-        value
-      end
-
-      private
-
-      # Serializes a single element value.
-      #
-      # - Uses a serializer if the value is a Castkit::DataObject.
-      # - Converts `to_h` if the value is hash-like.
-      #
-      # @param value [Object, nil] the element to dump
-      # @param visited [Set, nil]
-      # @return [Object, nil]
-      def dump_element(value, visited: nil)
-        return value if value.nil? || primitive?(value)
-
-        if value.is_a?(Castkit::DataObject)
-          serializer = options[:serializer] || value.class.serializer || Castkit::DefaultSerializer
-          serializer.call(value, visited: visited)
-        elsif hashable?(value)
-          value.to_h(visited)
-        else
-          value
-        end
-      end
-
-      # Checks whether a value is a hashable object suitable for `to_h` dumping.
-      #
-      # @param value [Object, nil]
-      # @return [Boolean]
-      def hashable?(value)
-        value.respond_to?(:to_h) && !primitive?(value) && !value.is_a?(Castkit::Attribute)
-      end
-
-      # Determines if a value is a primitive type.
-      #
-      # @param value [Object, nil]
-      # @return [Boolean]
-      def primitive?(value)
-        case value
-        when String, Symbol, Numeric, TrueClass, FalseClass, NilClass, Hash, Array
-          true
-        else
-          false
-        end
-      end
-    end
-  end
-end

data/lib/castkit/attribute_extensions/validation.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "error_handling"
-require_relative "options"
-
-module Castkit
-  module AttributeExtensions
-    # Provides validation logic for attribute configuration.
-    #
-    # These checks are typically performed at attribute initialization to catch misconfigurations early.
-    module Validation
-      include Castkit::AttributeExtensions::ErrorHandling
-
-      private
-
-      # Runs all validation checks on the attribute definition.
-      #
-      # This includes:
-      # - Custom validator integrity
-      # - Access mode validity
-      # - Unwrapped prefix usage
-      # - Array `of:` type presence
-      #
-      # @return [void]
-      def validate!
-        validate_custom_validator!
-        validate_access!
-        validate_unwrapped_options!
-        validate_array_options!
-      end
-
-      # Validates the presence and interface of a custom validator.
-      #
-      # @return [void]
-      # @raise [Castkit::AttributeError] if the validator is not callable
-      def validate_custom_validator!
-        return unless options[:validator]
-        return if options[:validator].respond_to?(:call)
-
-        raise_error!("Custom validator for `#{field}` must respond to `.call`")
-      end
-
-      # Validates that each declared access mode is valid.
-      #
-      # @return [void]
-      # @raise [Castkit::AttributeError] if any access mode is invalid and enforcement is enabled
-      def validate_access!
-        access.each do |mode|
-          next if Castkit::AttributeExtensions::Options::DEFAULT_OPTIONS[:access].include?(mode)
-
-          handle_error(:access, mode: mode, context: to_h)
-        end
-      end
-
-      # Ensures prefix is only used with unwrapped attributes.
-      #
-      # @return [void]
-      # @raise [Castkit::AttributeError] if prefix is used without `unwrapped: true`
-      def validate_unwrapped_options!
-        handle_error(:unwrapped, context: to_h) if prefix && !unwrapped?
-      end
-
-      # Ensures `of:` is provided for array-typed attributes.
-      #
-      # @return [void]
-      # @raise [Castkit::AttributeError] if `of:` is missing for `type: :array`
-      def validate_array_options!
-        handle_error(:array_options, context: to_h) if type == :array && options[:of].nil?
-      end
-    end
-  end
-end