etcher 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16f4335440726392076ca31e69cd180b72ba62a0251f53df1d03360a4e457c3a
-  data.tar.gz: 0c471d6980811751707ee8f1db95b3a8d8c58c29b3a486138e9608d4649f1f9f
+  metadata.gz: 4a7381f41e75ad83f44a491f33f396be3ffb5b401a1a72fdcef2086984424fff
+  data.tar.gz: '09b9c86d96af82fbc821e23c92e7966c97234e61625d3d23838471b930906629'
 SHA512:
-  metadata.gz: d99e98d45fca9aef28ebda93b18a19ee5d29a03b723377a5ae17aa6bc37af096b1760b8c9a025347f41ee88f659017e451c9d1c414bdca2b1c29a7b2ffb61392
-  data.tar.gz: 85af46afc0a618d7ea121743e7868d1a5f2b0a186fd0efcb26aefbd2ec7c75aa4ca2fcd87d4737476ec17f996321432a53a355cb9a115c6e13974fddd15ac189
+  metadata.gz: 3d3008b4581dfd66426ba9e9c2ed0158241d130c2e68372f124369dd42c5893fed86aff36fe9e1b14612fff2139f39cf7e4b07492b5faac13699a3f0d87f609c
+  data.tar.gz: 885d3f522cefba39eeb8765fe671ea822d52edefc700d1633997825fd7cb61c834db7d6111cbd92881c5c9d232519e70bb4aa120027cc6ad432e82286d15fb99

data/README.adoc

@@ -4,7 +4,6 @@
 
 :data_link: link:https://alchemists.io/articles/ruby_data[Data]
 :demeter_link: link:https://en.wikipedia.org/wiki/Law_of_Demeter[Law of Demeter]
-:dry_container_link: link:https://dry-rb.org/gems/dry-container[Dry Container]
 :dry_monads_link: link:https://dry-rb.org/gems/dry-monads[Dry Monads]
 :dry_schema_link: link:https://dry-rb.org/gems/dry-schema[Dry Schema]
 :dry_types_link: link:https://dry-rb.org/gems/dry-types[Dry Types]
@@ -13,10 +12,10 @@
 :gitt_link: link:https://alchemists.io/projects/gitt[Gitt]
 :hash_link: link:https://rubyapi.org/o/hash[Hash]
 :json_link: link:https://rubyapi.org/o/json[JSON]
+:pipeable_link: link:https://alchemists.io/projects/pipeable[Pipeable]
 :runcom_link: link:https://alchemists.io/projects/runcom[Runcom]
 :sod_link: link:https://alchemists.io/projects/sod[Sod]
 :struct_link: link:https://alchemists.io/articles/ruby_structs[Struct]
-:transactable_link: link:https://alchemists.io/projects/transactable[Transactable]
 :versionaire_link: link:https://alchemists.io/projects/versionaire[Versionaire]
 :xdg_link: link:https://alchemists.io/projects/xdg[XDG]
 :yaml_link: link:https://rubyapi.org/o/yaml[YAML]
@@ -29,7 +28,7 @@ ____
 [Use] strong acid or mordant to cut into the unprotected parts of a metal surface to create a design in intaglio (incised) in the metal.
 ____
 
-By using Etcher, you have a reliable way to load default configurations (i.e. {environment_link}, {json_link}, {yaml_link}) which can be validated and etched into _frozen_ records (i.e. {hash_link}, {data_link}, {struct_link}) for consumption within your application which doesn't violate the {demeter_link}. This comes complete with transformations and validations all via a simple Object API. Pairs well with the {xdg_link}, {runcom_link}, and {sod_link} gems.
+By using Etcher, you have a reliable way to load default configurations (i.e. {environment_link}, {json_link}, {yaml_link}) which can be validated and etched into _frozen_ records (i.e. {hash_link}, {data_link}, {struct_link}) for consumption within your application which doesn't violate the {demeter_link}. This comes complete with transformations and validations all via a simple Object API and pairs well with the {xdg_link}, {runcom_link}, and {sod_link} gems.
 
 toc::[]
 
@@ -89,7 +88,7 @@ etcher.call({one: 1, two: 2})
 # Success({:one=>1, :two=>2})
 ----
 
-Notice you get a monad -- either a `Success` or `Failure` -- as provided by the {dry_monads_link} gem. This allows you to create more sophisticated pipelines as found with the {transactable_link} gem or any kind of failsafe workflow you might need.
+Notice you get a monad -- either a `Success` or `Failure` -- as provided by the {dry_monads_link} gem. This allows you to create more sophisticated pipelines as found with the {pipeable_link} gem or any kind of failsafe workflow you might need.
 
 By default, any attributes you message the instance with will only pass through what you gave it and always answer a `Success`. This is nice for initial experimentation but true power comes with full customization of the instance. Here's an advanced configuration showing all features:
 
@@ -107,8 +106,8 @@ end
 
 model = Data.define :user, :home
 
-transformer = lambda do |content, key = :user|
-  Dry::Monads::Success content.merge! key => content[key].upcase
+transformer = lambda do |attributes, key = :user|
+  Dry::Monads::Success attributes.merge! key => attributes[key].upcase
 end
 
 Etcher::Registry.new(contract:, model:, transformers: [transformer])
@@ -123,7 +122,7 @@ The above can be broken down into a series of steps:
 . A {dry_schema_link} contract -- loaded with {dry_monads_link} extensions -- is created to verify untrusted attributes.
 . A model is created with attributes: `user` and `home`.
 . A registry is constructed with a custom contract, model, loader, and transformer.
-. Finally, we see a _successfully_ built configuration for further use.
+. Finally, we see a _successfully_ built configuration for further use within your application.
 
 While this is a more advanced use case, you'll usually only need to register a contract and model. The loaders and transformers provide additional firepower in situations where you need to do more with your data. We'll look at each of these components in greater detail next.
 
@@ -133,11 +132,11 @@ While this is a more advanced use case, you'll usually only need to register a c
 
 As hinted at above, the complete sequence of steps are performed in the order listed:
 
-. *Load*: Each loader, if any, is called and merged with the previous loader to build initial content.
-. *Override*: Any overrides are merged with the result of the last loader to produce updated content. _In Version 2.0.0, this step happen after the Transform step._
-. *Transform*: Each transformer, if any, is called to transform and manipulate the content.
-. *Validate*: The contract is called to validate the content as previously loaded, overwritten, and transformed.
-. *Model*: The model consumes the content of the validated contract and creates a new record for you to use as needed.
+. *Load*: Each loader, if any, is called and merged with the previous loader to build initial attributes.
+. *Override*: Any overrides are merged with the result of the last loader to produce updated attributes. ⚠️ _In Version 2.0.0, this step will happen after the Transform step._
+. *Transform*: Each transformer, if any, is called to transform and manipulate the attributes.
+. *Validate*: The contract is called to validate the attributes as previously loaded, overwritten, and transformed.
+. *Model*: The model consumes the attributes of the validated contract and creates a new record for you to use as needed.
 
 You can use the above steps as a reference when using this gem. Each step is explained in greater detail below.
 
@@ -151,7 +150,7 @@ Etcher::Registry.new
 # #<data Etcher::Registry contract=#<Proc:0x000000010e393550 contract.rb:7 (lambda)>, model=Hash, loaders=[], transformers=[]>
 ----
 
-Since the registry is a {data_link}, you can initialize with everything you need:
+Since the registry is {data_link}, you can initialize with everything you need:
 
 [source,ruby]
 ----
@@ -176,11 +175,11 @@ registry = Etcher::Registry.new
 
 === Contracts
 
-Contracts are critical piece of this workflow as they provide a way to validate incoming data, remove unwanted data, and create a sanitized record for use in your application. Any contract that has the following behavior will work:
+Contracts are a critical piece of this workflow as they provide a way to validate incoming data, remove unwanted data, and create a sanitized record for use in your application. Any contract that has the following behavior will work:
 
 * `#call`: Must be able to consume a {hash_link} and answer an object which can respond to `#to_monad`.
 
-The best gems which adhere to this interface are: {dry_schema_link} and {dry_validation_link}. You'll also want to make sure the {dry_monads_link} extensions are loaded as briefly shown earlier so the result will respond to `#to_monad`. Here's how to enable monad support if using both gems:
+The best gems which adhere to this interface are: {dry_schema_link} and {dry_validation_link}. You'll also want to make sure the {dry_monads_link} extensions are loaded, as briefly shown earlier, so the result will respond to `#to_monad`. Here's how to enable monad support if using both gems:
 
 [source,ruby]
 ----
@@ -210,7 +209,7 @@ etcher.call from: "Mork", to: "Mindy"
 # Success({:from=>"Mork", :to=>"Mindy"})
 ----
 
-Here you can see the power of using a contract to validate your data both as a failure and a success. Unfortunately, with the success, we only get a {hash_link} as a record and it would be nice to structured model which which we'll look at next.
+Here you can see the power of using a contract to validate your data both as a failure and a success. Unfortunately, with the success, we only get a {hash_link} as a record and it would be nice to structured record which will be explained shortly.
 
 === Types
 
@@ -268,7 +267,7 @@ model = Data.define :from, :to
 etcher = Etcher::Registry[model:].then { |registry| Etcher.new registry }
 
 etcher.call
-# Failure({:step=>:record, :payload=>"Missing keywords: :from, :to."})
+# Failure({:step=>:model, :payload=>"Missing keywords: :from, :to."})
 
 etcher.call from: "Mork", to: "Mindy"
 # Success(#<data Model from="Mork", to="Mindy">)
@@ -345,7 +344,7 @@ loader = Etcher::Loaders::JSON.new "your/path/to/configuration.json",
 loader.call  # Success({})
 ----
 
-If the file did exist and had content, you'd get a `Success` with a `Hash` of the contents.
+Otherwise, if the file exists with content, you'll get a `Hash` wrapped as a `Success`.
 
 ℹ️ The logger is only used to log debug information when issues are encountered when reading from the file. This is done to reduce noise in your console when a configuration might have issues and can safely revert to the fallback in order to load the rest of the configuration.
 
@@ -370,7 +369,7 @@ loader = Etcher::Loaders::YAML.new "your/path/to/configuration.yml",
 loader.call  # Success({})
 ----
 
-If the file did exist and had content, you'd get a `Success` with a `Hash` of the contents.
+Otherwise, if the file exists with content, you'll get a `Hash` wrapped as a `Success`.
 
 ℹ️ The logger is only used to log debug information when issues are encountered when reading from the file. This is done to reduce noise in your console when a configuration might have issues and can safely revert to the fallback in order to load the rest of the configuration.
 
@@ -418,9 +417,9 @@ registry = Etcher::Registry.new.add_transformer MyTransformer
 Here are a few guidelines to using them:
 
 * They can be initialized with whatever requirements you might need.
-* They must respond to `#call` which takes a required `content` positional argument and answers a modified representation of this content as a monad with a `Hash` for content.
-* A second _optional_ positional `key` parameter should follow your `content` parameter when implementing your transformer. This allows you to quickly refactor the key later while also reducing key duplication throughout your implementation.
-* The `content` passed to your transformer will have symbolized keys so you don't need to do this yourself.
+* They must respond to `#call` which takes a required `attributes` positional argument and answers a modified version of these attributes (`Hash`) wrapped as a monad.
+* A second _optional_ positional `key` parameter should follow your `attributes` parameter when implementing your transformer. This allows you to quickly refactor the key later while also reducing key duplication throughout your implementation.
+* The `attributes` passed to your transformer will have symbolized keys so you don't need to transform them further.
 
 Here are a few examples of where you could go with this:
 
@@ -430,7 +429,7 @@ The following capitalizes all values (which may or may not be good depending on
 ----
 require "dry/monads"
 
-Capitalize = -> content { Dry::Monads::Success content.transform_values!(&:capitalize) }
+Capitalize = -> attributes { Dry::Monads::Success attributes.transform_values!(&:capitalize) }
 Capitalize.call(name: "test")
 
 # Success({:name=>"Test"})
@@ -442,9 +441,9 @@ The following updates current time relative to when configuration was transforme
 ----
 require "dry/monads"
 
-CurrentTime = lambda do |content, key = :at, at: Time.now|
-  content.fetch(key) { at }
-         .then { |value| Dry::Monads::Success content.merge!(key => value) }
+CurrentTime = lambda do |attributes, key = :at, at: Time.now|
+  attributes.fetch(key) { at }
+            .then { |value| Dry::Monads::Success attributes.merge!(key => value) }
 end
 
 CurrentTime.call({})
@@ -470,7 +469,7 @@ class GitEmail
     @git = git
   end
 
-  def call(content) = git.get("user.email").fmap { |value| content[key] = value }
+  def call(attributes) = git.get("user.email").fmap { |value| attributes[key] = value }
 
   private
 
@@ -517,7 +516,7 @@ Etcher.call name: "demo"
 # {:name=>"demo"}
 ----
 
-When called _and there are no issues_, you'll get the fully formed record as a result (in this case a Hash which is the default model). You'll never a get a monad when using `Etcher.call` because this is meant to resolve the monadic pipeline for you. If any failure is encountered, then Etcher will _abort_ with a fatal log message. Here's a variation of earlier examples which demonstrates fatal errors:
+When called -- and there are no issues -- you'll get the fully formed record as a result (in this case a Hash which is the default model). You'll never a get a monad when using `Etcher.call` because this is meant to resolve the monadic pipeline for you. If any failure is encountered, then Etcher will _abort_ with a fatal log message. Here's a variation of earlier examples which demonstrates fatals:
 
 [source,ruby]
 ----

data/etcher.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "etcher"
-  spec.version = "1.2.0"
+  spec.version = "1.4.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/etcher"

data/lib/etcher/builder.rb

@@ -16,42 +16,39 @@ module Etcher
     end
 
     def call(**overrides)
-      load(overrides.symbolize_keys!).then { |content| transform content }
-                                     .bind { |content| validate content }
-                                     .bind { |content| record content }
+      load(overrides.symbolize_keys!).then { |attributes| transform attributes }
+                                     .bind { |attributes| validate attributes }
+                                     .bind { |attributes| model attributes }
     end
 
     private
 
     attr_reader :registry
 
-    # :reek:NestedIterators
-    # :reek:TooManyStatements
     def load overrides
       registry.loaders
-              .map { |loader| loader.call.fmap { |content| content.flatten_keys.symbolize_keys! } }
+              .map { |loader| loader.call.fmap { |pairs| pairs.flatten_keys.symbolize_keys! } }
               .each
-              .with_object({}) { |content, all| content.bind { |body| all.merge! body } }
+              .with_object({}) { |attributes, all| attributes.bind { |body| all.merge! body } }
               .merge!(overrides.flatten_keys)
-              .then { |content| Success content }
+              .then { |attributes| Success attributes }
     end
 
-    # :reek:NestedIterators
-    def transform content
-      registry.transformers.reduce content do |all, transformer|
+    def transform attributes
+      registry.transformers.reduce attributes do |all, transformer|
         all.bind { |body| transformer.call body }
       end
     end
 
-    def validate content
+    def validate attributes
       registry.contract
-              .call(content)
+              .call(attributes)
               .to_monad
               .or { |result| Failure step: __method__, payload: result.errors.to_h }
     end
 
-    def record content
-      Success registry.model[**content.to_h].freeze
+    def model attributes
+      Success registry.model[**attributes.to_h].freeze
     rescue ArgumentError => error
       Failure step: __method__, payload: "#{error.message.capitalize}."
     end

data/lib/etcher/contract.rb

@@ -4,8 +4,8 @@ require "dry/monads"
 
 module Etcher
   # A simple passthrough contract.
-  Contract = lambda do |content|
-    def content.to_monad = Dry::Monads::Success self unless content.respond_to? :to_monad
-    content
+  Contract = lambda do |result|
+    def result.to_monad = Dry::Monads::Success self unless result.respond_to? :to_monad
+    result
   end
 end

data/lib/etcher/resolver.rb

@@ -18,7 +18,7 @@ module Etcher
 
     def call(**overrides)
       case builder.call(**overrides)
-        in Success(content) then content
+        in Success(attributes) then attributes
         in Failure(step:, payload: String => payload)
           logger.fatal { "Build failure: #{step.inspect}. #{payload}" }
           kernel.abort

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: etcher
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-03-03 00:00:00.000000000 Z
+date: 2024-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -182,7 +182,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.5.10
 signing_key:
 specification_version: 4
 summary: A monadic configuration loader, transformer, and validator.