easy_exports 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed1cc375db87028330d34ded26b7e247a1ff4382267254118e06b994d5ae66d6
-  data.tar.gz: 4529a792f705691f04ea2b707a00503866d324ca2388bb5587ffd61563a8f98c
+  metadata.gz: 99d64117b05b63ec1f0cd4ef5b8b6a7ec3d653087678d9b4831edb87c8dd61c4
+  data.tar.gz: 884619c1077d8ff642ceb1466f4c9ffcbb50bac95277b5bf7765303f53d666f3
 SHA512:
-  metadata.gz: c5ca2b24a5a23f685d04dfd020cff2dea3bab1d550f40c1467cfbc04608cfaf701bd69fd6eb91652a1f4ede40f8608fee8f87ac4bd22ff3742155b7238f19eab
-  data.tar.gz: 565ddc57bd713f6097aad5717ddb9c95d39fc18d7e3a5db2a81b5d489098c0fdf17723b7b83d9b018f25ef88c6ecb7edebfc7c364fb6aa1b5add5ae7db80ad5c
+  metadata.gz: e843ce5e1aa5edab56616992a16d989952c52343a854619d0fb46715617af59a2e4ca641d69bb8dc243d2aea63b7bdae42a164e2e39e3ce9784e471ff04f3054
+  data.tar.gz: 4915abc76083e2e755e954699b788e4d5debaef66cd764c42af7d85eb2dc56dafff68589ca81c38a71fbdb64962c8a891c1291781f8591af20702f4be8f463a4

data/README.md

@@ -58,11 +58,12 @@ Retrieve exportable attributes using the `exportable_attributes` method. This me
 
 ### Generating Exports from Exportable Attributes
 
-To generate exports, use the `generate_exports(exportable_attributes, ids)` method.
+To generate exports, use the `generate_exports(exportable_attributes, ids, order:)` 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 `order:` keyword argument is optional; see [Ordering Exports](#ordering-exports) for details.
 
 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.
 
@@ -107,6 +108,142 @@ Exported CSV showcases data for:
 - The main CSV header includes association names and attribute names.
 
 
+### Ordering Exports
+
+Control the order of rows in the generated export using the `order:` keyword argument on `generate_exports`.
+
+- `order:` accepts any value ActiveRecord's `order` accepts — a hash, string, symbol, or array.
+- When `order:` is omitted and the model has a `created_at` column, exports default to newest first (`created_at DESC`).
+- When `order:` is omitted and no `created_at` column exists, no ordering is applied.
+
+```ruby
+  # Example: explicit ordering
+
+  # Order by first_name ascending
+  User.generate_exports(user_exportable_attributes, [], order: { first_name: :asc })
+
+  # Order by a raw SQL fragment
+  User.generate_exports(user_exportable_attributes, [], order: 'last_name DESC, id ASC')
+
+  # Default ordering (newest first when created_at exists)
+  User.generate_exports(user_exportable_attributes)
+```
+
+For performance, records are fetched in batches of 1,000 internally while preserving the requested order across the full result set. The batch size is configurable — see [Configuration](#configuration).
+
+### Configuration
+
+Configure gem-wide defaults using `EasyExports.configure`.
+
+```ruby
+  # config/initializers/easy_exports.rb
+  EasyExports.configure do |c|
+    c.batch_size = 500                                          # default: 1000
+    c.sensitive_attributes += %w[internal_note ssn]             # extends the default list
+    c.type_formatters[:datetime] = ->(v) { v.strftime('%d/%m/%Y') }
+    c.csv_header_formatter = ->(key) { key.humanize.upcase }    # or set to nil to disable
+  end
+```
+
+- `batch_size` — number of records fetched per database round trip during export. Override per call with `generate_exports(..., batch_size: 2_000)`.
+- `sensitive_attributes` — attributes auto-excluded from every export. See [Sensitive Attributes](#sensitive-attributes) for the default list and per-model opt-out.
+- `type_formatters` — per-type value formatters applied before a raw value is written to CSV. See [Type Formatters](#type-formatters).
+- `csv_header_formatter` — callable applied to every header in the CSV row. Defaults to `humanize.titleize` (e.g. `registration_email` → `Registration Email`). Set to `nil` to keep raw snake_case headers.
+
+### Sensitive Attributes
+
+EasyExports automatically excludes commonly sensitive attributes from all exports. The default list is:
+
+```ruby
+  %w[
+    password_digest
+    encrypted_password
+    remember_token
+    reset_password_token
+    confirmation_token
+    session_token
+    api_key
+    secret_token
+  ]
+```
+
+To include these on a specific model (e.g. for admin-only exports), opt in at the class level:
+
+```ruby
+  class AdminLogin < ApplicationRecord
+    self.include_sensitive_exportable_attributes = true
+  end
+```
+
+Extend or replace the default list through [Configuration](#configuration).
+
+### Type Formatters
+
+EasyExports applies type-based formatters automatically, so you don't have to write a lambda for every boolean or timestamp column.
+
+| Type | Matches | Shipped formatter | Example output |
+|------|---------|-------------------|----------------|
+| `boolean` | `true` / `false` | `->(v) { v ? 'Yes' : 'No' }` | `Yes`, `No` |
+| `datetime` | `Date`, `Time`, `DateTime`, `ActiveSupport::TimeWithZone` | `->(v) { v.strftime('%A, %B %-d, %Y %H:%M') }` | `Sunday, January 5, 2025 09:17` |
+| `leading_zero_string` | `String` starting with `0` | `->(v) { "'#{v}" }` | `'0244867596` (preserves leading zero in spreadsheets) |
+| `string` | `String` not containing `@` | *(none — opt in per model)* | — |
+
+`nil` values always pass through untouched.
+
+**Turn off a type formatter for a specific model:**
+
+```ruby
+  class Transaction < ApplicationRecord
+    disable_exportable_type_formatter :datetime               # one type
+    disable_exportable_type_formatter :boolean, :datetime     # multiple types
+  end
+```
+
+**Replace a type formatter for a specific model** — apply a different format to *all* values of that type on this one model:
+
+```ruby
+  class Registration < ApplicationRecord
+    # Every datetime on Registration renders as "January 5, 2025" — no time portion
+    format_exportable_type :datetime, ->(v) { v.strftime('%B %-d, %Y') }
+
+    # Capitalize the first letter of every plain string (emails are skipped automatically)
+    format_exportable_type :string, ->(v) { v.sub(/^./, &:upcase) }
+
+    # Block form
+    format_exportable_type(:boolean) { |v| v ? '✓' : '✗' }
+  end
+```
+
+**Change or disable a type formatter globally** — see [Configuration](#configuration).
+
+### Custom Value Formatters
+
+For a specific attribute, override the default with your own formatter using `format_exportable_attribute`.
+
+- Declare it on the class that owns the attribute. It applies whenever that attribute is exported, whether from the owner model directly or through an association.
+- Accepts either a callable (lambda/proc) or a block.
+- A custom formatter takes precedence over any default formatter for that attribute.
+
+```ruby
+  class Registration < ApplicationRecord
+    # Override the global datetime default with a shorter format for this attribute
+    format_exportable_attribute :registered_on, ->(v) { v&.strftime('%Y-%m-%d') }
+
+    # Override the global boolean default with custom glyphs
+    format_exportable_attribute :is_archived, ->(v) { v ? '✓' : '' }
+
+    # Block form
+    format_exportable_attribute(:status) { |v| v.to_s.titleize }
+  end
+```
+
+**Precedence** (top wins):
+1. Per-attribute `format_exportable_attribute`
+2. Per-model `disable_default_formatter` (if disabled → raw value)
+3. Per-model `override_default_formatter` (if overridden → override wins)
+4. Global `EasyExports.default_formatters[:type]`
+5. Raw value
+
 ### Exportable Attributes Aliases
 
 Configure an alternative association name for exportable attributes using the `exportable_association_aliases(aliases)` model method.

data/lib/easy_exports/data_attributes_resolver.rb

@@ -26,15 +26,42 @@ module EasyExports
       end
 
       def resolve_attributes(attribute, objects)
-        objects.empty? ? [nil] : objects.map { |object| parse_attribute_value(object.send(attribute)) }.flatten
+        return [nil] if objects.empty?
+
+        objects.map do |object|
+          raw_value = object.send(attribute)
+          format_value_for_export(object.class, attribute, raw_value)
+        end.flatten
+      end
+
+      def format_value_for_export(klass, attribute, value)
+        custom = exportable_attribute_formatter_for(klass, attribute)
+        return custom.call(value) if custom
+        return value if value.nil?
+
+        type_formatter = type_formatter_for(klass, value)
+        type_formatter ? type_formatter.call(value) : value
       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)
+      def exportable_attribute_formatter_for(klass, attribute)
+        store = exportable_attribute_formatters_store[klass.name.underscore.downcase]
+        store && store[attribute.to_s]
+      end
+
+      def type_formatter_for(klass, value)
+        klass_key = klass.name.underscore.downcase
+        disabled = disabled_type_formatters_store[klass_key] || []
+        overrides = overridden_type_formatters_store[klass_key] || {}
 
-        return "'#{value}" if value.is_a?(String) && value&.start_with?('0')
+        EasyExports::TYPE_MATCHERS.each do |type, matcher|
+          next if disabled.include?(type)
+          next unless matcher.call(value)
+
+          formatter = overrides[type] || EasyExports.type_formatters[type]
+          return formatter if formatter
+        end
 
-        value
+        nil
       end
 
       def objects_for_attribute(association_name, record)

data/lib/easy_exports/data_loader.rb

@@ -7,34 +7,23 @@ module EasyExports
     class_methods do
       private
 
-      def fetch_records(ids, selected_attributes)
+      def fetch_records(ids, selected_attributes, order = nil, batch_size = EasyExports.batch_size)
         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
+        scope = ids.blank? ? all : where(id: ids)
+        ordered_ids = apply_export_order(scope, order).pluck(:id)
+        associations_to_preload = selected_attributes.keys - [underscored_self_name]
 
-        association_name.constantize.attribute_names
+        ordered_ids.each_slice(batch_size).flat_map do |id_slice|
+          batch = apply_export_order(where(id: id_slice), order).to_a
+          ActiveRecord::Associations::Preloader.new(records: batch, associations: associations_to_preload).call
+          batch
+        end
       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
+      def apply_export_order(records, order)
+        return records.order(order) if order.present?
+        return records.order(created_at: :desc) if column_names.include?('created_at')
 
         records
       end

data/lib/easy_exports/exportable_attribute_formatters_configurations.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module EasyExports
+  module ExportableAttributeFormattersConfigurations
+    extend ActiveSupport::Concern
+
+    class_methods do
+      private
+
+      def format_exportable_attribute(attribute, formatter = nil, &block)
+        formatter ||= block
+        unless formatter.respond_to?(:call)
+          raise ArgumentError, 'format_exportable_attribute requires a callable (proc or block)'
+        end
+
+        exportable_attribute_formatters_store[underscored_self_name] ||= {}
+        exportable_attribute_formatters_store[underscored_self_name][attribute.to_s] = formatter
+      end
+
+      def disable_exportable_type_formatter(*types)
+        validate_known_type_formatter!(types, 'disable_exportable_type_formatter')
+
+        disabled_type_formatters_store[underscored_self_name] ||= []
+        disabled_type_formatters_store[underscored_self_name] |= types.map(&:to_sym)
+      end
+
+      def format_exportable_type(type, formatter = nil, &block)
+        formatter ||= block
+        unless formatter.respond_to?(:call)
+          raise ArgumentError, 'format_exportable_type requires a callable (proc or block)'
+        end
+        validate_known_type_formatter!([type], 'format_exportable_type')
+
+        overridden_type_formatters_store[underscored_self_name] ||= {}
+        overridden_type_formatters_store[underscored_self_name][type.to_sym] = formatter
+      end
+
+      def validate_known_type_formatter!(types, method)
+        invalid = types.map(&:to_sym) - EasyExports::TYPE_MATCHERS.keys
+        return if invalid.empty?
+
+        raise ArgumentError,
+              "#{method} unknown type(s): #{invalid.join(', ')}. " \
+              "Known types: #{EasyExports::TYPE_MATCHERS.keys.join(', ')}"
+      end
+    end
+  end
+end

data/lib/easy_exports/exportable_attribute_resolvers.rb

@@ -20,7 +20,15 @@ module EasyExports
 
       def resolve_attributes_for_association(association)
         association_attributes = association.class_name.constantize.attribute_names
-        association_attributes - resolve_excluded_exportable_attributes(association.name.to_s.downcase)
+        association_attributes -
+          resolve_excluded_exportable_attributes(association.name.to_s.downcase) -
+          resolve_sensitive_attributes_to_exclude
+      end
+
+      def resolve_sensitive_attributes_to_exclude
+        return [] if include_sensitive_exportable_attributes
+
+        EasyExports.sensitive_attributes.map(&:to_s)
       end
 
       def resolve_associations_names_aliases(association_name)

data/lib/easy_exports/exportable_attributes.rb

@@ -8,17 +8,21 @@ module EasyExports
       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)
+      cattr_accessor :exportable_attribute_formatters_store, default: {}, instance_writer: false
+      cattr_accessor :disabled_type_formatters_store, default: {}, instance_writer: false
+      cattr_accessor :overridden_type_formatters_store, default: {}, instance_writer: false
+      cattr_accessor :include_sensitive_exportable_attributes, default: false, instance_writer: false
 
       include EasyExports::ExportableAssociationAliasesConfigurations
       include EasyExports::ExportableAttributeResolvers
       include EasyExports::ExcludeExportableAttributesConfigurations
+      include EasyExports::ExportableAttributeFormattersConfigurations
       include EasyExports::ExportsGenerable
     end
 
     class_methods do
       def exportable_attributes
-        self_with_associations.each_with_object({}) do |association, attributes|
+        @exportable_attributes ||= self_with_associations.each_with_object({}) do |association, attributes|
           association_name = association.name.to_s.downcase
           next if associations_to_exclude_store[underscored_self_name]&.include? association_name
 
@@ -29,6 +33,10 @@ module EasyExports
         end
       end
 
+      def reset_exportable_attributes_cache!
+        @exportable_attributes = nil
+      end
+
       private
 
       def self_with_associations

data/lib/easy_exports/exports_generable.rb

@@ -10,7 +10,7 @@ module EasyExports
     end
 
     class_methods do
-      def generate_exports(fields_to_export = {}, ids = [])
+      def generate_exports(fields_to_export = {}, ids = [], order: nil, batch_size: nil)
         validate_exclude_exportable_attributes_argument(fields_to_export, 'generate_exports')
 
         selected_exportable_attributes = revert_transformed_names(fields_to_export)
@@ -19,7 +19,7 @@ module EasyExports
         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)
+        records = fetch_records(ids, selected_attributes, order, batch_size || EasyExports.batch_size)
 
         exported_data = records.each_with_object([]) do |record, hash_to_export|
           hash_to_export << value_from_selected_attributes(selected_attributes, record, export_row_template.dup)
@@ -31,8 +31,12 @@ module EasyExports
       end
 
       def write_exported_data_to_csv(exported_data, export_row_template)
+        header_formatter = EasyExports.csv_header_formatter
+        keys = export_row_template.keys
+        headers = header_formatter ? keys.map { |k| header_formatter.call(k) } : keys
+
         CSV.generate(headers: true) do |csv|
-          csv << export_row_template.keys
+          csv << headers
 
           exported_data.each do |data|
             csv << data.values
@@ -60,7 +64,7 @@ module EasyExports
       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)
+            export_row.merge!(export_header(association_name, attribute) => nil)
           end
         end
       end

data/lib/easy_exports/version.rb

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

data/lib/easy_exports.rb

@@ -1,13 +1,54 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext/module/attribute_accessors'
+
 require 'easy_exports/version'
 require 'easy_exports/railtie'
 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/exportable_attribute_formatters_configurations'
 require 'easy_exports/export'
 require 'easy_exports/data_loader'
 require 'easy_exports/data_attributes_resolver'
 require 'easy_exports/exports_generable'
 require 'easy_exports/exportable_attributes'
+
+module EasyExports
+  DEFAULT_BATCH_SIZE = 1_000
+  DEFAULT_SENSITIVE_ATTRIBUTES = %w[
+    password_digest
+    encrypted_password
+    remember_token
+    reset_password_token
+    confirmation_token
+    session_token
+    api_key
+    secret_token
+  ].freeze
+
+  TYPE_MATCHERS = {
+    boolean: ->(v) { v == true || v == false },
+    datetime: ->(v) { v.is_a?(Date) || v.is_a?(Time) || v.is_a?(DateTime) || v.is_a?(ActiveSupport::TimeWithZone) },
+    leading_zero_string: ->(v) { v.is_a?(String) && v.start_with?('0') },
+    string: ->(v) { v.is_a?(String) && !v.include?('@') }
+  }.freeze
+
+  TYPE_FORMATTERS = {
+    boolean: ->(v) { v ? 'Yes' : 'No' },
+    datetime: ->(v) { v.strftime('%A, %B %-d, %Y %H:%M') },
+    leading_zero_string: ->(v) { "'#{v}" }
+  }.freeze
+
+  DEFAULT_CSV_HEADER_FORMATTER = ->(key) { key.to_s.humanize.titleize }
+
+  mattr_accessor :batch_size, default: DEFAULT_BATCH_SIZE
+  mattr_accessor :sensitive_attributes, default: DEFAULT_SENSITIVE_ATTRIBUTES.dup
+  mattr_accessor :type_formatters, default: TYPE_FORMATTERS.dup
+  mattr_accessor :csv_header_formatter, default: DEFAULT_CSV_HEADER_FORMATTER
+
+  def self.configure
+    yield self
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: easy_exports
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Dapilah Sydney
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -112,6 +111,7 @@ files:
 - lib/easy_exports/exclude_exportable_attributes_configurations.rb
 - lib/easy_exports/export.rb
 - lib/easy_exports/exportable_association_aliases_configurations.rb
+- lib/easy_exports/exportable_attribute_formatters_configurations.rb
 - lib/easy_exports/exportable_attribute_resolvers.rb
 - lib/easy_exports/exportable_attributes.rb
 - lib/easy_exports/exports_generable.rb
@@ -126,7 +126,6 @@ metadata:
   homepage_uri: https://github.com/SydDaps/easy_exports
   source_code_uri: https://github.com/SydDaps/easy_exports
   changelog_uri: https://rubygems.org/
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -141,8 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Streamline data retrieval from Rails models
 test_files: []