json_data_extractor 0.0.10 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be51d8200f061eb267a9c591934a29072729462d242c349c6057e48cb5e77627
-  data.tar.gz: 88213a955399a735f2cd15546d9c0b9ad22ba38de8798e9070d5a35e4a47902f
+  metadata.gz: 0b205c1e3094b426d39161a47261d0d0168244cff62b3c99b557d7f0e286a322
+  data.tar.gz: 3bf7cc322309d9e0c7bb8997eaae41346fbb97e42280a78b5e663c8307ec5311
 SHA512:
-  metadata.gz: f724f3a5b3542644abe1103d8831bdefa0e6bbf2f073d8bfe928cce6f8d42992ecf570527f4adceba4b8a01f12fe0146511ae2ef80301f1a48a52b7e0f5c697a
-  data.tar.gz: e4318e950ec778eb19558cc1a7da37234f730ba977b42ff19f5be4d5b86c8b7a4b8a7e50a85705fa38c89d41d9cb0f39493d8f6c0bfa1e79215956f2e9817528
+  metadata.gz: 7973f7ca4b7575333282cbb0033f6d326b30003b8c36a7f9b7f0be4e7ee6194bbeb712e5abe2446d77e8ab8ffd5b7bf48c9d125a280da4c7d54aa62d11d2c0a8
+  data.tar.gz: 23507463438d1a106da73c0b561912ac16963aa49160563d876883586792c89ca2a2b0531ab236fffb11a45dc2eba0573f012727b28b518cb72ea3b7db35d558

data/README.md

@@ -88,14 +88,16 @@ an optional modifier field that specifies one or more modifiers to apply to the
 Modifiers are used to transform the data in some way before placing it in the output JSON.
 
 Here's an example schema that extracts the authors and categories from a JSON structure similar to
-the one used in the previous example (here it's in YAML just for readability):
-
-```yaml
-schemas:
-  authors:
-    path: $.store.book[*].author
-    modifier: downcase
-  categories: $..category
+the one used in the previous example:
+
+```json
+{
+  "authors": {
+    "path": "$.store.book[*].author",
+    "modifier": "downcase"
+  },
+  "categories": "$..category"
+}
 ```
 
 The resulting json will be:
@@ -161,7 +163,90 @@ results = extractor.extract(schema)
 ```
 
 Modifiers are called in the order in which they are defined, so keep that in mind when defining your
-schema.
+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
 
@@ -187,6 +272,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.
+
+### 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.
+
+```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.
+
+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
 
 Update this readme for better usage cases. Add info on arrays and modifiers.

data/lib/json_data_extractor.rb

@@ -1,4 +1,5 @@
 require 'src/version'
+require 'src/configuration'
 require 'jsonpath'
 
 class JsonDataExtractor
@@ -22,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
@@ -37,6 +45,7 @@ class JsonDataExtractor
       else
         path      = val
         modifiers = []
+        maps      = []
       end
 
       extracted_data = JsonPath.on(@data, path)
@@ -44,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)
@@ -71,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
@@ -88,8 +106,20 @@ class JsonDataExtractor
       modifiers[modifier].call(value)
     elsif value.respond_to?(modifier)
       value.send(modifier)
+    elsif self.class.configuration.strict_modifiers
+      raise ArgumentError, "Invalid modifier: :#{modifier}"
     else
       value
     end
   end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
 end

data/lib/src/configuration.rb

@@ -0,0 +1,9 @@
+class JsonDataExtractor
+  class Configuration
+    attr_accessor :strict_modifiers
+
+    def initialize
+      @strict_modifiers = true
+    end
+  end
+end

data/lib/src/version.rb

@@ -1,3 +1,3 @@
 class JsonDataExtractor
-  VERSION = '0.0.10'
+  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.10
+  version: 0.0.12
 platform: ruby
 authors:
 - Max Buslaev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-05-12 00:00:00.000000000 Z
+date: 2023-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -116,6 +116,7 @@ files:
 - bin/setup
 - json_data_extractor.gemspec
 - lib/json_data_extractor.rb
+- lib/src/configuration.rb
 - lib/src/version.rb
 homepage: https://github.com/austerlitz/json_data_extractor
 licenses: