transient_record 1.0.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 05ecb3ea508a5454c5a108e2f46ef5e0a390a4467aa5a965db12094bf955dfaf
+  data.tar.gz: 39d965ea81d0ca307db1c0559c91fe5713df7a44206b5893470e617a479f851c
+SHA512:
+  metadata.gz: b04aa876557bcfe4488a42f97786c3abdfe6d4621fe6e9956708e005fc0b5a0f51c13fa65e5261c7ce89186e0691107f0c9ce3ce0e998796ef20425a0800d79f
+  data.tar.gz: 934d8eb96dc127056a33e1907649eaf17dbb0b01902345c3f48cfdb6c495da976c63221aadf5070ba7b5d9aad4e92c557277462a25ac5109458821d9dbc0542c

data/MIT-LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright 2023 Greg Navis
+
+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,137 @@
+# Transient Record
+
+`transient-record` is a gem to define temporary tables and Active Record models
+for testing purposes. It's a great tool for testing **generic Active Record code
+and libraries**.
+
+The library was extracted from [active_record_doctor](https://github.com/gregnavis/active_record_doctor)
+to allow reuse.
+
+## Installation
+
+Installing Transient Record is a two-step process.
+
+### Step 1: Installing the Gem
+
+You can include Transient Record in your `Gemfile`:
+
+```ruby
+gem "transient_record", group: :test
+```
+
+The above assumes it'll be used for testing purposes only, hence the `test`
+group. However, if you intend to use the gem in other circumstances then you may
+need to adjust the group accordingly.
+
+If you'd like to use the latest development release then use the line below
+instead:
+
+```ruby
+gem "transient_record", github: "gregnavis/transient_record", group: :test
+```
+
+After modifying `Gemfile`, run `bundle install`.
+
+### Step 2: Integrating with the Test Suite
+
+After installing the gem, Transient Record must be integrated with the test
+suite. `TransientRecord.cleanup` must be called around every test case: before
+(to prepare a clean database state for the test case) and after (to leave the
+database in a clean state).
+
+The snippet below demonstrates integrations with various testing libraries:
+
+```ruby
+# When using Minitest
+class TransientRecordTest < Minitest::Test
+  def before
+    TransientRecord.cleanup
+  end
+
+  def after
+    TransientRecord.cleanup
+  end
+end
+
+# When using Minitest::Spec
+class TransientRecordTest < Minitest::Spec
+  before do
+    TransientRecord.cleanup
+  end
+
+  after do
+    TransientRecord.cleanup
+  end
+end
+
+# When using RSpec
+RSpec.describe TransientRecord do
+  before(:each) do
+    TransientRecord.cleanup
+  end
+
+  after(:each) do
+    TransientRecord.cleanup
+  end
+end
+```
+
+## Usage
+
+Transient Record can be used to create temporary tables and, optionally, models
+backed by them.
+
+A table can be created by calling `create_table`: a thin wrapper around the
+method of the same name in Active Record. The only difference is the method
+in Transient Record implemented a fluent interface that allows calling
+`define_model` on the return value.
+
+For example, the statement below creates a table named `users` with two one
+string column `name` and one integer column `age`:
+
+```ruby
+create_table :users do |t|
+  t.string :name, null: false
+  t.integer :age, null: false
+end
+```
+
+Refer to [Ruby on Rails API documentation](https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html)
+for details.
+
+In order to define a model backed by that table `define_model` can be called
+**on the return value** of `create_table` with a block containing the model
+class body. For example, to define 
+
+```ruby
+create_table :users do |t|
+  # ...
+end.define_model do
+  validates :email, presence: true
+end
+```
+
+Models are automatically assigned to constants in `TransientRecord::Models`. The
+example above creates `TransientRecord::Models::User`, and is equivalent to:
+
+```ruby
+class TransientRecord::Models::User < ActiveRecord::Base
+  validates :email, presence: true
+end
+```
+
+## Caveats and Limitations
+
+Transient Record does **NOT** default to using temporary tables (created via
+`CREATE TEMPORARY TABLE`) because of their second-class status in Active Record.
+For example, temporary table are not listed by the `tables` method. For this
+reason it was decided to use regular tables with an explicit cleanup step.
+
+Transient Record may not work properly in parallelized test suites, e.g. if two
+test workers attempt to create a table with the same name then it's likely to
+result in an error. Full support for parallelism **is** on the roadmap, so feel
+free to report any errors and contribute updates.
+
+## Author
+
+This gem is developed and maintained by [Greg Navis](http://www.gregnavis.com).

data/lib/transient_record.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+# Transient Record helps define transient tables and Active Record models.
+#
+# Defining a transient table and model is a two-step process:
+#
+# 1. {#create_table} to create the table.
+# 2. {#define_model} to define the model.
+#
+# @example Creating a table without a model
+#   # #create_table is a wrapper around #create_table in Active Record, and
+#   # works almost exactly like the that method.
+#   TransientRecord.create_table :users do |t|
+#     t.string :email, null: false
+#   end
+#
+# @example Creating a table and a model using fluent interface
+#   # The difference between #create_table and its Active Record counterpart is
+#   # the return value: Transient Record allows calling #define_model on it.
+#   TransientRecord.create_table :users do |t|
+#     t.string :email, null: false
+#   end.define_model do
+#     validates :email, presence: true
+#   end
+#
+#   # The transient model can be referenced via TransientRecord::Models::User.
+#   # For example, a new user instance can be instantiated via:
+#   user = TransientRecord::Models::User.new email: nil
+#
+# @example Creating a table and a model with regular interface
+#   # Assuming the users table has been created (using Transient Record or
+#   # another method), a User model can be defined via:
+#   TransientRecord.define_model :User do
+#     validates :email, presence: true
+#   end
+module TransientRecord
+  # Transient Record version number.
+  VERSION = "1.0.0.rc1"
+
+  # A module where all temporary models are defined.
+  #
+  # Models defined via {TransientRecord.define_model}, {TransientRecord#define_model}
+  # or {ModelDefinitionProxy#define_model} are put here in order to avoid
+  # polluting the top-level namespace, potentially conflicting with identically
+  # named constants defined elsewhere.
+  #
+  # @example
+  #   # If a transient users table and its corresponding User model are defined then ...
+  #   TransientRecord.create_table :users do |t|
+  #     t.string :email, null: false
+  #   end.define_model do
+  #     validates :email, presence: true
+  #   end
+  #
+  #   # ... the user model can be referenced via:
+  #   TransientRecord::Models::User
+  module Models
+    # Remove all constants from the module.
+    #
+    # This method is used by {TransientRecord.cleanup} to undefine temporary
+    # model classes.
+    #
+    # @api private
+    def self.remove_all_consts
+      constants.each { |name| remove_const name }
+    end
+  end
+
+  def create_table *args, &block
+    TransientRecord.create_table(*args, &block)
+  end
+
+  def define_model *args, &block
+    TransientRecord.define_model(*args, &block)
+  end
+
+  class << self
+    # Create a transient table.
+    #
+    # This method can be considered to be a wrapper around +#create_table+ in
+    # Active Record, as it forwards its arguments and the block.
+    #
+    # Transient tables are **not** made temporary in the database (in other
+    # words, they are **not** created using +CREATE TEMPORARY TABLE+), because
+    # temporary tables are treated differently by Active Record. For example,
+    # they aren't listed by +#tables+. If a temporary table is needed then pass
+    # +temporary: true+ via options, which Active Record will recognized out of
+    # the box.
+    #
+    # Transient tables must be dropped explicitly by calling {.cleanup}.
+    #
+    # @param table_name [String, Symbol] name of the table to create.
+    # @param options [Hash] options to use during table creation; they are
+    #   forwarded as is to +create_table+ in Active Record.
+    #
+    # @yield [table] table definition forwarded to +create_table+ in Active
+    #   Record.
+    #
+    # @return [ModelDefinitionProxy]
+    #
+    # @see https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-create_table Documentation for #create_table in Ruby on Rails
+    def create_table table_name, options = {}, &block
+      table_name = table_name.to_sym
+
+      ::ActiveRecord::Migration.suppress_messages do
+        ::ActiveRecord::Migration.create_table table_name, **options, &block
+      end
+
+      # Return a proxy object allowing the caller to chain #define_model
+      # right after creating a table so that it can be followed by the model
+      # definition.
+      ModelDefinitionProxy.new table_name
+    end
+
+    # Define a transient Active Record model.
+    #
+    # Calling this method is roughly equivalent to defining a class inheriting
+    # from +ActiveRecord::Base+ with class body defined by the block passed to
+    # the method.
+    #
+    # Transient models must be removed explicitly by calling {.cleanup}.
+    #
+    # @example
+    #   # The following method call ...
+    #   TransientRecord.define_model(:User) do
+    #     validates :email, presence: true
+    #   end
+    #
+    #   # ... is roughly equivalent to this class definition.
+    #   class TransientRecord::Models::User < ActiveRecord::Base
+    #     validates :email, presence: true
+    #   end
+    #
+    #
+    # @param model_name [String, Symbol] name of model to define.
+    # @param base_class [Class] model base class.
+    #
+    # @yield expects the class body to be passed via the block
+    #
+    # @return [nil]
+    def define_model model_name, base_class = ::ActiveRecord::Base, &block
+      model_name = model_name.to_sym
+
+      # Normally, when a class is defined via `class MyClass < MySuperclass` the
+      # .name class method returns the name of the class when called from within
+      # the class body. However, anonymous classes defined via Class.new DO NOT
+      # HAVE NAMES. They're assigned names when they're assigned to a constant.
+      # If we evaluated the class body, passed via block here, in the class
+      # definition below then some Active Record macros would break
+      # (e.g. has_and_belongs_to_many) due to nil name.
+      #
+      # We solve the problem by defining an empty model class first, assigning to
+      # a constant to ensure a name is assigned, and then reopening the class to
+      # give it a non-trivial body.
+      klass = Class.new base_class
+      Models.const_set model_name, klass
+
+      klass.class_eval(&block) if block_given?
+
+      nil
+    end
+
+    # Drop transient tables and models.
+    #
+    # This method **MUST** be called after every test cases that used Transient
+    # Record, as it's responsible for ensuring a clean slate for the next run.
+    # It does the following:
+    #
+    # 1. Remove all models defined via {.define_model}.
+    # 2. Drop all tables created via {.create_table}.
+    # 3. Start garbage collection.
+    #
+    # The last step is to ensure model classes are actually removed, and won't
+    # appear among the descendants hierarchy of +ActiveRecord::Base+.
+    #
+    # @return [nil]
+    def cleanup
+      Models.remove_all_consts
+
+      connection = ::ActiveRecord::Base.connection
+      tables_to_remove = connection.tables
+      drop_attempts = tables_to_remove.count * (1 + tables_to_remove.count) / 2
+
+      drop_attempts.times do
+        table = tables_to_remove.shift
+        break if table.nil?
+
+        begin
+          connection.drop_table table, force: :cascade, if_exists: true
+        rescue ActiveRecord::InvalidForeignKey, ActiveRecord::StatementInvalid
+          # ActiveRecord::StatementInvalid is raised by MySQL when attempting to
+          # drop a table that has foreign keys referring to it.
+          tables_to_remove << table
+        end
+      end
+
+      GC.start
+
+      nil
+    end
+  end
+
+  # A model definition proxy is a helper class used to implement a fluent
+  # interface to callers allowing them to create a table and its corresponding
+  # model in close succession. It's marked private as there's no need for
+  # callers to access it.
+  class ModelDefinitionProxy
+    def initialize table_name
+      @table_name = table_name.to_s
+    end
+
+    def define_model &block
+      TransientRecord.define_model @table_name.classify, &block
+    end
+  end
+
+  private_constant :ModelDefinitionProxy
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: transient_record
+version: !ruby/object:Gem::Version
+  version: 1.0.0.rc1
+platform: ruby
+authors:
+- Greg Navis
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-01-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.3
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.4
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.4
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 12.3.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 12.3.3
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.28
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.28
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.43.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.43.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+description:
+email:
+- contact@gregnavis.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE.txt
+- README.md
+- lib/transient_record.rb
+homepage: https://github.com/gregnavis/transient_record
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.2.33
+signing_key:
+specification_version: 4
+summary: Define transient tables and Active Record models for testing purposes.
+test_files: []