dbee 2.1.0.pre.alpha → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acc518f50b6b9e95165347240882ca415194e6b641e68ff292d5b2a6d3937527
-  data.tar.gz: 954dbcdfac112f2098e7c1828d8c243369092526ee65179c9819ceaafddc70f7
+  metadata.gz: 234c40439102547cc3c8b78cbde5bc3755fcf49d8515c81eed7c7942f1c6a526
+  data.tar.gz: b9bb06a2e773786bb7e19b541f1dd6f104909baeea93148bbde78f9c5965ced8
 SHA512:
-  metadata.gz: 5731c83ec9b0ded7f36c6b07d16597f97337240bd65bbec7dc82a9ca7f4de4da0cac9063a6e9aa9cf8199e6f5c32e7ab0a2904684b64bebde9e996f9bceb8e41
-  data.tar.gz: c47a038d7fac640a620a13373460bbd8df05a35b209264de1b0fedd727eab072925d0f2cfa82a800ddd2362756f887b0cd227d1e1cd01c98a0334b1c3cd55cd0
+  metadata.gz: 3484318a258c8788fa7b08533cb3b27679fc52903e70f2914d4ab8ddd36921fcf628d3f934dbc0704fbf38f1d49c03c087a3c656121d0266083c3c98e41cde75
+  data.tar.gz: 53c8425f56c659f222d729c71855d4c1ecaaa3dd90d21ced647152d49c00bdc5ed2bc550bae7c307f098835a13d165c423685033df6ffee62e3867bfc32c0224

data/.circleci/config.yml

@@ -0,0 +1,71 @@
+version: 2.1
+
+orbs:
+  status_to_ms_teams: bluemarblepayroll/status_to_ms_teams_pure_bash@1.0.0
+
+jobs:
+  build:
+    parameters:
+      use-bundler-cache:
+        type: boolean
+        default: true
+
+    docker:
+      - image: circleci/ruby:2.6.6-buster
+        environment:
+          FORBID_FOCUSED_SPECS: 1
+    working_directory: ~/dbee
+    steps:
+      - checkout
+
+      # TODO: wrap bundler caching logic into an Orb:
+      - when:
+          condition: << parameters.use-bundler-cache >>
+          steps:
+            - restore_cache:
+                key: v1.0.0-build-ruby-dependency-cache-{{ checksum "dbee.gemspec" }}-{{ checksum "Gemfile" }}-{{ checksum ".ruby-version" }}
+
+      - run: bundle install --path vendor/bundle
+
+      - when:
+          condition: << parameters.use-bundler-cache >>
+          steps:
+            - save_cache:
+                key: v1.0.0-build-ruby-dependency-cache-{{ checksum "dbee.gemspec" }}-{{ checksum "Gemfile" }}-{{ checksum ".ruby-version" }}
+                paths:
+                  - vendor/bundle
+
+      - store_artifacts:
+          path: Gemfile.lock
+
+      - run: bundle exec rubocop
+
+      - run: COVERAGE=true bundle exec rspec -r rspec_junit_formatter --format progress --format RspecJunitFormatter -o test-results/rspec/results.xml
+
+      - store_test_results:
+          path: test-results
+
+      - store_artifacts:
+          path: coverage
+
+      - status_to_ms_teams/report:
+          webhook_url: $MS_TEAMS_WEBHOOK_URL
+
+workflows:
+  version: 2.1
+  build:
+    jobs:
+      - build:
+          context: org-global
+  monthly-gem-dependency-refresh-check:
+    triggers:
+      - schedule:
+          cron: '0 0 1 * *'
+          filters:
+            branches:
+              only:
+                - master
+    jobs:
+      - build:
+          context: org-global
+          use-bundler-cache: false

data/.gitignore

@@ -4,3 +4,4 @@
 /coverage
 Gemfile.lock
 /pkg
+.vscode

data/.rubocop.yml

@@ -1,20 +1,15 @@
 AllCops:
   TargetRubyVersion: 2.5
+  NewCops: enable
 
 Layout/LineLength:
   Max: 100
 
-Lint/RaiseException:
-  Enabled: True
-
-Lint/StructNewOverride:
-  Enabled: True
-
 Metrics/AbcSize:
-  Max: 16
+  Max: 20
 
 Metrics/BlockLength:
-  ExcludedMethods:
+  IgnoredMethods:
     - let
     - it
     - describe
@@ -22,17 +17,11 @@ Metrics/BlockLength:
     - specify
     - define
 
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
 Metrics/ClassLength:
   Max: 125
 
 Metrics/MethodLength:
   Max: 25
-
-Style/HashEachMethods:
-  Enabled: True
-
-Style/HashTransformKeys:
-  Enabled: True
-
-Style/HashTransformValues:
-  Enabled: True

data/.tool-versions

@@ -0,0 +1 @@
+ruby 2.6.6

data/CHANGELOG.md

@@ -1,4 +1,24 @@
-# 2.1.0 (TBD)
+# 3.1.0 (October 4th, 2021)
+
+Additions
+
+* Added Query#offset to help with callers needing paging support.
+# 3.0.0 (March 11th, 2021)
+
+### Additions
+
+* Support for graph based models. This paves the way for representing more advanced features, such as sub-queries in a more clear way. Since graph based models are similar to DSL models, the hope is that they will be easier to work with and understand.
+
+### Breaking Changes
+
+* The `to_model` method on `Dbee::Base` objects has been removed. Use `to_schema` instead.
+* The `ancestors!` method on `Dbee::Model` has been removed. Use `Dbee::Schema#expand_query_path` instead.
+
+# 2.1.1 (July 14th, 2020)
+
+* Removed guard that ensured a query has at least one field to establish a more rational base-case.
+
+# 2.1.0 (July 13th, 2020)
 
 ### Additions:
 

data/README.md

@@ -1,6 +1,6 @@
 # Dbee
 
-[![Gem Version](https://badge.fury.io/rb/dbee.svg)](https://badge.fury.io/rb/dbee) [![Build Status](https://travis-ci.org/bluemarblepayroll/dbee.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/dbee) [![Maintainability](https://api.codeclimate.com/v1/badges/208b36a1d13751687df9/maintainability)](https://codeclimate.com/github/bluemarblepayroll/dbee/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/208b36a1d13751687df9/test_coverage)](https://codeclimate.com/github/bluemarblepayroll/dbee/test_coverage) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CircleCI](https://circleci.com/bb/bluemarble-ondemand/dbee/tree/master.svg?style=svg&circle-token=7f7afbea94912b2b75a889cae3e2c46a3a869d21)](https://circleci.com/bb/bluemarble-ondemand/dbee/tree/master)
 
 Dbee arose out of a need for an ad-hoc reporting solution that included:
 
@@ -20,12 +20,12 @@ Both of these solutions ended up closely coupling our domain data layer to ad-ho
 
 ## Installation
 
-This specific library is the core modeling component of the Dbee framework, but by itself, it not completely usable.  You will need to provide a SQL generator which understands how to convert the data and query modeling to actual SQL.  This library comes with a stub: Dbee::Providers::NullProvider, while the main reference implementation is split out into its own library: [dbee-active_record](https://github.com/bluemarblepayroll/dbee-active_record). Together these two libraries comprise a complete solution.  Refer to the other library for more information on installation.
+This specific library is the core modeling component of the Dbee framework, but by itself, it is not completely usable.  You will need to provide a SQL generator which understands how to convert the data and query modeling to actual SQL.  This library comes with a stub: Dbee::Providers::NullProvider, while the main reference implementation is split out into its own library: [dbee-active_record](https://github.com/bluemarblepayroll/dbee-active_record). Together these two libraries comprise a complete solution.  Refer to the other library for more information on installation.
 
 To install through Rubygems:
 
 ````
-gem install install dbee
+gem install dbee
 ````
 
 You can also add this to your Gemfile:
@@ -189,49 +189,58 @@ The two code-first examples above should be technically equivalent.
 You can choose to alternatively describe your data model using configuration.  The YAML below is equivalent to the Ruby sub-classes above:
 
 ````yaml
-name: practice
-models:
-  - name: patients
-    constraints:
-      - type: reference
-        name: practice_id
-        parent: id
-    models:
-      - name: notes
-        constraints:
-          - type: reference
-            name: patient_id
-            parent: id
-      - name: work_phone_number
-        table: phones
-        constraints:
-          - type: reference
-            name: patient_id
-            parent: id
-          - type: static
-            name: phone_number_type
-            value: work
-      - name: cell_phone_number
-        table: phones
-        constraints:
-          - type: reference
-            name: patient_id
-            parent: id
-          - type: static
-            name: phone_number_type
-            value: cell
-      - name: fax_phone_number
-        table: phones
-        constraints:
-          - type: reference
-            name: patient_id
-            parent: id
-          - type: static
-            name: phone_number_type
-            value: fax
+practice:
+  table: practices
+  relationships:
+    patients:
+      model: patient
+      constraints:
+        - type: reference
+          name: practice_id
+          parent: id
+patient:
+  table: patients
+  relationships:
+    notes:
+      model: note
+      constraints:
+        - type: reference
+          name: patient_id
+          parent: id
+    work_phone_number:
+      model: phone_number
+      constraints:
+        - type: reference
+          name: patient_id
+          parent: id
+        - type: static
+          name: phone_number_type
+          value: work
+    cell_phone_number:
+      model: phone_number
+      constraints:
+        - type: reference
+          name: patient_id
+          parent: id
+        - type: static
+          name: phone_number_type
+          value: cell
+    fax_phone_number:
+      model: phone_number
+      constraints:
+        - type: reference
+          name: patient_id
+          parent: id
+        - type: static
+          name: phone_number_type
+          value: fax
+note:
+  table: notes
+phone_number:
+  table: phones
 ````
 
-It is up to you to determine which modeling technique to use as both are equivalent.  Technically speaking, the code-first DSL is nothing more than syntactic sugar on top of Dbee::Model.
+It is up to you to determine which modeling technique to use as both are equivalent.  Technically speaking, the code-first DSL is nothing more than syntactic sugar on top of `Dbee::Schema` and `Dbee::Model`. Also note that prior to version three of this project, a more hierarchical tree based model configuration was used. See [Tree Based Model Backward Compatibility](#tree-based-model-backward-compatibility) below for more information on this.
 
 #### Table Partitioning
 
@@ -275,6 +284,7 @@ Cats:
 The Query API (Dbee::Query) is a simplified and abstract way to model an SQL query.  A Query has the following components:
 
 * fields (SELECT)
+* from (FROM)
 * filters (WHERE)
 * sorters (ORDER BY)
 * limit (LIMIT/TAKE)
@@ -291,6 +301,7 @@ Get all practices:
 
 ````ruby
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id' },
     { key_path: 'active' },
@@ -299,10 +310,11 @@ query = {
 }
 ````
 
-Get all practices, limit to 10, and sort by name (descending) then id (ascending):
+Get all practices, limit to 2, offset by 3, and sort by name (descending) then id (ascending):
 
 ````ruby
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id' },
     { key_path: 'active' },
@@ -312,7 +324,8 @@ query = {
     { key_path: 'name', direction: :descending },
     { key_path: 'id' }
   ],
-  limit: 10
+  limit: 2,
+  offset: 3
 }
 ````
 
@@ -320,6 +333,7 @@ Get top 5 active practices and patient whose name start with 'Sm':
 
 ````ruby
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'name', display: 'Practice Name' },
     { key_path: 'patients.first', display: 'Patient First Name' },
@@ -338,6 +352,7 @@ Get practice IDs, patient IDs, names, and cell phone numbers that starts with '5
 
 ````ruby
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id', display: 'Practice ID #' },
     { key_path: 'patients.id', display: 'Patient ID #' },
@@ -363,6 +378,22 @@ You execute a Query against a Data Model, using a Provider.  The sample provider
 
 Here are some sample executions based off the preceding examples:
 
+##### Base Case
+
+If a query has no fields then it is implied you would like all fields on the root table.  For example:
+
+````ruby
+require 'dbee/providers/active_record_provider'
+
+class Practice < Dbee::Base; end
+
+provider = Dbee::Providers::ActiveRecordProvider.new
+query    = { from: 'practice' }
+sql      = Dbee.sql(Practice, query, provider)
+````
+
+It equivalent to saying: `SELECT practices.* FROM practices`.  This helps to establish a deterministic base-case: it returns the same implicit columns that is independent of sql joins (sorters and/or filters may require sql joins.)
+
 ##### Code-First Execution
 
 ````ruby
@@ -373,6 +404,7 @@ class Practice < Dbee::Base; end
 provider = Dbee::Providers::ActiveRecordProvider.new
 
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id' },
     { key_path: 'active' },
@@ -391,10 +423,11 @@ require 'dbee/providers/active_record_provider'
 provider = Dbee::Providers::ActiveRecordProvider.new
 
 model = {
-  name: :practice
+  practice: { table: 'practices' }
 }
 
 query = {
+  from: 'practice',
   fields: [
     { key_path: 'id' },
     { key_path: 'active' },
@@ -414,19 +447,24 @@ Fields can be configured to use aggregation by setting its `aggregator` attribut
 **Data Model**:
 
 ````yaml
-name: practice
-models:
-  - name: patients
-    constraints:
-      - type: reference
-        name: practice_id
-        parent: id
+practice:
+  table: practices
+  relationships:
+    patients:
+      model: patient
+      constraints:
+        - type: reference
+          name: practice_id
+          parent: id
+patient:
+  table: patients
 ````
 
 **Query**:
 
 ````ruby
 query = {
+  from: 'practice',
   fields: [
     {
       key_path: 'id',
@@ -476,19 +514,21 @@ id | patient_id | key             | value
 **Model Configuration**:
 
 ````yaml
-name: patients
-models:
-  - name: patient_fields
-    constraints:
-      - type: reference
-        parent: id
-        name: patient_id
+patients:
+  relationships:
+    - patient_fields:
+      constraints:
+        - type: reference
+          parent: id
+          name: patient_id
+patient_fields:
 ````
 
 **Query**:
 
 ````ruby
 query = {
+  from: 'patients',
   fields: [
     {
       key_path: 'id',
@@ -530,7 +570,59 @@ ID # | First Name | Date of Birth | Drivers License #
 --   | ---------- | ------------- | -----------------
 1    | frank      | 1900-01-01    | ABC123
 
+## Tree Based Model Backward Compatibility
+
+In version three of this gem, the representation of configuration based models was changed to be more of a graph structure than the previous tree structure. For backwards compatibility, it is still possible to pass this older tree based structure as the first argument `Dbee.sql`. The practices example would be represented this way in the old structure:
+
+````yaml
+  # Deprecated tree based model configuration:
+  name: practice
+  table: practices
+  models:
+    - name: patients
+      constraints:
+        - type: reference
+          name: practice_id
+          parent: id
+      models:
+        - name: notes
+          constraints:
+            - type: reference
+              name: patient_id
+              parent: id
+        - name: work_phone_number
+          table: phones
+          constraints:
+            - type: reference
+              name: patient_id
+              parent: id
+            - type: static
+              name: phone_number_type
+              value: work
+        - name: cell_phone_number
+          table: phones
+          constraints:
+            - type: reference
+              name: patient_id
+              parent: id
+            - type: static
+              name: phone_number_type
+              value: cell
+        - name: fax_phone_number
+          table: phones
+          constraints:
+            - type: reference
+              name: patient_id
+              parent: id
+            - type: static
+              name: phone_number_type
+              value: fax
+````
 
+Also note to further maintain backwards compatibility, queries issued against
+tree based models do not need the "from" attribute to be defined. This is
+because the from/starting point of the query can be inferred as the model at
+the root of the tree.
 ## Contributing
 
 ### Development Environment Configuration
@@ -570,7 +662,7 @@ 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/dbee/version.rb` using [semantic versioning](https://semver.org/)
+2. Update `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

data/dbee.gemspec

@@ -17,15 +17,7 @@ Gem::Specification.new do |s|
   s.test_files  = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.bindir      = 'exe'
   s.executables = []
-  s.homepage    = 'https://github.com/bluemarblepayroll/dbee'
   s.license     = 'MIT'
-  s.metadata    = {
-    'bug_tracker_uri' => 'https://github.com/bluemarblepayroll/dbee/issues',
-    'changelog_uri' => 'https://github.com/bluemarblepayroll/dbee/blob/master/CHANGELOG.md',
-    'documentation_uri' => 'https://www.rubydoc.info/gems/dbee',
-    'homepage_uri' => s.homepage,
-    'source_code_uri' => s.homepage
-  }
 
   s.required_ruby_version = '>= 2.5'
 
@@ -34,9 +26,13 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency('guard-rspec', '~>4.7')
   s.add_development_dependency('pry', '~>0')
+  s.add_development_dependency('pry-byebug')
   s.add_development_dependency('rake', '~> 13')
   s.add_development_dependency('rspec')
-  s.add_development_dependency('rubocop', '~>0.81.0')
-  s.add_development_dependency('simplecov', '~>0.17.0')
+  s.add_development_dependency('rspec_junit_formatter')
+  s.add_development_dependency('rubocop', '~> 1')
+  s.add_development_dependency('rubocop-rake')
+  s.add_development_dependency('rubocop-rspec')
+  s.add_development_dependency('simplecov', '~>0.19.0')
   s.add_development_dependency('simplecov-console', '~>0.7.0')
 end

data/lib/dbee/base.rb

@@ -7,8 +7,8 @@
 # LICENSE file in the root directory of this source tree.
 #
 
-require_relative 'dsl/association'
 require_relative 'dsl/association_builder'
+require_relative 'dsl/association'
 require_relative 'dsl/methods'
 require_relative 'dsl/reflectable'
 
@@ -22,23 +22,9 @@ module Dbee
     BASE_CLASS_CONSTANT = Dbee::Base
 
     class << self
-      # This method is cycle-resistant due to the fact that it is a requirement to send in a
-      # key_chain.  That means each model produced using to_model is specific to a set of desired
-      # fields.  Basically, you cannot derive a Model from a Base subclass without the context
-      # of a Query.  This is not true for configuration-first Model definitions because, in that
-      # case, cycles do not exist since the nature of the configuration is flat.
-      def to_model(key_chain, name = nil, constraints = [], path_parts = [])
-        derived_name  = name.to_s.empty? ? inflected_class_name(self.name) : name.to_s
-        key           = [key_chain, derived_name, constraints, path_parts]
-
-        to_models[key] ||= Model.make(
-          model_config(
-            key_chain,
-            derived_name,
-            constraints,
-            path_parts + [name]
-          )
-        )
+      # Returns the smallest needed Dbee::Schema for the provided key_chain.
+      def to_schema(key_chain)
+        DslSchemaBuilder.new(self, key_chain).to_schema
       end
 
       def inherited_table_name
@@ -58,43 +44,15 @@ module Dbee
         end
       end
 
-      private
-
-      def model_config(key_chain, name, constraints, path_parts)
-        {
-          constraints: constraints,
-          models: associations(key_chain, path_parts),
-          name: name,
-          partitioners: inherited_partitioners,
-          table: inherited_table_name
-        }
-      end
-
-      def associations(key_chain, path_parts)
-        inherited_associations.select { |c| key_chain.ancestor_path?(path_parts, c.name) }
-                              .map do |association|
-          model_constant = association.model_constant
-
-          model_constant.to_model(
-            key_chain,
-            association.name,
-            association.constraints,
-            path_parts
-          )
-        end
+      def inflected_class_name
+        inflector.underscore(inflector.demodulize(name))
       end
 
-      def to_models
-        @to_models ||= {}
-      end
+      private
 
       def inflected_table_name(name)
         inflector.pluralize(inflector.underscore(inflector.demodulize(name)))
       end
-
-      def inflected_class_name(name)
-        inflector.underscore(inflector.demodulize(name))
-      end
     end
   end
 end