konstruo 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cccc52dd5a0bb45d72f6803a221630cbc719379df63340ae8370de323b5b505
-  data.tar.gz: 4685e92abbe8ac2a12ab7061bd2d4729d59268b50b7f8d11c1e4ffe9758537f6
+  metadata.gz: 99a8367fd1ff2d8dd01183376df49a1209708ef0df033e2d7033294f1a1991d5
+  data.tar.gz: 6b94c45951ad489563412dff3d1e626434d8da373f11a07f56e48ad7cec935bd
 SHA512:
-  metadata.gz: a250f9b1ee78620f4baac110fd5bd8c7a788a24c5994b7d4b15adfd9c0e2a38069208a6273bac05a933d7e8af91ae23eecaae36bda9f2af2523842eddafd6fd0
-  data.tar.gz: 25f74a3f3d3e2c9154e966ca75e92ec3a89f3428b1a3c9287829fe279891147cc1fe912404e25ddd2d7eb6a4aac1362258dfda4dbf2a376c4847627339d86ec6
+  metadata.gz: 4390eb0a4b2cacdad3b73e3f8bfdd31e37685d903bd665c816e69e58d7d2a560975a7304f5768e9fac10b2a939227aebe67ceb85c4d7c337e69aedae7094ccc8
+  data.tar.gz: dd22e4f912cb0edeaa9f9854ab6d1bbc8695164fe4ed4516a9a7ea3dc06b15e28d79ce86ac4e9cb5160a08fc68099ce31a4555b003eab6b91d958eb775e1ed1a

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.0.2](https://github.com/DashBrains/konstruo/compare/v1.0.1...v1.0.2) (2026-03-31)
+
+
+### Features
+
+* dependencies upgrade ([99cf328](https://github.com/DashBrains/konstruo/commit/99cf328777114dbdec699f0855f1028a1cf65c5a))
+* harden mapper validation ([c79db34](https://github.com/DashBrains/konstruo/commit/c79db343a1aeebb7566ca24b23760a0d71fd8808))
+* improve parsing and logic ([6ee7acd](https://github.com/DashBrains/konstruo/commit/6ee7acd6556203e21cadb0a0773319fd5429bc9a))
+
+
+### Miscellaneous Chores
+
+* **release:** force version bump ([7380066](https://github.com/DashBrains/konstruo/commit/7380066927747bef07ea2e557155c5e89e35ff93))
+* **release:** force version bump ([41378dc](https://github.com/DashBrains/konstruo/commit/41378dcf047cb5621d685e6764a7d617e547a7f5))
+
 ## [1.0.1](https://github.com/DashBrains/konstruo/compare/v1.0.0...v1.0.1) (2024-09-07)
 
 

data/README.md

@@ -1,35 +1,254 @@
 # Konstruo
 
-TODO: Delete this and the text below, and describe your gem
+Konstruo maps JSON, hashes, and Rails params into typed Ruby objects with:
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/konstruo`. To experiment with that code, run `bin/console` for an interactive prompt.
+- Required field validation
+- Runtime type checks
+- Custom key mapping (for example `userId` -> `user_id`)
+- Value transformation hooks (mappers)
+- Nested object support (including arrays of nested objects)
+- Inherited field definitions for mapper subclasses
+- Optional strict mode to reject unknown input keys
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add to your `Gemfile`:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem 'konstruo'
+```
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+Then install:
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+```bash
+bundle install
+```
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+Or install directly:
 
-## Usage
+```bash
+gem install konstruo
+```
 
-TODO: Write usage instructions here
+## Quick Start
+
+```ruby
+require 'konstruo'
+
+class Address < Konstruo::Mapper
+  field :street, String, required: true
+  field :city, String, required: true
+end
+
+class Person < Konstruo::Mapper
+  field :name, String, required: true
+  field :age, Integer
+  field :is_active, Konstruo::Boolean, required: true
+  field :address, Address, required: true
+  field :tags, [String]
+
+  # Map external keys to ruby-style attribute names
+  field :user_id, Integer, required: true, custom_name: 'userId'
+
+  # Transform value before type validation/assignment
+  field :signup_date, Date, custom_name: 'signupDate', mapper: ->(v) { Date.parse(v) }
+end
+
+json = <<~JSON
+  {
+    "name": "John Doe",
+    "age": 30,
+    "is_active": true,
+    "address": { "street": "123 Main St", "city": "New York" },
+    "tags": ["ruby", "rails"],
+    "userId": 42,
+    "signupDate": "2023-08-31"
+  }
+JSON
+
+person = Person.from_json(json)
+person.name         # => "John Doe"
+person.user_id      # => 42
+person.signup_date  # => #<Date: 2023-08-31 ...>
+person.address.city # => "New York"
+```
+
+## Inheritance
+
+Mapper fields are inherited by subclasses:
+
+```ruby
+class BasePayload < Konstruo::Mapper
+  field :request_id, String, required: true, custom_name: 'requestId'
+end
+
+class CreateUserPayload < BasePayload
+  field :name, String, required: true
+end
+
+payload = CreateUserPayload.from_hash(requestId: 'abc-123', name: 'Jane')
+payload.request_id # => "abc-123"
+payload.name       # => "Jane"
+```
+
+## Defining Fields
+
+Field API:
+
+```ruby
+field(name, type, required: false, custom_name: nil, mapper: nil, error_message: nil)
+```
+
+Options:
+
+- `name` (`Symbol`): Ruby attribute name.
+- `type` (`Class` or `[Class]`): Expected value type.
+- `required` (`Boolean`): Raises `Konstruo::ValidationError` when missing.
+- `custom_name` (`String`): External key name to read from input.
+- `mapper` (`Proc`): Converts raw input value before assignment.
+- `error_message` (`String`): Custom validation error message.
+
+Supported type patterns:
+
+- Primitive/class values: `String`, `Integer`, `Date`, etc.
+- Boolean: `Konstruo::Boolean`
+- Nested mapper: any subclass of `Konstruo::Mapper`
+- Array of primitives: `[String]`, `[Integer]`, etc.
+- Array of nested mappers: `[Address]`
+
+Array type declarations must contain exactly one element class (for example `[String]`).
+
+## Parsing Input
+
+Konstruo supports three entry points:
+
+- `YourMapper.from_json(json_string)`
+- `YourMapper.from_hash(hash)`
+- `YourMapper.from_params(action_controller_params)`
+
+All return an instance of your mapper class.
+
+Notes:
+
+- `from_hash` accepts string or symbol keys.
+- `from_json` expects a JSON object at the root and raises `Konstruo::ValidationError` otherwise.
+
+```ruby
+person = Person.from_hash(
+  name: 'Jane',
+  is_active: true,
+  address: { street: '42 Broadway', city: 'NYC' },
+  userId: 7
+)
+```
+
+## Validation Behavior
+
+### Required fields
+
+Missing required fields raise:
+
+```ruby
+Konstruo::ValidationError
+```
+
+Default message format:
+
+```text
+Missing required field: field_name
+```
+
+### Type errors
+
+Type mismatches raise `Konstruo::ValidationError` with details like:
+
+```text
+Expected Integer for field: age, got String
+Expected String for field: friends[0], got Integer
+Expected Boolean for field: is_active, got String
+```
+
+`Konstruo::Boolean` only accepts real booleans (`true` or `false`).
+
+### Nested error paths
+
+Errors coming from nested mappers are prefixed with their full path:
+
+```text
+address: Street is required.
+addresses[0]: Street is required.
+Missing required field: address.city
+```
+
+### Strict unknown key mode
+
+Enable strict mode in a mapper to reject keys that are not declared with `field`:
+
+```ruby
+class StrictPerson < Konstruo::Mapper
+  strict_unknown_keys
+  field :name, String, required: true
+end
+
+StrictPerson.from_hash(name: 'Jane', extra: 'value')
+# => raises Konstruo::ValidationError: Unknown fields: extra
+```
+
+By default, unknown keys are ignored.  
+Strict mode is inherited by subclasses.  
+You can explicitly disable it with `strict_unknown_keys(false)`.
+
+### Custom mappers
+
+Mapper lambdas are executed as provided. If they raise (for example `Date.parse`), that error bubbles up.
+
+### Custom error messages
+
+`error_message:` is used for both missing required fields and type errors on that field.
+
+## Sorbet Integration
+
+`field` is defined dynamically at runtime, so static typing for generated accessors comes from Tapioca DSL RBIs.
+
+Konstruo exports a Tapioca DSL compiler from the gem path `tapioca/dsl/compilers`, so consumer apps pick it up automatically when Konstruo is in the bundle.
+
+Run:
+
+```bash
+bundle exec tapioca dsl
+```
+
+The compiler generates typed accessors for mapper fields, so you do not need to manually write repeated `sig + attr_accessor` declarations for each field.
+
+## Rails Params Support
+
+Use `from_params` when parsing `ActionController::Parameters`:
+
+```ruby
+def create
+  person = Person.from_params(params.require(:person).permit!)
+  # ...
+end
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```bash
+bin/setup
+bundle exec rake test
+```
+
+Useful commands:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- `bin/console` for interactive experimentation
+- `bundle exec rake install` to install the gem locally
+- `bundle exec rake release` to tag and publish
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/konstruo.
+Issues and pull requests are welcome:
+https://github.com/DashBrains/konstruo
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT: [LICENSE.txt](LICENSE.txt)

data/Rakefile

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
+require 'rake/testtask'
 
 Dir['tasks/**/*.rake'].each { |t| load t }
 
-RSpec::Core::RakeTask.new(:spec)
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
 
-task default: :spec
+task default: :test

data/lib/konstruo/mapper.rb

@@ -8,91 +8,208 @@ module Konstruo
   class Mapper
     extend T::Sig
 
-    # Class variable to store field definitions
-    @fields = T.let([], T::Array[T::Hash[Symbol, T.untyped]])
+    FieldClass = T.type_alias { T.class_of(Object) }
+    FieldType = T.type_alias { T.any(FieldClass, T::Array[FieldClass]) }
+    InputHash = T.type_alias { T::Hash[T.any(String, Symbol), T.untyped] }
+
+    class FieldDefinition < T::Struct
+      const :name, Symbol
+      const :type, FieldType
+      const :required, T::Boolean
+      const :custom_name, String
+      const :mapper, T.nilable(T.proc.params(value: T.untyped).returns(T.untyped))
+      const :error_message, T.nilable(String)
+    end
 
     class << self
       extend T::Sig
 
-      sig { returns(T::Array[T::Hash[Symbol, T.untyped]]) }
-      attr_reader :fields
-    end
+      sig { returns(T::Array[FieldDefinition]) }
+      def fields
+        existing = T.let(T.unsafe(self).instance_variable_get(:@fields), T.nilable(T::Array[FieldDefinition]))
+        return existing unless existing.nil?
 
-    sig do
-      params(name: Symbol, type: T.any(T.class_of(Object), T::Array[T.class_of(Object)]), required: T::Boolean,
-             custom_name: T.nilable(String), mapper: T.nilable(T.proc.params(value: T.untyped).returns(T.untyped)),
-             error_message: T.nilable(String)).void
-    end
-    def self.field(name, type, required: false, custom_name: nil, mapper: nil, error_message: nil)
-      # Check if the attribute is already defined
-      attr_accessor name unless method_defined?(name)
+        initialized = T.let([], T::Array[FieldDefinition])
+        T.unsafe(self).instance_variable_set(:@fields, initialized)
+        initialized
+      end
 
-      @fields ||= [] if @fields.nil?
-      @fields << { name:, type:, required:, custom_name: custom_name || name.to_s, mapper:, error_message: }
-    end
+      sig { returns(T::Array[T.class_of(::Konstruo::Mapper)]) }
+      def descendants
+        existing = T.let(
+          T.unsafe(self).instance_variable_get(:@descendants),
+          T.nilable(T::Array[T.class_of(::Konstruo::Mapper)])
+        )
+        return existing unless existing.nil?
 
-    sig { params(json_string: String).returns(T.attached_class) }
-    def self.from_json(json_string)
-      hash = JSON.parse(json_string)
-      new.from_hash(hash)
-    end
+        initialized = T.let([], T::Array[T.class_of(::Konstruo::Mapper)])
+        T.unsafe(self).instance_variable_set(:@descendants, initialized)
+        initialized
+      end
 
-    sig { params(params: ActionController::Parameters).returns(T.attached_class) }
-    def self.from_params(params)
-      hash = params.to_unsafe_h
-      new.from_hash(hash)
-    end
+      sig do
+        params(
+          name:          Symbol,
+          type:          FieldType,
+          required:      T::Boolean,
+          custom_name:   T.nilable(String),
+          mapper:        T.nilable(T.proc.params(value: T.untyped).returns(T.untyped)),
+          error_message: T.nilable(String)
+        ).void
+      end
+      def field(name, type, required: false, custom_name: nil, mapper: nil, error_message: nil)
+        attr_accessor name unless method_defined?(name)
+
+        validate_field_type!(type)
+
+        fields << FieldDefinition.new(
+          name:          name,
+          type:          type,
+          required:      required,
+          custom_name:   custom_name || name.to_s,
+          mapper:        mapper,
+          error_message: error_message
+        )
+      end
+
+      sig { params(value: T::Boolean).void }
+      def strict_unknown_keys(value = true)
+        T.unsafe(self).instance_variable_set(:@strict_unknown_keys, value)
+      end
+
+      sig { returns(T::Boolean) }
+      def strict_unknown_keys?
+        value = T.let(T.unsafe(self).instance_variable_get(:@strict_unknown_keys), T.nilable(T::Boolean))
+        value == true
+      end
+
+      sig { params(subclass: T.class_of(Konstruo::Mapper)).void }
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@fields, fields.dup)
+        subclass.instance_variable_set(:@strict_unknown_keys, strict_unknown_keys?)
+        ::Konstruo::Mapper.send(:register_descendant, subclass)
+      end
+
+      sig { params(json_string: String).returns(T.attached_class) }
+      def from_json(json_string)
+        parsed = JSON.parse(json_string)
+        raise Konstruo::ValidationError, 'Expected JSON object at root' unless parsed.is_a?(Hash)
+
+        new.from_hash(parsed)
+      end
+
+      sig { params(params: ActionController::Parameters).returns(T.attached_class) }
+      def from_params(params)
+        new.from_hash(params.to_unsafe_h)
+      end
+
+      sig { params(hash: InputHash).returns(T.attached_class) }
+      def from_hash(hash)
+        new.from_hash(hash)
+      end
+
+      private
 
-    sig { params(hash: T::Hash[Symbol, T.untyped]).returns(T.attached_class) }
-    def self.from_hash(hash)
-      new.from_hash(hash)
+      sig { params(type: FieldType).void }
+      def validate_field_type!(type)
+        return unless type.is_a?(Array)
+        return if type.size == 1 && type.first.is_a?(Class)
+
+        raise ArgumentError, 'Array field type must contain exactly one class'
+      end
+
+      sig { params(subclass: T.class_of(::Konstruo::Mapper)).void }
+      def register_descendant(subclass)
+        root = ::Konstruo::Mapper
+        list = root.descendants
+        list << subclass unless list.include?(subclass)
+      end
     end
 
-    sig { params(hash: T::Hash[Symbol, T.untyped]).returns(T.self_type) }
+    sig { params(hash: InputHash).returns(T.self_type) }
     def from_hash(hash)
+      validate_unknown_keys!(hash) if self.class.strict_unknown_keys?
+
       self.class.fields.each do |field|
-        key = field[:custom_name]
-        value = hash[key.to_s] || hash[key.to_sym]
+        key = field.custom_name
+        symbol_key = key.to_sym
+        has_string_key = hash.key?(key)
+        has_symbol_key = hash.key?(symbol_key)
+
+        unless has_string_key || has_symbol_key
+          raise Konstruo::ValidationError, (field.error_message || "Missing required field: #{key}") if field.required
+
+          next
+        end
+
+        value = has_string_key ? hash[key] : hash[symbol_key]
 
         if value.nil?
-          raise Konstruo::ValidationError, (field[:error_message] || "Missing required field: #{key}") if field[:required]
+          raise Konstruo::ValidationError, (field.error_message || "Missing required field: #{key}") if field.required
         else
-          assign_value(field[:name], field[:type], value, field[:mapper], field[:error_message])
+          assign_value(field.name, field.type, value, field.mapper, field.error_message)
         end
       end
+
       self
     end
 
     private
 
+    sig { params(hash: InputHash).void }
+    def validate_unknown_keys!(hash)
+      allowed_keys = Set.new(self.class.fields.map(&:custom_name))
+      unknown_keys = hash.keys.map(&:to_s).reject { |key| allowed_keys.include?(key) }.uniq.sort
+      return if unknown_keys.empty?
+
+      raise Konstruo::ValidationError, "Unknown fields: #{unknown_keys.join(", ")}"
+    end
+
     sig do
-      params(field_name: Symbol, field_type: T.any(T.class_of(Object), T::Array[T.class_of(Object)]), value: T.untyped, mapper: T.nilable(T.proc.params(value: T.untyped).returns(T.untyped)),
-             error_message: T.nilable(String)).void
+      params(
+        field_name:    Symbol,
+        field_type:    FieldType,
+        value:         T.untyped,
+        mapper:        T.nilable(T.proc.params(value: T.untyped).returns(T.untyped)),
+        error_message: T.nilable(String)
+      ).void
     end
     def assign_value(field_name, field_type, value, mapper = nil, error_message = nil)
       value = mapper.call(value) if mapper
 
       if field_type.is_a?(Array)
-        # Check if the value is an array
         raise Konstruo::ValidationError, (error_message || "Expected Array for field: #{field_name}, got #{value.class}") unless value.is_a?(Array)
 
-        # Validate each element in the array
-        element_type = field_type.first
+        element_type = T.must(field_type.first)
 
         validated_array = value.map.with_index do |element, index|
-          if T.must(element_type) < Konstruo::Mapper
-            # If it's a nested AutoMapper object, recursively map it
-            T.cast(element_type, T.class_of(Konstruo::Mapper)).new.from_hash(element)
+          if element_type < Konstruo::Mapper
+            unless element.is_a?(Hash)
+              raise Konstruo::ValidationError, (error_message || "Expected Hash for field: #{field_name}[#{index}], got #{element.class}")
+            end
+
+            begin
+              element_type.new.from_hash(element)
+            rescue Konstruo::ValidationError => e
+              raise Konstruo::ValidationError, prefix_nested_error(e.message, "#{field_name}[#{index}]")
+            end
           else
-            # Validate individual element types
-            validate_type!(element, T.must(element_type), "#{field_name}[#{index}]", error_message)
+            validate_type!(element, element_type, "#{field_name}[#{index}]", error_message)
             element
           end
         end
 
         send(:"#{field_name}=", validated_array)
       elsif field_type < Konstruo::Mapper
-        send(:"#{field_name}=", field_type.new.from_hash(value))
+        raise Konstruo::ValidationError, (error_message || "Expected Hash for field: #{field_name}, got #{value.class}") unless value.is_a?(Hash)
+
+        mapped_value = begin
+          field_type.new.from_hash(value)
+        rescue Konstruo::ValidationError => e
+          raise Konstruo::ValidationError, prefix_nested_error(e.message, field_name.to_s)
+        end
+        send(:"#{field_name}=", mapped_value)
       else
         validate_type!(value, field_type, field_name, error_message)
         send(:"#{field_name}=", value)
@@ -102,19 +219,39 @@ module Konstruo
     sig do
       params(
         value:         T.untyped,
-        expected_type: T.any(T.class_of(Object), T::Array[T.class_of(Object)]),
+        expected_type: FieldClass,
         field_name:    T.any(Symbol, String),
         error_message: T.nilable(String)
       ).void
     end
     def validate_type!(value, expected_type, field_name, error_message = nil)
-      # Custom handling for Boolean type
       if expected_type == Konstruo::Boolean
-        raise Konstruo::ValidationError, (error_message || "Expected Boolean for field: #{field_name}, got #{value.class}") unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        unless Konstruo::Boolean.boolean?(value)
+          raise Konstruo::ValidationError, (error_message || "Expected Boolean for field: #{field_name}, got #{value.class}")
+        end
       else
-        # Fallback to is_a? for runtime type checking if Sorbet is not available
-        raise Konstruo::ValidationError, (error_message || "Expected #{expected_type} for field: #{field_name}, got #{value.class}") unless value.is_a?(expected_type)
+        unless value.is_a?(expected_type)
+          raise Konstruo::ValidationError, (error_message || "Expected #{expected_type} for field: #{field_name}, got #{value.class}")
+        end
+      end
+    end
+
+    sig { params(message: String, prefix: String).returns(String) }
+    def prefix_nested_error(message, prefix)
+      missing_field_match = message.match(/\AMissing required field: (.+)\z/)
+      if missing_field_match
+        return "Missing required field: #{prefix}.#{T.must(missing_field_match[1])}"
       end
+
+      type_error_match = message.match(/\AExpected (.+) for field: (.+), got (.+)\z/)
+      if type_error_match
+        expected = T.must(type_error_match[1])
+        field_path = T.must(type_error_match[2])
+        actual = T.must(type_error_match[3])
+        return "Expected #{expected} for field: #{prefix}.#{field_path}, got #{actual}"
+      end
+
+      "#{prefix}: #{message}"
     end
   end
 end

data/lib/konstruo/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Konstruo
-  VERSION = '1.0.1'
+  VERSION = '1.0.2'
 end

data/lib/konstruo.rb

@@ -11,7 +11,7 @@ module Konstruo
   class Boolean
     extend T::Sig
 
-    sig { params(value: T.untyped).returns(Boolean) }
+    sig { params(value: T.untyped).returns(T::Boolean) }
     def self.boolean?(value)
       value.is_a?(TrueClass) || value.is_a?(FalseClass)
     end