dynamicschema 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d54fbc1c5dafddb6d0cd08445f1c8d34cf9e3ab56532d606f773a06a5706862
-  data.tar.gz: 3283113491a276388ad171c1364e7a1f71a3bb9ed6ec70efa9cdfe7cc1b11b1d
+  metadata.gz: 96f20951dea52b231f5f4f9c8c5eae91647f2688be56877066a0aafd694c980a
+  data.tar.gz: 7a33def23c8a542d583d6f7b17fb831b564516ae3e3d5700f095eb51356c8b80
 SHA512:
-  metadata.gz: de140ec999832c80332b96c9be76e4a8f6947bb85cc885a879597d480b0c94cad064ddefe1d9ec78dae43ebb385a95c16d21f7272e092e2e20ccb50368261835
-  data.tar.gz: 3f2b50815dfa7687f23c59421fc91bccc1c0b7f4db8cba9aacd54ff1b53e9f7eba1ade96727c7c556d1671166f5fbdf056bc514e83b503dbacb128e7d5773a36
+  metadata.gz: 3d746d4a0fc541475c2aea4bac6d9780d2d044ebe00987b18725f5c300ecaefa3348fd0dd74ca46f58c15c93d758ee5427c3727ecab696da0f6b44e21e4ff26d
+  data.tar.gz: ea6bee74de0c880dba3f6ea44a0f885d0885ef3e845c6d2d07d846dcf40724f625cdb4c599f29386ae67427cf2697c2d968bd7a1ef19c1c0f7b52677eefdafb6

data/README.md

@@ -1,6 +1,6 @@
 # DynamicSchema
 
-The **DynamicSchema** gem provides a elegant and expressive way to define a domain-specific 
+The **DynamicSchema** gem provides an elegant and expressive way to define domain-specific 
 language (DSL) schemas, making it effortless to build and validate complex Ruby `Hash` 
 constructs. 
 
@@ -27,7 +27,7 @@ openai_request_schema = DynamicSchema.define do
 end
 ```
 
-And then repetedly use that schema to elegantly build a schema conformant `Hash`:
+And then repeatedly use that schema to elegantly build a schema-conformant `Hash`:
 ```ruby
 request = openai_request_schema.build {
   message :system do 
@@ -60,6 +60,7 @@ You can find a full OpenAI request example in the `/examples` folder of this rep
 - [Class Schema](#class-schemas)
   - [Definable](#definable) 
   - [Buildable](#buildable) 
+- [Struct](#struct)
 - [Validation Methods](#validation-methods)
   - [Validation Rules](#validation-rules) 
   - [validate!](#validate)
@@ -103,32 +104,191 @@ require 'dynamic_schema'
 
 ### Defining Schemas with **DynamicSchema**
 
-DynamicSchema permits the caller to define a domain specific language (DSL) schema with *values*, 
-*objects* and related *options*. You can use the `DynamicSchema.define` convenience method, or 
-instantiate `DynamicSchema::Builder`, then call it's `define` method, to prepare a builder.
+DynamicSchema lets you define a DSL made of values, objects, and options, then reuse that DSL to 
+build and validate Ruby Hashes.
 
-In all cases the `define` methods require a block where the names of schema components as well as 
-their options are specified. 
+You start by constructing a `DynamicSchema::Builder`. You can do this by calling: 
+- `DynamicSchema.define { … }` 
+- `DynamicSchema::Builder.new.define { … }` 
 
-Once a schema is defined you may repeatedly use the `Builder` instance to 'build' a Hash of values 
-using the DSL you've defined. The builder has a 'build' method which will construct a Hash without 
-validating the values. If you've specified that a value should be of a specific type and an 
-incompatible type was given that type will be in the Hash with no indication of that violation. 
-Alterativelly, you can call the `build!` method which will validate the Hash, raising an exception
-if any of the schema criteria is violated. 
+In both cases, you pass a block that declares the schema values and objects with their options.
 
-Finally, you can use a builder to validate a given Hash against the schema you've defined using 
-the `validate`, `validate!` and `valid?` `Builder` instance methods.
+```ruby
+schema = DynamicSchema.define do
+  # values with an optional default
+  api_key        String
+  model          String,  default: 'gpt-4o'
+
+  # object with its own values
+  chat_options do
+    max_tokens   Integer, default: 1024
+    temperature  Float,   in: 0..1
+  end
+end
+```
+
+You can then:
+
+```ruby
+# build without validation
+built = schema.build do
+  api_key 'secret'
+  chat_options do
+    temperature 0.7
+  end
+end
+
+# build with validation (raises on first error)
+built_validated = schema.build! do
+  api_key 'secret'
+  chat_options do
+    temperature 0.7
+  end
+end
+
+# validate an existing Hash (no building)
+errors = schema.validate( { api_key: 'secret', chat_options: { temperature: 0.7 } } )
+valid  = schema.valid?( { api_key: 'secret', chat_options: { temperature: 0.7 } } )
+```
+
+#### Inheritance
+
+You can extend an existing schema using the `inherit:` option. Pass a Proc that describes 
+the parent schema—typically from a class that includes `DynamicSchema::Definable` via 
+its `schema` method.
+
+```ruby
+class BaseSettings
+  include DynamicSchema::Definable
+  schema do
+    api_key String, required: true
+  end
+end
+
+# extend the base schema with additional fields
+builder = DynamicSchema.define( inherit: BaseSettings.schema ) do
+  region Symbol, in: %i[us eu apac]
+end
+
+settings = builder.build! do
+  api_key 'secret'
+  region  :us
+end
+```
+
+You can call `build`, `build!`, `validate`, `validate!`, and `valid?` on the builder as needed.
+
+---
+
+## Struct
+
+In addition to building plain Ruby `Hash` values, DynamicSchema can generate lightweight
+Ruby classes from a schema. A `DynamicSchema::Struct` exposes readers and writers for the
+fields you define, and transparently wraps nested objects so that you can access them with
+dot-style accessors rather than deep hash indexing.
+
+You create a struct class by passing the same schema shape you would give to a Builder. The
+schema can be provided as:
+
+- a `Proc` that defines the schema
+- a `DynamicSchema::Builder`
+- a compiled `Hash` (advanced)
+
+```ruby
+require 'dynamic_schema'
+
+# simple struct with typed fields
+Person = DynamicSchema::Struct.define do
+  full_name String
+  age       Integer
+end
+
+person = Person.build( full_name: 'Sam Lee', age: '42' )
+person.age          # => 42 (coerced using the same converters as Builder)
+person.full_name = 'Samira Lee'
+person.to_h         # => { full_name: 'Samira Lee', age: 42 }
+
+# nested object with its own accessors
+Company = DynamicSchema::Struct.define do
+  employee do
+    full_name String
+    years_of_service Integer
+  end
+end
+
+acme = Company.build( employee: { full_name: 'Alex', years_of_service: 5 } )
+acme.employee.full_name        # => 'Alex'
+acme.employee.years_of_service # => 5
+
+# array of nested objects
+Order = DynamicSchema::Struct.define do
+  items array: true do
+    name  String
+    price Integer
+  end
+end
+
+order = Order.build( items: [ { name: 'Desk', price: 100 }, { name: 'Chair', price: 50 } ] )
+order.items.map { | i | i.name }   # => [ 'Desk', 'Chair' ]
+
+# referencing another struct class
+OrderItem = DynamicSchema::Struct.define do
+  name     String
+  quantity Integer
+end
+
+OrderCollection = DynamicSchema::Struct.define do
+  order_number String
+  line_items   OrderItem, array: true
+end
+
+collection = OrderCollection.new( {
+  order_number: 'A-100',
+  line_items: [ { name: 'Desk', quantity: 1 }, { name: 'Chair', quantity: 2 } ]
+} )
+collection.line_items[ 0 ].name     # => 'Desk'
+collection.line_items[ 1 ].quantity # => 2
+```
+
+- defining
+  - `DynamicSchema::Struct.define` takes a block that looks exactly like a Builder schema.
+  - Use `array: true` to expose arrays of nested structs.
+  - You may reference another struct class as a value type; arrays of that type expose
+    nested accessors for each element.
+- building
+  - `StructClass.build( attributes )` constructs an instance and (optionally) coerces typed
+    scalar fields using the same converters as the Builder.
+  - `StructClass.build!` additionally validates the instance just like `builder.build!`.
+- accessing
+  - Use standard Ruby readers/writers: `instance.attribute`, `instance.attribute = value`.
+  - `#to_h` returns a deep Hash of the current values (nested structs become hashes).
+
+You can also create a struct class from a builder or a compiled hash if you already have a
+schema elsewhere:
+
+```ruby
+builder = DynamicSchema.define do
+  name String
+end
+
+NameStruct = DynamicSchema::Struct.new( builder )
+NameStruct.build( name: 'Taylor' ).name  # => 'Taylor'
+```
+
+- validation
+  - struct instances include the same validation helpers as hashes built via a builder.
+  - `StructClass.build!` validates immediately and raises on the first error.
+  - instances respond to `#validate!`, `#validate`, and `#valid?` using the compiled schema.
 
 ---
 
 ## Values 
 
-A *value* is the basic building blocks of your schema. Values represent individual settings, 
-options or API paramters that you can define with specific types, defaults, and other options.
+A *value* is a basic building block of your schema. Values represent individual settings,
+options or API parameters that you can define with specific types, defaults, and other options.
 
 When defining a value, you provide the name as though you were calling a Ruby method, with 
-arguments that include an optional type (which can be a `Class`, `Module` or an `Array` of these ) 
+arguments that include an optional type (which can be a `Class`, `Module` or an `Array` of these) 
 as well as a `Hash` of options, all of which are optional: 
 
 `name {type} default: {true|false}, required: {true|false}, array: {true|false}, as: {name}, in: {Array|Range}`
@@ -158,7 +318,7 @@ puts result[:version]     # => "1.0"
   - `api_key` defines a value named `api_key`. Any type can be used to assign the value.
   - `version, String, default: '1.0'` defines a value with a default.
 - building 
-  - `schema.build!` build accepts both a Hash and a block where you can set the values.
+  - `schema.build!` accepts both a Hash and a block where you can set the values.
   - Inside the block, `api_key 'your-api-key'` sets the value of `api_key`.
 - accessing 
   - `result[:api_key]` retrieves the value of `api_key`.
@@ -388,7 +548,7 @@ result = schema.build! do
 end
 ```
 
-### :arguments Option 
+### :arguments Option
 
 The `:arguments` option allows objects to accept arguments when building. Any arguments provided
 must appear when the object is built ( and so are implicitly 'required' ).
@@ -424,7 +584,7 @@ their definition and construction.
 
 ### Definable 
 
-The `Definable` module, when inclued in a class, will add the `schema` and the `builder` class 
+The `Definable` module, when included in a class, will add the `schema` and the `builder` class 
 methods. 
 
 By calling `schema` with a block you can define a schema for that specific class. You may also 
@@ -433,7 +593,7 @@ may be called repeatedly to build up a schema with each call adding to the exist
 ( replacing values and objects of the same name if they appear in subsequent calls ). 
 
 The `schema` method will integrate with a class hierarchy. By including Definable in a base class 
-you can call `schema` to define a schema for that base class and then in subsequent dervied classes
+you can call `schema` to define a schema for that base class and then in subsequent derived classes
 to augment it for those classes. 
 
 The `builder` method will return a memoized builder of the schema defined by calls to the `schema` 
@@ -456,7 +616,7 @@ class DatabaSetting < Setting
     end 
   end 
 
-  def initalize( attributes = {} )
+  def initialize( attributes = {} )
     # validate the attributes 
     self.class.builder.validate!( attributes )
     # retain them for future access 
@@ -468,13 +628,13 @@ end
 
 ### Buildable 
 
-The `Buildable` module can be included in a class, in addition to `Definable` to faciliate 
+The `Buildable` module can be included in a class, in addition to `Definable`, to facilitate 
 building that class using a schema assisted builder pattern. The `Buildable` module adds 
 `build!` and `build` methods to the class which can be used to build that class, with and 
-without validation respectivelly. 
+without validation respectively. 
 
-These methods accept both a hash with attributes that follow the schema, as well as a block 
-that can be used to build the class instance. The attributes and block can be used simultanously. 
+These methods accept both a Hash with attributes that follow the schema, as well as a block 
+that can be used to build the class instance. The attributes and block can be used simultaneously. 
 
 **Important** Note that `Buildable` requires a class method `builder` ( which `Definable` 
 provides ) and an initializer that accepts a `Hash` of attributes.
@@ -488,17 +648,17 @@ class Setting
   end 
 end 
 
-class DatabaSetting < Setting  
+class DatabaseSetting < Setting  
   schema do 
     database do 
-      adapter   Symbol, 
+      adapter   Symbol
       host      String
       port      String 
       name      String 
     end 
   end 
 
-  def initalize( attributes = {} )
+  def initialize( attributes = {} )
     # validate the attributes 
     self.class.builder.validate!( attributes )
     # retain them for the future  
@@ -506,7 +666,7 @@ class DatabaSetting < Setting
   end
 end 
 
-database_settings = DatabaSettings.build! name: 'settings.database' do 
+database_settings = DatabaseSetting.build! name: 'settings.database' do 
   database adapter: :pg do 
     host     "localhost"
     port     "127.0.0.1"
@@ -520,7 +680,7 @@ end
 DynamicSchema provides three different methods for validating Hash structures against your 
 defined schema: `validate!`, `validate`, and `valid?`. 
 
-These methods allow you to verify that your data conforms to your schema's requirements, 
+These methods allow you to verify that your data conforms to your schema requirements, 
 including type constraints, required fields, and value ranges.
 
 ### Validation Rules
@@ -528,13 +688,13 @@ including type constraints, required fields, and value ranges.
 When validating, DynamicSchema checks:
 
 1. **Required Fields**: 
-   Any value or object marked as `required: true` are present.
+   Any value or object marked as `required: true` is present.
 2. **Type Constraints**: 
    Any values match their specified types or can be coerced to the specified type.
 3. **Value Ranges**:
    Any values fall within their specified `:in` constraints.
 4. **Objects**: 
-   Any objects are recursively validates.
+   Any objects are recursively validated.
 5. **Arrays**: 
    Any validation rules are applied to each element when `array: true`
 
@@ -642,7 +802,7 @@ Each error includes helpful context about the validation failure, including the
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at [https://github.com/EndlessInternational/adaptive-schema](https://github.com/EndlessInternational/dynamic-schema).
+Bug reports and pull requests are welcome on GitHub at [https://github.com/EndlessInternational/dynamic_schema](https://github.com/EndlessInternational/dynamic_schema).
 
 ## License
 

data/dynamicschema.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do | spec |
 
   spec.name           = 'dynamicschema'
-  spec.version        = '1.0.0'
+  spec.version        = '2.0.0'
   spec.authors        = [ 'Kristoph Cichocki-Romanov' ]
   spec.email          = [ 'rubygems.org@kristoph.net' ]
 
@@ -19,6 +19,11 @@ Gem::Specification.new do | spec |
     and validations. By allowing default values, type constraints, nested schemas, and 
     transformations, DynamicSchema ensures that your data structures are both robust and 
     flexible.  
+
+    New in 2.0, DynamicSchema adds DynamicSchema::Struct which faciliates effortless definition
+    and construction of complex object hierarchies, with optional type coersion and validation.
+    Where DynamicSchema simplified configuration and API payload construction, 
+    DynamicSchema::Struct simplifies construction of complex API reponses.
   TEXT
 
   spec.license        = 'MIT'

data/lib/dynamic_schema/buildable.rb

@@ -6,15 +6,15 @@ module DynamicSchema
     end
 
     module ClassMethods
+      [ :build, :build_from_bytes, :build_from_file ].each do | name |
+        define_method( name ) do | *args, **kwargs, &block |
+          new( builder.public_send( name, *args, **kwargs, &block ) )
+        end
 
-      def build( attributes = nil, &block )
-        new( builder.build( attributes, &block ) )
-      end 
-
-      def build!( attributes = nil, &block )
-        new( builder.build!( attributes, &block ) )
-      end 
-
+        define_method( :"#{name}!" ) do | *args, **kwargs, &block |
+          new( builder.public_send( :"#{name}!", *args, **kwargs, &block ) )
+        end
+      end
     end 
 
   end

data/lib/dynamic_schema/builder.rb

@@ -1,38 +1,63 @@
-require_relative 'builder_methods/conversion'
-require_relative 'builder_methods/validation'
-require_relative 'resolver'
-require_relative 'receiver'
+require_relative 'compiler'
+require_relative 'receiver/object'
 
 module DynamicSchema
   class Builder 
-
-    include BuilderMethods::Validation 
-    include BuilderMethods::Conversion 
+    include Validator
+    include Converter
   
-    def initialize( schema = nil )
-      self.schema = schema 
-      super()
+    def initialize
+      self.compiled_schema = nil 
+      @schema_blocks = []
     end
 
-    def define( &block )
-      self.schema = Resolver.new( self.schema ).resolve( &block )._schema 
+    def define( inherit: nil, &block )
+      @schema_blocks << inherit if inherit
+      @schema_blocks << block if block
+
+      compiler = Compiler.new( self.compiled_schema )
+      compiler.compile( &inherit ) if inherit
+      compiler.compile( &block ) if block
+      self.compiled_schema = compiler.compiled
       self
     end 
 
+    def schema
+      blocks = @schema_blocks.dup
+      proc do 
+        blocks.each { | block | instance_eval( &block ) }
+      end
+    end
+
     def build( values = nil, &block )
-      receiver = Receiver.new( values, schema: self.schema, converters: self.converters )
+      receiver = Receiver::Object.new( values, schema: self.compiled_schema, converter: self )      
       receiver.instance_eval( &block ) if block
       receiver.to_h 
     end
 
-    def build!( values = nil, &block )
-      result = self.build( values, &block )
-      validate!( result )
-      result 
+    def build_from_bytes( bytes, filename: '(schema)', values: nil )
+      receiver = Receiver::Object.new( values, schema: compiled_schema, converter: self )
+      receiver.instance_eval( bytes, filename, 1 )
+      receiver.to_h
+    end
+
+    def build_from_file( path, values: nil )
+      self.build_from_bytes( 
+        File.read( path, encoding: 'UTF-8' ), 
+        filename: path, values: values 
+      )
+    end
+
+    [ :build, :build_from_bytes, :build_from_file ].each do |name|
+      define_method( :"#{name}!" ) do |*args, **kwargs, &blk|
+        result = public_send(name, *args, **kwargs, &blk)
+        validate!(result)
+        result
+      end
     end
 
   private 
-    attr_accessor :schema
+    attr_accessor :compiled_schema
 
   end
 end

data/lib/dynamic_schema/{resolver.rb → compiler.rb}

@@ -1,56 +1,57 @@
-require_relative 'receiver'
+require_relative 'receiver/object'
 
 module DynamicSchema
-  class Resolver < BasicObject
+  class Compiler < BasicObject
     
-    def initialize( schema = nil, resolved_blocks: nil )
-      @schema = schema || {}
+    def initialize( compiled_schema = nil, compiled_blocks: nil )
+      @compiled_schema = compiled_schema || {}
       
       @block = nil 
-      @resolved = false 
-      @resolved_blocks = resolved_blocks || []
+      @compiled = false 
+      @compiled_blocks = compiled_blocks || []
     end
 
-    def resolve( &block )
+    def compile( &block )
       @block = block 
-      @resolved = false 
-      unless @resolved_blocks.include?( @block )
-        @resolved_blocks << @block
+      @compiled = false 
+      unless @compiled_blocks.include?( @block )
+        @compiled_blocks << @block
         self.instance_eval( &@block )
-        @resolved = true 
+        @compiled = true 
       end
       self
     end
         
-    def _schema 
-
-      if !@resolved && @block 
-        @resolved_blocks << @block unless @resolved_blocks.include?( @block )
+    def compiled 
+      if !@compiled && @block 
+        @compiled_blocks << @block unless @compiled_blocks.include?( @block )
         self.instance_eval( &@block ) 
-        @resolved = true
+        @compiled = true
       end
-      @schema 
+      @compiled_schema 
     end
 
     def _value( name, options )
       name = name.to_sym
+      receiver = ::DynamicSchema::Receiver::Object
       ::Kernel.raise ::NameError, "The name '#{name}' is reserved and cannot be used for parameters." \
-        if ::DynamicSchema::Receiver.instance_methods.include?( name )
+        if receiver.method_defined?( name ) || receiver.private_method_defined?( name )
   
       _validate_in!( name, options[ :type ], options[ :in ] ) if options[ :in ] 
       
-      @schema[ name ] = options
+      @compiled_schema[ name ] = options
       self
     end
 
     def _object( name, options = {}, &block )
       name = name.to_sym
+      receiver = ::DynamicSchema::Receiver::Object
       ::Kernel.raise ::NameError, "The name '#{name}' is reserved and cannot be used for parameters." \
-        if ::DynamicSchema::Receiver.instance_methods.include?( name )
+        if receiver.method_defined?( name ) || receiver.private_method_defined?( name )
 
-      @schema[ name ] = options.merge( {
+      @compiled_schema[ name ] = options.merge( {
         type: ::Object,
-        resolver: Resolver.new( resolved_blocks: @resolved_blocks ).resolve( &block )
+        compiler: Compiler.new( compiled_blocks: @compiled_blocks ).compile( &block )
       } )    
       self
     end
@@ -60,15 +61,11 @@ module DynamicSchema
       options = nil
       if args.empty?
         options = {}
-      # when called with just options:              name as: :streams
       elsif first.is_a?( ::Hash )
         options = first 
-      # when called with just type:                 name String 
-      #                                             name [ TrueClass, FalseClass ] 
       elsif args.length == 1 && 
             ( first.is_a?( ::Class ) || first.is_a?( ::Module ) || first.is_a?( ::Array ) )
         options = { type: first }
-      # when called with just type and options:     name String, default: 'the default'
       elsif args.length == 2 && 
             ( first.is_a?( ::Class ) || first.is_a?( ::Module ) || first.is_a?( ::Array ) ) && 
             args[ 1 ].is_a?( ::Hash )
@@ -81,9 +78,9 @@ module DynamicSchema
       end
 
       type = options[ :type ]
-      if type == ::Object || type.nil? && block 
+      if type == ::Object || ( type.nil? && block )
         _object( method, options, &block )
-      else 
+      else
         _value( method, options )
       end
     
@@ -94,15 +91,15 @@ module DynamicSchema
     end
 
     def inspect
-      { schema: @schema }.inspect 
+      { schema: @compiled_schema }.inspect 
     end
 
     def class
-      ::DynamicSchema::Schema::Resolver
+      ::DynamicSchema::Compiler
     end
 
     def is_a?( klass )
-      klass == ::DynamicSchema::Resolver || klass == ::BasicObject
+      klass == ::DynamicSchema::Compiler || klass == ::BasicObject
     end
 
     alias :kind_of? :is_a?
@@ -110,7 +107,7 @@ module DynamicSchema
     if defined?( ::PP )
       include ::PP::ObjectMixin 
       def pretty_print( pp )
-        pp.pp( { schema: @schema } )
+        pp.pp( { schema: @compiled_schema } )
       end
     end      
   
@@ -124,6 +121,3 @@ module DynamicSchema
 
   end
 end
-
-
-