repository-base 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2769d07ba1f7cb1de214818a131ff6743a56c93254278d2f4fdbba87d5e15845
+  data.tar.gz: f41460497cb374c7eec66a1440ba7509a61371b92d71b49dc1d550cf1ee2996a
+SHA512:
+  metadata.gz: 73d5aad44196d642b1ab3f4e3d496569d79cc004f819c893bea69d0280e8ad52c33d73fba7549ddaba7821ec670c64b4abd2c37e52185f619f26a8b5e7ee6227
+  data.tar.gz: 3ab7d049341d50c94dce4b51b2a0b015470e3f6dfc9975e563d8aa04e0cc53620b0ad4090babd661d746a7234963bf4f89ac90d68a7d18c3cfbe02e57bb93d4e

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.rbenv-gemsets
+.yardoc

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,27 @@
+
+AllCops:
+  TargetRubyVersion: 2.5
+
+Metrics/BlockLength:
+  Max: 500
+  Include:
+    - 'spec/**/*_spec.rb'
+
+Metrics/ModuleLength:
+  Max: 500
+  Include:
+    - 'spec/**/*_spec.rb'
+
+Style/CommentedKeyword:
+  Enabled: false
+
+# This silences 'Missing top-level class documentation comment.', which we
+# particularly want to do on (initially-)generated files.
+Style/Documentation:
+  Enabled: false
+  Include:
+    - 'apps/**/*.rb'
+    - 'lib/**/*.rb'
+
+Rails/DynamicFindBy:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.2.1
+  - rbx
+  - 2.1.5
+

data/.yardopts

@@ -0,0 +1 @@
+--private --protected lib/repository/base.rb lib/repository/base/internals/internals.rb lib/repository/base/internals/record_deleter.rb lib/repository/base/internals/record_saver.rb lib/repository/base/internals/record_updater.rb lib/repository/base/internals/slug_finder.rb lib/repository/base/version.rb - CHANGELOG.md README.md

data/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Change Log
+
+## [v0.4.0](https://github.com/jdickey/repository-base/tree/v0.3.0) (2018-02-03)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.2.0...v0.3.0)
+
+* Added [YARD-generated documentation](./doc/index.html)
+* Updated Ruby version to 2.5.0;
+* Updated developer dependencies to now-current versions;
+* Made trivial code changes to satisfy static-analysis tools. Tests still green.
+
+## [v0.3.0](https://github.com/jdickey/repository-base/tree/v0.3.0) (2015-03-30)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.2.0...v0.3.0)
+
+**Fixed bugs:**
+
+- Adding an entity? Its attributes may not always be a Hash. [\#19](https://github.com/jdickey/repository-base/issues/19)
+
+**Merged pull requests:**
+
+- Support entity attributes conversion. Also, merge fixed Travis into master. [\#20](https://github.com/jdickey/repository-base/pull/20) ([jdickey](https://github.com/jdickey))
+
+## [v0.2.0](https://github.com/jdickey/repository-base/tree/v0.2.0) (2015-02-22)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.1.2...v0.2.0)
+
+**Fixed bugs:**
+
+- Public methods should return entities, not DAO records. [\#18](https://github.com/jdickey/repository-base/issues/18)
+
+## [v0.1.2](https://github.com/jdickey/repository-base/tree/v0.1.2) (2015-02-20)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.1.1...v0.1.2)
+
+**Fixed bugs:**
+
+- The \#update method should return an entity, not a record. [\#17](https://github.com/jdickey/repository-base/issues/17)
+
+## [v0.1.1](https://github.com/jdickey/repository-base/tree/v0.1.1) (2015-02-19)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.1.0...v0.1.1)
+
+**Implemented enhancements:**
+
+- Add Inch badge \(and prodded docs\). [\#14](https://github.com/jdickey/repository-base/issues/14)
+
+**Fixed bugs:**
+
+- The `\#add` method should return an entity on success, NOT a record. [\#16](https://github.com/jdickey/repository-base/issues/16)
+
+**Merged pull requests:**
+
+- \[Close \#14\] Added Inch CI badge and internal docs. [\#15](https://github.com/jdickey/repository-base/pull/15) ([jdickey](https://github.com/jdickey))
+
+## [v0.1.0](https://github.com/jdickey/repository-base/tree/v0.1.0) (2015-02-18)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.0.5...v0.1.0)
+
+**Closed issues:**
+
+- Integrate `repository-support` Gem in place of `lib/repository/support/\*` sources. [\#13](https://github.com/jdickey/repository-base/issues/13)
+
+## [v0.0.5](https://github.com/jdickey/repository-base/tree/v0.0.5) (2015-02-17)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.0.4...v0.0.5)
+
+**Closed issues:**
+
+- Implement \#delete method. [\#11](https://github.com/jdickey/repository-base/issues/11)
+
+**Merged pull requests:**
+
+- Implement \#delete method. [\#12](https://github.com/jdickey/repository-base/pull/12) ([jdickey](https://github.com/jdickey))
+
+## [v0.0.4](https://github.com/jdickey/repository-base/tree/v0.0.4) (2015-02-17)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.0.3...v0.0.4)
+
+**Closed issues:**
+
+- Implement \#update method. [\#9](https://github.com/jdickey/repository-base/issues/9)
+
+**Merged pull requests:**
+
+- Implement \#update method. [\#10](https://github.com/jdickey/repository-base/pull/10) ([jdickey](https://github.com/jdickey))
+
+## [v0.0.3](https://github.com/jdickey/repository-base/tree/v0.0.3) (2015-02-17)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.0.2...v0.0.3)
+
+**Closed issues:**
+
+- Implement \#find\_by\_slug method. [\#7](https://github.com/jdickey/repository-base/issues/7)
+
+**Merged pull requests:**
+
+- Implement `\#find\_by\_slug` method. [\#8](https://github.com/jdickey/repository-base/pull/8) ([jdickey](https://github.com/jdickey))
+
+## [v0.0.2](https://github.com/jdickey/repository-base/tree/v0.0.2) (2015-02-16)
+
+[Full Changelog](https://github.com/jdickey/repository-base/compare/v0.0.1...v0.0.2)
+
+**Closed issues:**
+
+- Implement \#all method. [\#5](https://github.com/jdickey/repository-base/issues/5)
+
+- Badges! [\#2](https://github.com/jdickey/repository-base/issues/2)
+
+**Merged pull requests:**
+
+- Implement \#all method. [\#6](https://github.com/jdickey/repository-base/pull/6) ([jdickey](https://github.com/jdickey))
+
+## [v0.0.1](https://github.com/jdickey/repository-base/tree/v0.0.1) (2015-02-16)
+
+**Closed issues:**
+
+- Implement \#add method [\#3](https://github.com/jdickey/repository-base/issues/3)
+
+**Merged pull requests:**
+
+- \[Close \#3\] Implement `\#add` method. [\#4](https://github.com/jdickey/repository-base/pull/4) ([jdickey](https://github.com/jdickey))
+
+- Add a Gitter chat badge to README.md [\#1](https://github.com/jdickey/repository-base/pull/1) ([gitter-badger](https://github.com/gitter-badger))
+
+
+
+\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in repository-base.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Jeff Dickey
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+<h1>Repository::Base</h1>
+
+[![Join the chat at https://gitter.im/jdickey/repository-base](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jdickey/repository-base?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Gem Version](https://badge.fury.io/rb/repository-base.svg)](http://badge.fury.io/rb/repository-base)
+[![Code Climate](https://codeclimate.com/github/jdickey/repository-base.png)](https://codeclimate.com/github/jdickey/repository-base)
+[ ![Codeship Status for jdickey/repository-base](https://codeship.com/projects/ae57fed0-969f-0132-1faa-76c54edd661d/status?branch=master)](https://codeship.com/projects/63061)
+[![security](https://hakiri.io/github/jdickey/repository-base/master.svg)](https://hakiri.io/github/jdickey/repository-base/master)
+[![Dependency Status](https://gemnasium.com/jdickey/repository-base.svg)](https://gemnasium.com/jdickey/repository-base)
+[![Inline docs](http://inch-ci.org/github/jdickey/repository-base.svg?style=shields)](http://inch-ci.org/github/jdickey/repository-base)
+
+This Gem supplies a class, `Repository::Base`, which can be used as a base class
+for Repositories in an application that uses the
+[Data Mapper pattern](http://martinfowler.com/eaaCatalog/dataMapper.html).
+As described by Fowler, Data Mapper "moves data between objects and a database
+while keeping them independent of each other and the mapper itself".
+
+This was originally developed within the structure of an R&D test-bed application,
+[`new_poc`](https://github.com/jdickey/new_poc). That app has a fairly wide-ranging
+history; after browsing its README and
+[commit history](https://github.com/jdickey/new_poc/commits), you may find Pull
+Requests [#153](https://github.com/jdickey/new_poc/pull/153) and
+[#200](https://github.com/jdickey/new_poc/pull/153) informative as to the
+historical basis of this code.
+
+<h2>Contents</h2>
+
+- [Installation](#installation)
+- [Usage](#usage)
+  * [IMPORTANT LEGACY NOTICE](#important-legacy-notice)
+  * [Concepts](#concepts)
+    + [Entities](#entities)
+    + [Entity Factories](#entity-factories)
+    + [StoreResult](#storeresult)
+    + [`Repository::Base` Instance Methods](#repositorybase-instance-methods)
+  * [More Details](#more-details)
+- [Contributing](#contributing)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'repository-base'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install repository-base
+
+## Usage
+
+### IMPORTANT LEGACY NOTICE
+
+**_NOTICE!_** This Gem was created to support a solo, ad-hoc, early learning experience in what is now known as Clean Architecture. It was part of our first attempt to build an alternative to the ActiveRecord/ActiveModel scheme native to Ruby on Rails.
+
+As such, it has been superseded and far outshone by other, team efforts, notably [ROM](http://rom-rb.org/) as used with [Hanami](http://hanamirb.org/) and [Trailblazer](http://trailblazer.to/). You are *strongly advised* to examine these and other tools rather than to use this for *any* new development. The Gem is being republished as an 0.4.0 release purely for internal archaeological purposes.
+
+### Concepts
+
+As mentioned at the top of this file, `Repository::Base` is intended to serve as
+the base class for your app's Repositories. As with most Data Mapper
+implementations, it makes use of a database access object, or DAO, which you
+specify as one of the two parameters to `#initialize`. The other parameter is an
+"entity factory", whose `.create` class method hands back an "entity" reflecting
+the content of an individual record in the underlying DAO.
+
+#### Entities
+
+What is an "entity"? It's a domain object in your application, with methods
+expressing the business logic applicable to the object represented by the underlying
+database record. This is distinct from an ActiveRecord-style *model*, in that
+more than one variation of entity may exist in your application for a given DAO.
+Most applications have Users, for example; some applications may have distinct
+variation of User *entities* (ordinary punters, admins, a "guest user" entity
+representing a user who has not authenticated as a more-privileged user, etc),
+that all share a common persistence layer (the underlying DAO) and an entity
+factory that *knows* how to create the correct type of entity for a given DAO
+record.
+
+An entity is uniquely identified by a *slug* rather than a numeric ID. Generally,
+a slug encodes textual, relatively SEO-friendly information corresponding to an
+individual record (the title of an article, the name of a user, etc) such that
+the corresponding record may be uniquely identified by the DAO. This is in
+preference to a "traditional" numeric record ID number; `Repository::Base` has
+no knowledge of nor direct support for numeric record IDs.
+
+#### Entity Factories
+
+Again, the entity factory, one of the parameters to this class' `#initialize`
+method, is responsible for creating an entity from a DAO instance (record). The
+`Repository::Base` class knows nothing of the details of how that is done; it
+simply calls methods on the DAO and/or entity factory to accomplish the tasks
+encapsulated by its own individual methods. 
+
+#### StoreResult
+
+What is a `StoreResult`? It is a simple value object which communicates the
+result of a call to a method on the underlying DAO *as reported by the DAO*,
+with the following properties:
+
+* `success?` (accessible as `result.success?` or as `result[:success?]`), has the value `true` after a successful operation or `false` after an unsuccessful one;
+* `entity` (`result.entity` or `result[:entity]`) is the instance or enumeration of instances of your domain entity resulting from a successful operation. After an unsuccessful operation, this property will be `nil`;
+* `errors` (`result.errors` or `result[:errors]`) is an Array-like object which is empty after a successful operation. After an unsuccessful operation, it will contain an Array of Hash instances, with each Hash having a key identifying the field or similar concept for which an individual error is being reported, and a value of the specific error message. For example, to report that a `:name` field was empty or blank, you might have a Hash of `{ name: 'is empty or blank' }. Your application domain logic should then understand how to deal with that convention.
+
+#### `Repository::Base` Instance Methods
+
+* `#add` adds a new record to the underlying *DAO* (data-access object; see above) using the field values specified by the *entity* passed as the only parameter. Returns a `StoreResult` (see above) which indicates the success or failure of the operation. On success, the `StoreResult` contains a *new* entity that represents the state of the record added to the underlying DAO;
+* `#all` returns a collection of entities matching all records as reported by the underlying DAO, with entities created by the appropriate entity factory;
+* `#delete` instructs the DAO to delete the record corresponding to the specified `slug`. Returns a `StoreResult` with an entity corresponding to the deleted record on success, or with appropriate error message(s) on failure;
+* `#find_by_slug` instructs the DAO to retrieve the record whose unique slug value matches the supplied parameter. On success, returns a `StoreResult` with an entity corresponding to the selected record; on failure, the `StoreResult` has an `entity` value of `nil` and appropriate error messages in `errors`;
+* `update` causes the DAO to attempt to update the record identified by the passed-in slug using the passed-in field values. On success, returns a `StoreResult` whose `entity` value mirrors the updated DAO record; on failure, has appropriate error indications in the `StoreResult`'s `errors` property.
+
+### More Details
+
+This Gem now has [full documentation available](./doc/index.html). (No, this isn't 1990s-era `rdoc`.)
+
+This Gem was built with **MRI Ruby 2.5.0**. It **is likely to** work when rebuilt with any version after 2.0.0; however, as it makes use of [keyword arguments](http://ruby-doc.org//core-2.1.0/doc/syntax/methods_rdoc.html#label-Keyword+Arguments) for various methods, it is *incompatible* with Ruby 1.9 or earlier.
+
+## Contributing
+
+1. Fork it ( https://github.com/jdickey/repository-base/fork )
+1. Create your feature branch (`git checkout -b my-new-feature`)
+1. Ensure that your changes are completely covered by *passing* specs, and comply with the [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide) as enforced by [RuboCop](https://github.com/bbatsov/rubocop). To verify this, run `bundle exec rake`, noting and repairing any lapses in coverage or style violations;
+1. Commit your changes (`git commit -a`). Please *do not* use a single-line commit message (`git commit -am "some message"`). A good commit message notes what was changed and why in sufficient detail that a relative newcomer to the code can understand your reasoning and your code;
+1. Push to the branch (`git push origin my-new-feature`)
+1. Create a new Pull Request. Describe at some length the rationale for your new feature; your implementation strategy at a higher level than each individual commit message; anything future maintainers should be aware of; and so on. *If this is a modification to existing code, reference the open issue being addressed*.
+1. Don't be discouraged if the PR generates a discussion that leads to further refinement of your PR through additional commits. These should *generally* be discussed in comments on the PR itself; discussion in the Gitter room (see below) may also be useful;
+1. If you've comments, questions, or just want to talk through your ideas, don't hesitate to hang out in the project's [room on Gitter](https://gitter.im/jdickey/repository-base). Ask away!

data/Rakefile

@@ -0,0 +1,33 @@
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+require 'kramdown'
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.patterns = [
+    'lib/**/*.rb',
+    'spec/spec_helper.rb',
+    'spec/**/*_spec.rb'
+  ]
+  task.formatters = ['simple', 'd']
+  task.fail_on_error = true
+  task.options << '--rails'
+end
+
+RSpec::Core::RakeTask.new :spec
+
+YARD::Rake::YardocTask.new
+
+# YARD::Rake::YardocTask.new do |t|
+#   OTHER_PATHS = %w(CHANGELOG.md README.md)
+#   t.files   = ['lib/**/*.rb', OTHER_PATHS]
+#   t.options = %w(--private --protected -m markdown --main=README.md)
+# end
+
+task(:default).clear
+task default: [:spec, :rubocop]

data/bin/bundle

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'bundle' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "rubygems"
+
+m = Module.new do
+    module_function
+
+  def invoked_as_script?
+    File.expand_path($0) == File.expand_path(__FILE__)
+  end
+
+  def env_var_version
+    ENV["BUNDLER_VERSION"]
+  end
+
+  def cli_arg_version
+    return unless invoked_as_script? # don't want to hijack other binstubs
+    return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update`
+    bundler_version = nil
+    update_index = nil
+    ARGV.each_with_index do |a, i|
+      if update_index && update_index.succ == i && a =~ Gem::Version::ANCHORED_VERSION_PATTERN
+        bundler_version = a
+      end
+      next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/
+      bundler_version = $1 || ">= 0.a"
+      update_index = i
+    end
+    bundler_version
+  end
+
+  def gemfile
+    gemfile = ENV["BUNDLE_GEMFILE"]
+    return gemfile if gemfile && !gemfile.empty?
+
+    File.expand_path("../../Gemfile", __FILE__)
+  end
+
+  def lockfile
+    lockfile =
+      case File.basename(gemfile)
+      when "gems.rb" then gemfile.sub(/\.rb$/, gemfile)
+      else "#{gemfile}.lock"
+      end
+    File.expand_path(lockfile)
+  end
+
+  def lockfile_version
+    return unless File.file?(lockfile)
+    lockfile_contents = File.read(lockfile)
+    return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/
+    Regexp.last_match(1)
+  end
+
+  def bundler_version
+    @bundler_version ||= begin
+      env_var_version || cli_arg_version ||
+        lockfile_version || "#{Gem::Requirement.default}.a"
+    end
+  end
+
+  def load_bundler!
+    ENV["BUNDLE_GEMFILE"] ||= gemfile
+
+    # must dup string for RG < 1.8 compatibility
+    activate_bundler(bundler_version.dup)
+  end
+
+  def activate_bundler(bundler_version)
+    if Gem::Version.correct?(bundler_version) && Gem::Version.new(bundler_version).release < Gem::Version.new("2.0")
+      bundler_version = "< 2"
+    end
+    gem_error = activation_error_handling do
+      gem "bundler", bundler_version
+    end
+    return if gem_error.nil?
+    require_error = activation_error_handling do
+      require "bundler/version"
+    end
+    return if require_error.nil? && Gem::Requirement.new(bundler_version).satisfied_by?(Gem::Version.new(Bundler::VERSION))
+    warn "Activating bundler (#{bundler_version}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_version}'`"
+    exit 42
+  end
+
+  def activation_error_handling
+    yield
+    nil
+  rescue StandardError, LoadError => e
+    e
+  end
+end
+
+m.load_bundler!
+
+if m.invoked_as_script?
+  load Gem.bin_path("bundler", "bundle")
+end