orphanage 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 836545ad30600d71a455f70709b18d2b4cc8be81
-  data.tar.gz: 8b6244756796620d588c8f2a7b81990c6d1215fa
+  metadata.gz: 96c180f014edb46218c44e21d23954cc93ef61ea
+  data.tar.gz: 67b4ae194d309a8d16254944417432878cab0ff8
 SHA512:
-  metadata.gz: 1d66fef97ce142481663940b661df8f68849d78296e93dc2e41dcbc1503e0e092321b3635a995c2b513a1ed91ddcb8d95f1f9c0743788bc4d9434d5bc9038145
-  data.tar.gz: 371eb0170d728e6485ef993b185da8404e11a42425241d2be587cde0103660deeed35001eab083ec38ce7b505149b4f8218ea53201b475157b4d54ebbfffec17
+  metadata.gz: 221a8c0b2d28fae31cbe96d2bd262340e1e93443ee5acea7bd4b499be9631b9d1b8b89d50c608e94cab845daff626ea7f122f6fe02d51f328a33bae14dd8f8cc
+  data.tar.gz: 1d1b52c071e2c96ad270f21ab3df6616fe4d54dfddc7d41c346155341bc97386f07a1e1559f07be80c4054a01526151d97667fc188e1f72996e23dae8d97f184

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Jacob Stoebel
+
+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,92 @@
+# Orphanage:
+#### A simple library for storing temporary orphan records.
+
+Orphanage is a super lightweight library for persisting orphan records. Let's say you have some data but don't yet know all of its foreign keys. Orphanage streamlines the process of keeping it in a temporary table and then, when all foreign keys become available, transferring it to the proper table in the database.
+
+## Installation
+
+```
+gem 'orphanage'
+```
+
+## A simple use case
+
+Let's say you are have a database with `students` having many `exams`. Exam results come in to your database via an external source, but sometimes you can't match them up perfectly. A person may have a different last name due to marriage for example. When `exam` records can not be identified to a `student` they should be stored in the table `exam_temps`. Later when an an admin user audits the ambiguous records and provides a `student`, the record is transferred from`exam_temps` to `exams`.
+
+
+## Usage
+
+### Model Creation
+
+#### Using the generator
+
+Assuming your home model already exists and its corresponding table exists in the database run `rails generate orphanage:init <HomeModelName>`. For example:
+
+```
+rails generate orphanage:init Exam
+```
+
+generates a model for your orphan table as well as a migration file that will give you all of the columns existing in the home model. You'll also get any other files you would expect when running `rails generate model` (such as tests, factories, fixtures, etc as the case may be)
+
+#### Manually
+
+Creating an orphan model by hand isn't much more work. By default orphanage expects the model to have `Temp` appended to the original, so for example an orphan model to `Exam` would be `ExamTemp`.
+
+Then inside that model:
+```
+require 'orphanage'
+
+class ExamTemp < ActiveRecord::Base
+  include Orphanage
+  orphan
+end
+```
+
+From there you can add temporary records to this orphan table like you normally would.
+
+#### Adoption
+
+Transferring a model to its home table is done by calling the `adopt` method. For example:
+
+```
+# record can't be stored in exam table because it has no student_id
+exam_temp = ExamTemp.create!({:score => 150,
+  :taken_on => Date.today,
+  :first_name => "Jacob",
+  :last_name => "Stoebel"
+})
+
+#later, a student_id is provided for this record
+exam_temp.adopt({:student_id => 1})
+```
+
+Calling `adopt`, if successful, will return the created permanent record. The temporary record will stick around unless you explicitly as for it to be destroyed (see below)
+
+## Customizations
+
+You can customize the behavior at the model level and/or the instance level with instance level customizations taking precedence. To do so, pass in a hash with any of the following keys.
+
+ - __home__ The ActiveRecord model to which orphan records will be transferred to when made permanent. By default the value is generated by removing `Temp` from the orphan model (example: `ExamTemp` -> `Exam`)
+ - __destroy_on_adopt__ (boolean) if the orphan record should be destroyed after successful transfer of record. Defaults to `false`.
+ - __update_time_stamps__ a hash of booleans with the following keys
+    - __created__ if the `created_at` timestamp should be persisted from the orphan record. Defaults to `true`.
+    - __updated__ if the `updated_at` timestamp should be persisted from the orphan record. Defaults to `true`.
+
+### Examples
+
+Let's say our orphan model is `ExamTemp`
+
+```
+# define a different home class throughout the orphan class...
+orphan :home => Examination
+
+# ... or inside just this instance
+temp_exam.adopt({:student_id => 1}, {:home => Examination})
+
+# don't destroy temp records after adoption
+orphan :destroy_on_adopt => false
+
+# for this instance, don't update the timestamps after adoption
+temp_exam.adopt({:student_id => 1}, {:update_timestamps => {:created => false, :updated => false}})
+
+```

data/lib/generators/orphanage/init_generator.rb

@@ -0,0 +1,72 @@
+require 'rails/generators/base'
+
+module Orphanage
+
+  class InitGenerator < Rails::Generators::Base
+    containing_dir = File.expand_path("..", __FILE__)
+    template_dir = File.join(containing_dir, 'templates')
+    source_root File.expand_path(template_dir)
+
+    argument :home_model_name, :type => :string
+
+    def ensure_home_model_and_table_exists
+
+      begin
+        home_model
+      rescue NameError => e
+        fail "Home model not found. Plese generate it first."
+      end
+
+      table_exists = ActiveRecord::Base.connection.data_source_exists? home_table_name
+      fail "table #{home_table_name} does not exist. Stopping." if !table_exists
+
+    end # ensure_home_model_exists
+
+    def generate_model
+      generate "model #{home_model_name}Temp --skip-migration"
+
+    end
+
+    def orphanize_model
+      # change the model to be an orphan model
+      puts "replacing model..."
+      template "model.rb.erb", "app/models/#{home_file_name}_temp.rb", force: true
+    end
+
+    def create_migration
+      puts "creating migration file..."
+      migration_file_name = "#{Time.now.utc.strftime("%Y%m%d%H%M%S")}_create_#{home_file_name}_temps.rb"
+      template "migration.rb.erb", "db/migrate/#{migration_file_name}"
+    end # create_migration
+
+    private
+
+    def home_model
+      home_model_name.constantize
+    end # home_model
+
+    def home_file_name
+      home_model_name.underscore
+    end # file_name
+
+    def home_table_name
+      home_file_name.pluralize
+    end # home_table_name
+
+    def orphan_table_name
+      (home_model_name + "Temp").underscore.pluralize
+    end # orphan_table_name
+
+    def migration_columns
+      # get all column names
+      needed_cols = home_model.columns.select { |col| !%w(id created_at updated_at).include? col.name }
+
+      # returns an array of strings each representing a single column to add in the migration.
+      migrations = needed_cols.map {|col| "t.#{col.type} :#{col.name}, null: #{col.null}" }
+
+      return migrations
+
+    end # orphan_columns
+  end
+
+end

data/lib/generators/orphanage/templates/migration.rb.erb

@@ -0,0 +1,14 @@
+class Create<%= home_model_name %>Temps < ActiveRecord::Migration
+  def up
+    create_table :<%= orphan_table_name -%> do |t|
+      <%- migration_columns.each do |col| %>
+      <%= col %>
+      <% end %>
+      t.timestamps
+    end
+  end
+
+  def down
+    drop_table :<%= orphan_table_name -%>
+  end
+end

data/lib/generators/orphanage/templates/model.rb.erb

@@ -0,0 +1,7 @@
+require 'active_record'
+require 'orphanage'
+
+class <%= home_model_name %>Temp < ActiveRecord::Base
+    include Orphanage
+    orphan
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: orphanage
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jacob Stoebel
@@ -78,12 +78,31 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.10.4
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 description: A simple library for storing temporary orphan records.
 email: jstoebel@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
+- lib/generators/orphanage/init_generator.rb
+- lib/generators/orphanage/templates/migration.rb.erb
+- lib/generators/orphanage/templates/model.rb.erb
 - lib/orphanage.rb
 homepage: https://github.com/jstoebel/orphanage
 licenses: