magic-report 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b11733b1128011acfba29bf24cbf2846ce42e226aeccadfcdfc6ce713c2b1b3e
+  data.tar.gz: 0dbec29ea7c05acf3744fc1a62d4b200455a88926d1e938826243df683d9ce93
+SHA512:
+  metadata.gz: ad63138a1fe01308e5ddfef0f50d3feb04ae5dd49e9fe8c2e81dcac6ed5f376daf32de12baf1912695c798ade584d96652d7c1c0a0fc6f801992fd41c0a09bce
+  data.tar.gz: 2fff4d4f90864fded9a18846e718fbc82671907f106ce16c5240df94d57d2e92c27c2f7e423d02da1ee88a93b4f49a21db201636ffc04bb1b9c020c04a74d562

data/README.md

@@ -0,0 +1,138 @@
+# MagicReport
+
+An easy way to export data to CSV
+
+[![Build Status](https://github.com/thefaded/magic-report/workflows/test/badge.svg?branch=master)](https://github.com/thefaded/magic-report/actions)
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem "magic-operation"
+```
+
+## Getting Started
+
+This gem provides an ActiveRecord-like DSL to create CSV reports. One of the common use cases is when you have nested data.
+
+```ruby
+class User < MagicReport::Report
+  field :id
+  field :is_admin, ->(user) { user.is_admin ? "Yes" : "No" }
+end
+
+report = User.new
+report.process(UserModel.first)
+
+# You can also `process` on a collection
+# report.process(User.all.limit(50))
+
+report.as_csv
+```
+
+The example above is basic - you have a User model and you want to export the two fields `id` and `is_admin`.
+The users of your application may not particularly like the naming `true` or `false` since these are more technical terms, that's why you can pass an additional block to the field.
+
+Also, for each report you must provide locales file:
+
+```yaml
+en:
+  magic_report:
+    headings:
+      user:
+        id: ID
+        is_admin: Admin?
+```
+
+CSV will be
+| ID | Admin? |
+| ---- | -------- |
+| 123 | Yes |
+| 222 | No |
+
+## Nested
+
+Let's look at a more complex example. Now we have a user model with an address and several cars.
+
+```ruby
+class User < MagicReport::Report
+  field :id
+  field :is_admin, ->(user) { user.is_admin ? "Yes" : "No" }
+
+  has_one :shipping_address, class: Address, prefix: -> { t("shipping_address") }
+  has_one :billing_address, class: Address, prefix: -> { t("billing_address") }
+
+  has_many :cars, class: Car, prefix: -> { t("car") }
+end
+
+class Address < MagicReport::Report
+  fields :address_line_1, :city
+end
+
+class Car < MagicReport::Report
+  field :name
+end
+```
+
+Because we have explicitly said that the user `has_many :cars`, the number of lines in the CSV will be equal to the number of cars.
+
+```yaml
+en:
+  magic_report:
+    headings:
+      user:
+        id: ID
+        is_admin: Admin?
+        address: User address
+        cars: Car
+        shipping_address: Shipping address
+        billing_address: Billing address
+      car:
+        name: Name
+      address:
+        address_line_1: Line 1
+        city: City
+```
+
+CSV will be
+| ID | Admin? | Shipping address Line 1 | Shipping address City | Billing address Line 1 | Billing address City | Car Name |
+| ---- | -------- | ------------------- | ----------------- | -------- | -------- | ------- |
+| 123 | Yes | 5th Ave | NY | Chester st | San Francisco | Lexus |
+| 123 | Yes | 5th Ave | NY | Chester st | San Francisco | BMW |
+
+### Using with blocks
+
+The above example can be rewritten using blocks instead of class
+
+```ruby
+class User < MagicReport::Report
+  field :id
+  field :is_admin, ->(user) { user.is_admin ? "Yes" : "No" }
+
+  # You should always provide `name` option if you're using block instead of class
+  # From this option will be used locales for `address_line_1` and `city`
+  has_one :shipping_address, name: :address, prefix: -> { t("shipping_address") } do
+    fields :address_line_1, :city
+  end
+  # Prefix locale is taken from `user.billing_address`
+  has_one :billing_address, name: :address, prefix: -> { t("billing_address") } do
+    fields :address_line_1, :city
+  end
+
+  has_many :cars, name: :car, prefix: -> { t("car") } do
+    field :name
+  end
+end
+```
+
+## Contributing
+
+Everyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/thefaded/magic-report/issues)
+- Fix bugs and [submit pull requests](https://github.com/thefaded/magic-report/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+To get started with development and testing, check out the [Contributing Guide](CONTRIBUTING.md).

data/lib/magic_report/report/class_helpers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MagicReport
+  class Report
+    module ClassHelpers
+      def name_from_class
+        ::MagicReport::Utils.underscore(self.class.name)
+      end
+
+      def fields_from_class
+        self.class.instance_variable_get(:@fields) || []
+      end
+
+      def has_one_from_class
+        self.class.instance_variable_get(:@has_one) || []
+      end
+
+      def has_many_from_class
+        self.class.instance_variable_get(:@has_many) || []
+      end
+    end
+  end
+end

data/lib/magic_report/report/configuration.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MagicReport
+  class Report
+    module Configuration
+      class Field
+        attr_reader :key, :processor
+
+        def initialize(key:, processor: nil)
+          @key = key
+          @processor = processor
+        end
+
+        def process(entity)
+          processor ? processor.call(entity) : entity.send(key)
+        end
+      end
+
+      class HasOne
+        attr_reader :klass, :opts, :prefix, :key
+
+        def initialize(klass:, opts:, key:)
+          @klass = klass
+          @prefix = opts[:prefix]
+          @key = key
+          @opts = opts
+        end
+
+        def process_entity(entity)
+          report.process(entity)
+        end
+
+        def report
+          @report ||= init_report
+        end
+
+        private
+
+        # { class: Exports::Supplier, prefix: lambda }
+
+        def init_report
+          klass.new(report_params)
+        end
+
+        def report_opts
+          opts
+        end
+
+        def report_params
+          opts.reject { |k, v| %i[class].include? k }.merge(nested_field: key)
+        end
+      end
+
+      class HasMany < HasOne; end
+    end
+  end
+end

data/lib/magic_report/report/csv.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module MagicReport
+  class Report
+    class Csv
+      attr_reader :report, :file, :csv
+
+      def initialize(report)
+        @report = report
+        @file = Tempfile.new
+        @csv = ::CSV.new(@file, write_headers: true)
+      end
+
+      def generate
+        write_headers
+
+        report.result.each do |row|
+          row.to_h.each { |nested_row| csv << nested_row.values }
+        end
+        # ensure
+        # file.close
+      end
+
+      def unlink
+        file.unlink
+      end
+
+      private
+
+      def write_headers
+        csv << report.headings
+      end
+    end
+  end
+end

data/lib/magic_report/report/process.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module MagicReport
+  class Report
+    class Process
+      attr_reader :report
+
+      def initialize(report)
+        @report = report
+      end
+
+      def call(input)
+        if input.is_a? Enumerable
+          input.map do |entity|
+            process_entity(entity)
+          end
+        else
+          process_entity(input)
+        end
+      end
+
+      private
+
+      def process_entity(entity)
+        row = Row.new
+
+        process_fields(entity, row)
+        process_has_one(entity, row)
+        process_has_many(entity, row)
+
+        row
+      end
+
+      def process_fields(entity, row)
+        report.fields.each do |field|
+          row.add(field: report.resolve_path(field.key), value: field.process(entity))
+        end
+      end
+
+      def process_has_one(entity, row)
+        report.has_one.each do |association|
+          inner_row = association.process_entity(entity.send(association.key))
+
+          row.add_inner_row(field: report.resolve_path(association.key), row: inner_row)
+        end
+      end
+
+      def process_has_many(entity, row)
+        report.has_many.each do |association|
+          entity.send(association.key).each do |entity|
+            nested_row = association.process_entity(entity)
+
+            row.add_nested_row(field: report.resolve_path(association.key), row: nested_row)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/magic_report/report/row.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module MagicReport
+  class Report
+    class Row
+      attr_accessor :data, :inner_rows, :nested_rows
+
+      def initialize
+        @data = {}
+        @inner_rows = {}
+        @nested_rows = {}
+      end
+
+      def add(field:, value:)
+        data[field] = value
+      end
+
+      def add_inner_row(field:, row:)
+        inner_rows[field] = row
+      end
+
+      def add_nested_row(field:, row:)
+        nested_rows[field] ||= []
+        nested_rows[field].push(row)
+      end
+
+      def values
+        data.values
+      end
+
+      def complex?
+        nested_rows.any?
+      end
+
+      def each_nested_row(&block)
+        nested_rows.keys.flat_map do |key|
+          nested_rows[key].map do |nested_row|
+            block.call(nested_row)
+          end
+        end
+      end
+
+      def each_inner_row(&block)
+        inner_rows.values.map do |inner_row|
+          block.call(inner_row)
+        end
+      end
+
+      def to_h
+        @to_h ||= begin
+          original_hash = inner_rows.any? ? data.merge(each_inner_row { |inner_row| inner_row.to_h }.reduce({}, :merge)) : data
+
+          if complex?
+            each_nested_row do |nested_row|
+              original_hash.merge(nested_row.to_h)
+            end
+          else
+            original_hash
+          end
+        end
+      end
+    end
+  end
+end

data/lib/magic_report/report.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module MagicReport
+  class Report
+    include ClassHelpers
+
+    attr_reader :fields, :has_one, :has_many, :name, :nested_field, :prefix, :result
+
+    def initialize(fields: nil, has_one: nil, has_many: nil, name: nil, prefix: nil, nested_field: nil)
+      @fields = fields || fields_from_class
+      @has_one = has_one || has_one_from_class
+      @has_many = has_many || has_many_from_class
+      @name = name || name_from_class
+
+      @prefix = prefix
+      @nested_field = nested_field
+    end
+
+    def process(input)
+      @result = ::MagicReport::Report::Process.new(self).call(input)
+    end
+
+    def as_csv
+      @as_csv ||= begin
+        csv = ::MagicReport::Report::Csv.new(self)
+        csv.generate
+
+        csv
+      end
+    end
+
+    def headings
+      @headings ||= (fields.map { |field| t(field.key) } + has_one.map { |association| association.report.headings } + has_many.map { |association| association.report.headings }).flatten
+    end
+
+    class << self
+      def t(key)
+        ::MagicReport::Utils.t(name: name, key: key)
+      end
+
+      def fields(*attrs)
+        @fields ||= []
+
+        Types::SymbolArray[attrs].each do |key|
+          @fields << Configuration::Field.new(key: key)
+        end
+      end
+
+      def field(*attrs)
+        key, processor = attrs
+
+        @fields ||= []
+        @fields << Configuration::Field.new(key: key, processor: processor)
+      end
+
+      def has_one(attribute, opts = {}, &block)
+        @has_one ||= []
+
+        coerced_attribute = Types::Coercible::Symbol[attribute]
+
+        klass = ::MagicReport::Utils.derive_class(opts, &block)
+
+        if (prefix = opts[:prefix])
+          opts[:prefix] = new.instance_exec(&prefix)
+        end
+
+        @has_one << Configuration::HasOne.new(klass: klass, opts: opts, key: coerced_attribute)
+      end
+
+      def has_many(attribute, opts = {}, &block)
+        @has_many ||= []
+
+        coerced_attribute = Types::Coercible::Symbol[attribute]
+
+        klass = ::MagicReport::Utils.derive_class(opts, &block)
+
+        if (prefix = opts[:prefix])
+          opts[:prefix] = new.instance_exec(&prefix)
+        end
+
+        @has_many << Configuration::HasMany.new(klass: klass, opts: opts, key: coerced_attribute)
+      end
+    end
+
+    def resolve_path(key)
+      nested_field ? "#{nested_field}.#{key}".to_sym : key
+    end
+
+    private
+
+    def t(key)
+      translated = ::MagicReport::Utils.t(name: name, key: key)
+
+      prefix ? "#{prefix} #{translated}" : translated
+    end
+  end
+end

data/lib/magic_report/utils.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MagicReport
+  module Utils
+    def underscore(klass)
+      klass.gsub(/::/, "/")
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr("-", "_")
+        .downcase
+    end
+
+    def derive_class(opts, &block)
+      if block
+        raise "name option must be provided" unless opts[:name]
+
+        cloned_klass = ::MagicReport::Report.clone
+        cloned_klass.class_eval(&block)
+        cloned_klass
+      else
+        opts[:class]
+      end
+    end
+
+    # @param name is the report name
+    # @key is a field
+    def t(name:, key:)
+      I18n.translate!("magic_report.headings.#{name}.#{key}")
+    end
+
+    module_function :underscore
+    module_function :derive_class
+    module_function :t
+  end
+end

data/lib/magic_report/version.rb

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

data/lib/magic_report.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "dry-types"
+require "i18n"
+
+require "magic_report/version"
+
+module MagicReport
+  class Error < StandardError; end
+
+  module Types
+    include ::Dry.Types()
+
+    SymbolArray = Array.of(Types::Coercible::Symbol)
+  end
+
+  require "magic_report/utils"
+
+  require "magic_report/report/class_helpers"
+  require "magic_report/report/configuration"
+  require "magic_report/report/process"
+  require "magic_report/report/row"
+  require "magic_report/report/csv"
+  require "magic_report/report"
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: magic-report
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dan Pankratev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-10-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email: thepoddubstep@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/magic_report.rb
+- lib/magic_report/report.rb
+- lib/magic_report/report/class_helpers.rb
+- lib/magic_report/report/configuration.rb
+- lib/magic_report/report/csv.rb
+- lib/magic_report/report/process.rb
+- lib/magic_report/report/row.rb
+- lib/magic_report/utils.rb
+- lib/magic_report/version.rb
+homepage: https://github.com/thefaded/magic-report
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: An easy way to export data to CSV
+test_files: []