konstruo 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99a8367fd1ff2d8dd01183376df49a1209708ef0df033e2d7033294f1a1991d5
-  data.tar.gz: 6b94c45951ad489563412dff3d1e626434d8da373f11a07f56e48ad7cec935bd
+  metadata.gz: 54c20c9b4279be4b434685e57738654da55fbb75fe21e5bc8d4286bdd292aaf4
+  data.tar.gz: e924f4facbf95273bc16585e994c455877d28723763c05ce223e38e05a451ece
 SHA512:
-  metadata.gz: 4390eb0a4b2cacdad3b73e3f8bfdd31e37685d903bd665c816e69e58d7d2a560975a7304f5768e9fac10b2a939227aebe67ceb85c4d7c337e69aedae7094ccc8
-  data.tar.gz: dd22e4f912cb0edeaa9f9854ab6d1bbc8695164fe4ed4516a9a7ea3dc06b15e28d79ce86ac4e9cb5160a08fc68099ce31a4555b003eab6b91d958eb775e1ed1a
+  metadata.gz: c04a03b2187dc910e08e38fa4a27619d9b0d935a7fb518af14061c8780773c768b3dc435194c3aa14abc60ff94afca2bcdc448e25c2ae14bf0d0fcf052fe484d
+  data.tar.gz: 0f03affbf375f28e6fdaa2b7b17638df508cdd7d384631130677ba2e6de57e8b49fd81be59c476974d236391974f40956ea5498386ab0ea16d25ab1a9026ded6

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.0.3](https://github.com/DashBrains/konstruo/compare/v1.0.2...v1.0.3) (2026-04-01)
+
+
+### Features
+
+* add nilable field ([c3422ea](https://github.com/DashBrains/konstruo/commit/c3422ea68611223f77bfcdee2b6497a302bfc975))
+
+
+### Miscellaneous Chores
+
+* **release:** 1.0.3 ([86ae552](https://github.com/DashBrains/konstruo/commit/86ae552f0aff66bbdbdda20a06e549f5e38bff51))
+
 ## [1.0.2](https://github.com/DashBrains/konstruo/compare/v1.0.1...v1.0.2) (2026-03-31)
 
 

data/README.md

@@ -96,7 +96,7 @@ payload.name       # => "Jane"
 Field API:
 
 ```ruby
-field(name, type, required: false, custom_name: nil, mapper: nil, error_message: nil)
+field(name, type, required: false, nullable: nil, custom_name: nil, mapper: nil, error_message: nil)
 ```
 
 Options:
@@ -104,6 +104,7 @@ Options:
 - `name` (`Symbol`): Ruby attribute name.
 - `type` (`Class` or `[Class]`): Expected value type.
 - `required` (`Boolean`): Raises `Konstruo::ValidationError` when missing.
+- `nullable` (`Boolean`, optional): Controls whether a present key can have `nil` value.
 - `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.
@@ -118,6 +119,11 @@ Supported type patterns:
 
 Array type declarations must contain exactly one element class (for example `[String]`).
 
+`nullable` default behavior:
+
+- If `required: true` and `nullable` is omitted, `nullable` defaults to `false`.
+- If `required: false` and `nullable` is omitted, `nullable` defaults to `true`.
+
 ## Parsing Input
 
 Konstruo supports three entry points:
@@ -158,6 +164,17 @@ Default message format:
 Missing required field: field_name
 ```
 
+### Nullability
+
+When a key is present with `nil` value:
+
+- `nullable: true` allows it.
+- `nullable: false` raises:
+
+```text
+Field cannot be nil: field_name
+```
+
 ### Type errors
 
 Type mismatches raise `Konstruo::ValidationError` with details like:

data/lib/konstruo/mapper.rb

@@ -16,6 +16,7 @@ module Konstruo
       const :name, Symbol
       const :type, FieldType
       const :required, T::Boolean
+      const :nullable, 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)
@@ -52,20 +53,23 @@ module Konstruo
           name:          Symbol,
           type:          FieldType,
           required:      T::Boolean,
+          nullable:      T.nilable(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)
+      def field(name, type, required: false, nullable: nil, custom_name: nil, mapper: nil, error_message: nil)
         attr_accessor name unless method_defined?(name)
 
         validate_field_type!(type)
+        resolved_nullable = nullable.nil? ? !required : nullable
 
         fields << FieldDefinition.new(
           name:          name,
           type:          type,
           required:      required,
+          nullable:      resolved_nullable,
           custom_name:   custom_name || name.to_s,
           mapper:        mapper,
           error_message: error_message
@@ -146,7 +150,9 @@ module Konstruo
         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 || "Field cannot be nil: #{key}") unless field.nullable
+
+          send(:"#{field.name}=", nil)
         else
           assign_value(field.name, field.type, value, field.mapper, field.error_message)
         end

data/lib/konstruo/version.rb

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

data/lib/tapioca/dsl/compilers/konstruo_mapper.rb

@@ -34,7 +34,7 @@ module Tapioca
           root.create_path(constant) do |klass|
             constant.fields.each do |field|
               field_type = as_type_string(field.type)
-              accessor_type = field.required ? field_type : "T.nilable(#{field_type})"
+              accessor_type = (field.required && !field.nullable) ? field_type : "T.nilable(#{field_type})"
               field_name = field.name.to_s
 
               klass.create_method(field_name, return_type: accessor_type)

data/sorbet/rbi/dsl/nullable_mapper.rbi

@@ -0,0 +1,38 @@
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This is an autogenerated file for dynamic methods in `NullableMapper`.
+# Please instead update this file by running `bin/tapioca dsl NullableMapper`.
+
+
+class NullableMapper
+  sig { returns(T.nilable(String)) }
+  def optional_non_nullable; end
+
+  sig { params(value: T.nilable(String)).returns(T.nilable(String)) }
+  def optional_non_nullable=(value); end
+
+  sig { returns(T.nilable(String)) }
+  def optional_nullable_default; end
+
+  sig { params(value: T.nilable(String)).returns(T.nilable(String)) }
+  def optional_nullable_default=(value); end
+
+  sig { returns(String) }
+  def required_non_nullable; end
+
+  sig { params(value: String).returns(String) }
+  def required_non_nullable=(value); end
+
+  sig { returns(String) }
+  def required_non_nullable_default; end
+
+  sig { params(value: String).returns(String) }
+  def required_non_nullable_default=(value); end
+
+  sig { returns(T.nilable(String)) }
+  def required_nullable; end
+
+  sig { params(value: T.nilable(String)).returns(T.nilable(String)) }
+  def required_nullable=(value); end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: konstruo
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - DashBrains
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -90,6 +90,7 @@ files:
 - sorbet/rbi/dsl/inheritance_child_mapper.rbi
 - sorbet/rbi/dsl/invalid_field_definition_mapper.rbi
 - sorbet/rbi/dsl/loose_person_mapper.rbi
+- sorbet/rbi/dsl/nullable_mapper.rbi
 - sorbet/rbi/dsl/person.rbi
 - sorbet/rbi/dsl/strict_person_mapper.rbi
 - sorbet/rbi/gems/.gitattributes