activekit 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1305c44f47755be521e42ebb643e3ec9d4e267d2d04199b5e1d182e444d0b275
-  data.tar.gz: 10b756b23a70d5054c1b69f48523c575756a73c184e36ae1fc9aa23291d2a2b7
+  metadata.gz: 2dffaf7d844bba5ea65c34b98f3872cf70cb44c76963fb0d7a96bb39df174acb
+  data.tar.gz: 5c64d866b07f8460145f0a8069ac316e96d9ee15985fcce13e9a598fd2f6dedc
 SHA512:
-  metadata.gz: 271eb9911286e8970c7ef6327ba67d912b83208d554ebfed7129a4821834373883bb14ef1acd1f43028fcf79fb062f95fda1ff48e7a53bdb2cdfce648d49a0ce
-  data.tar.gz: 2049ff4e916f3f5ba230b060db073380e90e60981393c6dd2abf1870a127a91b2508a92d0d786448c80c17d4d2aeb0b849d06a60ce136317dec932257b7efc95
+  metadata.gz: f704f847169d738fa9f708246661b1dfff4594349fd3c8297b9070542046684106b5f5a831505bc5160c544fcc79d13b2c2920520e5184191832f34ff3e62979
+  data.tar.gz: af2af6217c992fb16c4205b88e0172947b043c2f52c93f389570989444a4726aa0fa62392e7d27b4dc48450120cb943c0e7e38c9f4606a3719d0a868badc8608

data/README.md

@@ -3,6 +3,40 @@ Add the essential kit for rails ActiveRecord models and be happy.
 
 ## Usage
 
+### Export Attribute
+
+Add exporting to your ActiveRecord models.
+Export Attribute provides full exporting functionality for your model database records.
+
+You can define any number of model attributes and association attributes in one model to export together.
+
+Define the export attributes in accordance with the column name in your model like below.
+```ruby
+class Product < ApplicationRecord
+  export_attribute :name
+  export_attribute :sku, heading: "SKU No."
+  export_attribute :image_name, value: lambda { |record| record.image&.name }, includes: :image
+  export_attribute :variations, value: lambda { |record| record.variations }, includes: :variations, attributes: [:name, :price, discount_value: { heading: "Discount" }]
+end
+```
+
+You can also define an export_describer to describe the details of the export instead of using the defaults.
+```ruby
+class Product < ApplicationRecord
+  # export_describer method_name, kind: :csv, database: -> { ActiveRecord::Base.connection_db_config.database.to_sym }
+  export_describer :to_csv, kind: :csv, database: -> { System::Current.tenant.database.to_sym }
+  export_attribute :name
+  export_attribute :sku, heading: "SKU No."
+  export_attribute :image_name, value: lambda { |record| record.image&.name }, includes: :image
+  export_attribute :variations, value: lambda { |record| record.variations }, includes: :variations, attributes: [:name, :price, discount_value: { heading: "Discount" }]
+end
+```
+
+The following class methods will be added to your model class to use in accordance with details provided for export_describer:
+```ruby
+Product.to_csv
+```
+
 ### Position Attribute
 
 Add positioning to your ActiveRecord models.

data/lib/active_kit/engine.rb

@@ -9,10 +9,12 @@ module ActiveKit
       app.middleware.use ActiveKit::Position::Middleware
     end
 
-    initializer "active_kit.position" do
+    initializer "active_kit.activekitable" do
+      require "active_kit/export/exportable"
       require "active_kit/position/positionable"
 
       ActiveSupport.on_load(:active_record) do
+        include ActiveKit::Export::Exportable
         include ActiveKit::Position::Positionable
       end
     end

data/lib/active_kit/export/exportable.rb

@@ -0,0 +1,65 @@
+require 'active_support/concern'
+
+module ActiveKit
+  module Export
+    module Exportable
+      extend ActiveSupport::Concern
+
+      included do
+      end
+
+      class_methods do
+        def exporter
+          @exporter ||= ActiveKit::Export::Exporter.new(current_class: self)
+        end
+
+        def export_describer(name, **options)
+          name = name.to_sym
+          options.deep_symbolize_keys!
+
+          unless exporter.find_describer_by(describer_name: name)
+            exporter.new_describer(name: name, options: options)
+            define_describer_method(kind: options[:kind], name: name)
+          end
+        end
+
+        def export_attribute(name, **options)
+          export_describer(:to_csv, kind: :csv, database: -> { ActiveRecord::Base.connection_db_config.database.to_sym }) unless exporter.describers?
+
+          options.deep_symbolize_keys!
+          exporter.new_attribute(name: name.to_sym, options: options)
+        end
+
+        def define_describer_method(kind:, name:)
+          case kind
+          when :csv
+            define_singleton_method name do
+              describer = exporter.find_describer_by(describer_name: name)
+              raise "could not find describer for the describer name '#{name}'" unless describer.present?
+
+              # The 'all' relation must be captured outside the Enumerator,
+              # else it will get reset to all the records of the class.
+              all_activerecord_relation = all.includes(describer.includes)
+
+              Enumerator.new do |yielder|
+                ActiveRecord::Base.connected_to(role: :writing, shard: describer.database.call) do
+                  exporting = exporter.new_exporting(describer: describer)
+
+                  # Add the headings.
+                  yielder << CSV.generate_line(exporting.headings) if exporting.headings?
+
+                  # Add the values.
+                  # find_each will ignore any order if set earlier.
+                  all_activerecord_relation.find_each do |record|
+                    lines = exporting.lines_for(record: record)
+                    lines.each { |line| yielder << CSV.generate_line(line) }
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_kit/export/exporter.rb

@@ -0,0 +1,106 @@
+module ActiveKit
+  module Export
+    class Exporter
+      attr_reader :describers
+
+      def initialize(current_class:)
+        @current_class = current_class
+        @describers = {}
+      end
+
+      def find_describer_by(describer_name:)
+        describer_options = @describers.dig(describer_name)
+        return nil unless describer_options.present?
+
+        describer_attributes = describer_options[:attributes]
+        includes = describer_attributes.values.map { |options| options.dig(:includes) }.compact.flatten(1).uniq
+        fields = build_describer_fields(describer_attributes)
+        hash = {
+          name: describer_name,
+          kind: describer_options[:kind],
+          database: describer_options[:database],
+          attributes: describer_attributes,
+          includes: includes,
+          fields: fields
+        }
+        OpenStruct.new(hash)
+      end
+
+      def new_describer(name:, options:)
+        options.store(:attributes, {})
+        @describers.store(name, options)
+      end
+
+      def describers?
+        @describers.present?
+      end
+
+      def new_attribute(name:, options:)
+        describer_names = Array(options.delete(:describers))
+        describer_names = @describers.keys if describer_names.blank?
+
+        describer_names.each do |describer_name|
+          if describer_options = @describers.dig(describer_name)
+            describer_options[:attributes].store(name, options)
+          end
+        end
+      end
+
+      def new_exporting(describer:)
+        Exporting.new(describer: describer)
+      end
+
+      private
+
+      def build_describer_fields(describer_attributes)
+        describer_attributes.inject({}) do |fields_hash, (name, options)|
+          enclosed_attributes = Array(options.dig(:attributes))
+
+          if enclosed_attributes.blank?
+            field_key, field_value = (get_heading(options.dig(:heading))&.to_s || name.to_s.titleize), (options.dig(:value) || name)
+          else
+            field_key, field_value = get_nested_field(name, options, enclosed_attributes)
+          end
+          fields_hash.store(field_key, field_value)
+
+          fields_hash
+        end
+      end
+
+      def get_nested_field(name, options, enclosed_attributes, ancestor_heading = nil)
+        parent_heading = ancestor_heading.present? ? ancestor_heading : ""
+        parent_heading += (get_heading(options.dig(:heading))&.to_s || name.to_s.singularize.titleize) + " "
+        parent_value = options.dig(:value) || name
+
+        enclosed_attributes.inject([[], [parent_value]]) do |nested_field, enclosed_attribute|
+          unless enclosed_attribute.is_a? Hash
+            nested_field_key = parent_heading + enclosed_attribute.to_s.titleize
+            nested_field_val = enclosed_attribute
+
+            nested_field[0].push(nested_field_key)
+            nested_field[1].push(nested_field_val)
+          else
+            enclosed_attribute.each do |enclosed_attribute_key, enclosed_attribute_value|
+              wrapped_attributes = Array(enclosed_attribute_value.dig(:attributes))
+              if wrapped_attributes.blank?
+                nested_field_key = parent_heading + (get_heading(enclosed_attribute_value.dig(:heading))&.to_s || enclosed_attribute_key.to_s.titleize)
+                nested_field_val = enclosed_attribute_value.dig(:value) || enclosed_attribute_key
+              else
+                nested_field_key, nested_field_val = get_nested_field(enclosed_attribute_key, enclosed_attribute_value, wrapped_attributes, parent_heading)
+              end
+
+              nested_field[0].push(nested_field_key)
+              nested_field[1].push(nested_field_val)
+            end
+          end
+
+          nested_field
+        end
+      end
+
+      def get_heading(options_heading)
+        options_heading.is_a?(Proc) ? options_heading.call(@current_class) : options_heading
+      end
+    end
+  end
+end

data/lib/active_kit/export/exporting.rb

@@ -0,0 +1,104 @@
+module ActiveKit
+  module Export
+    class Exporting
+
+      def initialize(describer:)
+        @describer = describer
+      end
+
+      def headings
+        @headings ||= @describer.fields.keys.flatten
+      end
+
+      def headings?
+        headings.present?
+      end
+
+      def lines_for(record:)
+        row_counter, column_counter = 1, 0
+
+        @describer.fields.inject([[]]) do |rows, (heading, value)|
+          if value.is_a? Proc
+            rows[0].push(value.call(record))
+            column_counter += 1
+          elsif value.is_a?(Symbol) || value.is_a?(String)
+            rows[0].push(record.public_send(value))
+            column_counter += 1
+          elsif value.is_a? Array
+            deeprows = get_deeprows(record, heading, value, column_counter)
+            deeprows.each do |deeprow|
+              rows[row_counter] = deeprow
+              row_counter += 1
+            end
+
+            column_count = get_column_count_for(value)
+            column_count.times { |i| rows[0].push(nil) }
+            column_counter += column_count
+          else
+            raise "Could not identify '#{value}' for '#{heading}'."
+          end
+
+          rows
+        end
+      end
+
+      private
+
+      def get_deeprows(record, heading, value, column_counter)
+        value_clone = value.clone
+        assoc_value = value_clone.shift
+
+        if assoc_value.is_a? Proc
+          assoc_records = assoc_value.call(record)
+        elsif assoc_value.is_a?(Symbol) || assoc_value.is_a?(String)
+          assoc_records = record.public_send(assoc_value)
+        else
+          raise "Count not identity '#{assoc_value}' for '#{heading}'."
+        end
+
+        subrows = []
+        assoc_records.each do |assoc_record|
+          subrow, subrow_column_counter, deeprows = [], 0, []
+          column_counter.times { |i| subrow.push(nil) }
+
+          subrow = value_clone.inject(subrow) do |subrow, v|
+            if v.is_a? Proc
+              subrow.push(v.call(assoc_record))
+              subrow_column_counter += 1
+            elsif v.is_a?(Symbol) || v.is_a?(String)
+              subrow.push(assoc_record.public_send(v))
+              subrow_column_counter += 1
+            elsif v.is_a? Array
+              deeprows = get_deeprows(assoc_record, heading, v, (column_counter + subrow_column_counter))
+
+              column_count = get_column_count_for(v)
+              column_count.times { |i| subrow.push(nil) }
+              subrow_column_counter += column_count
+            end
+
+            subrow
+          end
+
+          subrows.push(subrow)
+          deeprows.each { |deeprow| subrows.push(deeprow) }
+        end
+
+        subrows
+      end
+
+      def get_column_count_for(value)
+        count = 0
+
+        value.each do |v|
+          unless v.is_a? Array
+            count += 1
+          else
+            count += get_column_count_for(v)
+          end
+        end
+
+        count - 1
+      end
+    end
+  end
+end

data/lib/active_kit/export.rb

@@ -0,0 +1,8 @@
+module ActiveKit
+  module Export
+    extend ActiveSupport::Autoload
+
+    autoload :Exporter
+    autoload :Exporting
+  end
+end

data/lib/active_kit/version.rb

@@ -1,3 +1,3 @@
 module ActiveKit
-  VERSION = '0.3.2'
+  VERSION = '0.4.0'
 end

data/lib/active_kit.rb

@@ -4,5 +4,6 @@ require "active_kit/engine"
 module ActiveKit
   extend ActiveSupport::Autoload
 
+  autoload :Export
   autoload :Position
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activekit
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - plainsource
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-01 00:00:00.000000000 Z
+date: 2024-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -51,6 +51,10 @@ files:
 - config/routes.rb
 - lib/active_kit.rb
 - lib/active_kit/engine.rb
+- lib/active_kit/export.rb
+- lib/active_kit/export/exportable.rb
+- lib/active_kit/export/exporter.rb
+- lib/active_kit/export/exporting.rb
 - lib/active_kit/position.rb
 - lib/active_kit/position/harmonize.rb
 - lib/active_kit/position/middleware.rb