better_seeder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7d791cd07db093b5651fff8ee43c8a9b04360efd6ad7aaa83978f9233f53f7a2
+  data.tar.gz: 4b4ca980a85b832b9261750db2742a89f61a18bc6a33f253a6486076a9a572ea
+SHA512:
+  metadata.gz: 765e67ac2cac0af3e1b3a443f9896ce1212a0a6e0e6815b4bd7e7e148f75aabab3b6da279f2b5dc32c5a070c02024567524e175c710a5604e297221aa70157e8
+  data.tar.gz: a87f473eb71a6156dfdb829435323b67bcfe5645ebb30e32143071ba94107cdd99d730452032b6360c870212967d4d8e8c8b4f6fb496d6ba723384aa1e52e03e

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 alessiobussolari
+
+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,215 @@
+# BetterSeeder
+
+**BetterSeeder** is a Rails gem designed to simplify and centralize your application's seeding process. It provides a flexible system to generate dynamic data, validate it using Dry-schema, enforce uniqueness constraints, load it into the database, and export it in various formats (SQL, CSV, JSON). Configuration is centralized via a Rails initializer, while model-specific logic is defined in dedicated structure files.
+
+---
+
+## Features
+
+- **Dynamic Data Generation**  
+  Define custom data generators for each model in dedicated structure files.
+
+- **Validation and Uniqueness**  
+  Validate generated records using Dry-schema and enforce uniqueness constraints (both single and multi-column).
+
+- **Loading & Exporting**  
+  - Load generated data directly into your database (with support for parent/child relationships).  
+  - Export data as a single SQL INSERT statement, or in CSV or JSON formats.
+
+- **Centralized Configuration**  
+  Easily customize settings such as `log_language`, `structure_path`, and `preload_path` via a Rails initializer. If no initializer is provided, default values are used.
+
+- **Automatic Initializer Installation**  
+  Use the `BetterSeeder.install` method to automatically create the initializer file in your Rails app.
+
+---
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'better_seeder'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+---
+
+## Configuration
+
+BetterSeeder uses a centralized configuration defined in `BetterSeeder.configuration`. You can override the default settings via an initializer. For example, create a file:
+
+```ruby
+# config/initializers/better_seeder.rb
+require 'better_seeder'
+
+BetterSeeder.configure do |config|
+  config.log_language   = :en
+  config.structure_path = Rails.root.join('db', 'seed', 'structure')
+  config.preload_path   = Rails.root.join('db', 'seed', 'preload')
+end
+```
+
+If these values are set in the initializer, they will be used; otherwise, the gem will fall back to its default values.
+
+---
+
+## Install Method
+
+BetterSeeder provides an `install` method that automatically creates an initializer file. To run the installer, simply execute in your Rails console:
+
+```ruby
+BetterSeeder.install
+```
+
+This command creates (if not already present) the file `config/initializers/better_seeder.rb` with content similar to:
+
+```ruby
+# BetterSeeder initializer
+BetterSeeder.configure do |config|
+  config.log_language   = :en
+  config.structure_path = Rails.root.join('db', 'seed', 'structure')
+  config.preload_path   = Rails.root.join('db', 'seed', 'preload')
+end
+```
+
+---
+
+## Structure Files
+
+For each model, create a structure file that centralizes the logic for generating, validating, and configuring seed data. Each structure file should define at least the following methods:
+
+- **`structure`**  
+  Returns a hash where each key represents an attribute and its value is an array in the format `[type, lambda_generator]`.
+
+- **`seed_schema` (Optional)**  
+  Defines a Dry-schema for validating the generated records.
+
+- **`seed_config`**  
+  Returns a hash with model-specific seeding settings:
+    - `file_name`: The output file name (without extension)
+    - `columns: { excluded: [...] }`: Columns to exclude from the generated data
+    - `generate_data`: Boolean flag indicating whether to generate data dynamically (if false, existing records are used)
+    - `count`: The number of records to generate (default: 10)
+    - `load_data`: Boolean flag indicating whether the generated records should be inserted into the database
+    - `parent`: For child models, this specifies the parent model(s) used for injecting foreign keys
+
+- **`unique_keys` (Optional)**  
+  Returns an array of column groups (each group is an array of symbols) that must be unique.  
+  For example:
+
+  ```ruby
+  def self.unique_keys
+    [[:email], [:first_name, :last_name]]
+  end
+  ```
+
+### Example Structure File
+
+For a generic model `MyModel` in the namespace `MyNamespace`, create a file at `db/seed/structure/my_namespace/my_model_structure.rb`:
+
+```ruby
+# db/seed/structure/my_namespace/my_model_structure.rb
+module MyNamespace
+  class MyModelStructure < BetterSeeder::StructureBase
+    # Defines generators for each attribute.
+    def self.structure
+      {
+        name:       [:string,   -> { FFaker::Name.name }],
+        email:      [:string,   -> { FFaker::Internet.email }],
+        created_at: [:datetime, -> { Time.zone.now }]
+      }
+    end
+
+    # Optional: Validate generated records using Dry-schema.
+    def self.seed_schema
+      Dry::Schema.Params do
+        required(:name).filled(:string)
+        required(:email).filled(:string)
+        required(:created_at).filled(:time)
+      end
+    end
+
+    # Specific seeding configuration for MyModel.
+    def self.seed_config
+      {
+        file_name: 'my_model_seed',
+        columns: { excluded: [:id, :updated_at] },
+        generate_data: true,
+        count: 50,
+        load_data: true,
+        parent: nil
+      }
+    end
+
+    # Optional: Uniqueness constraints; for example, email must be unique.
+    def self.unique_keys
+      [[:email]]
+    end
+  end
+end
+```
+
+---
+
+## How It Works
+
+When you call `BetterSeeder.magic` with a configuration that contains an array of model names (as strings), the gem will:
+
+1. **Load Structure Files**  
+   For each model, the gem loads the corresponding structure file from `BetterSeeder.configuration.structure_path`.
+
+2. **Retrieve Seeding Configurations**  
+   It calls the model's `seed_config` method to get its specific settings.
+
+3. **Generate or Retrieve Records**  
+   Using the `structure` method, the gem generates data dynamically (or retrieves existing records) and validates them with `seed_schema` if provided. Uniqueness is enforced based on `unique_keys`.
+
+4. **Handle Parent/Child Relationships**  
+   For child models, foreign keys are automatically injected using the records from the parent models.
+
+5. **Load and Export**  
+   If enabled (`load_data: true`), the generated records are inserted into the database and then exported in the specified format (SQL, CSV, or JSON). Export files are saved in the directory defined by `BetterSeeder.configuration.preload_path` (default: `db/seed/preload`).
+
+### Example Usage
+
+```ruby
+BetterSeeder.magic(
+  {
+    configurations: { export_type: :sql },
+    data: [
+      'MyNamespace::MyModel',
+      'OtherNamespace::OtherModel'
+    ]
+  }
+)
+```
+
+This command processes each model by:
+
+- Reading its structure file and retrieving its configuration via `seed_config`.
+- Generating or fetching data according to the specified rules.
+- Inserting the data into the database (if `load_data` is enabled).
+- Exporting the data as an SQL file (or CSV/JSON, depending on `export_type`).
+
+---
+
+## Conclusion
+
+BetterSeeder provides a modular, configurable, and extensible system for seeding your Rails application's data:
+
+- **Centralized Configuration:**  
+  Configure paths and logging via a Rails initializer.
+
+- **Modular Structure Files:**  
+  Define generation, validation, and configuration logic for each model in dedicated structure files.
+
+- **Seamless Data Handling:**  
+  Automatically generate, validate, load, and export seed data with support for parent/child relationships and various export formats.
+
+For further details or contributions, please refer to the official repository or documentation.

data/lib/better_seeder/configuration.rb

@@ -0,0 +1,38 @@
+# lib/better_seeder/configuration.rb
+
+module BetterSeeder
+  class Configuration
+    attr_accessor :log_language, :structure_path, :preload_path
+
+    def initialize
+      if defined?(Rails) && Rails.respond_to?(:root)
+        @log_language   = :en
+        @structure_path = Rails.root.join('db', 'seed', 'structure')
+        @preload_path   = Rails.root.join('db', 'seed', 'preload')
+      else
+        @log_language   = :en
+        @structure_path = File.join(Dir.pwd, 'db', 'seed', 'structure')
+        @preload_path   = File.join(Dir.pwd, 'db', 'seed', 'preload')
+      end
+    end
+  end
+
+  # Restituisce l'istanza globale di configurazione. Se non esiste, viene creata con i valori di default.
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Permette di configurare BetterSeeder tramite un blocco. Ad esempio, in config/initializers/better_seeder.rb:
+  #
+  #   BetterSeeder.configure do |config|
+  #     config.log_language = :en
+  #     config.structure_path = Rails.root.join('db', 'seed', 'structure')
+  #     config.preload_path = Rails.root.join('db', 'seed', 'preload')
+  #   end
+  #
+  # Se questo blocco viene eseguito, i valori della configurazione verranno aggiornati; altrimenti,
+  # verranno utilizzati quelli definiti nel costruttore (default).
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/better_seeder/exporters/base.rb

@@ -0,0 +1,65 @@
+# lib/better_seeder/exporter/base_exporter.rb
+
+module BetterSeeder
+  module Exporters
+    class Base
+      # I dati da esportare.
+      # output_path: nome del file (senza estensione) da concatenare al preload_path configurato.
+      # table_name: (opzionale) nome della tabella, utile ad esempio per SqlExporter.
+      attr_reader :data, :output_path, :table_name
+
+      # Inizializza l'exporter.
+      #
+      # Esempio d'uso:
+      #   data = [
+      #     { id: 1, name: "Alice", email: "alice@example.com" },
+      #     { id: 2, name: "Bob", email: "bob@example.com" }
+      #   ]
+      #
+      #   json_exporter = BetterSeeder::Performers::JsonExporter.new(data, output_path: 'users', table_name: 'users')
+      #   json_exporter.export
+      #
+      # @param data [Array<Hash>] I dati da esportare.
+      # @param output_path [String] Nome del file (senza estensione).
+      # @param table_name [String] Nome della tabella (usato in SqlExporter).
+      def initialize(data, output_path:, table_name: 'my_table')
+        @data = data
+        # Utilizza il preload_path definito nella configurazione BetterSeeder (impostato nell'initializer).
+        @output_path = File.join(BetterSeeder.configuration.preload_path, output_path)
+        @table_name = table_name
+      end
+
+      # Restituisce la directory in cui salvare i file.
+      # In questo caso, utilizza la configurazione BetterSeeder.configuration.preload_path.
+      #
+      # @return [String] il percorso della directory di output.
+      def output_directory
+        BetterSeeder.configuration.preload_path.to_s
+      end
+
+      # Verifica che la directory di output esista; se non esiste, la crea.
+      def ensure_output_directory
+        FileUtils.mkdir_p(output_directory) unless Dir.exist?(output_directory)
+      end
+
+      # Costruisce il percorso completo del file di output, combinando la directory, l'output_path e l'estensione.
+      #
+      # @return [String] il percorso completo del file.
+      def full_output_path
+        ensure_output_directory
+        "#{output_path}#{extension}"
+      end
+
+      # Metodo astratto per ottenere l'estensione del file (es. ".json", ".csv", ".sql").
+      # Le classi derivate devono implementarlo.
+      def extension
+        raise NotImplementedError, "Subclasses must implement #extension"
+      end
+
+      # Metodo astratto per effettuare l'export.
+      def export
+        raise NotImplementedError, "Subclasses must implement the export method"
+      end
+    end
+  end
+end

data/lib/better_seeder/exporters/csv.rb

@@ -0,0 +1,23 @@
+module BetterSeeder
+  module Exporters
+    class Csv < Base
+      # Esporta i dati in formato CSV e li salva in un file nella cartella "db/seed/preload".
+      # Se la cartella non esiste, viene creata automaticamente.
+      def export
+        return if data.empty?
+        headers = data.first.keys
+
+        # Costruisce il percorso completo del file di output
+        full_path = File.join(full_output_path)
+
+        CSV.open(full_path, 'w', write_headers: true, headers: headers) do |csv|
+          data.each { |row| csv << row.values }
+        end
+      end
+
+      def extension
+        '.csv'
+      end
+    end
+  end
+end

data/lib/better_seeder/exporters/json.rb

@@ -0,0 +1,20 @@
+module BetterSeeder
+  module Exporters
+    class Json < Base
+      # Esporta i dati in formato JSON e li salva in un file nella cartella "db/seed/preload".
+      # Se la cartella non esiste, viene creata automaticamente.
+      def export
+        # Imposta la directory di output
+        full_path = File.join(full_output_path)
+
+        File.open(full_path, 'w') do |file|
+          file.write(JSON.pretty_generate(data))
+        end
+      end
+
+      def extension
+        '.json'
+      end
+    end
+  end
+end

data/lib/better_seeder/exporters/sql.rb

@@ -0,0 +1,41 @@
+module BetterSeeder
+  module Exporters
+    class Sql < Base
+      # Esporta i dati in formato SQL, generando una singola istruzione INSERT
+      # che inserisce in blocco tutti i record.
+      #
+      # Il metodo costruisce una stringa con la sintassi:
+      # INSERT INTO table_name (col1, col2, ...) VALUES
+      #   (val11, val12, ...),
+      #   (val21, val22, ...),
+      #   ... ;
+      def export
+        return if data.empty?
+        columns = data.first.keys
+
+        # Crea l'array delle tuple di valori per ciascun record.
+        values_list = data.map do |row|
+          row_values = columns.map do |col|
+            value = row[col]
+            # Se il valore è nil restituisce NULL, altrimenti esegue l'escaping delle virgolette singole.
+            value.nil? ? "NULL" : "'#{value.to_s.gsub("'", "''")}'"
+          end
+          "(#{row_values.join(', ')})"
+        end
+
+        # Costruisce la query INSERT unica
+        insert_statement = "INSERT INTO #{table_name} (#{columns.join(', ')}) VALUES #{values_list.join(', ')};"
+
+        full_path = File.join(full_output_path)
+
+        File.open(full_path, 'w') do |file|
+          file.puts(insert_statement)
+        end
+      end
+
+      def extension
+        '.sql'
+      end
+    end
+  end
+end

data/lib/better_seeder/generators/data_generator.rb

@@ -0,0 +1,117 @@
+module BetterSeeder
+  module Generators
+    class DataGenerator
+      # Genera dati fittizi per il modello specificato utilizzando il file di structure.
+      #
+      # Opzioni attese (Hash):
+      #   :model => Nome del modello come stringa, es. 'Media::Participant'
+      #   :count => Numero di record da generare (default: 10)
+      #
+      # Se la classe di structure definisce il metodo `unique_keys` (che deve restituire un array di array,
+      # es. [[:media_id, :creator_id], [:role]]), verrà controllato che ogni record generato sia univoco,
+      # sia in memoria (tra quelli generati in questa esecuzione) che rispetto ai dati già presenti nel database.
+      # Se il record è duplicato, verrà rigenerato.
+      #
+      # Se la classe di structure definisce il metodo `seed_schema`, il record verrà validato tramite Dry-schema.
+      #
+      # @return [Array<Hash>] Array di record validati e univoci generati
+      def self.generate(options = {})
+        model_name = options[:model] or raise ArgumentError, "Missing :model option"
+        count      = options[:count]  || 10
+
+        # Costruisce il percorso del file di structure.
+        # Ad esempio, per il modello "Media::Participant", il file atteso sarà:
+        # "db/seed/structure/media/participant_structure.rb"
+        structure_file = File.expand_path(
+          File.join(BetterSeeder.configuration.structure_path, "#{model_name.underscore}_structure.rb"),
+          Dir.pwd
+        )
+        raise "Structure file not found: #{structure_file}" unless File.exist?(structure_file)
+
+        # Carica il file di structure.
+        load structure_file
+
+        # Costruisce il nome della classe di structure: semplice concatenazione.
+        # Es: "Media::Participant" => "Media::ParticipantStructure"
+        structure_class_name = "#{model_name}Structure"
+        begin
+          structure_class = Object.const_get(structure_class_name)
+        rescue error
+          message = "Structure class not found: #{structure_class_name}"
+          BetterSeeder::Utils.logger(message: message)
+          raise error
+        end
+
+        generation_rules = structure_class.structure
+        raise "Structure must be a Hash" unless generation_rules.is_a?(Hash)
+
+        # Recupera lo schema per la validazione, se definito.
+        schema = structure_class.respond_to?(:seed_schema) ? structure_class.seed_schema : nil
+
+        # Gestione dei vincoli di unicità.
+        # Se il metodo unique_keys è definito, lo si aspetta come array di array,
+        # ad esempio: [[:media_id, :creator_id], [:role]]
+        unique_key_sets = structure_class.respond_to?(:unique_keys) ? structure_class.unique_keys : []
+        # Pre-carica i valori già presenti nel database per ciascun gruppo di colonne.
+        unique_sets = unique_key_sets.map do |cols|
+          existing_keys = Set.new
+          # Usa pluck per recuperare le colonne specificate dal modello.
+          # Se il gruppo è di una sola colonna, pluck restituirà un array di valori; se multi, un array di array.
+          db_rows = Object.const_get(model_name).pluck(*cols)
+          db_rows.each do |row|
+            composite_key = cols.size == 1 ? row.to_s : row.join("_")
+            existing_keys.add(composite_key)
+          end
+          { columns: cols, set: existing_keys }
+        end
+
+        generated_records = []
+        progressbar = ProgressBar.create(total: count, format: '%a %B %p%% %t')
+        attempts = 0
+
+        # Continua a generare record finché non si raggiunge il numero richiesto.
+        while generated_records.size < count
+          attempts += 1
+          record = {}
+          generation_rules.each do |attribute, rule|
+            # Ogni rule è un array: [tipo, generatore]
+            generator = rule[1]
+            value = generator.respond_to?(:call) ? generator.call : generator
+            record[attribute] = value
+          end
+
+          # Se è definito uno schema, valida il record.
+          if schema
+            result = schema.call(record)
+            unless result.success?
+              message = "[ERROR] Record validation failed for #{model_name}: #{result.errors.to_h}"
+              BetterSeeder::Utils.logger(message: message)
+              progressbar.increment
+              next  # Rigenera il record se la validazione fallisce.
+            end
+          end
+
+          # Controlla i vincoli di unicità: verifica che il record non sia già presente
+          duplicate = unique_sets.any? do |unique_set|
+            composite_key = unique_set[:columns].map { |col| record[col].to_s }.join("_")
+            unique_set[:set].include?(composite_key)
+          end
+          next if duplicate
+
+          # Aggiorna le strutture per il controllo di unicità con il nuovo record.
+          unique_sets.each do |unique_set|
+            composite_key = unique_set[:columns].map { |col| record[col].to_s }.join("_")
+            unique_set[:set].add(composite_key)
+          end
+
+          generated_records << record
+          progressbar.increment
+        end
+
+        message = "[INFO] Generated #{generated_records.size} unique records for #{model_name} after #{attempts} attempts."
+        BetterSeeder::Utils.logger(message: message)
+        generated_records
+      end
+    end
+  end
+end

data/lib/better_seeder/structure/utils.rb

@@ -0,0 +1,15 @@
+require 'dry-types'
+
+module BetterSeeder
+  # Superclasse per tutte le structures.
+  # Fornisce il modulo Types da utilizzare per la definizione dei tipi.
+  module Structure
+    class Utils
+      module Types
+        include Dry.Types()
+      end
+    end
+  end
+end
+
+BetterSeederTypes = BetterSeeder::Structure::Utils::Types

data/lib/better_seeder/utils.rb

@@ -0,0 +1,22 @@
+# lib/better_seeder/utils.rb
+
+module BetterSeeder
+  module Utils
+    # Trasforma un nome di classe in snake_case.
+    # Esempio: "Campaigns::Campaign" => "campaigns_campaign"
+    def self.transform_class_name(class_name)
+      elements = class_name.split("::").map(&:underscore)
+      # Aggiunge "_structure.rb" all'ultimo elemento
+      elements[-1] = "#{elements[-1]}_structure.rb"
+      elements.join("/")
+    end
+
+    def self.logger(message: nil)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.info message
+      else
+        puts message
+      end
+    end
+  end
+end

data/lib/better_seeder/version.rb

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

data/lib/better_seeder.rb

@@ -0,0 +1,269 @@
+require_relative "better_seeder/utils"
+require_relative "better_seeder/configuration"
+require_relative "better_seeder/structure/utils"
+require_relative "better_seeder/generators/data_generator"
+require_relative "better_seeder/exporters/base"
+require_relative "better_seeder/exporters/json"
+require_relative "better_seeder/exporters/csv"
+require_relative "better_seeder/exporters/sql"
+
+module BetterSeeder
+  class Configuration
+    attr_accessor :log_language, :structure_path, :preload_path
+
+    def initialize
+      if defined?(Rails) && Rails.respond_to?(:root)
+        @log_language   = :en
+        @structure_path = Rails.root.join('db', 'seed', 'structure')
+        @preload_path   = Rails.root.join('db', 'seed', 'preload')
+      else
+        @log_language   = :en
+        @structure_path = File.join(Dir.pwd, 'db', 'seed', 'structure')
+        @preload_path   = File.join(Dir.pwd, 'db', 'seed', 'preload')
+      end
+    end
+  end
+
+  # Restituisce l'istanza globale di configurazione. Se non esiste, viene creata con i valori di default.
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Permette di configurare BetterSeeder tramite un blocco. Ad esempio, in config/initializers/better_seeder.rb:
+  #
+  #   BetterSeeder.configure do |config|
+  #     config.log_language = :en
+  #     config.structure_path = Rails.root.join('db', 'seed', 'structure')
+  #     config.preload_path = Rails.root.join('db', 'seed', 'preload')
+  #   end
+  #
+  # Se questo blocco viene eseguito, i valori della configurazione verranno aggiornati; altrimenti,
+  # verranno utilizzati quelli definiti nel costruttore (default).
+  def self.configure
+    yield(configuration)
+  end
+
+  # Metodo install che crea l'initializer di BetterSeeder in config/initializers
+  # con le seguenti impostazioni:
+  #   - log_language: lingua da usare per i log (es. :en, :it)
+  #   - structure_path: percorso dove sono memorizzati i file di structure (default: Rails.root/db/seed/structure)
+  #   - preload_path: percorso dove verranno salvati i file esportati (default: Rails.root/db/seed/preload)
+  def self.install
+    initializer_path = File.join(Rails.root, "config", "initializers", "better_seeder.rb")
+
+    if File.exist?(initializer_path)
+      message = "BetterSeeder initializer already exists at #{initializer_path}"
+    else
+      content = <<~RUBY
+        # BetterSeeder initializer
+        # This file was generated by BetterSeeder.install
+        BetterSeeder.configure do |config|
+          config.log_language = :en
+          config.structure_path = Rails.root.join('db', 'seed', 'structure')
+          config.preload_path = Rails.root.join('db', 'seed', 'preload')
+        end
+      RUBY
+
+      FileUtils.mkdir_p(File.dirname(initializer_path))
+      File.write(initializer_path, content)
+      message = "BetterSeeder initializer created at #{initializer_path}"
+    end
+
+    # Use Rails.logger if available, otherwise fallback to STDOUT.
+    BetterSeeder::Utils.logger(message: message)
+  end
+
+  # Metodo master della gemma.
+  #
+  # La configurazione attesa è un hash con la seguente struttura:
+  #
+  # {
+  #   configurations: { export_type: :sql },
+  #   data: [
+  #     'Campaigns::Campaign',
+  #     'Creators::Creator',
+  #     'Media::Media',
+  #     'Media::Participant'
+  #   ]
+  # }
+  #
+  # Per ciascun modello (identificato da stringa), viene:
+  #   - Caricato il file di structure relativo, che definisce la configurazione specifica tramite `seed_config`
+  #   - Recuperati (o generati) i record, con eventuali controlli di esclusione e iniezione di foreign key per modelli child
+  #   - Se abilitato, i record vengono caricati nel database e successivamente esportati nel formato richiesto
+  #   - Vengono raccolte statistiche e loggato il tempo totale di esecuzione
+  def self.magic(config)
+    start_time = Time.now
+    stats = {}                   # Statistiche: modello => numero di record caricati
+    parent_loaded_records = {}   # Per memorizzare i record creati per i modelli parent
+
+    ActiveRecord::Base.transaction do
+      export_type = config[:configurations][:export_type]
+      model_names = config[:data]
+      model_names.each do |model_name|
+        process_config(model_name, export_type, stats, parent_loaded_records)
+      end
+    end
+
+    total_time = Time.now - start_time
+    log_statistics(stats, total_time)
+  end
+
+  private
+
+  # Processa la configurazione per un singolo modello.
+  # Carica il file di structure corrispondente e recupera la configurazione tramite `seed_config`.
+  # Quindi, esegue il recupero o la generazione dei record, iniezione di eventuali foreign key per modelli child,
+  # caricamento nel database (se abilitato) ed esportazione dei dati.
+  def self.process_config(model_name, export_type, stats, parent_loaded_records)
+    # Costruisce il percorso del file di structure in base al nome del modello.
+    # Esempio: per "Campaigns::Campaign", si attende "db/seed/structure/campaigns/campaign_structure.rb"
+    structure_file = File.expand_path(
+      File.join(BetterSeeder.configuration.structure_path, "#{model_name.underscore}_structure.rb"),
+      Dir.pwd
+    )
+    raise "Structure file not found: #{structure_file}" unless File.exist?(structure_file)
+
+    # Carica il file di structure.
+    load structure_file
+
+    # Il nome della classe di structure viene ottenuto semplicemente concatenando "Structure" al nome del modello.
+    # Es: "Campaigns::Campaign" => "Campaigns::CampaignStructure"
+    structure_class_name = "#{model_name}Structure"
+    begin
+      structure_class = Object.const_get(structure_class_name)
+    rescue error
+      message = "[ERROR] Structure class not found: #{structure_class_name}"
+      BetterSeeder::Utils.logger(message: message)
+      raise error
+    end
+
+    # Recupera la configurazione specifica dal file di structure tramite il metodo seed_config.
+    # Se non definito, vengono usati dei valori di default.
+    seed_config = structure_class.respond_to?(:seed_config) ? structure_class.seed_config : {}
+    file_name        = seed_config[:file_name] || "#{model_name.underscore}_seed"
+    excluded_columns = seed_config.dig(:columns, :excluded) || []
+    generate_data    = seed_config.fetch(:generate_data, true)
+    count            = seed_config[:count] || 10
+    load_data        = seed_config.fetch(:load_data, true)
+    parent           = seed_config[:parent]   # nil oppure valore (o array) per modelli child
+
+    # Log per indicare se il modello è parent o child.
+    message = if parent.nil?
+                "[INFO] Processing parent model #{model_name}"
+              else
+                "[INFO] Processing child model #{model_name} (parent: #{parent.inspect})"
+              end
+    BetterSeeder::Utils.logger(message: message)
+
+    # Recupera la classe reale del modello (ActiveRecord).
+    model_class = Object.const_get(model_name) rescue nil
+    unless model_class
+      message = "[ERROR] Model #{model_name} not found."
+      BetterSeeder::Utils.logger(message: message)
+
+      raise Object.const_get(model_name)
+    end
+
+    # Recupera o genera i record.
+    records = if generate_data
+                Generators::DataGenerator.generate(model: model_name, count: count)
+              else
+                model_class.all.map(&:attributes)
+              end
+
+    # Rimuove le colonne escluse.
+    processed_records = records.map do |record|
+      record.reject { |key, _| excluded_columns.include?(key.to_sym) }
+    end
+
+    # Se il modello è child, inietta le foreign key.
+    if parent
+      Array(parent).each do |parent_model_name|
+        parent_records = parent_loaded_records[parent_model_name]
+        if parent_records.nil? || parent_records.empty?
+          message = "[ERROR] No loaded records found for parent model #{parent_model_name}. Cannot assign foreign key for #{model_name}."
+          BetterSeeder::Utils.logger(message: message)
+        else
+          # Il nome della foreign key è ottenuto prendendo l'ultima parte del nome del modello padre,
+          # trasformandola in minuscolo e in forma singolare, e aggiungendo "_id".
+          foreign_key = parent_model_name.split("::").last.underscore.singularize + "_id"
+          processed_records.each do |record|
+            record[foreign_key] = parent_records.sample.id
+          end
+        end
+      end
+    end
+
+    # Se abilitato, carica i record nel database.
+    if load_data
+      total_records = processed_records.size
+      stats[model_name] = total_records
+      created_records = load_records_into_db(model_class, processed_records, total_records, model_name)
+      # Se il modello è parent, salva i record creati per poterli utilizzare in seguito per i modelli child.
+      parent_loaded_records[model_name] = created_records if parent.nil?
+    else
+      stats[model_name] = 0
+    end
+
+    # Esporta i record nel formato richiesto.
+    export_records(model_class, processed_records, export_type, file_name)
+  end
+
+  # Carica i record nel database, utilizzando una progress bar per monitorare il progresso.
+  # I log delle query SQL vengono temporaneamente disabilitati.
+  #
+  # @return [Array<Object>] Array dei record creati (istanze ActiveRecord)
+  def self.load_records_into_db(model_class, processed_records, total_records, model_name)
+    created_records = []
+    progressbar = ProgressBar.create(total: total_records, format: '%a %B %p%% %t')
+    message = "[INFO] Starting to load #{total_records} records for model #{model_name}..."
+    BetterSeeder::Utils.logger(message: message)
+
+    previous_level = ActiveRecord::Base.logger.level
+    ActiveRecord::Base.logger.level = Logger::ERROR
+
+    processed_records.each do |record|
+      created = model_class.create!(record)
+      created_records << created
+      progressbar.increment
+    end
+
+    ActiveRecord::Base.logger.level = previous_level
+    message = "[INFO] Finished loading #{total_records} records into model #{model_name}."
+    BetterSeeder::Utils.logger(message: message)
+    created_records
+  end
+
+  # Esporta i record nel formato specificato (json, csv, sql).
+  def self.export_records(model_class, processed_records, export_type, file_name)
+    exporter = case export_type.to_s.downcase
+               when 'json'
+                 Exporters::Json.new(processed_records, output_path: file_name)
+               when 'csv'
+                 Exporters::Csv.new(processed_records, output_path: file_name)
+               when 'sql'
+                 table_name = model_class.respond_to?(:table_name) ? model_class.table_name : transform_class_name(model_class.name)
+                 Exporters::Sql.new(processed_records, output_path: file_name, table_name: table_name)
+               else
+                 raise ArgumentError, "Unsupported export type: #{export_type}"
+               end
+
+    exporter.export
+    message = "[INFO] Exported data for #{model_class.name} to #{file_name}"
+    BetterSeeder::Utils.logger(message: message)
+  end
+
+  # Log finale con le statistiche raccolte e il tempo totale di esecuzione.
+  def self.log_statistics(stats, total_time)
+    stats_message = stats.map { |model, count| "#{model}: #{count} records" }.join(", ")
+    message = "[INFO] Finished processing all models in #{total_time.round(2)} seconds. Statistics: #{stats_message}"
+    BetterSeeder::Utils.logger(message: message)
+  end
+
+  # Metodo di utilità per trasformare il nome della classe in un formato in cui le lettere
+  # sono in minuscolo e separate da underscore.
+  def self.transform_class_name(class_name)
+    class_name.split("::").map(&:underscore).join("_")
+  end
+end

metadata

@@ -0,0 +1,171 @@
+--- !ruby/object:Gem::Specification
+name: better_seeder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- alessio_bussolari
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-02-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffaker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.19'
+- !ruby/object:Gem::Dependency
+  name: dry-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: ruby-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !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'
+description: A Rails gem that provides simple methods to optimize and maintain seed
+  data, making seeding more efficient and your code more maintainable and performant.
+email:
+- alessio.bussolari@pandev.it
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/better_seeder.rb
+- lib/better_seeder/configuration.rb
+- lib/better_seeder/exporters/base.rb
+- lib/better_seeder/exporters/csv.rb
+- lib/better_seeder/exporters/json.rb
+- lib/better_seeder/exporters/sql.rb
+- lib/better_seeder/generators/data_generator.rb
+- lib/better_seeder/structure/utils.rb
+- lib/better_seeder/utils.rb
+- lib/better_seeder/version.rb
+homepage: https://github.com/alessiobussolari/better_seeder
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/alessiobussolari/better_seeder
+  source_code_uri: https://github.com/alessiobussolari/better_seeder
+  changelog_uri: https://github.com/alessiobussolari/better_seeder/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: 'BetterSeeder: Simplify and optimize seeding.'
+test_files: []