staging_table 0.1.0

data/sig/staging_table/adapters/base.rbs

@@ -0,0 +1,18 @@
+module StagingTable
+  module Adapters
+    class Base
+      attr_reader connection: ActiveRecord::ConnectionAdapters::AbstractAdapter
+
+      def initialize: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> void
+
+      # Create a staging table based on the source table structure
+      def create_table: (String temp_table_name, String source_table_name, ?Hash[Symbol, untyped] options) -> void
+
+      # Drop the staging table
+      def drop_table: (String temp_table_name) -> void
+
+      # Factory method to get the appropriate adapter for a connection
+      def self.for: (ActiveRecord::ConnectionAdapters::AbstractAdapter connection) -> Base
+    end
+  end
+end

data/sig/staging_table/adapters/mysql.rbs

@@ -0,0 +1,7 @@
+module StagingTable
+  module Adapters
+    class Mysql < Base
+      def create_table: (String temp_table_name, String source_table_name, ?Hash[Symbol, untyped] options) -> void
+    end
+  end
+end

data/sig/staging_table/adapters/postgresql.rbs

@@ -0,0 +1,7 @@
+module StagingTable
+  module Adapters
+    class Postgresql < Base
+      def create_table: (String temp_table_name, String source_table_name, ?Hash[Symbol, untyped] options) -> void
+    end
+  end
+end

data/sig/staging_table/adapters/sqlite.rbs

@@ -0,0 +1,11 @@
+module StagingTable
+  module Adapters
+    class Sqlite < Base
+      def create_table: (String temp_table_name, String source_table_name, ?Hash[Symbol, untyped] options) -> void
+
+      private
+
+      def copy_indexes: (String temp_table_name, String source_table_name) -> void
+    end
+  end
+end

data/sig/staging_table/bulk_inserter.rbs

@@ -0,0 +1,16 @@
+module StagingTable
+  class BulkInserter
+    attr_reader model: singleton(ActiveRecord::Base)
+    attr_reader batch_size: Integer
+
+    def initialize: (singleton(ActiveRecord::Base) model, ?batch_size: Integer) -> void
+
+    # Insert records in batches
+    def insert: (Array[Hash[String | Symbol, untyped]] records) -> void
+
+    private
+
+    def connection: () -> ActiveRecord::ConnectionAdapters::AbstractAdapter
+    def quote: (untyped value) -> String
+  end
+end

data/sig/staging_table/configuration.rbs

@@ -0,0 +1,8 @@
+module StagingTable
+  class Configuration
+    attr_accessor default_batch_size: Integer
+    attr_accessor default_transfer_strategy: Symbol
+
+    def initialize: () -> void
+  end
+end

data/sig/staging_table/errors.rbs

@@ -0,0 +1,25 @@
+module StagingTable
+  # Base error class for all StagingTable errors
+  class Error < StandardError
+  end
+
+  # Raised when configuration options are invalid
+  class ConfigurationError < Error
+  end
+
+  # Raised when the database adapter is not supported
+  class AdapterError < Error
+  end
+
+  # Raised when staging table operations fail
+  class TableError < Error
+  end
+
+  # Raised when transfer strategy fails or is misconfigured
+  class TransferError < Error
+  end
+
+  # Raised when record data is invalid for insertion
+  class RecordError < Error
+  end
+end

data/sig/staging_table/instrumentation.rbs

@@ -0,0 +1,19 @@
+module StagingTable
+  # Provides ActiveSupport::Notifications instrumentation for StagingTable operations
+  module Instrumentation
+    NAMESPACE: String
+    EVENTS: Array[Symbol]
+
+    # Instruments a block with the given event name
+    def self.instrument: [T] (Symbol event_name, ?Hash[Symbol, untyped] payload) { (?Hash[Symbol, untyped]) -> T } -> T
+
+    # Subscribe to a StagingTable event
+    def self.subscribe: (Symbol | String event_name) { (ActiveSupport::Notifications::Event) -> void } -> ActiveSupport::Notifications::Fanout::Subscribers::Evented
+
+    # Unsubscribe from a StagingTable event
+    def self.unsubscribe: (untyped subscriber) -> void
+
+    # Subscribe to all StagingTable events
+    def self.subscribe_all: () { (ActiveSupport::Notifications::Event) -> void } -> ActiveSupport::Notifications::Fanout::Subscribers::Evented
+  end
+end

data/sig/staging_table/model_factory.rbs

@@ -0,0 +1,6 @@
+module StagingTable
+  class ModelFactory
+    # Build a dynamic staging model class based on the source model
+    def self.build: (singleton(ActiveRecord::Base) source_model, String table_name, ?excluded_columns: Array[Symbol | String]) -> singleton(ActiveRecord::Base)
+  end
+end

data/sig/staging_table/session.rbs

@@ -0,0 +1,40 @@
+module StagingTable
+  class Session
+    # Supported callback options
+    CALLBACK_OPTIONS: Array[Symbol]
+
+    attr_reader source_model: singleton(ActiveRecord::Base)
+    attr_reader staging_model: singleton(ActiveRecord::Base)?
+    attr_reader options: Hash[Symbol, untyped]
+
+    def initialize: (singleton(ActiveRecord::Base) source_model, **untyped options) -> void
+
+    # Creates the staging table in the database
+    def create_table: () -> void
+
+    # Drops the staging table from the database
+    def drop_table: () -> void
+
+    # Insert records into the staging table
+    def insert: (Array[Hash[String | Symbol, untyped]] | ActiveRecord::Relation records) -> void
+
+    # Insert records from an ActiveRecord relation
+    def insert_from_query: (ActiveRecord::Relation relation) -> void
+
+    # Transfer staged data to the target table
+    def transfer: () -> TransferResult
+
+    # Delegate unknown methods to staging_model
+    def method_missing: (Symbol method, *untyped args) ?{ (*untyped) -> untyped } -> untyped
+
+    def respond_to_missing?: (Symbol method, ?bool include_private) -> bool
+
+    private
+
+    def run_callback: (Symbol name, *untyped args) -> void
+    def adapter: () -> Adapters::Base
+    def staging_table_name: () -> String
+    def ensure_table_created!: () -> void
+    def normalize_records: (untyped records) -> Array[Hash[String, untyped]]
+  end
+end

data/sig/staging_table/transfer_result.rbs

@@ -0,0 +1,22 @@
+module StagingTable
+  # Holds statistics about a transfer operation
+  class TransferResult
+    attr_reader inserted: Integer
+    attr_reader updated: Integer
+    attr_reader skipped: Integer
+    attr_reader total: Integer
+
+    def initialize: (?inserted: Integer, ?updated: Integer, ?skipped: Integer) -> void
+
+    # Returns a hash representation of the result
+    def to_h: () -> Hash[Symbol, Integer]
+
+    # Returns true if any records were inserted or updated
+    def success?: () -> bool
+
+    # Returns true if no records were processed
+    def empty?: () -> bool
+
+    def inspect: () -> String
+  end
+end

data/sig/staging_table/transfer_strategies/insert.rbs

@@ -0,0 +1,15 @@
+module StagingTable
+  module TransferStrategies
+    class Insert
+      @source_model: singleton(ActiveRecord::Base)
+      @staging_model: singleton(ActiveRecord::Base)
+      @options: Hash[Symbol, untyped]
+      @connection: ActiveRecord::ConnectionAdapters::AbstractAdapter
+
+      def initialize: (singleton(ActiveRecord::Base) source_model, singleton(ActiveRecord::Base) staging_model, ?Hash[Symbol, untyped] options) -> void
+
+      # Transfer all staged records to the target table
+      def transfer: () -> TransferResult
+    end
+  end
+end

data/sig/staging_table/transfer_strategies/upsert.rbs

@@ -0,0 +1,26 @@
+module StagingTable
+  module TransferStrategies
+    class Upsert
+      @source_model: singleton(ActiveRecord::Base)
+      @staging_model: singleton(ActiveRecord::Base)
+      @options: Hash[Symbol, untyped]
+      @connection: ActiveRecord::ConnectionAdapters::AbstractAdapter
+      @staged_count: Integer
+
+      def initialize: (singleton(ActiveRecord::Base) source_model, singleton(ActiveRecord::Base) staging_model, ?Hash[Symbol, untyped] options) -> void
+
+      # Transfer staged records with upsert semantics (insert or update)
+      def transfer: () -> TransferResult
+
+      private
+
+      def postgresql_upsert: () -> TransferResult
+      def mysql_upsert: () -> TransferResult
+      def sqlite_upsert: () -> TransferResult
+      def quote: (untyped value) -> String
+      def column_names: () -> Array[String]
+      def quote_column: (String | Symbol name) -> String
+      def quote_table: (String name) -> String
+    end
+  end
+end

data/sig/staging_table/version.rbs

@@ -0,0 +1,3 @@
+module StagingTable
+  VERSION: String
+end

data/sig/staging_table.rbs

@@ -0,0 +1,9 @@
+# Type signatures for staging_table gem
+# See https://github.com/ruby/rbs for more information
+
+module StagingTable
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.stage: (singleton(ActiveRecord::Base) source_model, **untyped options) -> Session
+                | [T] (singleton(ActiveRecord::Base) source_model, **untyped options) { (Session) -> T } -> TransferResult
+end

data/staging_table.gemspec

@@ -0,0 +1,35 @@
+lib = File.expand_path("../lib", __FILE__)
+
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "staging_table/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "staging_table"
+  spec.version = StagingTable::VERSION
+  spec.authors = ["eagerworks"]
+  spec.email = ["hello@eagerworks.com"]
+
+  spec.summary = "Mass data imports via temporary staging tables"
+  spec.description = "Handles mass data imports via temporary staging tables, supporting PostgreSQL and MySQL, with a clean DSL for table lifecycle management and built-in bulk insert capabilities."
+  spec.homepage = "https://github.com/eagerworks/staging_table"
+  spec.license = "MIT"
+
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activerecord", ">= 6.0"
+  spec.add_dependency "activesupport", ">= 6.0"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pg"
+  spec.add_development_dependency "mysql2"
+  spec.add_development_dependency "sqlite3"
+end

metadata

@@ -0,0 +1,195 @@
+--- !ruby/object:Gem::Specification
+name: staging_table
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- eagerworks
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Handles mass data imports via temporary staging tables, supporting PostgreSQL
+  and MySQL, with a clean DSL for table lifecycle management and built-in bulk insert
+  capabilities.
+email:
+- hello@eagerworks.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/rbs.yml"
+- ".github/workflows/test.yml"
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- README.md
+- Rakefile
+- lib/staging_table.rb
+- lib/staging_table/adapters/base.rb
+- lib/staging_table/adapters/mysql.rb
+- lib/staging_table/adapters/postgresql.rb
+- lib/staging_table/adapters/sqlite.rb
+- lib/staging_table/bulk_inserter.rb
+- lib/staging_table/configuration.rb
+- lib/staging_table/errors.rb
+- lib/staging_table/instrumentation.rb
+- lib/staging_table/model_factory.rb
+- lib/staging_table/session.rb
+- lib/staging_table/transfer_result.rb
+- lib/staging_table/transfer_strategies/insert.rb
+- lib/staging_table/transfer_strategies/upsert.rb
+- lib/staging_table/version.rb
+- rbs_collection.yaml
+- sig/manifest.yaml
+- sig/staging_table.rbs
+- sig/staging_table/adapters/base.rbs
+- sig/staging_table/adapters/mysql.rbs
+- sig/staging_table/adapters/postgresql.rbs
+- sig/staging_table/adapters/sqlite.rbs
+- sig/staging_table/bulk_inserter.rbs
+- sig/staging_table/configuration.rbs
+- sig/staging_table/errors.rbs
+- sig/staging_table/instrumentation.rbs
+- sig/staging_table/model_factory.rbs
+- sig/staging_table/session.rbs
+- sig/staging_table/transfer_result.rbs
+- sig/staging_table/transfer_strategies/insert.rbs
+- sig/staging_table/transfer_strategies/upsert.rbs
+- sig/staging_table/version.rbs
+- staging_table.gemspec
+homepage: https://github.com/eagerworks/staging_table
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Mass data imports via temporary staging tables
+test_files: []