easy_exports 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9e4470d18b361781bf745a2ca0dc563b82ccf603b456a55ad75a96113d3975c
-  data.tar.gz: 2576218f1f50c7743f1ef0a9cbada4e4ebe452f20dfb12dec4613aedcb0f23d4
+  metadata.gz: ed1cc375db87028330d34ded26b7e247a1ff4382267254118e06b994d5ae66d6
+  data.tar.gz: 4529a792f705691f04ea2b707a00503866d324ca2388bb5587ffd61563a8f98c
 SHA512:
-  metadata.gz: 401cf20c2ee26d378b6f31d02acb64e34bf49761c417f65e0954d9132f45855feb8fcc13be73948cbdbb5e1b941df1e30363a23828ed14bdec8601e1a13c4309
-  data.tar.gz: 2c5e04b944b9551843802c46ce131f5d0c7ff0e732d1db1f3fc07ef93a9e2227b67771e3a287da54b123d8b4e254e20206e41b9f8a70728cf79f4a3d287fb835
+  metadata.gz: c5ca2b24a5a23f685d04dfd020cff2dea3bab1d550f40c1467cfbc04608cfaf701bd69fd6eb91652a1f4ede40f8608fee8f87ac4bd22ff3742155b7238f19eab
+  data.tar.gz: 565ddc57bd713f6097aad5717ddb9c95d39fc18d7e3a5db2a81b5d489098c0fdf17723b7b83d9b018f25ef88c6ecb7edebfc7c364fb6aa1b5add5ae7db80ad5c

data/README.md

@@ -1,8 +1,5 @@
 # EasyExports
-Short description and motivation.
-
-## Usage
-How to use my plugin.
+EasyExports is a rails ActiveRecord ORM extension dedicated to streamlining and simplifying the model data export process by eliminating common complexities.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -20,9 +17,211 @@ Or install it yourself as:
 ```bash
 $ gem install easy_exports
 ```
+## Usage
+Upon installation, EasyExports seamlessly integrates with ```ActiveRecord::Base```, granting all models immediate access to its efficient export methods.
+
+### Generating Exportable Attributes
+
+Retrieve exportable attributes using the `exportable_attributes` method. This method retrieves attributes of the model itself and those of all its associations.
+
+```ruby
+  # Example Models and Exportable Attributes
+  
+  # User model with columns: first_name, last_name, created_at, updated_at
+  class User < ApplicationRecord
+    has_and_belongs_to_many :emails
+    has_many :phones
+  end
+  
+  # Exportable attributes for the User model
+  User.exportable_attributes
+    # =>
+    # {
+    #   "User" => ["id", "first name", "last name", "created at", "updated at"],
+    #   "Emails" => ["id", "address", "created at", "updated at"],
+    #   "Phones" => ["id", "number", "user id", "created at", "updated at"]
+    # }
+  
+  # Phone model with columns: number, user_id, created_at, updated_at
+  class Phone < ApplicationRecord
+    belongs_to :user
+  end
+  
+  # Exportable attributes for the Phone model
+  Phone.exportable_attributes
+    # =>
+    # {
+    #   "Phone" => ["id", "number", "user id", "created at", "updated at"],
+    #   "User" => ["id", "first name", "last name", "created at", "updated at"]
+    # }
+```
+
+### Generating Exports from Exportable Attributes
+
+To generate exports, use the `generate_exports(exportable_attributes, ids)` method.
+
+- The `exportable_attributes` argument specifies the chosen attributes from the exportable attributes list.
+- The `ids` argument is optional; provide IDs to export data for specific records.
+- Omitting `ids` will trigger exports for all records of the given model.
+
+The method returns an `EasyExports::Export` object containing hash data from the records and a `csv_string` that can be written to a CSV file.
+
+```ruby
+user_exportable_attributes = {"User"=>["id", "first name"], "Phones"=>["id", "number"], "Emails"=>["id", "address"]}
+
+exports_object = User.generate_exports(user_exportable_attributes)
+# => EasyExports::Export(Object)
+
+exports_data = exports_object.data
+# =>
+# [
+#   {"user_id"=>1, "user_first_name"=>"Sydney", "phones_id"=>1, "phones_number"=>"(473) 693-8745", "emails_id"=>5, "emails_address"=>"blake_armstrong@bahringer.test"},
+#   {"user_id"=>1, "user_first_name"=>"Sydney", "phones_id"=>2, "phones_number"=>"594-299-0722", "emails_id"=>6, "emails_address"=>"dulce@mertz.example"},
+#   {"user_id"=>1, "user_first_name"=>"Sydney", "phones_id"=>3, "phones_number"=>"1-609-662-2028", "emails_id"=>nil, "emails_address"=>nil},
+#   {"user_id"=>2, "user_first_name"=>"Stan", "phones_id"=>4, "phones_number"=>"951-671-9548", "emails_id"=>7, "emails_address"=>"dominick@durgan.example"},
+#   {"user_id"=>2, "user_first_name"=>"Stan", "phones_id"=>5, "phones_number"=>"1-698-432-7489", "emails_id"=>nil, "emails_address"=>nil}
+# ]
+
+exports_csv_string = exports_object.csv_string
+# =>
+# "user_id,user_first_name,phones_id,phones_number,emails_id,emails_address\n
+# 1,Sydney,1,(473) 693-8745,5,blake_armstrong@bahringer.test\n
+# 1,Sydney,2,594-299-0722,6,dulce@mertz.example\n
+# 1,Sydney,3,1-609-662-2028,,\n
+# 2,Stan,4,951-671-9548,7,dominick@durgan.example\n
+# 2,Stan,5,1-698-432-7489,,\n"
+
+# Writing csv_string to a file to visualize the generated export
+File.open(file_path, 'w') do |file|
+  file.write(exports_csv_string)
+end
+```
+<div align="center">
+  <img width="600" alt="csv_with_emails" src="https://github.com/SydDaps/easy_exports/assets/51008616/8b9df43c-419d-4ca0-8cb1-6217025b8050">
+</div>
+
+Exported CSV showcases data for:
+
+- User "Sydney" with 3 phones and 2 emails
+- User "Stan" with 2 phones and 1 email.
+- The main CSV header includes association names and attribute names.
+
+
+### Exportable Attributes Aliases
+
+Configure an alternative association name for exportable attributes using the `exportable_association_aliases(aliases)` model method.
+
+- Invoke this method below all association definitions.
+- `aliases` should be a hash in the pattern: `{valid_association_name or model_name: "alternative_name"}`.
+- Ensure all hash arguments are snake-cased.
+
+```ruby
+# Example Model with exportable_association_aliases
+
+# User model with columns: first_name, last_name, created_at, updated_at
+  class User < ApplicationRecord
+    has_many :phones
+  
+    exportable_association_aliases phones: :mobile_phones
+  end
+  
+  # Exportable attributes for the User model will now be
+  User.exportable_attributes
+  # =>
+  # {
+  #   "User" => ["id", "first name", "last name", "created at", "updated at"],
+  #   "Mobile phones" => ["id", "number", "user id", "created at", "updated at"]
+  # }
+```
+With the exportable_association_aliases configured, the phones association has been renamed to "Mobile phones". This new name will appear in the export header when generating exports with this alias for exportable attributes.
+
+### Excluding Specific Exportable Attributes
+
+Configure associations to exclude certain attributes from exportable attributes using the `exclude_exportable_attributes(association_attributes)` model method.
+
+- Invoke this method below all association declarations.
+- `association_attributes` should follow the pattern `{valid_association_name or model_name: [valid_attributes_to_remove]}`.
+- For removing attributes across all associations and the model itself, use the "all" key as the association_name.
+
+```ruby
+  # Example Model with exclude_exportable_attributes
+  
+  # User model with columns: first_name, last_name, created_at, updated_at
+  class User < ApplicationRecord
+    has_many :phones
+  
+    exclude_exportable_attributes all: [:id], user: [:last_name], phones: [:user_id]
+  end
+  
+  # Exportable attributes for the User model will now be
+  User.exportable_attributes
+  # =>
+  # {
+  #   "User" => ["first name", "created at", "updated at"],
+  #   "Phones" => ["number", "created at", "updated at"]
+  # }
+```
+In this example, note that:
+- All associations exclude the id attribute.
+- The User model excludes the last_name attribute.
+- The Phones association excludes the user_id attribute.
+  
+
+### Excluding Specific Exportable Attribute Associations
+
+Configure model's exportable attributes to exclude certain associations using the `associations_to_exclude(associations)` model method.
+
+- Apply this method below all association declarations.
+- `associations` should follow the pattern `['association_name']`.
 
-## Contributing
-Contribution directions go here.
+```ruby
+  # Example Model with associations_to_exclude
+  
+  # User model with columns: first_name, last_name, created_at, updated_at
+  class User < ApplicationRecord
+    has_many :phones
+    
+    associations_to_exclude [:phones]
+  end
+  
+  # Exportable attributes for the User model will now be
+  User.exportable_attributes
+  # =>
+  # {
+  #   "User" => ["id", "first name", "last name", "created at", "updated at"]
+  # }
+```
+In this example, the attributes of the phones association are excluded from the exportable attributes of the User model.
+
+
+### Adding Custom Attribute to Exportable Attributes
+
+Leverage a handy Rails method to transform a model instance method into an attribute, incorporating it into the exportable attributes.
+
+```ruby
+# Example Model with Custom Virtual Attribute
+
+# User model with columns: first_name, last_name, created_at, updated_at
+class User < ApplicationRecord
+  attribute :total_number_of_phones
+
+  has_many :phones
+    
+  associations_to_exclude [:phones]
+
+  def total_number_of_phones
+    phones.size
+  end
+end
+
+# Exportable attributes for the User model will now include
+User.exportable_attributes
+# =>
+# {
+#   "User" => ["id", "first name", "last name", "created at", "updated at", "total number of phones"]
+# }
+```
+In this example, the custom attribute "total number of phones" has been seamlessly integrated into the exportable attributes, showcasing the flexibility of Rails' capabilities.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/easy_exports/data_attributes_resolver.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module EasyExports
+  module DataAttributesResolver
+    extend ActiveSupport::Concern
+
+    class_methods do
+      private
+
+      def value_from_selected_attributes(selected_attributes, record, export_row_template)
+        selected_attributes.each_with_object([export_row_template]) do |(association_name, attributes), export_rows|
+          objects = objects_for_attribute(association_name, record)
+
+          attributes.each do |attribute|
+            attribute_values = resolve_attributes(attribute, objects)
+
+            attribute_values.each_with_index do |value, index|
+              export_column = export_rows[index] || export_row_template
+
+              export_rows[index] = export_column.merge(export_header(association_name, attribute) => value)
+            end
+          end
+
+          export_row_template.merge!(export_rows.first) if association_name == underscored_self_name
+        end
+      end
+
+      def resolve_attributes(attribute, objects)
+        objects.empty? ? [nil] : objects.map { |object| parse_attribute_value(object.send(attribute)) }.flatten
+      end
+
+      def parse_attribute_value(value)
+        return DateTime.parse(value.to_s).strftime('%Y-%m-%d %H:%M:%S') if value.is_a?(ActiveSupport::TimeWithZone)
+
+        return "'#{value}" if value.is_a?(String) && value&.start_with?('0')
+
+        value
+      end
+
+      def objects_for_attribute(association_name, record)
+        object = association_name == underscored_self_name ? record : record.send(association_name)
+        object.respond_to?(:each) ? object : [object].compact
+      end
+
+      def export_header(association_name, attribute)
+        association_alias = associations_aliases_store[underscored_self_name]
+        association_alias = association_alias.blank? ? nil : association_alias[association_name]
+
+        "#{association_alias || association_name}_#{attribute}"
+      end
+    end
+  end
+end

data/lib/easy_exports/data_loader.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module EasyExports
+  module DataLoader
+    extend ActiveSupport::Concern
+
+    class_methods do
+      private
+
+      def fetch_records(ids, selected_attributes)
+        validate_association_attributes(selected_attributes, 'to_exported_data')
+
+        records_with_preloaded_associations(ids, selected_attributes)
+      end
+
+      def association_attributes(association_name)
+        association_name = if association_name == underscored_self_name
+                             association_name.classify
+                           else
+                             reflect_on_all_associations.find do |association|
+                               association.name.to_s == association_name
+                             end&.class_name
+                           end
+
+        association_name.constantize.attribute_names
+      end
+
+      def records_with_preloaded_associations(ids, selected_attributes)
+        records = ids.blank? ? all : where(id: ids)
+
+        associations_to_preload = selected_attributes.keys
+        associations_to_preload.delete(underscored_self_name)
+
+        ActiveRecord::Associations::Preloader.new(
+          records: records,
+          associations: associations_to_preload
+        ).call
+
+        records
+      end
+    end
+  end
+end

data/lib/easy_exports/exclude_exportable_attributes_configurations.rb

@@ -50,6 +50,4 @@ module EasyExports
       end
     end
   end
-end
-
-ActiveRecord::Base.include EasyExports::ExcludeExportableAttributesConfigurations
+end

data/lib/easy_exports/exportable_association_aliases_configurations.rb

@@ -42,4 +42,4 @@ module EasyExports
   end
 end
 
-ActiveRecord::Base.include EasyExports::ExportableAssociationAliasesConfigurations
+# ActiveRecord::Base.include EasyExports::ExportableAssociationAliasesConfigurations

data/lib/easy_exports/exportable_attribute_resolvers.rb

@@ -32,5 +32,3 @@ module EasyExports
     end
   end
 end
-
-ActiveRecord::Base.include EasyExports::ExportableAttributeResolvers

data/lib/easy_exports/exportable_attributes.rb

@@ -4,11 +4,19 @@ module EasyExports
   module ExportableAttributes
     extend ActiveSupport::Concern
 
-    class_methods do
+    included do
       cattr_accessor :excluded_exportable_attributes_store, default: {}, instance_writer: false
       cattr_accessor :associations_aliases_store, default: {}, instance_writer: false
       cattr_accessor :associations_to_exclude_store, default: {}, instance_writer: false
+      #TODO: cache attributes(make option)
+
+      include EasyExports::ExportableAssociationAliasesConfigurations
+      include EasyExports::ExportableAttributeResolvers
+      include EasyExports::ExcludeExportableAttributesConfigurations
+      include EasyExports::ExportsGenerable
+    end
 
+    class_methods do
       def exportable_attributes
         self_with_associations.each_with_object({}) do |association, attributes|
           association_name = association.name.to_s.downcase
@@ -41,7 +49,7 @@ module EasyExports
       end
 
       def humanize_attribute_names(attributes)
-        attributes.map { |attribute| attribute.humanize(keep_id_suffix: true).downcase }
+        attributes.map { |attribute| attribute.humanize(keep_id_suffix: true).downcase }.sort
       end
     end
   end

data/lib/easy_exports/exports_generable.rb

@@ -4,18 +4,25 @@ module EasyExports
   module ExportsGenerable
     extend ActiveSupport::Concern
 
+    included do
+      include EasyExports::DataLoader
+      include EasyExports::DataAttributesResolver
+    end
+
     class_methods do
       def generate_exports(fields_to_export = {}, ids = [])
         validate_exclude_exportable_attributes_argument(fields_to_export, 'generate_exports')
 
         selected_exportable_attributes = revert_transformed_names(fields_to_export)
+        selected_exportable_attributes = rearrange_selected_attributes(selected_exportable_attributes)
+
         export_row_template = generate_export_row_template(selected_exportable_attributes)
 
         selected_attributes = revert_exportable_attributes_aliases(selected_exportable_attributes)
         records = fetch_records(ids, selected_attributes)
 
         exported_data = records.each_with_object([]) do |record, hash_to_export|
-          hash_to_export << value_from_selected_attributes(selected_attributes, record, export_row_template)
+          hash_to_export << value_from_selected_attributes(selected_attributes, record, export_row_template.dup)
         end.flatten
 
         csv_string = write_exported_data_to_csv(exported_data, export_row_template)
@@ -33,90 +40,31 @@ module EasyExports
         end
       end
 
-      def generate_export_row_template(selected_attributes)
-        selected_attributes.each_with_object({}) do |(association_name, attributes), export_row|
-          attributes.each do |attribute|
-            export_row.merge!("#{association_name}_#{attribute}" => nil)
-          end
-        end
-      end
+      def rearrange_selected_attributes(selected_attributes)
+        selected_attributes = selected_attributes.to_a
+        self_alias_name = associations_aliases_store[underscored_self_name]&.fetch(underscored_self_name, nil)
+        self_name = self_alias_name || underscored_self_name
 
-      def fetch_records(ids, selected_attributes)
-        validate_association_attributes(selected_attributes, 'to_exported_data')
-
-        records_with_preloaded_associations(ids, selected_attributes)
-      end
-
-      def association_attributes(association_name)
-        association_name = if association_name == underscored_self_name
-                             association_name.classify
-                           else
-                             reflect_on_all_associations.find do |association|
-                               association.name.to_s == association_name
-                             end&.class_name
-                           end
-
-        association_name.constantize.attribute_names
-      end
-
-      def records_with_preloaded_associations(ids, selected_attributes)
-        records = ids.blank? ? all : where(id: ids)
-
-        associations_to_preload = selected_attributes.keys
-        associations_to_preload.delete(underscored_self_name)
+        self_exportable_attributes = selected_attributes.find do |selected_attribute|
+          selected_attribute.first == self_name
+        end
 
-        ActiveRecord::Associations::Preloader.new(
-          records: records,
-          associations: associations_to_preload
-        ).call
+        if self_exportable_attributes.blank? || selected_attributes[0] == self_exportable_attributes
+          return selected_attributes.to_h
+        end
 
-        records
+        selected_attributes.delete(self_exportable_attributes)
+        selected_attributes.unshift(self_exportable_attributes).to_h
       end
 
-      def value_from_selected_attributes(selected_attributes, record, export_row_template)
-        selected_attributes.each_with_object([export_row_template]) do |(association_name, attributes), export_rows|
-          objects = objects_for_attribute(association_name, record)
-
+      def generate_export_row_template(selected_attributes)
+        selected_attributes.each_with_object({}) do |(association_name, attributes), export_row|
           attributes.each do |attribute|
-            attribute_values = resolve_attributes(attribute, objects)
-
-            attribute_values.each_with_index do |value, index|
-              export_column = export_rows[index] || export_row_template
-
-              export_rows[index] = export_column.merge(export_header(association_name, attribute) => value)
-            end
+            export_row.merge!("#{association_name}_#{attribute}" => nil)
           end
         end
       end
 
-      def export_header(association_name, attribute)
-        association_alias = associations_aliases_store[underscored_self_name]
-        association_alias = association_alias.blank? ? nil : association_alias[association_name]
-
-        "#{association_alias || association_name}_#{attribute}"
-      end
-
-      def resolve_attributes(attribute, objects)
-        objects.empty? ? [nil] : objects.map { |object| parse_attribute_value(object.send(attribute)) }.flatten
-      end
-
-      def parse_attribute_value(value)
-        value_class = value.class
-
-        if value_class.eql?(ActiveSupport::TimeWithZone)
-          DateTime.parse(value.to_s).strftime('%Y-%m-%d %H:%M:%S')
-        elsif !value_class.eql?(String)
-          value
-        else
-          value.start_with?('0') ? "'#{value}" : value
-        end
-      end
-
-      def objects_for_attribute(association_name, record)
-        object = association_name == underscored_self_name ? record : record.send(association_name)
-        object.respond_to?(:each) ? object : [object].compact
-      end
-
       def revert_exportable_attributes_aliases(attributes_with_aliases)
         attributes_with_aliases.transform_keys { |key| reversed_associations_name_aliases[key] || key }
       end
@@ -138,5 +86,3 @@ module EasyExports
     end
   end
 end
-
-ActiveRecord::Base.include EasyExports::ExportsGenerable

data/lib/easy_exports/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EasyExports
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/easy_exports.rb

@@ -2,14 +2,12 @@
 
 require 'easy_exports/version'
 require 'easy_exports/railtie'
-require 'easy_exports/exportable_attributes'
 require 'easy_exports/exportable_attribute_resolvers'
 require 'easy_exports/exclude_associations_configurations'
 require 'easy_exports/exclude_exportable_attributes_configurations'
 require 'easy_exports/exportable_association_aliases_configurations'
-require 'easy_exports/exports_generable'
 require 'easy_exports/export'
-
-module EasyExports
-  # Your code goes here...
-end
+require 'easy_exports/data_loader'
+require 'easy_exports/data_attributes_resolver'
+require 'easy_exports/exports_generable'
+require 'easy_exports/exportable_attributes'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: easy_exports
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Dapilah Sydney
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-16 00:00:00.000000000 Z
+date: 2023-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -106,6 +106,8 @@ files:
 - README.md
 - Rakefile
 - lib/easy_exports.rb
+- lib/easy_exports/data_attributes_resolver.rb
+- lib/easy_exports/data_loader.rb
 - lib/easy_exports/exclude_associations_configurations.rb
 - lib/easy_exports/exclude_exportable_attributes_configurations.rb
 - lib/easy_exports/export.rb