hws-transactions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1205ba882568d97a1a6443a6a3d3dbcf885e7449c985658e29da4b81d2ac8527
+  data.tar.gz: 5e28853389dc197feb0fdf12d417e82792f3f91f971e8d4734e7b686882802f0
+SHA512:
+  metadata.gz: a9d4888fd58c53a6e7cdb3a56f073b1cf47f2a7e84b2e88ba1dee7a5e07be83924b445540250f32da552fafc3a489e180c422570a4fbc61b18abb97c0524eafd
+  data.tar.gz: bbd70d2ffcd3302bdb34177ecb813a0d7b151db7251deb74a73700bee172e5a32e84f14cedf3eace725aee769e0ec743c8609fc36759b79049da76adfc50088d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,21 @@
+AllCops:
+  TargetRubyVersion: 2.5
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/ClassAndModuleChildren:
+  Enabled: true
+  EnforcedStyle: compact
+
+Style/RedundantSelf:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2021-11-18
+
+- Initial release

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hws-tansactions.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+
+gem 'rspec', '~> 3.0'
+
+gem 'rubocop', '~> 1.7'
+
+gem 'lsuuid'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Karthick
+
+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,73 @@
+# Hws::Transactions
+
+**Financial Primitive - Transaction**
+
+Any financial usecase will have the need to maintain the list of transactions performed. This is the primitive library to manage them.
+There are two entities - TransactionGroup and TransactionEntry.
+
+- TransactionGroup - This can be used to dictate the type of transaction and provide the scheme for the entries.
+- TransactionEntry - These are the actual transactions that occur in the usecase.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hws-transactions'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install hws-transactions
+
+## Usage
+
+### Generate migration file:
+The gem needs two tables transaction_groups and transaction_entries. They can be created by running the following commands.
+```
+    $ bundle exec rails generate hws:transaction:install
+    $ bundle exec rake db:migrate
+```
+
+### Create a transaction group
+```ruby
+Hws::Transactions.create_group('Vendor Payments', 'Track Vendor Payments Sent', ['status', 'vendor_acknowledged'], ['vendor_name', 'invoice_number', 'payment_date'])
+=> #<Hws::Transactions::Models::TransactionGroup id: "619f676d-085a-f890-9f73-6b6821ea1cad", name: "Vendor Payments", description: "Track Vendor Payments Sent", tags: {"mutable_tags"=>["status", "vendor_acknowledged"], "immutable_tags"=>["vendor_name", "invoice_number", "payment_date"]}, created_at: "2021-11-25 10:37:33", updated_at: "2021-11-25 10:37:33"> # returns the TransactionGroup object which was created
+```
+
+### Get a transaction group
+```ruby
+Hws::Transactions.get_group("619f676d-085a-f890-9f73-6b6821ea1cad")
+=> #<Hws::Transactions::Models::TransactionGroup id: "619f676d-085a-f890-9f73-6b6821ea1cad", name: "Vendor Payments", description: "Track Vendor Payments Sent", tags: {"mutable_tags"=>["status", "vendor_acknowledged"], "immutable_tags"=>["vendor_name", "invoice_number", "payment_date"]}, created_at: "2021-11-25 10:37:33", updated_at: "2021-11-25 10:37:33">
+```
+
+### Add a transaction entry
+```ruby
+Hws::Transactions.add_entry("619f676d-085a-f890-9f73-6b6821ea1cad", 15.25, Time.now, { mutable_tags: {status: 'SENT', 'vendor_acknowledged': true}, immutable_tags: {vendor_name: 'ACME Inc', invoice_number: 'DEMO123', payment_date: '2021-11-25'}})
+=> #<Hws::Transactions::Models::TransactionEntry id: "619f6e3d-2090-e0a0-668d-d4da170b77c0", transaction_group_id: "619f676d-085a-f890-9f73-6b6821ea1cad", value: 15, txn_time: "2021-11-25 11:06:37", immutable_tags: {"vendor_name"=>"ACME Inc", "invoice_number"=>"DEMO123", "payment_date"=>"2021-11-25"}, mutable_tags: {"status"=>"SENT", "vendor_acknowledged"=>false}, created_at: "2021-11-25 11:06:37", updated_at: "2021-11-25 11:06:37">
+```
+
+### Update a transaction entry
+```ruby
+Hws::Transactions.update_entry("619f676d-085a-f890-9f73-6b6821ea1cad", "619f6e3d-2090-e0a0-668d-d4da170b77c0", {status: 'COMPLETED', 'vendor_acknowledged': true})
+=> true # Update successful
+```
+
+### Fetch a transaction entry list
+```ruby
+Hws::Transactions.list_entries("619f676d-085a-f890-9f73-6b6821ea1cad", {immutable_tags: {invoice_number: 'DEMO123'}}, {page_size: 10})
+=> #<ActiveRecord::AssociationRelation [#<Hws::Transactions::Models::TransactionEntry id: "619f6e3d-2090-e0a0-668d-d4da170b77c0", transaction_group_id: "619f676d-085a-f890-9f73-6b6821ea1cad", value: 15, txn_time: "2021-11-25 11:06:37", immutable_tags: {"vendor_name"=>"ACME Inc", "payment_date"=>"2021-11-25", "invoice_number"=>"DEMO123"}, mutable_tags: {"status"=>"COMPLETED", "vendor_acknowledged"=>true}, created_at: "2021-11-25 11:06:37", updated_at: "2021-11-25 11:07:04">]>
+
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/hwslabs/hws-transactions-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "hws/tansactions"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/hws/transactions/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Adds necessary ActiveRecord migrations to the rails application
+
+Example:
+    bundle exec rails generate hws:transactions:install
+
+    This will create:
+        db/migrate/<migration_number>_create_transaction_group_and_entries.rb

data/lib/generators/hws/transactions/install_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module Hws
+  module Transactions # :nodoc:
+    module Generators # :nodoc:
+      class InstallGenerator < ::Rails::Generators::Base # :nodoc:
+        include Rails::Generators::Migration
+        source_root File.expand_path('templates', __dir__)
+
+        def self.next_migration_number(path)
+          ActiveRecord::Generators::Base.next_migration_number(path)
+        end
+
+        desc 'copying migrations to db/migrate'
+        def copy_migrations
+          migration_template 'create_transaction_group_and_entries.rb.erb',
+                             'db/migrate/create_hws_transaction_tables.rb'
+        end
+      end
+    end
+  end
+end

data/lib/generators/hws/transactions/templates/create_transaction_group_and_entries.rb.erb

@@ -0,0 +1,30 @@
+class <%= @migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def self.up
+    enable_extension 'pgcrypto' unless extensions.include?('pgcrypto')
+    create_table :transaction_groups, id: :uuid, force: true do |t|
+      t.string   :name
+      t.text     :description
+      t.jsonb    :tags
+      t.timestamps
+    end
+
+    create_table :transaction_entries, id: :uuid, force: true do |t|
+      t.uuid     :transaction_group_id
+      t.integer  :value
+      t.datetime :txn_time
+      t.jsonb    :immutable_tags
+      t.jsonb    :mutable_tags
+
+      t.timestamps
+    end
+
+    add_index :transaction_entries, :immutable_tags, using: :gin
+    add_index :transaction_entries, :mutable_tags, using: :gin
+    add_index :transaction_entries, :txn_time
+  end
+
+  def self.down
+    drop_table :transaction_groups
+    drop_table :transaction_entries
+  end
+end

data/lib/hws-transactions/helpers/query.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Hws::Helpers # :nodoc:
+  class Query # :nodoc:
+    class << self
+      def construct_query(base, filter_hash)
+        mut = filter_hash.key?('mutable_tags') ? filter_hash.delete('mutable_tags') : {}
+        immut = filter_hash.key?('immutable_tags') ? filter_hash.delete('immutable_tags') : {}
+
+        query = base.where(filter_hash)
+        query = query_jsonb(query, 'mutable_tags', mut)
+        query_jsonb(query, 'immutable_tags', immut)
+      end
+
+      def query_jsonb(base, column_name, filter_hash)
+        return base if filter_hash.empty?
+
+        base.where("#{column_name} @> ?", filter_hash.to_json)
+      end
+    end
+  end
+end

data/lib/hws-transactions/models/base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Hws::Transactions::Models
+  class Base < ActiveRecord::Base # :nodoc:
+    self.abstract_class = true
+
+    before_create :set_uuid
+
+    def set_uuid
+      self.id = LSUUID.generate if self.id.blank?
+    end
+  end
+end

data/lib/hws-transactions/models/transaction_entry.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'hws-transactions/models/base'
+
+module Hws::Transactions::Models
+  class TransactionEntry < Base
+    belongs_to :transaction_group, class_name: 'TransactionGroup', foreign_key: 'transaction_group_id'
+  end
+end

data/lib/hws-transactions/models/transaction_group.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'hws-transactions/models/base'
+require 'hws-transactions/helpers/query'
+
+module Hws::Transactions::Models
+  class TransactionGroup < Base
+    has_many :transaction_entries, foreign_key: 'transaction_group_id'
+
+    DEFAULT_LIMIT = 10
+
+    # tags: hash of the form mentioned below.
+    # {
+    #   'mutable_tags': {mutable_tag_key1: m_tag_val1, mutable_tag_key2: m_tag_val2},
+    #   'immutable_tags': {immutable_tag_key1: i_tag_val1, immutable_tag_key2: i_tag_val2}
+    # }
+    def add_entry(value, txn_time, tags = {})
+      tags = validate_and_sanitize_tags(tags)
+
+      self.transaction_entries.create(
+        value: value,
+        txn_time: txn_time,
+        mutable_tags: tags['mutable_tags'],
+        immutable_tags: tags['immutable_tags']
+      )
+    end
+
+    # only mutable tags are allowed to be updated
+    # TODO: Optimistic locking?
+    def update_entry(entry_id, mutable_tags)
+      entry = self.transaction_entries.find(entry_id)
+
+      unless mutable_tags.keys.all? { |key| self.mutable_tags.include?(key) }
+        raise 'Invalid mutable tags present in update_entry request.'
+      end
+
+      entry.update!(mutable_tags: entry.mutable_tags.merge(mutable_tags))
+    end
+
+    # filters struture:
+    # {
+    #   'col1' => 'val1',
+    #   'col2' => 'val2',
+    #   'mut1' => {
+    #     'jsonf1' => 'val1',
+    #     'jsonf2' => {'nested_jsonf3' => 'val2'}
+    #   }
+    # }
+    # pagination_context structure:
+    # {
+    #   'last_entry': '',
+    #   'page_size': 10
+    # }
+    def list_entries(filters = {}, page_context = {})
+      filtered_query = if filters.empty?
+                         self.transaction_entries
+                       else
+                         Hws::Helpers::Query.construct_query(self.transaction_entries, filters)
+                       end
+
+      unless page_context['last_entry'].nil?
+        filtered_query = filtered_query.where('id > ?', page_context['last_entry'])
+      end
+      filtered_query.order('id').limit(page_context['page_size'] || DEFAULT_LIMIT)
+    end
+
+    def mutable_tags
+      @m_tags ||= self.tags['mutable_tags'].to_set
+      @m_tags
+    end
+
+    def immutable_tags
+      @i_tags ||= self.tags['immutable_tags'].to_set
+      @i_tags
+    end
+
+    private
+
+    def validate_and_sanitize_tags(tags)
+      tags['mutable_tags'] = {} unless tags.key? 'mutable_tags'
+      tags['immutable_tags'] = {} unless tags.key? 'immutable_tags'
+
+      unless tags['mutable_tags'].keys.all? { |key| self.mutable_tags.include?(key) }
+        raise 'Invalid mutable tags present in add_entry request.'
+      end
+
+      unless tags['immutable_tags'].keys.all? { |key| self.immutable_tags.include?(key) }
+        raise 'Invalid immutable_tags tags present in add_entry request.'
+      end
+
+      tags
+    end
+  end
+end

data/lib/hws-transactions.rb

@@ -0,0 +1,62 @@
+# rubocop:disable Naming/FileName
+# frozen_string_literal: true
+
+module Hws # :nodoc:
+  module Transactions
+    # name: name of the journal
+    # description: description of the journal
+    # mutable_tags: []
+    # immutable_tags: []
+    def self.create_group(name, description, mutable_tags, immutable_tags)
+      ::Hws::Transactions::Models::TransactionGroup.create(name: name, description: description,
+                                      tags: { mutable_tags: mutable_tags, immutable_tags: immutable_tags }.with_indifferent_access)
+    end
+
+    def self.get_group(id)
+      ::Hws::Transactions::Models::TransactionGroup.find(id)
+    end
+
+    # tags: hash of the form mentioned below.
+    # {
+    #   'mutable_tags' => {mutable_tag_key1 => m_tag_val1, mutable_tag_key2 => m_tag_val2},
+    #   'immutable_tags' => {immutable_tag_key1 => i_tag_val1, immutable_tag_key2 => i_tag_val2}
+    # }
+    def self.add_entry(transaction_group_id, value, txn_time, tags)
+      self.get_group(transaction_group_id).try(:add_entry, value, txn_time, tags.with_indifferent_access)
+    end
+
+    def self.update_entry(transaction_group_id, entry_id, mutable_tags)
+      self.get_group(transaction_group_id).try(:update_entry, entry_id, mutable_tags.with_indifferent_access)
+    end
+
+    # filters: hash of the form mentioned below.
+    # {
+    #   'col1' => 'val1',
+    #   'col2' => 'val2',
+    #   'mutable_tags' => {
+    #     'jsonf1' => 'val1',
+    #     'jsonf2' => {'nested_jsonf3' => 'val2'}
+    #   }
+    #   'immutable_tags' => {
+    #     'jsonf1' => 'val1',
+    #     'jsonf2' => {'nested_jsonf3' => 'val2'}
+    #   }
+    # }
+    # pagination_context: hash of the form mentioned below.
+    # {
+    #   'last_entry': '',
+    #   'page_size': 10
+    # }
+    def self.list_entries(transaction_group_id, filters, page_context)
+      self.get_group(transaction_group_id).try(:list_entries, filters.with_indifferent_access, page_context.with_indifferent_access)
+    end
+
+    module Models # :nodoc:
+    end
+  end
+end
+
+require 'hws-transactions/models/transaction_entry'
+require 'hws-transactions/models/transaction_group'
+
+# rubocop:enable Naming/FileName

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: hws-transactions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Hypto Engineering Team
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-11-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lsuuid
+  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'
+description: Experimental transaction primitive
+email:
+- engineering@hypto.in
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/generators/hws/transactions/USAGE
+- lib/generators/hws/transactions/install_generator.rb
+- lib/generators/hws/transactions/templates/create_transaction_group_and_entries.rb.erb
+- lib/hws-transactions.rb
+- lib/hws-transactions/helpers/query.rb
+- lib/hws-transactions/models/base.rb
+- lib/hws-transactions/models/transaction_entry.rb
+- lib/hws-transactions/models/transaction_group.rb
+homepage: https://github.com/hwslabs/hws-transactions-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hwslabs/hws-transactions-ruby
+  source_code_uri: https://github.com/hwslabs/hws-transactions-ruby
+  changelog_uri: https://github.com/hwslabs/hws-transactions-ruby/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: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Experimental transaction primitive
+test_files: []