nxt_schema 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36a741174bf1669b013e32f2b3693c99cae2b4e479378cb1494069dd66f1af44
-  data.tar.gz: 2984ab8830a495bf1a694cd369216dee00e0dc5cc2cf1c87c173dd5c1e984963
+  metadata.gz: d1aba2ccbd135921f48a84de3e51d11b0592522b8d9e9e9fd3a5ff188117ffae
+  data.tar.gz: 1c67ef1beda4a6e6a33bd67bc7a9294c7bfbc14ccf72be3b621748212192c8c0
 SHA512:
-  metadata.gz: f1924005010c80140b9d545fb307ef373cb237a31e166195d6e959af56b41208d49db1d48ff3ab68c77ad45bdee3941821e9c2584cfe50cd2da47134a15a1eac
-  data.tar.gz: '001459e22044cfef5aded2ade7d9b8b0fe15c944c4bb886a992578a82886777c2a92e5ce1711919414b79910577b68671249b8bdc74526a89ee0c1437ba4c421'
+  metadata.gz: 34cd6cdacddb969ac3532dc8f52150dc16e8be80b12bf8ceaec9cd147df93547cc02e655eaff1d05eee359b660e1143187adb704fbac91a3f09d4a18ebd28087
+  data.tar.gz: 5f77d02ed8b601aa255a4b9be082c48f1da0e7fa157561547e7c99a726c8a9d2f34a4c76be78cbd60ec529bce719e0b06e42d6645cbbe18e65facf7de9e7a1fc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nxt_schema (1.0.0)
+    nxt_schema (1.0.1)
       activesupport
       dry-types
       nxt_init
@@ -50,7 +50,7 @@ GEM
     minitest (5.14.2)
     nxt_init (0.1.5)
       activesupport
-    nxt_registry (0.3.2)
+    nxt_registry (0.3.3)
       activesupport
     pry (0.13.1)
       coderay (~> 1.1)
@@ -72,7 +72,7 @@ GEM
     thread_safe (0.3.6)
     tzinfo (1.2.8)
       thread_safe (~> 0.1)
-    zeitwerk (2.4.1)
+    zeitwerk (2.4.2)
 
 PLATFORMS
   ruby

data/README.md

@@ -16,10 +16,13 @@ Or install it yourself as:
 
     $ gem install nxt_schema
 
-## What it is for?
+## What is it for?
 
-NxtSchema is a type casting and validation framework that allows you to validate and type cast arbitrary nested 
-structures of data. 
+NxtSchema is a type coercion and validation framework that allows you to coerce and validate arbitrary nested 
+structures of data. The original idea is taken from https://dry-rb.org/gems/dry-schema and 
+https://dry-rb.org/gems/dry-validation from the amazing dry.rb eco system. In contrast to dry-schema, 
+NxtSchema aims to be a simpler solution that hopefully is easier to understand and debug. 
+It also ships with some handy features that dry-schema does not implement. 
 
 ### Usage
 
@@ -31,7 +34,7 @@ PERSON = NxtSchema.schema(:person) do
 end
 
 input = {
-  first_name: 'Andy',
+  first_name: 'Ändy',
   last_name: 'Robecke',
   email: 'andreas@robecke.de'
 }
@@ -58,9 +61,9 @@ The kind of node dictates how the schema is applied to the input. On the root le
 to create schemas:
 
 ```ruby
-  NxtSchema.schema { ... } # => Create a schema node 
-  NxtSchema.collection { ... } # => Create an array of nodes
-  NxtSchema.any_of { ... } # => Create a collection of allowed schemas
+  NxtSchema.schema { ... } # => Creates a schema node 
+  NxtSchema.collection { ... } # => Creates an array of nodes
+  NxtSchema.any_of { ... } # => Creates a collection of allowed schemas
 ```
 
 #### Node predicate aliases
@@ -85,6 +88,8 @@ into a schema you also have to combine the node predicates with default value me
 check out the examples below:
 
 ```ruby
+# Optional node without default value
+
 schema = NxtSchema.schema(:person) do
   optional(:email, :String)
 end
@@ -99,19 +104,24 @@ result.output # => {}
 ```
 
 ```ruby
+# Optional node with default value
+
 schema = NxtSchema.schema(:person) do
   optional(:email, :String).default('andreas@robecke.de')
 end
 
 result = schema.apply(input: { email: nil })
 result.errors # => {}
+result.output # => {:email=>"andreas@robecke.de"}
 
 result = schema.apply(input: {})
 result.errors # => {}
-result.output # => {:email=>"andreas@robecke.de"}
+result.output # => {}
 ```
 
 ```ruby
+# Omnipresent node without default value
+
 schema = NxtSchema.schema(:person) do
   omnipresent(:email, :String)
 end
@@ -122,8 +132,9 @@ result.output # => {:email=>NxtSchema::MissingInput}
 ```
 
 ```ruby
+# Omnipresent node with default value and maybe expression to allow default value to break type contract.
+
 schema = NxtSchema.schema(:person) do
-  # make sure a node is always present and at least nil even though the type is String
   omnipresent(:email, :String).default(nil).maybe(:nil?)
 end
 
@@ -131,15 +142,16 @@ result = schema.apply(input: {})
 result.errors # => {}
 result.output # => {:email=>nil}
 
-result = schema.apply(input:  { email: 'andreas@robecke.de' })
+result = schema.apply(input: { email: 'andreas@robecke.de' })
 result.errors # => {}
 result.output # => {:email=>"andreas@robecke.de"}
 ```
 
 ##### Conditionally optional nodes
 
-You can also pass a proc as the optional option. This will add a validator to the parent node that makes sure thar the 
-key is present if the optional condition does not apply.
+You can also pass a proc as the optional option. This is a shortcut for adding a validation to the parent node 
+that will result in a validation error in case the optional condition does not apply and the parent node does not 
+contain a sub node with that name (here contact schema not including an email node). 
 
 ```ruby
 schema = NxtSchema.schema(:contact) do
@@ -180,10 +192,6 @@ The type system is built with dry-types from the amazing https://dry-rb.org eco
 offers features such as default values for types as well as maybe types, these features are built directly into 
 NxtSchema. 
 
-Please note that Dry.rb also has a gem for schemas: https://dry-rb.org/gems/dry-schema and another one dedicated to 
-validations explicitly https://dry-rb.org/gems/dry-validation. You should probably go and check those out! NxtSchema
-is trying to implement a simpler solution that is easy to understand yet powerful enough for most tasks.  
-
 In NxtSchema every node has a type and you can either provide a symbol that will be resolved 
 through the type system of the schema or you can directly provide an instance of dry type and thus use your 
 custom types. This means you can basically build any kind of objects such as structs and models from your data and 
@@ -197,11 +205,11 @@ type system that was specified NxtSchema will always fallback to nominal types.
 a separate type system per node if that's what you need. 
                                
 ```ruby
-NxtSchema.root do
+NxtSchema.schema do
   required(:test, :String) # The :String will resolve to NxtSchema::Types::Nominal::String
 end
 
-NxtSchema.root(type_system: NxtSchema::Types::JSON) do
+NxtSchema.schema(type_system: NxtSchema::Types::JSON) do
   required(:test, :Date) # The :Date will resolve to NxtSchema::Types::JSON::Date
   # When the type does not exist in the default type system (there is non JSON::String) we fallback to nominal types
   required(:test, :String) 
@@ -234,7 +242,7 @@ NxtSchema.register_type(
 
 # once registered you can use the type in your schema
 
-NxtSchema.root(:company) do
+NxtSchema.schema(:company) do
   required(:name, :MyCustomStrippedString)
 end
 ```
@@ -244,21 +252,21 @@ end
 #### Default values
 
 ```ruby
-# Define default values as options or with the default method
+# Define default values with the default method
+required(:test, :DateTime).default(nil)
 required(:test, :DateTime).default(-> { Time.current })
-required(:test, :String, default: 'Andy')
 ```
 
 #### Maybe values 
 
-With maybe you can allow your values to be of a certain type and halt conversion. **Note: This means that your output
-will simply be set to the input without coercing the value!**
+With maybe expressions you can halt coercion and allow your values to break the type contract. 
+**Note: This means that your output will simply be set to the input without coercing the value!**
 
 ```ruby
 # Define maybe values (values that do not match the type)
 required(:test, :String).maybe(:nil?)
 
-nodes(:tests).maybe(:empty?) do # will allow the collection to be empty
+nodes(:tests).maybe(:empty?) do # will allow the collection to be empty and thus not contain strings
   required(:test, :String)
 end
 
@@ -272,6 +280,8 @@ based on some condition. When the node is yielded to your validation proc you ha
 `node.input` and `node.index` when the node is within a collection of nodes as well as `node.name`. Furthermore you have 
 access to the context that was passed in when defining the schema or passed to the apply method later.
 
+**NOTE: Validations only run when no maybe expression applies and the node input could be coerced successfully**
+
 ```ruby
   # Simple custom validation
   required(:test, :String).validate(-> (node) { node.add_error("#{node.input} is not valid") if node.input == 'not allowed' })
@@ -320,7 +330,7 @@ end
 NxtSchema.register_validator(MyCustomExclusionValidator, :my_custom_exclusion_validator)
 
 # and then simply reference it with the key you've registered it
-schema = NxtSchema.root(:company) do
+schema = NxtSchema.schema(:company) do
   requires(:name, :String).validate(:my_custom_exclusion_validator, %w[lemonade])
 end
 
@@ -333,25 +343,24 @@ schema.apply(name: 'lemonade').valid? # => false
 - Add translated errors
 - Interpolate with actual vs. expected 
 
-#### Combining validators with custom logic
+#### Combining validators
 
 `node(:test, String).validate(...)` basically adds a validator to the node. Of course you can add multiple validators.
-But that means that they will all be executed and errors aggregated. If you want your validator to only run in case 
+But that means that they will all be executed. If you want your validator to only run in case 
 another was false, you can use `:validat_with do ... end` in order to combine validators based on custom logic. 
 
  ```ruby
-NxtSchema.root do
+NxtSchema.schema do
   required(:test, :Integer).validate_with do
     validator(:greater_than, 5) &&
-      validator(:greater_than, 6) &&
+      validator(:greater_than, 6) ||
       validator(:greater_than, 7)
   end
 end
 ```
 
-This has one drawback however. Let's say your test value is 4. This would only run your first validator and then exit 
-from the logic since validators are combined with &&. In this example it might not make much sense, but it basically 
-means that you might not have the full validation errors when combining validations with `:validate_with` 
+Note that this will not run subsequent validators once one was valuated to false and thus might not contain all error 
+messages of all validators that would have failed.  
 
 
 ### Schema options
@@ -363,17 +372,17 @@ You can change this behaviour by providing a strategy for the `:additional_keys`
 
 ```ruby
 # This will simply ignore any other key except test 
-NxtSchema.root(additional_keys: :ignore) do
+NxtSchema.schema(additional_keys: :ignore) do
   required(:test, :String) 
 end
 
 # This would give you an error in case you apply anything other than { test: '...' }
-NxtSchema.root(additional_keys: :restrict) do
+NxtSchema.schema(additional_keys: :restrict) do
   required(:test, :String) 
 end
 
 # This will merge other keys into your output
-schema = NxtSchema.root(additional_keys: :allow) do
+schema = NxtSchema.schema(additional_keys: :allow) do
   required(:test, :String) 
 end
 
@@ -388,7 +397,7 @@ You may want to transform the keys from your input. Therefore specify the transf
 when you want your schema to return only symbolized keys for example. 
 
 ```ruby
-schema = NxtSchema.root(transform_keys: ->(key) { key.to_sym}) do
+schema = NxtSchema.schema(transform_keys: ->(key) { key.to_sym}) do
   required(:test, :String)
 end
 
@@ -402,7 +411,7 @@ You want to give nodes an ID or some other meta data? You can use the meta metho
 information onto any node.  
 
 ```ruby
-schema = NxtSchema.root do
+schema = NxtSchema.schema do
   ERROR_MESSAGES = {
     test: 'This is always broken'
   }
@@ -416,12 +425,43 @@ schema.error #  {"root.test"=>["This is always broken"]}
 
 #### Contexts
 
-# TODO
+When defining a schema it is possible to pass in a context option. This can be anything that you would like to access
+during building your schema. A context could provide custom validators or default values depending of the name of your
+nodes for instance.  
 
 ##### Build time
 
+```ruby
+context = OpenStruct.new(email_validator: ->(node) { node.input && node.input.includes?('@') }) 
+
+NxtSchema.schema(:developers, context: context) do
+  required(:first_name, :String)
+  required(:last_name, :String)
+  required(:email, :String).validate(context.email_validator)
+end
+```
+
 ##### Apply time
 
+You can also pass in a context at apply time. If you do not pass in a specific 
+context at apply time you can still access the context passed in at build time. 
+Basically passing in a context at apply time will overwrite the context from before. You can access it simply through
+the node.  
+
+```ruby
+build_context = OpenStruct.new(email_validator: ->(node) { node.input.includes?('@') })
+apply_context = OpenStruct.new(default_role: 'BOSS')
+
+schema = NxtSchema.schema(:developers, context: build_context) do
+  # context at build time
+  required(:email, :String).validate(context.email_validator) # 
+  # access the context at apply time through the node 
+  required(:role, :String).default { |_, node| node.context.default_role }
+end
+
+schema.apply(input: input, context: apply_context)
+```
+
 ## 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.
@@ -438,6 +478,8 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## TODO:
 
+- Explain node interface
+- Add apply! method to readme
 - Allow to disable validation when applying 
     --> Are there attributes that should be moved to apply time?
 - Should we have a global and a local registry for validators?

data/lib/nxt_schema.rb

@@ -7,7 +7,7 @@ require 'yaml'
 
 require_relative 'nxt_schema/types'
 require_relative 'nxt_schema/callable'
-require_relative 'nxt_schema/application'
+require_relative 'nxt_schema/node'
 require_relative 'nxt_schema/missing_input'
 require_relative 'nxt_schema/error'
 require_relative 'nxt_schema/errors/invalid'
@@ -31,26 +31,26 @@ require_relative 'nxt_schema/validators/excluded_in'
 require_relative 'nxt_schema/validators/excludes'
 require_relative 'nxt_schema/validators/query'
 
-require_relative 'nxt_schema/node/on_evaluator'
-require_relative 'nxt_schema/node/maybe_evaluator'
-require_relative 'nxt_schema/node/type_resolver'
-require_relative 'nxt_schema/node/type_system_resolver'
+require_relative 'nxt_schema/template/on_evaluator'
+require_relative 'nxt_schema/template/maybe_evaluator'
+require_relative 'nxt_schema/template/type_resolver'
+require_relative 'nxt_schema/template/type_system_resolver'
+require_relative 'nxt_schema/template/base'
+require_relative 'nxt_schema/template/sub_nodes'
+require_relative 'nxt_schema/template/has_sub_nodes'
+require_relative 'nxt_schema/template/any_of'
+require_relative 'nxt_schema/template/collection'
+require_relative 'nxt_schema/template/schema'
+require_relative 'nxt_schema/template/leaf'
+
+require_relative 'nxt_schema/node/errors/schema_error'
+require_relative 'nxt_schema/node/errors/validation_error'
+require_relative 'nxt_schema/node/error_store'
 require_relative 'nxt_schema/node/base'
-require_relative 'nxt_schema/node/sub_nodes'
-require_relative 'nxt_schema/node/has_sub_nodes'
 require_relative 'nxt_schema/node/any_of'
+require_relative 'nxt_schema/node/leaf'
 require_relative 'nxt_schema/node/collection'
 require_relative 'nxt_schema/node/schema'
-require_relative 'nxt_schema/node/leaf'
-
-require_relative 'nxt_schema/application/errors/schema_error'
-require_relative 'nxt_schema/application/errors/validation_error'
-require_relative 'nxt_schema/application/error_store'
-require_relative 'nxt_schema/application/base'
-require_relative 'nxt_schema/application/any_of'
-require_relative 'nxt_schema/application/leaf'
-require_relative 'nxt_schema/application/collection'
-require_relative 'nxt_schema/application/schema'
 require_relative 'nxt_schema/dsl'
 
 module NxtSchema

data/lib/nxt_schema/dsl.rb

@@ -2,8 +2,8 @@ module NxtSchema
   module Dsl
     DEFAULT_OPTIONS = { type_system: NxtSchema::Types }.freeze
 
-    def collection(name = :root, type: NxtSchema::Node::Collection::DEFAULT_TYPE, **options, &block)
-      NxtSchema::Node::Collection.new(
+    def collection(name = :root, type: NxtSchema::Template::Collection::DEFAULT_TYPE, **options, &block)
+      NxtSchema::Template::Collection.new(
         name: name,
         type: type,
         parent_node: nil,
@@ -14,8 +14,8 @@ module NxtSchema
 
     alias nodes collection
 
-    def schema(name = :roots, type: NxtSchema::Node::Schema::DEFAULT_TYPE, **options, &block)
-      NxtSchema::Node::Schema.new(
+    def schema(name = :roots, type: NxtSchema::Template::Schema::DEFAULT_TYPE, **options, &block)
+      NxtSchema::Template::Schema.new(
         name: name,
         type: type,
         parent_node: nil,
@@ -25,7 +25,7 @@ module NxtSchema
     end
 
     def any_of(name = :roots, **options, &block)
-      NxtSchema::Node::AnyOf.new(
+      NxtSchema::Template::AnyOf.new(
         name: name,
         parent_node: nil,
         **DEFAULT_OPTIONS.merge(options),
@@ -35,8 +35,8 @@ module NxtSchema
 
     # schema root with NxtSchema::Types::Params type system
 
-    def params(name = :params, type: NxtSchema::Node::Schema::DEFAULT_TYPE, **options, &block)
-      NxtSchema::Node::Schema.new(
+    def params(name = :params, type: NxtSchema::Template::Schema::DEFAULT_TYPE, **options, &block)
+      NxtSchema::Template::Schema.new(
         name: name,
         type: type,
         parent_node: nil,

data/lib/nxt_schema/{application.rb → node.rb}

@@ -1,5 +1,5 @@
 module NxtSchema
-  module Application
+  module Node
 
   end
 end

data/lib/nxt_schema/node/any_of.rb

@@ -1,50 +1,38 @@
 module NxtSchema
   module Node
-    class AnyOf < Base
-      include HasSubNodes
-
-      def initialize(name:, type: nil, parent_node:, **options, &block)
-        super
-      end
-
-      def collection(name = sub_nodes.count, type = NxtSchema::Node::Collection::DEFAULT_TYPE, **options, &block)
-        super
+    class AnyOf < Node::Base
+      def valid?
+        valid_application.present?
       end
 
-      def schema(name = sub_nodes.count, type = NxtSchema::Node::Schema::DEFAULT_TYPE, **options, &block)
-        super
-      end
-
-      def node(name = sub_nodes.count, node_or_type_of_node = nil, **options, &block)
-        super
-      end
+      def call
+        child_applications.map(&:call)
 
-      # TODO: Maybe overwrite sub node methods to not have to provide a name here and use node count instead
+        if valid?
+          self.output = valid_application.output
+        else
+          child_applications.each do |application|
+            merge_errors(application)
+          end
+        end
 
-      def on(*args)
-        raise NotImplementedError
-      end
-
-      def maybe(*args)
-        raise NotImplementedError
+        self
       end
 
       private
 
-      def resolve_type(name_or_type)
-        nil
-      end
+      delegate :[], to: :child_applications
 
-      def resolve_optional_option
-        return unless options.key?(:optional)
-
-        raise InvalidOptions, "The optional option is not available for nodes of type #{self.class.name}"
+      def valid_application
+        child_applications.find(&:valid?)
       end
 
-      def resolve_omnipresent_option
-        return unless options.key?(:omnipresent)
+      def child_applications
+        @child_applications ||= nodes.map { |node| node.build_application(input: input, context: context, parent: self) }
+      end
 
-        raise InvalidOptions, "The omnipresent option is not available for nodes of type #{self.class.name}"
+      def nodes
+        @nodes ||= node.sub_nodes.values
       end
     end
   end