db_fuel 1.0.0.pre.alpha → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c90c249149cb9a69ba04ba4fbd9932ced38651dd67fa52710f1f2baf55b965e0
-  data.tar.gz: 2cd95f53e9e16b90aa94aefa36ebe17c3f4ebcd9db308aa2d504327823394f62
+  metadata.gz: 181a57c237b43052c5aa968663e4d3d6d8e6141a3affaf5b0de1ad4147e0725c
+  data.tar.gz: 817df3889c7c39f228cc2a860e19cd1cefb97f9ba23697972e04aa163413b359
 SHA512:
-  metadata.gz: 02b7fa4938884bb81987105fa6be014490a7cbf2c01d58679d9185acae8ded68998b42f3bab854dbdeb9b8b565b9e9b596ad37ce91b0852e702e8ce46d98626d
-  data.tar.gz: ea64e9426e672b57f399d82e0fab173fdcf20319febbfcb6dcee9722d6cf7c645af3bc051d048a227b434b29294b19d2cd0876be9d06c50d0d357506bfc0544d
+  metadata.gz: d8bdbd205ee2c03f2954057f199c58e7d94d2ee64ebcc3735bb4a380dea175be7eb0ed9ac05e1dff12f985f8831e2bb15d76227d61bea0c4e3091b4185cb47d8
+  data.tar.gz: f03df133b8563d7e035654ccaab7c4789a818683dd68a4bf5471d4d7261ea53fcddf989ab5c5e91cbfd3bbc57cb1ed75ab86ec355496571aeb5b816ff4a19f35

data/CHANGELOG.md

@@ -1,6 +1,9 @@
-# 1.0.0 (TBD)
+# 1.0.0 (November 18th, 2020)
 
-Initial implementation.
+Initial implementation.  Includes jobs:
+
+* db_fuel/dbee/query
+* db_fuel/dbee/range
 
 # 0.0.1
 

data/README.md

@@ -1,5 +1,177 @@
-# Db Fuel
+# DB Fuel
 
----
+[![Gem Version](https://badge.fury.io/rb/db_fuel.svg)](https://badge.fury.io/rb/db_fuel) [![Build Status](https://travis-ci.org/bluemarblepayroll/db_fuel.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/db_fuel) [![Maintainability](https://api.codeclimate.com/v1/badges/21945483950d9c35fabb/maintainability)](https://codeclimate.com/github/bluemarblepayroll/db_fuel/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/21945483950d9c35fabb/test_coverage)](https://codeclimate.com/github/bluemarblepayroll/db_fuel/test_coverage) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Under construction.
+This library is a plugin for [Burner](https://github.com/bluemarblepayroll/burner).  Burner, by itself, cannot use a database.  So, if you wish to use a database as a data source or as a target for mutation then you need to add a library similar to this.
+
+## Installation
+
+To install through Rubygems:
+
+````bash
+gem install db_fuel
+````
+
+You can also add this to your Gemfile:
+
+````bash
+bundle add db_fuel
+````
+
+## Jobs
+
+Refer to the [Burner](https://github.com/bluemarblepayroll/burner) library for more specific information on how Burner works.  This section will just focus on what this library directly adds.
+
+* **db_fuel/dbee/query** [model, query, register]:  Pass in a [Dbee](https://github.com/bluemarblepayroll/dbee) model and query and store the results in the specified register.  Refer to the [Dbee](https://github.com/bluemarblepayroll/dbee) library directly on how to craft a model or query.
+* **db_fuel/dbee/range** [key, key_path, model, query, register, separator]: Similar to `db_fuel/dbee/query` with the addition of being able to grab a list of values from the register to use as a Dbee EQUALS/IN filter.  This helps to dynamically limit the resulting record set.  The key is used to specify where to grab the list of values, while the key_path will be used to craft the [Dbee equal's filter](https://github.com/bluemarblepayroll/dbee/blob/master/lib/dbee/query/filters/equals.rb).  Separator is exposed in case nested object support is necessary.
+
+## Examples
+
+### Querying the Database
+
+The `db_fuel/dbee/query` job can be utilized to process a SQL query and store the results in a Burner::Payload register.
+
+Let's say for example we have a list of patients we would like to retrieve:
+
+````ruby
+pipeline = {
+  jobs: [
+    {
+      name: 'retrieve_patients',
+      type: 'db_fuel/dbee/query',
+      model: {
+        name: :patients
+      },
+      query: {
+        fields: [
+          { key_path: :id },
+          { key_path: :first_name }
+        ],
+        sorters: [
+          { key_path: :first_name }
+        ]
+      },
+      register: :patients
+    }
+  ],
+  steps: %w[retrieve_patients]
+}
+
+payload = Burner::Payload.new
+
+Burner::Pipeline.make(pipeline).execute(payload: payload)
+````
+
+If we were to inspect the contents of `payload` we should see the patient's result set loaded:
+
+````ruby
+payload['patients'] # array in form of: [ { "id" => 1, "first_name" => "Something" }, ... ]
+````
+
+### Limiting Result Sets
+
+The `db_fuel/dbee/query` does not provide a way to dynamically connect the query to existing data.  You are free to put any Dbee query filters in the query declaration, but what if you would like to further limit this based on the knowledge of a range of values?  The `db_fuel/dbee/range` job is meant to do exactly this.  On the surface it is mainly an extension of the `db_fuel/dbee/query` job.
+
+Let's say we would like to query patients but we want to limit it to an inputted list of first names:
+
+````ruby
+pipeline = {
+  jobs: [
+    {
+      name: :load_first_names,
+      type: 'b/value/static',
+      register: :patients,
+      value: [
+        { fname: 'Bozo' },
+        { fname: 'Bugs' },
+      ]
+    },
+    {
+      name: 'retrieve_patients',
+      type: 'db_fuel/dbee/range',
+      model: {
+        name: :patients
+      },
+      query: {
+        fields: [
+          { key_path: :id },
+          { key_path: :first_name }
+        ],
+        sorters: [
+          { key_path: :first_name }
+        ]
+      },
+      register: :patients,
+      key: :fname,
+      key_path: :first_name
+    }
+  ],
+  steps: %w[load_first_names retrieve_patients]
+}
+
+payload = Burner::Payload.new
+
+Burner::Pipeline.make(pipeline).execute(payload: payload)
+````
+
+If we were to inspect the contents of `payload` we should see the patient's result set loaded:
+
+````ruby
+payload['patients'] # array in form of: [ { "id" => 1, "first_name" => "Something" }, ... ]
+````
+
+The only difference between the query and range jobs should be the latter is limited based on the incoming first names.
+
+
+## Contributing
+
+### Development Environment Configuration
+
+Basic steps to take to get this repository compiling:
+
+1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (check db_fuel.gemspec for versions supported)
+2. Install bundler (gem install bundler)
+3. Clone the repository (git clone git@github.com:bluemarblepayroll/db_fuel.git)
+4. Navigate to the root folder (cd db_fuel)
+5. Install dependencies (bundle)
+
+### Running Tests
+
+To execute the test suite run:
+
+````bash
+bundle exec rspec spec --format documentation
+````
+
+Alternatively, you can have Guard watch for changes:
+
+````bash
+bundle exec guard
+````
+
+Also, do not forget to run Rubocop:
+
+````bash
+bundle exec rubocop
+````
+
+### Publishing
+
+Note: ensure you have proper authorization before trying to publish new versions.
+
+After code changes have successfully gone through the Pull Request review process then the following steps should be followed for publishing new versions:
+
+1. Merge Pull Request into master
+2. Update `lib/db_fuel/version.rb` using [semantic versioning](https://semver.org/)
+3. Install dependencies: `bundle`
+4. Update `CHANGELOG.md` with release notes
+5. Commit & push master to remote and ensure CI builds master successfully
+6. Run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Code of Conduct
+
+Everyone interacting in this codebase, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bluemarblepayroll/db_fuel/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+This project is MIT Licensed.

data/db_fuel.gemspec

@@ -5,10 +5,10 @@ require './lib/db_fuel/version'
 Gem::Specification.new do |s|
   s.name        = 'db_fuel'
   s.version     = DbFuel::VERSION
-  s.summary     = 'TBD'
+  s.summary     = 'Dbee and ActiveRecord jobs for Burner'
 
   s.description = <<-DESCRIPTION
-    TBD
+    This library adds database-centric jobs to the Burner library.  Burner does not ship with database jobs out of the box.
   DESCRIPTION
 
   s.authors     = ['Matthew Ruggio']

data/lib/db_fuel/library/dbee/base.rb

@@ -16,6 +16,11 @@ module DbFuel
                     :provider,
                     :query
 
+        # Arguments:
+        # - model:    Dbee Model configuration
+        # - query:    Dbee Query configuration
+        # - register: Name of the register to use for gathering the IN clause values and where
+        #             to store the resulting recordset.
         def initialize(
           name:,
           model: {},

data/lib/db_fuel/library/dbee/query.rb

@@ -12,8 +12,8 @@ require_relative 'base'
 module DbFuel
   module Library
     module Dbee
-      # Execute a Dbee Query against a Dbee Model and store the resulting records in the designated
-      # payload register.
+      # Executes a Dbee Query against a Dbee Model and stores the resulting records
+      # in the designated payload register.
       #
       # Expected Payload[register] input: nothing
       # Payload[register] output: array of objects.

data/lib/db_fuel/library/dbee/range.rb

@@ -23,6 +23,15 @@ module DbFuel
                     :key_path,
                     :resolver
 
+        # Arguments:
+        # - key:       Specifies which key to use to aggregate a list of values for within
+        #              the specified register's dataset.
+        # - key_path:  Specifies the Dbee identifier (column) to use for the IN filter.
+        # - model:     Dbee Model configuration
+        # - query:     Dbee Query configuration
+        # - register:  Name of the register to use for gathering the IN clause values and where
+        #              to store the resulting recordset.
+        # - separator: Character to use to split the key-path for nested object support.
         def initialize(
           name:,
           key:,
@@ -58,20 +67,24 @@ module DbFuel
           array(payload[register]).map { |o| resolver.get(o, key) }.compact
         end
 
-        def dynamic_filter(payload)
+        def dynamic_filters(payload)
           values = map_values(payload)
 
-          {
-            type: :equals,
-            key_path: key_path,
-            value: values,
-          }
+          return [] if values.empty?
+
+          [
+            {
+              type: :equals,
+              key_path: key_path,
+              value: values,
+            }
+          ]
         end
 
         def compile_dbee_query(payload)
           ::Dbee::Query.make(
             fields: query.fields,
-            filters: query.filters + [dynamic_filter(payload)],
+            filters: query.filters + dynamic_filters(payload),
             limit: query.limit,
             sorters: query.sorters
           )

data/lib/db_fuel/version.rb

@@ -8,5 +8,5 @@
 #
 
 module DbFuel
-  VERSION = '1.0.0-alpha'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: db_fuel
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.alpha
+  version: 1.0.0
 platform: ruby
 authors:
 - Matthew Ruggio
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-11-15 00:00:00.000000000 Z
+date: 2020-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -212,7 +212,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1'
-description: "    TBD\n"
+description: "    This library adds database-centric jobs to the Burner library.  Burner
+  does not ship with database jobs out of the box.\n"
 email:
 - mruggio@bluemarblepayroll.com
 executables: []
@@ -260,12 +261,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: TBD
+summary: Dbee and ActiveRecord jobs for Burner
 test_files: []