json_data_extractor 0.0.11 → 0.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aeef2dddd8e11795c682d9db785b955164fbab87e4dc1c63843ba02a76b65905
-  data.tar.gz: e17a062f72e0ae56bc09b42ccaa237c12149b667b63dfb0e58a60dd3ea8e5830
+  metadata.gz: bb96ee66beec96f117282087fadea7c8bf91febb79eddf8d588bfb26a4301466
+  data.tar.gz: b0a5221e3eb012da640233fac6fb5ff6a41715327de6cb381bd8896e184095bd
 SHA512:
-  metadata.gz: b574bc9f7c79a4405d7b86739e1bf50e0ccbc82f1016befedf3e5bbb0da040db263492ee8978cd3d83957546d47338980bcfba80770a620a9c637937675bad46
-  data.tar.gz: 2a83cf29049a8c4205851a83e12e0867f42ae684564c6bc7ae9e183b4399f9a2390f9be36724f137064bf8e76f74b30d977539fdb1c620972c05a949f19883f2
+  metadata.gz: 48e16964d90fc098e3d2b1c9ad5136f642546a9fa04121aea8b2ed28847224fe85ee43a576476e61fbcdf501e0ae188488c23cdd1bab6bf9d1af9781d301df60
+  data.tar.gz: 8b7fd89bbd4ecd36b24a542112da82baeccc789e8cf86b8ce8cbbbf3444d28c2073809ba105cb96f261d88c847ca74ba31d8cbeacfe95d74d79a22b2af913907

data/README.md

@@ -120,6 +120,35 @@ The resulting json will be:
 
 ```
 
+
+### Handling Default Values
+
+With JsonDataExtractor, you can specify default values in your schema for keys that might be absent in the input JSON. Use the `path` and `default` keys in the schema for this purpose.
+
+```ruby
+schema = {
+  absent_value: { path: nil },
+  default: { path: '$.some_real_path', default: 'foo' },
+  default_with_lambda: { path: '$.table', default: -> { 'DEFAULT' } },
+  absent_with_default: { path: nil, default: 'bar' }
+}
+```
+
+- `absent_value`: Will be `nil` in the output as there's no corresponding key in the input JSON and no default is provided.
+- `default`: Will either take the value from `$.some_real_path` in the input JSON or 'foo' if the path does not exist.
+- `default_with_lambda`: Will take the value from `$..table` in the input JSON or 'DEFAULT' if the path does not exist.
+- `absent_with_default`: Will be 'bar' in the output as there's no corresponding key in the input JSON but a default is provided.
+
+#### Simplified Syntax for Absent Values
+
+For keys that you expect to be absent in the input JSON but still want to include in the output with a `nil` value, you can use a simplified syntax by setting the schema value to `nil`.
+
+```ruby
+schema = {
+  absent_value: nil
+}
+```
+
 ### Modifiers
 
 Modifiers can be supplied on object creation and/or added later by calling `#add_modifier` method.
@@ -163,9 +192,91 @@ results = extractor.extract(schema)
 ```
 
 Modifiers are called in the order in which they are defined, so keep that in mind when defining your
-schema. By default JDE raises an ArgumentError if a modifier is not applicable, but this behaviour 
+schema. By default JDE raises an ArgumentError if a modifier is not applicable, but this behaviour
 can be configured to ignore missing modifiers. See Configuration options for details
 
+### Maps
+
+The JsonDataExtractor gem provides a powerful feature called "maps" that allows you to transform
+extracted data using predefined mappings. Maps are useful when you want to convert specific values
+from the source data into different values based on predefined rules. The best use case is when you
+need to traverse a complex tree to get to a value and them just convert it to your own disctionary.
+E.g.:
+
+```ruby
+data = {
+  cars: [
+          { make: 'A', fuel: 1 },
+          { make: 'B', fuel: 2 },
+          { make: 'C', fuel: 3 },
+          { make: 'D', fuel: nil },
+        ]
+}
+
+FUEL_TYPES = { 1 => 'Petrol', 2 => 'Diesel', nil => 'Unknown' }
+schema     = {
+  fuel: {
+    path: '$.cars[*].fuel',
+    map:  FUEL_TYPES
+  }
+}
+result     = JsonDataExtractor.new(data).extract(schema) # => {"fuel":["Petrol","Diesel",nil,"Unknown"]}
+```
+
+A map is essentially a dictionary that defines key-value pairs, where the keys represent the source
+values and the corresponding values represent the transformed values. When extracting data, you can
+apply one or multiple maps to modify the extracted values.
+
+#### Syntax
+
+To define a map, you can use the `map` or `maps` key in the schema. The map value can be a single
+hash or an array of hashes, where each hash represents a separate mapping rule. Here's an example:
+
+```ruby
+{
+  path: "$.data[*].category",
+  map:  {
+    "fruit"     => "Fresh Fruit",
+    "vegetable" => "Organic Vegetable",
+    "meat"      => "Premium Meat"
+  },
+}
+```
+
+Multiple maps can also be provided. In this case, each map is applied to the result of previous
+transformation:
+
+```ruby
+{
+  path: "$.data[*].category",
+  maps: [
+          {
+            "fruit"     => "Fresh Fruit",
+            "vegetable" => "Organic Vegetable",
+            "meat"      => "Premium Meat",
+          },
+          {
+            "Fresh Fruit"       => "Frisches Obst",
+            "Organic Vegetable" => "Biologisches Gemüse",
+            "Premium Meat"      => "Hochwertiges Fleisch",
+          }
+        ]
+}
+```
+
+_(the example is a little bit silly, but you should get the idea of chaining maps)_
+
+You can use keys `:map` and `:maps` interchangeably much like `:modifier`, `:modifiers`.
+
+#### Notes
+
+- Maps can be used together with modifiers but this has less sense as you can always apply complex
+  mapping rules in modifiers themselves.
+- If used together with modifiers, maps are applied **after** modifiers.
+- If a map does not have a key corresponding to a transformed value, it will return nil, be careful
+- Maps are applied in the order they are defined in the schema. Be cautious of the order if you have
+  overlapping or conflicting mapping rules.
+
 ### Nested schemas
 
 JDE supports nested schemas. Just provide your element with a type of `array` and add a `schema` key
@@ -189,26 +300,37 @@ E.g. this is a valid real-life schema with nested data:
   }
 }
 ```
+
 Nested schema can be also applied to objects, not arrays. See specs for more examples.
 
 ## Configuration Options
-The JsonDataExtractor gem provides a configuration option to control the behavior when encountering invalid modifiers.
+
+The JsonDataExtractor gem provides a configuration option to control the behavior when encountering
+invalid modifiers.
 
 ### Strict Modifiers
-By default, the gem operates in strict mode, which means that if an invalid modifier is encountered, an `ArgumentError` will be raised. This ensures that only valid modifiers are applied to the extracted data.
 
-To change this behavior and allow the use of invalid modifiers without raising an error, you can configure the gem to operate in non-strict mode.
+By default, the gem operates in strict mode, which means that if an invalid modifier is encountered,
+an `ArgumentError` will be raised. This ensures that only valid modifiers are applied to the
+extracted data.
+
+To change this behavior and allow the use of invalid modifiers without raising an error, you can
+configure the gem to operate in non-strict mode.
 
 ```ruby
 JsonDataExtractor.configure do |config|
   config.strict_modifiers = false
 end
 ```
-When `strict_modifiers` is set to `false`, any invalid modifiers will be ignored, and the original value will be returned without applying any modification.
 
-It is important to note that enabling non-strict mode should be done with caution, as it can lead to unexpected behavior if there are typos or incorrect modifiers specified in the schema.
+When `strict_modifiers` is set to `false`, any invalid modifiers will be ignored, and the original
+value will be returned without applying any modification.
+
+It is important to note that enabling non-strict mode should be done with caution, as it can lead to
+unexpected behavior if there are typos or incorrect modifiers specified in the schema.
 
-By default, `strict_modifiers` is set to `true`, providing a safe and strict behavior. However, you can customize this configuration option according to your specific needs.
+By default, `strict_modifiers` is set to `true`, providing a safe and strict behavior. However, you
+can customize this configuration option according to your specific needs.
 
 ## TODO
 

data/lib/json_data_extractor.rb

@@ -20,9 +20,18 @@ class JsonDataExtractor
   def extract(schema)
     results = {}
     schema.each do |key, val|
+      default_value = nil
       if val.is_a?(Hash)
         val.transform_keys!(&:to_sym)
         path       = val[:path]
+        default_value = val[:default]
+        maps       = Array([val[:maps] || val[:map]]).flatten.compact.map do |map|
+          if map.is_a?(Hash)
+            map
+          else
+            raise ArgumentError, "Invalid map: #{map.inspect}"
+          end
+        end
         modifiers  = Array(val[:modifiers] || val[:modifier]).map do |mod|
           case mod
           when Symbol, Proc
@@ -38,14 +47,17 @@ class JsonDataExtractor
       else
         path      = val
         modifiers = []
+        maps      = []
       end
 
-      extracted_data = JsonPath.on(@data, path)
+      extracted_data = JsonPath.on(@data, path) if path
 
-      if extracted_data.empty?
-        results[key] = nil
+      if extracted_data.nil? || extracted_data.empty?
+        results[key] = default_value.is_a?(Proc) ? default_value.call : (default_value || nil)
       else
-        results[key] = apply_modifiers(extracted_data, modifiers)
+        extracted_data.map! { |val| val.nil? ? default_value : val }
+        transformed_data = apply_modifiers(extracted_data, modifiers)
+        results[key]     = apply_maps(transformed_data, maps)
 
         if array_type && nested
           results[key] = extract_nested_data(results[key], nested)
@@ -72,6 +84,14 @@ class JsonDataExtractor
     end
   end
 
+  def apply_maps(data, maps)
+    data.map do |value|
+      mapped_value = value
+      maps.each { |map| mapped_value = map[mapped_value] }
+      mapped_value
+    end
+  end
+
   def apply_modifiers(data, modifiers)
     data.map do |value|
       modified_value = value
@@ -96,7 +116,6 @@ class JsonDataExtractor
     end
   end
 
-
   class << self
     def configuration
       @configuration ||= Configuration.new

data/lib/src/version.rb

@@ -1,3 +1,3 @@
 class JsonDataExtractor
-  VERSION = '0.0.11'
+  VERSION = '0.0.13'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: json_data_extractor
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.0.13
 platform: ruby
 authors:
 - Max Buslaev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-07-06 00:00:00.000000000 Z
+date: 2023-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler