json_data_extractor 0.0.11 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aeef2dddd8e11795c682d9db785b955164fbab87e4dc1c63843ba02a76b65905
-  data.tar.gz: e17a062f72e0ae56bc09b42ccaa237c12149b667b63dfb0e58a60dd3ea8e5830
+  metadata.gz: 0b205c1e3094b426d39161a47261d0d0168244cff62b3c99b557d7f0e286a322
+  data.tar.gz: 3bf7cc322309d9e0c7bb8997eaae41346fbb97e42280a78b5e663c8307ec5311
 SHA512:
-  metadata.gz: b574bc9f7c79a4405d7b86739e1bf50e0ccbc82f1016befedf3e5bbb0da040db263492ee8978cd3d83957546d47338980bcfba80770a620a9c637937675bad46
-  data.tar.gz: 2a83cf29049a8c4205851a83e12e0867f42ae684564c6bc7ae9e183b4399f9a2390f9be36724f137064bf8e76f74b30d977539fdb1c620972c05a949f19883f2
+  metadata.gz: 7973f7ca4b7575333282cbb0033f6d326b30003b8c36a7f9b7f0be4e7ee6194bbeb712e5abe2446d77e8ab8ffd5b7bf48c9d125a280da4c7d54aa62d11d2c0a8
+  data.tar.gz: 23507463438d1a106da73c0b561912ac16963aa49160563d876883586792c89ca2a2b0531ab236fffb11a45dc2eba0573f012727b28b518cb72ea3b7db35d558

data/README.md

@@ -163,9 +163,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     = described_class.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 +271,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

@@ -23,6 +23,13 @@ class JsonDataExtractor
       if val.is_a?(Hash)
         val.transform_keys!(&:to_sym)
         path       = val[:path]
+        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,6 +45,7 @@ class JsonDataExtractor
       else
         path      = val
         modifiers = []
+        maps      = []
       end
 
       extracted_data = JsonPath.on(@data, path)
@@ -45,7 +53,8 @@ class JsonDataExtractor
       if extracted_data.empty?
         results[key] = nil
       else
-        results[key] = apply_modifiers(extracted_data, modifiers)
+        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 +81,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 +113,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.12'
 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.12
 platform: ruby
 authors:
 - Max Buslaev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-07-06 00:00:00.000000000 Z
+date: 2023-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler