csv_wizard 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f0ac1e6eeb36ef75a527c25437cc2f7e89c32536eb6eda719ffff65a92ab5d79
+  data.tar.gz: f82fb939fd275974c66eb8567dccc4c2d75a8db9d748f5ca1a7dd82ec99dbef5
+SHA512:
+  metadata.gz: 7999f9a582bdaece1d3f0618a7ce16514ceb4a5a9a333e19fb9dc03809f4968e26c6b1c1ac4f18916a74070c2c731bf8e1722f14dec16b644bcb2cca77fd3b71
+  data.tar.gz: c52a76153ffc66d1a5c2d6a254c2a03fc7d692a1ccb6ffc7d30751930603e470a89c3514f39d028fa5b2e4841ff9fc6bbad1de5a0a7ff93882d4a3f138321ba1

data/.github/workflows/rubyonrails.yml

@@ -0,0 +1,26 @@
+name: Ruby CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@78c01b705fd9d5ad960d432d3a0cfa341d50e410 # v1.179.1
+        with:
+          ruby-version: 3.2.0
+          bundler-cache: true
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Run RSpec tests
+        run: bundle exec rspec

data/.ruby-version

@@ -0,0 +1 @@
+3.2.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 mrmalvi
+
+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,154 @@
+# CsvWizard
+
+CsvWizard is a Ruby gem for **importing CSV files into Rails models** with support for:
+
+- Required fields
+- Default values
+- Row-level validation
+- Pre- and post-import hooks
+- Logging with Rails.logger or the Logging gem
+
+It is designed to simplify CSV imports in Rails applications.
+
+---
+
+## Installation
+
+Add this line to your Rails application's Gemfile:
+
+```ruby
+gem "csv_wizard"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+---
+
+## Requirements
+
+- Ruby >= 2.6
+- Rails >= 6.0
+---
+
+## Usage
+
+### 1. Basic Import
+
+```ruby
+mappings = {
+  "Name" => :name,
+  "Email" => :email,
+  "Age" => :age
+}
+
+file_path = "path/to/users.csv"
+
+CsvWizard::ImportJob.new.perform("User", mappings, file_path)
+```
+
+- `model_name`: The name of the Rails model to import to.
+- `mappings`: A hash mapping CSV column headers to model attributes.
+- `file_path`: Path to the CSV file.
+
+---
+
+### 2. Using Pre- and Post-Processing Hooks
+
+```ruby
+importer = Object.new.extend(CsvWizard::Importer)
+importer.map_csv_to(User) do
+  column "Name", required: true
+  column "Email", required: true
+  column "Age", default: 18
+end
+
+failed_rows = importer.import(
+  "path/to/users.csv",
+  before_import: ->(attrs) { attrs[:name] = attrs[:name].strip },
+  after_import: ->(record) { puts "Imported #{record.id}" }
+)
+
+puts failed_rows.inspect
+```
+
+---
+
+### 3. Handling Logging
+
+- By default, `CsvWizard::ImportJob` logs via **Rails.logger** if Rails is defined.
+- Otherwise, it uses the **Logging gem**.
+
+```ruby
+require "logging"
+logger = Logging.logger["CsvWizard"]
+logger.level = :info
+
+CsvWizard::ImportJob.new.perform("User", mappings, file_path, logger: logger)
+```
+
+---
+
+### 4. Error Reporting
+
+You can use `CsvWizard::ErrorReporter` to generate a full report of errors:
+
+```ruby
+reporter = CsvWizard::ErrorReporter.new
+reporter.add_errors(["Name is required", "Email is invalid"], 2)
+reporter.add_errors(["Age must be numeric"], 5)
+
+puts reporter.full_report
+# Output:
+# Line 2: Name is required, Email is invalid
+# Line 5: Age must be numeric
+```
+
+---
+
+### 5. Example CSV
+
+```csv
+Name,Email,Age
+John Doe,john@example.com,30
+Jane Smith,,25
+Bob, bob@example.com,
+```
+
+- Missing values trigger **validation errors**.
+- Default values are applied if configured.
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my_feature`)
+3. Commit your changes (`git commit -am 'Add feature'`)
+4. Push to the branch (`git push origin feature/my_feature`)
+5. Open a Pull Request
+
+---
+
+## License
+
+MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
+
+---
+
+## Metadata for RubyGems
+
+- Homepage: [https://github.com/username/csv_wizard](https://github.com/username/csv_wizard)
+- Source code: [https://github.com/username/csv_wizard](https://github.com/username/csv_wizard)
+- Required Ruby version: >= 2.6
+- Required Rails version: >= 6.0
+
+---
+
+## Summary
+
+CsvWizard makes CSV imports **easy, reliable, and Rails-friendly**.
+It supports validations, defaults, hooks, and error reporting to make importing data **safe and efficient**.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/csv_wizard/error_reporter.rb

@@ -0,0 +1,21 @@
+module CsvWizard
+  class ErrorReporter
+    attr_reader :row_errors
+
+    def initialize
+      @row_errors = {}
+    end
+
+    def add_errors(errors, line_number)
+      @row_errors[line_number] = errors
+    end
+
+    def any?
+      row_errors.any?
+    end
+
+    def full_report
+      row_errors.map { |line, errors| "Line #{line}: #{errors.join(", ")}" }.join("\n")
+    end
+  end
+end

data/lib/csv_wizard/import_job.rb

@@ -0,0 +1,34 @@
+module CsvWizard
+  class ImportJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(model_name, mappings, file_path, logger: nil)
+      model = model_name.constantize
+      mapper = Mapper.new
+      mappings.each { |csv, attr| mapper.map(csv, to: attr) }
+
+      importer = Object.new.extend(Importer)
+      importer.instance_variable_set(:@mapper, mapper)
+      importer.instance_variable_set(:@model_class, model)
+
+      failed_rows = importer.import(file_path)
+
+      # Conditional logger
+      log =
+        if logger
+          logger
+        elsif defined?(Rails) && Rails.respond_to?(:logger)
+          Rails.logger
+        else
+          require "logging"
+          Logging.logger['CsvWizard'].tap { |l| l.level = :info }
+        end
+
+      if failed_rows.any?
+        log.error("[CSV Import] Errors: #{failed_rows.inspect}")
+      else
+        log.info("[CSV Import] Completed successfully.")
+      end
+    end
+  end
+end

data/lib/csv_wizard/importer.rb

@@ -0,0 +1,25 @@
+module CsvWizard
+  module Importer
+    def map_csv_to(model_class, &block)
+      @mapper = Mapper.new
+      instance_eval(&block)
+      @model_class = model_class
+    end
+
+    def column(name, required: false, default: nil)
+      @mapper.map(name, to: name.downcase.to_sym, required: required, default: default)
+    end
+
+    def import(file_path, before_import: nil, after_import: nil)
+      failed_rows = []
+
+      CSV.foreach(file_path, headers: true).with_index(2) do |row, idx|
+        processor = RowProcessor.new(@model_class, @mapper, row.to_h, idx, before_import: before_import, after_import: after_import)
+        success = processor.save
+        failed_rows << { line: idx, row: row.to_h, errors: processor.errors } unless success
+      end
+
+      failed_rows
+    end
+  end
+end

data/lib/csv_wizard/mapper.rb

@@ -0,0 +1,25 @@
+module CsvWizard
+  class Mapper
+    attr_reader :mappings
+
+    def initialize
+      @mappings = {}
+      @required_columns = []
+      @defaults = {}
+    end
+
+    def map(csv_column, to:, required: false, default: nil)
+      @mappings[csv_column] = to
+      @required_columns << csv_column if required
+      @defaults[to] = default if default
+    end
+
+    def required_columns
+      @required_columns
+    end
+
+    def defaults
+      @defaults
+    end
+  end
+end

data/lib/csv_wizard/row_processor.rb

@@ -0,0 +1,47 @@
+module CsvWizard
+  class RowProcessor
+    attr_reader :model, :mapper, :row, :line_number, :errors
+
+    def initialize(model, mapper, row, line_number, defaults: {}, before_import: nil, after_import: nil)
+      @model = model
+      @mapper = mapper
+      @row = row
+      @line_number = line_number
+      @errors = []
+      @defaults = defaults
+      @before_import = before_import
+      @after_import = after_import
+    end
+
+    def save
+      missing = mapper.required_columns.select { |col| row[col].nil? || row[col].strip.empty? }
+      unless missing.empty?
+        @errors = missing.map { |col| "#{col} is required" }
+        return false
+      end
+
+      attrs = mapped_attributes
+      attrs = @before_import.call(attrs) if @before_import
+
+      record = model.new(attrs)
+      if record.save
+        @after_import.call(record) if @after_import
+        true
+      else
+        @errors = record.errors.full_messages
+        false
+      end
+    rescue => e
+      @errors = ["Exception: #{e.message}"]
+      false
+    end
+
+    private
+
+    def mapped_attributes
+      mapper.mappings.each_with_object({}) do |(csv_col, attr), hash|
+        hash[attr] = row[csv_col] || @defaults[attr] || mapper.defaults[attr]
+      end
+    end
+  end
+end

data/lib/csv_wizard/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CsvWizard
+  VERSION = "0.1.0"
+end

data/lib/csv_wizard.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+require "csv"
+require "active_support"
+require "active_record"
+require "active_job"
+
+require "csv_wizard/importer"
+require "csv_wizard/mapper"
+require "csv_wizard/row_processor"
+require "csv_wizard/error_reporter"
+require "csv_wizard/import_job"
+
+module CsvWizard
+  class Error < StandardError; end
+  # Fucked up
+end

data/sig/csv_wizard.rbs

@@ -0,0 +1,4 @@
+module CsvWizard
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,170 @@
+--- !ruby/object:Gem::Specification
+name: csv_wizard
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- mrmalvi
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !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: 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: activejob
+  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: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description: CsvWizard provides a simple framework to import CSV files into Rails
+  models. It supports required fields, default values, row-level validation, and hooks
+  for pre- and post-processing.
+email:
+- malviyak00@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/rubyonrails.yml"
+- ".ruby-version"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/csv_wizard.rb
+- lib/csv_wizard/error_reporter.rb
+- lib/csv_wizard/import_job.rb
+- lib/csv_wizard/importer.rb
+- lib/csv_wizard/mapper.rb
+- lib/csv_wizard/row_processor.rb
+- lib/csv_wizard/version.rb
+- sig/csv_wizard.rbs
+homepage: https://github.com/mrmalvi/csv_wizard
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mrmalvi/csv_wizard
+  source_code_uri: https://github.com/mrmalvi/csv_wizard
+  changelog_uri: https://github.com/mrmalvi/csv_wizard/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.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: 'CsvWizard: Import and process CSV files into ActiveRecord models.'
+test_files: []