nxt_schema 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83dae4e0a58a5ec9ec18b68fe441ab358496912b26c8993f7a29eb1fc8079504
-  data.tar.gz: bc82ad37116553668920606298b5e5739a15e6647245c68befba798d96a7f771
+  metadata.gz: 36a741174bf1669b013e32f2b3693c99cae2b4e479378cb1494069dd66f1af44
+  data.tar.gz: 2984ab8830a495bf1a694cd369216dee00e0dc5cc2cf1c87c173dd5c1e984963
 SHA512:
-  metadata.gz: e03262430dcb11ab76da8ec2a6dc295d964a59e679a9fd8ba5492e5618a43769d16e9282b13091656aeb9cad932fa2adc5a31899b4b9ca8963eceb5b47b34b41
-  data.tar.gz: 28755070f8df4c055a14f3129d95bf5fdbc306d49737b21125ea94cff82ee419e34894517fb77c0a12e793ce338a2d6a502fb218a25b62103b502ed2befc758a
+  metadata.gz: f1924005010c80140b9d545fb307ef373cb237a31e166195d6e959af56b41208d49db1d48ff3ab68c77ad45bdee3941821e9c2584cfe50cd2da47134a15a1eac
+  data.tar.gz: '001459e22044cfef5aded2ade7d9b8b0fe15c944c4bb886a992578a82886777c2a92e5ce1711919414b79910577b68671249b8bdc74526a89ee0c1437ba4c421'

data/.ruby-version

@@ -0,0 +1 @@
+2.7.0

data/Gemfile

@@ -1,6 +1,5 @@
 source "https://rubygems.org"
 
 git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
-
 # Specify your gem's dependencies in nxt_schema.gemspec
 gemspec

data/Gemfile.lock

@@ -1,35 +1,36 @@
 PATH
   remote: .
   specs:
-    nxt_schema (0.1.2)
+    nxt_schema (1.0.0)
       activesupport
       dry-types
+      nxt_init
       nxt_registry
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.0.2.2)
+    activesupport (6.0.3.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-      zeitwerk (~> 2.2)
-    coderay (1.1.2)
-    concurrent-ruby (1.1.6)
-    diff-lcs (1.3)
-    dry-configurable (0.11.5)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.7)
+    diff-lcs (1.4.4)
+    dry-configurable (0.11.6)
       concurrent-ruby (~> 1.0)
       dry-core (~> 0.4, >= 0.4.7)
       dry-equalizer (~> 0.2)
     dry-container (0.7.2)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 0.1, >= 0.1.3)
-    dry-core (0.4.9)
+    dry-core (0.4.10)
       concurrent-ruby (~> 1.0)
     dry-equalizer (0.3.0)
     dry-inflector (0.2.0)
-    dry-logic (1.0.6)
+    dry-logic (1.0.8)
       concurrent-ruby (~> 1.0)
       dry-core (~> 0.2)
       dry-equalizer (~> 0.2)
@@ -41,35 +42,37 @@ GEM
       dry-inflector (~> 0.1, >= 0.1.2)
       dry-logic (~> 1.0, >= 1.0.2)
     hirb (0.7.3)
-    i18n (1.8.2)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
     method_profiler (2.0.1)
       hirb (>= 0.6.0)
-    method_source (0.9.2)
-    minitest (5.14.0)
-    nxt_registry (0.1.5)
+    method_source (1.0.0)
+    minitest (5.14.2)
+    nxt_init (0.1.5)
       activesupport
-    pry (0.12.2)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
+    nxt_registry (0.3.2)
+      activesupport
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
     rake (12.3.3)
-    rspec (3.8.0)
-      rspec-core (~> 3.8.0)
-      rspec-expectations (~> 3.8.0)
-      rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.2)
-      rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.4)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.0)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-support (3.8.2)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.0)
     thread_safe (0.3.6)
-    tzinfo (1.2.7)
+    tzinfo (1.2.8)
       thread_safe (~> 0.1)
-    zeitwerk (2.3.0)
+    zeitwerk (2.4.1)
 
 PLATFORMS
   ruby

data/README.md

@@ -16,138 +16,185 @@ Or install it yourself as:
 
     $ gem install nxt_schema
 
-## Usage
+## What it is for?
+
+NxtSchema is a type casting and validation framework that allows you to validate and type cast arbitrary nested 
+structures of data. 
+
+### Usage
 
 ```ruby
-# Schema with hash root
-schema = NxtSchema.root(:company) do 
-  requires(:name, :String)  
-  requires(:value, :Integer).maybe(nil)  
-  present(:stock_options, :Bool).default(false)
-  
-  schema(:address) do
-    requires(:street, :String)
-    requires(:street_number, :Integer)
-  end
+PERSON = NxtSchema.schema(:person) do
+  node(:first_name, :String)
+  node(:last_name, :String)
+  node(:email, :String, optional: true).validate(:includes, '@')
+end
 
-  # Use nodes to create an array of typed nodes
-  # The following simple means an array of strings 
-  nodes(:products) do
-    node(:product, :String)
-  end
+input = {
+  first_name: 'Andy',
+  last_name: 'Robecke',
+  email: 'andreas@robecke.de'
+}
 
-    
-  nodes(:employees) do
-    hash(:employee) do
-      POSITIONS = %w[senior junior intern]
+result = PERSON.apply(input: input)
 
-      requires(:first_name, :String)
-      requires(:last_name, :String)
-      optional(:email, :String).validate(:format, /\A.*@.*\z/)
-      requires(:position, NxtSchema::Types::Enums[*POSITIONS])
-    end
-  end
-end
-  
-# Schema with array root
-schema = NxtSchema.roots(:companies) do
-  schema(:company) do
-    requires(:name, :String)  
-    requires(:value, :Integer).maybe(nil)
-  end
-end
+result.valid? # => true
+result.output # => input
+```  
 
-schema.apply(your: 'values here')
-schema.errors # { 'name.spaced.key': ['all the errors'] }
+### Nodes
+
+A schema consists of a number of nodes. Every node has a name and an associated type for casting it's input when the 
+schema is applied. Schemas can consist of 4 different kinds of nodes: 
+
+```ruby
+NxtSchema::Node::Schema # => Hash of values 
+NxtSchema::Node::Collection # => Array of values
+NxtSchema::Node::AnyOf # => Any of the defined schemas
+NxtSchema::Node::Leaf # => Node without sub nodes
 ```
 
-### DSL
+The kind of node dictates how the schema is applied to the input. On the root level the following methods are available
+to create schemas:
 
-Create a new schema with `NxtSchema.root { ... }` or in case you have an array node as root, 
-use `NxtSchema.roots { ... }`. Within the schema you can create node simply with the `node(name, type_or_node, **options)` 
-method. Each node requires a name and a type and accepts additional options. Node are required per default. 
-But you can make them optional by providing the optional option.  
+```ruby
+  NxtSchema.schema { ... } # => Create a schema node 
+  NxtSchema.collection { ... } # => Create an array of nodes
+  NxtSchema.any_of { ... } # => Create a collection of allowed schemas
+```
 
-#### Nodes
+#### Node predicate aliases
+
+Of course these nodes can be combined and nested in arbitrary manner. When defining nodes within a schema, nodes are 
+always required per default. You can create nodes with the node method or several useful helper methods. 
 
 ```ruby
-NxtSchema.root do
-  node(:first_name, :String)
-  node(:last_name, :String, optional: true)
-  node(:email, :String, presence: true)
+NxtSchema.schema(:person) do
+  required(:first_name, :String) # => same as node(:first_name, :String)
+  optional(:last_name, :String) # => same as node(:first_name, :String, optional: true)
+  omnipresent(:email, :String) # => same as node(:first_name, :String, omnipresent: true)
 end
 ```
 
-In order to make the schema more readable you can make use of several predicate aliases to create required, optional or 
-(omni)present nodes.  
+**NOTE: The methods above only apply to the keys of your schema and do not make any assumptions about values!**
 
-#### Predicate aliases
+In other word this means that making a node optional only makes your node optional. When your input contains the key but
+the value is nil, you will still get an error in case there is no default or maybe expression that applies. Omnipresent
+node also only inject the node into the schema but do not inject a default value. In order to inject a key with value 
+into a schema you also have to combine the node predicates with default value method described below. For clarification
+check out the examples below:
 
 ```ruby
-NxtSchema.root do
-  required(:first_name, :String)
-  optional(:last_name, :String)
-  present(:email, :String)
+schema = NxtSchema.schema(:person) do
+  optional(:email, :String)
 end
+
+result = schema.apply(input: { email: nil })
+result.errors # => {"person.email"=>["nil violates constraints (type?(String, nil) failed)"]}
+result.output # => {:email=>nil}
+
+result = schema.apply(input: {})
+result.errors # => {}
+result.output # => {}
 ```
 
-### Nodes
+```ruby
+schema = NxtSchema.schema(:person) do
+  optional(:email, :String).default('andreas@robecke.de')
+end
 
-The following types of nodes exist
+result = schema.apply(input: { email: nil })
+result.errors # => {}
 
-#### Schema Nodes
+result = schema.apply(input: {})
+result.errors # => {}
+result.output # => {:email=>"andreas@robecke.de"}
+```
 
 ```ruby
-# Create schema nodes with:
-required(:test, :Schema) do ... end
-schema(:test) do ... end
-hash(:test) do ... end
-```
+schema = NxtSchema.schema(:person) do
+  omnipresent(:email, :String)
+end
 
-#### Collection Nodes
+result = schema.apply(input: {})
+result.errors # => {}
+result.output # => {:email=>NxtSchema::MissingInput}
+```
 
 ```ruby
-# Create collection (array) nodes with:
-required(:test, :Collection) do ... end
-
-nodes(:test) do
-  # For type checking of array items you can simply add a node with the expected type. 
-  # As always you need to give it a name. This would result in an array of string items  
-  required(:item, :String) 
+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
 
-array(:test) do ... end
+result = schema.apply(input: {})
+result.errors # => {}
+result.output # => {:email=>nil}
+
+result = schema.apply(input:  { email: 'andreas@robecke.de' })
+result.errors # => {}
+result.output # => {:email=>"andreas@robecke.de"}
 ```
 
-#### Leaf Nodes
+##### 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.
 
 ```ruby
-# Create leaf nodes with a basic type 
-required(:test, :String) do ... end
-```
+schema = NxtSchema.schema(:contact) do
+  required(:first_name, :String)
+  required(:last_name, :String)
+  node(:email, :String, optional: ->(node) { node.up[:last_name].input == 'Robecke' })
+end
+
+result = schema.apply(input: { first_name: 'Andy', last_name: 'Other' })
+result.errors # => {"contact"=>["Required key :email is missing"]}
+
+result = schema.apply(input: { first_name: 'Andy', last_name: 'Robecke' })
+result.errors # => {}
+```  
+
+#### Combining Schemas
 
-#### Struct Nodes
+You can also simply reuse a schema by passing it to the node method as the type of a node. When doing so the schema 
+will be cloned with the same options and configuration as the schema passed in. 
 
 ```ruby
-# Create structs from hash inputs 
-struct(:test) do ... end  
+ADDRESS = NxtSchema.schema(:address) do
+  required(:street, :String)
+  required(:town, :String)
+  required(:zip_code, :String)
+end 
+
+PERSON = NxtSchema.schema(:person) do
+  required(:first_name, :String)
+  required(:last_name, :String)
+  optional(:address, ADDRESS)
+end
 ```
 
 ### Types
 
-The type system is built with dry-types from the amazing https://dry-rb.org/ eco system. Even though dry-types also
+The type system is built with dry-types from the amazing https://dry-rb.org eco system. Even though dry-types also
 offers features such as default values for types as well as maybe types, these features are built directly into 
-NxtSchema. Dry.rb also has a gem for schemas and another one dedicated to validations. You should probably
-check those out! However, 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. But you can also directly provide an instance of dry type and thus use your 
-custom types.    
+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 
+you are not limited to just hashes arrays and primitives.  
 
 #### Default type system
 
 You can tell your schema which default type system it should use. Dry-Types comes with a few built in type systems.
 Per default NxtSchema will use nominal types if not specified otherwise. If the type cannot be resolved from the default
-type system that was specified, NxtSchema will again try to fallback to nominal types. In theory you can provide
-a separate type system per node if that's what you want :-D
+type system that was specified NxtSchema will always fallback to nominal types. In theory you can provide
+a separate type system per node if that's what you need. 
                                
 ```ruby
 NxtSchema.root do
@@ -188,7 +235,7 @@ NxtSchema.register_type(
 # once registered you can use the type in your schema
 
 NxtSchema.root(:company) do
-  required(:name, NxtSchema::Types::MyCustomStrippedString)
+  required(:name, :MyCustomStrippedString)
 end
 ```
 
@@ -198,34 +245,41 @@ end
 
 ```ruby
 # Define default values as options or with the default method
-required(:test, :String).default(value_or_proc)
-required(:test, :String, default: value_or_proc) do ... end
+required(:test, :DateTime).default(-> { Time.current })
+required(:test, :String, default: 'Andy')
 ```
 
 #### Maybe values 
 
-Allow specific values that are not being coerced
+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!**
 
 ```ruby
 # Define maybe values (values that do not match the type)
-required(:test, :String).maybe(value_or_proc)
-required(:test, :String, maybe: value_or_proc) do ... end
+required(:test, :String).maybe(:nil?)
+
+nodes(:tests).maybe(:empty?) do # will allow the collection to be empty
+  required(:test, :String)
+end
+
 ```  
 
 ### Validations
 
 NxtSchema comes with a simple validation system and ships with a small set of useful validators. Every node in a schema
 implements the `:validate` method. Similar to ActiveModel::Validations it allows you to simply add errors to a node
-based on some condition. 
+based on some condition. When the node is yielded to your validation proc you have access to the nodes input with
+`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.
 
 ```ruby
-  # Simple validation
-  required(:test, :String).validate -> (node, value) { node.add_error("#{value} is not valid") if value == 'not allowed' }
+  # Simple custom validation
+  required(:test, :String).validate(-> (node) { node.add_error("#{node.input} is not valid") if node.input == 'not allowed' })
   # Built in validations
   required(:test, :String).validate(:attribute, :size, ->(s) { s < 7 }) 
-  required(:test, :String).validate(:equality, 'same') 
-  required(:test, :String).validate(:excluded, %w[not_allowed]) # excluded in the target: %w[not_allowed]
-  required(:test, :String).validate(:included, %w[allowed]) # included in the target: %w[allowed]
+  required(:test, :String).validate(:equal_to, 'same') 
+  required(:test, :String).validate(:excluded_in, %w[not_allowed]) # excluded in the target: %w[not_allowed]
+  required(:test, :String).validate(:included_in, %w[allowed]) # included in the target: %w[allowed]
   required(:test, :Array).validate(:excludes, 'excluded') # array value itself must exclude 'excluded' 
   required(:test, :Array).validate(:includes, 'included') # array value itself must include 'included'
   required(:test, :Integer).validate(:greater_than, 1) 
@@ -323,7 +377,7 @@ schema = NxtSchema.root(additional_keys: :allow) do
   required(:test, :String) 
 end
 
-schema.apply(test: 'getsafe', other: 'Heidelberg')
+schema.apply(input: {test: 'getsafe', other: 'Heidelberg'})
 schema.valid? # => true
 schema.value # => { test: 'getsafe', other: 'Heidelberg' }
 ```
@@ -334,12 +388,12 @@ 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: :to_sym) do
+schema = NxtSchema.root(transform_keys: ->(key) { key.to_sym}) do
   required(:test, :String)
 end
 
-schema.apply('test' => 'getsafe') # => {:test=>"getsafe"}
-schema.apply(test: 'getsafe') # => {:test=>"getsafe"}
+schema.apply(input: { 'test' => 'getsafe' }) # => {:test=>"getsafe"}
+schema.apply(input: { test: 'getsafe' }) # => {:test=>"getsafe"}
 ``` 
 
 #### Adding meta data to nodes
@@ -356,10 +410,18 @@ schema = NxtSchema.root do
   required(:test, :String).meta(ERROR_MESSAGES).validate ->(node) { node.add_error(node.meta.fetch(node.name)) }
 end
 
-schema.apply(test: 'getsafe') 
+schema.apply(input: { test: 'getsafe' }) 
 schema.error #  {"root.test"=>["This is always broken"]}
 ```
 
+#### Contexts
+
+# TODO
+
+##### Build time
+
+##### Apply time
+
 ## 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.
@@ -368,22 +430,30 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/nxt_schema.
+Bug reports and pull requests are welcome on GitHub at https://github.com/getand.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-### TODO:    
-
-- Flatten schema errors like validation errors
-- Conditionally required keys:
-    required bool => required
-    required conditionally => condition applies => required
-    required conditionally => condition does not apply => not allowed 
-    
-- Explain the difference between array nodes and typed array nodes
-- Should we translate coercion errors as well?
-- Test the different scenarios of merging schemas array, hash, ...
-- Structure Errors 
-- NxtSchema::Json => Use json types, maybe even parse Json with Oj
+## TODO:
+
+- 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?
+    --> Would be cool to register things for the schema only
+    --> Would be cool if this was extendable 
+- Do we need all off in order to combine multiple schemas?
+- Think about a good implementation of params framework for controllers
+
+```ruby
+PARAMS = NxtRegistry::Registry.new do
+      register(:create) do
+        NxtSchema.params do
+
+        end
+      end
+    end
+
+PARAMS.resolve(:create).apply(input: params)
+```