etcher 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34d9eedad8aac01a9cc35426821d3e8893d312f03c21aa22a75ceb808347248f
-  data.tar.gz: a24eaa182c934a5974031e5ab3502c5bc7ae927ab7323989626c86923839e6af
+  metadata.gz: 4c9a9da371f697c41f455434c269b2230dc07ae9f9342d009c4f562e4a047a57
+  data.tar.gz: 2daffd0030266da21a1192a1031358f098f3523852e0857a9195009d18598b5a
 SHA512:
-  metadata.gz: 92e846388ce7fa423218b12db7c7082cdc4b9907bdfeebe6f0a86143ca0f3b82d053f35a6987a91d884bac2d9c9612d65abd5f764b41a8a423fc17837d842fe2
-  data.tar.gz: a7b0025873525c4e907ed455d5b5403bad83eac37d45710b62cc24339d75d22022797b18e42e92d51d72e6861da664854420ad8f901623d2f853054c866d4c8c
+  metadata.gz: 968e58e3c5f1fa21ae898d6d71fb3fca3134b368a6bdb85eaa397ca92d19e7de255ec1ae0bb8f31710d53163defeaace018b93eb52b41ac25ed47d6af9e35f1a
+  data.tar.gz: 99eea4d38800458cd1d674e250c09764bde7e32a34cf27eaeb33b640b3650346b9ddcb7687f6800553eca891ac209e29c33f5b71b6331abb56a8ce01b7f49371

checksums.yaml.gz.sig

@@ -1,4 +1,3 @@
-y�k�?�_̑$$�<o,��x"W��|j��?6�qu�7�]#�Qņ��^
-\�`�$�ٷn���X��'�1VN���TJ �����a�����<N�}�mp�-��?7Xˡ*ˡ
-6�>:b�|�6�>�-�����l��Nڰ���d�u �t����귽�mG@e��`�o�6�0�Aqa/��i�i���������;_#/J���RK�d�{�_9�Tpj��XE~v�r��*
-��ۤ�����И]�6��Qz�9����8Y<�U��c�W��8u3�_�
+�W�
+=t�ɘk�1
+
���TSƳ���\e�?en
y#:\�#/�ݥs��@��=� '�=�h�CwC���>���������\R,w��YF�fC����3��P����ܡ����(��gc�_U�v�ߐ�)m~�Zs��hML(|��t,�d�Yqa���mD�)6��%��_�
*���<�ԕ����`<��gI�d!��O:R�َ�#!�\��N�FI������S�pU6��Ф���SN`�MP�A�d���=

data/README.adoc

@@ -14,6 +14,7 @@
 :hash_link: link:https://rubyapi.org/o/hash[Hash]
 :json_link: link:https://rubyapi.org/o/json[JSON]
 :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]
 :xdg_link: link:https://alchemists.io/projects/xdg[XDG]
@@ -27,17 +28,17 @@ ____
 [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 turned into records (i.e. {hash_link}, {data_link}, {struct_link}) for consumption within your application. In other words, the ability to take primitive hashes and _etch_ them into a _frozen_ record with a nice interface that doesn't violate the {demeter_link}. This comes complete with transformations and validations all via a simple Object API. Finally, this pairs well with the {xdg_link} and {runcom_link} gems, Command Line Interfaces (CLIs), Application Programming Interfaces (APIs), or any application that can be configured by the user.
+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 turned into records (i.e. {hash_link}, {data_link}, {struct_link}) for consumption within your application. In other words, the ability to take primitive hashes and _etch_ them into a _frozen_ record with a nice interface that doesn't violate the {demeter_link}. This comes complete with transformations and validations all via a simple Object API. Finally, this pairs well with the {xdg_link}, {runcom_link}, and {sod_link} gems.
 
 toc::[]
 
 == Features
 
-* Supports contracts which respond to `#call` to validate a {hash_link} before building the final record. This works extremely well with the {dry_schema_link} and {dry_validation_link} gems.
-* Supports models which respond to `.[]` for consuming a splatted {hash_link} to instantiate new records. This works extremely well with primitives such as: {hash_link}, {data_link}, and {struct_link}.
+* Supports contracts which respond to `#call` to validate a {hash_link} before building the final record. This pairs well with the {dry_schema_link} and {dry_validation_link} gems.
+* Supports models which respond to `.[]` for consuming a splatted {hash_link} to instantiate new records. This pairs well with primitives such as: {hash_link}, {data_link}, and {struct_link}.
 * Supports loading of default configurations from the {environment_link}, a {json_link} configuration, a {yaml_link} configuration, or anything that can answer a hash.
 * Supports multiple transformations which can process loaded configuration hashes and answer a transformed hash.
-* Supports {hash_link} overrides as a final customization which is handy for Command Line Interfaces (CLI) or anything that might require user input at runtime.
+* Supports {hash_link} overrides as a final customization which is handy for Command Line Interfaces (CLIs), as aided by {sod_link}, or anything that might require user input at runtime.
 
 == Requirements
 
@@ -87,7 +88,9 @@ 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. The only problem is -- 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:
+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.
+
+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:
 
 [source,ruby]
 ----
@@ -120,6 +123,8 @@ The above can be broken down into a series of steps:
 
 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.
 
+ℹ️ All keys are converted to symbols before being processed. This is done to ensure consistency and improve debugablity when dealing with raw input that might be a mix of strings and/or symbols.
+
 === Registry
 
 The registry is provided as a way to register any/all complexity for before creating a new Etcher instance. Here's what you get by default:
@@ -155,7 +160,7 @@ registry = Etcher::Registry.new
 
 === Contracts
 
-Contracts are critical piece of this workflow as they provide a way to validate incoming data, strip out unwanted data, and create a sanitized record for use in your application. Any contract that has the following behavior will work:
+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:
 
 * `#call`: Must be able to consume a {hash_link} and answer an object which can respond to `#to_monad`.
 
@@ -240,12 +245,23 @@ Notice we get an failure if all attributes are not provided but if we supply the
 
 === Loaders
 
-Loaders are a great way to load _default_ configuration information for your application which can be in multiple formats. There are a few guidelines to using them:
+Loaders are a great way to load _default_ configuration information for your application which can be in multiple formats. Loaders can either be defined when creating a new registry instance or added after the fact. Here are a few examples:
+
+[source,ruby]
+----
+# Initializer
+registry = Etcher::Registry[loaders: [MyLoader.new]]
+
+# Method
+registry = Etcher::Registry.new.add_loader MyLoader.new
+----
+
+There are a few guidelines to using them:
 
 * They must respond to `#call` with no arguments.
 * All keys are symbolized which helps streamline merging and overriding values from the same keys across multiple configurations.
 * All nested keys will be flattened after being loaded. This means a key structure of `{demo: {one: "test"}}` will be flattened to `demo_one: "test"` which adheres to the {demeter_link} when a new recored is _etched_ for you.
-* The order in which you define your loaders matters. This means the first loader defined will be processed first, then the second, and so forth. Loaders defined last take precedence over loaders defined first when overriding the same keys.
+* The order in which you define your loaders matters. This means the first loader defined will be processed first, then the second, and so forth. Loaders defined last take precedence over previously defined loaders when overriding the same keys.
 
 The next couple of sections will help you learn about the supported loaders and how to build your own custom loader.
 
@@ -353,10 +369,22 @@ While the above isn't super useful since it only answers whatever you provide as
 
 === Transformers
 
-Transformers are great for modifying specific keys and values. They give you finer grained control over your configuration and are the last step before validating and creating an associated record of your configuration. There are a few guidelines to using them:
+Transformers are great for modifying specific keys and values. They give you finer grained control over your configuration and are the last step before validating and creating an associated record of your configuration. Transformers can either be defined when creating a new registry instance or added after the fact. Here are a few examples:
+
+[source,ruby]
+----
+# Initializer
+registry = Etcher::Registry[transformers: [MyTransformer]]
+
+# Method
+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 single argument (i.e. `content`) and answers a modified representation of this content as a `Success` with a `Hash` for content.
+* The `content` passed to your transformer will have symbolized keys.
 
 Here are a few examples of where you could go with this:
 

data/etcher.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "etcher"
-  spec.version = "0.1.0"
+  spec.version = "0.2.1"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/etcher"
@@ -23,11 +23,11 @@ Gem::Specification.new do |spec|
   spec.cert_chain = [Gem.default_cert_path]
 
   spec.required_ruby_version = "~> 3.2"
-  spec.add_dependency "cogger", "~> 0.9"
+  spec.add_dependency "cogger", "~> 0.10"
   spec.add_dependency "core", "~> 0.1"
   spec.add_dependency "dry-monads", "~> 1.6"
   spec.add_dependency "dry-types", "~> 1.7"
-  spec.add_dependency "refinements", "~> 10.0"
+  spec.add_dependency "refinements", "~> 11.0"
   spec.add_dependency "zeitwerk", "~> 2.6"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]

data/lib/etcher/builder.rb

@@ -47,7 +47,7 @@ module Etcher
       registry.contract
               .call(content)
               .to_monad
-              .or { |result| Failure(step: __method__, payload: result.errors.to_h) }
+              .or { |result| Failure step: __method__, payload: result.errors.to_h }
     end
 
     def record content

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: etcher
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-05-05 00:00:00.000000000 Z
+date: 2023-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: core
   requirement: !ruby/object:Gem::Requirement
@@ -99,14 +99,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '11.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '11.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -168,7 +168,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.12
+rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
 summary: A monadic configuration loader, transformer, and validator.