twobook 0.1.1

data/lib/twobook/corrections.rb

@@ -0,0 +1,111 @@
+module Twobook
+  module Corrections
+    def self.make_deletion(event, accounts, history, happened_at: Time.current)
+      correct_history = history - [event]
+
+      snapshots = accounts.map do |a|
+        Serialization.serialize_account(a, before_event: event, allow_empty: false)
+      end.compact
+
+      CorrectionMade.new(
+        account_snapshots: snapshots,
+        corrected_events: correct_history.map { |e| Serialization.serialize_event(e) },
+        correction_explanation: { event_uuid: event.uuid, type: 'deletion' },
+        happened_at: happened_at,
+      )
+    end
+
+    def self.make_edit(edited_event, accounts, history, happened_at: Time.current)
+      index = history.index(edited_event)
+      correct_history = history.deep_dup
+      correct_history[index] = edited_event
+
+      snapshots = accounts.map do |a|
+        Serialization.serialize_account(a, before_event: edited_event, allow_empty: false)
+      end.compact
+
+      CorrectionMade.new(
+        account_snapshots: snapshots,
+        corrected_events: correct_history.map { |e| Serialization.serialize_event(e) },
+        correction_explanation: { event_uuid: edited_event.uuid, type: 'edit', new_parameters: edited_event.data },
+        happened_at: happened_at,
+      )
+    end
+
+    class CorrectionBuffer < Twobook::Account
+      account_type :assets
+    end
+
+    class CorrectionMade < Twobook::Event
+      has :account_snapshots, :corrected_events, :correction_explanation
+
+      def fetch_agreements!
+        [Correction.new]
+      end
+    end
+
+    class SimulatedDifferenceAdjustment < Handler
+      def handle(account_snapshots:, corrected_events:)
+        correct_accounts = self.class.simulate_correction(corrected_events, account_snapshots)
+
+        correct_accounts.each do |correct|
+          original = where(name: correct.name).execute(@accounts_in_process).first
+          adjust_original_account_balance(original, correct)
+          adjust_original_account_data(original, correct)
+        end
+      end
+
+      def adjust_original_account_balance(original, correct)
+        correct_balance = correct.balance || Twobook.wrap_number(0)
+        original_balance = original.balance || Twobook.wrap_number(0)
+        diff = correct_balance - original_balance
+        return if diff.zero?
+
+        if original.class.account_type == :records
+          record original, amount: diff
+        else
+          diff *= -1 if %i(revenue liabilities).include?(original.class.account_type)
+          book diff, cr: buffer_account, dr: original if diff.positive?
+          book (-1 * diff), cr: original, dr: buffer_account if diff.negative?
+        end
+      end
+
+      def adjust_original_account_data(original, correct)
+        diff = correct.data.to_a - original.data.to_a
+        return if diff.empty?
+        original << entry(0, data: diff.to_h)
+      end
+
+      def accounts(corrected_events:, account_snapshots:)
+        corrected_accounts = self.class.simulate_correction(corrected_events, account_snapshots)
+
+        requirements = corrected_accounts.map do |account|
+          query = AccountQuery.where(
+            category: account.class.category,
+            **account.data.slice(*account.class.name_includes),
+          )
+          existing(query)
+        end
+
+        labelled_requirements = (0...requirements.count).map do |n|
+          "requirement_#{n}_account".to_sym
+        end.zip(requirements).to_h
+
+        {
+          buffer_account: one(where(category: 'twobook/corrections/correction_buffer')),
+          **labelled_requirements,
+        }
+      end
+
+      def self.simulate_correction(events, accounts)
+        deserialized_events = events.map { |e| Serialization.deserialize_event(e) }
+        deserialized_accounts = accounts.map { |a| Serialization.deserialize_account(a) }
+        Twobook.simulate(deserialized_events, deserialized_accounts)
+      end
+    end
+
+    class Correction < Agreement
+      handles 'twobook/corrections/correction_made', with: 'twobook/corrections/simulated_difference_adjustment'
+    end
+  end
+end

data/lib/twobook/entry.rb

@@ -0,0 +1,15 @@
+module Twobook
+  class Entry
+    attr_reader :amount, :event, :transaction_id, :account, :data
+
+    def initialize(amount, event, transaction_id: nil, data: {})
+      @amount = Twobook.wrap_number(amount)
+
+      raise 'Required an Event' unless event.is_a?(Event)
+      @event = event
+
+      @transaction_id = transaction_id
+      @data = data
+    end
+  end
+end

data/lib/twobook/event.rb

@@ -0,0 +1,87 @@
+module Twobook
+  class Event
+    include Comparable
+
+    attr_reader :data, :happened_at, :uuid, :partial_order
+    attr_accessor :entries, :agreements
+
+    def initialize(happened_at: Time.current, uuid: SecureRandom.uuid, **data)
+      @happened_at = happened_at
+      @data = data
+      @uuid = uuid
+      @agreements = []
+      @entries = []
+
+      remaining_keys_to_match = self.class.has.deep_dup
+      @data.each do |k, v|
+        raise "Cannot initialize event #{inspect}: unexpected parameter #{k}" if remaining_keys_to_match.delete(k).nil?
+        raise "Cannot initialize event #{inspect}: #{k} is nil" if v.nil?
+
+        @data[k] = Twobook.wrap_number(v) if v.is_a?(Numeric)
+
+        define_singleton_method k, -> { @data.dig(k) }
+      end
+      raise "Cannot initialize event #{inspect}: required #{remaining_keys_to_match}" if remaining_keys_to_match.any?
+    end
+
+    def clone
+      c = super
+      c.instance_variable_set(:@entries, @entries.map(&:clone))
+      c.instance_variable_set(:@data, @data.deep_dup)
+      c
+    end
+
+    def fetch_agreements!
+      raise "I don't know how to fetch the agreements for #{@name}"
+    end
+
+    def fetch_and_assign_agreements!
+      @agreements = fetch_agreements!
+      self
+    end
+    alias load! fetch_and_assign_agreements!
+
+    def inspect
+      "<#{self.class.name} @data=#{@data} @happened_at=#{@happened_at}>"
+    end
+
+    def update_partial_order(i)
+      @partial_order = i
+      self
+    end
+
+    def update_happened_at(happened_at)
+      @happened_at = happened_at
+      self
+    end
+
+    def ==(other)
+      other.is_a?(Event) && @uuid == other.uuid
+    end
+
+    def <=>(other)
+      return @happened_at <=> other if other.is_a?(Time)
+      [@happened_at, @partial_order || 0] <=> [other.happened_at, other.partial_order || 0]
+    end
+
+    def self.event_name
+      name.underscore.gsub("#{Twobook.configuration.accounting_namespace.underscore}/events/", '')
+    end
+
+    def self.from_name(name)
+      match = types.detect { |t| t.name =~ /#{name.camelize}$/ }
+      raise "Bad event name #{name}" unless match
+      match
+    end
+
+    def self.types
+      Utilities.types(self)
+    end
+
+    def self.has(*args)
+      @has ||= []
+      return @has if args.empty?
+      @has += args
+    end
+  end
+end

data/lib/twobook/event_processing.rb

@@ -0,0 +1,61 @@
+module Twobook
+  def self.simulate(event, input_accounts = [])
+    return simulate_chain(event, input_accounts) if event.is_a?(Array)
+    raise 'Cannot simulate: event has no agreements' unless event.agreements.any?
+
+    handlers = event.agreements.reduce([]) do |memo, agreement|
+      memo + agreement.handlers_for(event)
+    end
+
+    new_accounts = handlers.reduce(Set.new(input_accounts)) do |processing_accounts, handler|
+      handler.run(processing_accounts)
+    end
+
+    # All entries added while processesing that event should satisfy the accounting equation.
+    ensure_transaction! new_accounts, event
+
+    new_accounts
+  end
+
+  def self.simulate_chain(events, input_accounts = [])
+    sorted_groups = events.group_by(&:happened_at)
+    sorted = []
+    sorted_groups.keys.sort.each do |time|
+      group = sorted_groups[time]
+      # Assign order to groups of events with the same timestamp according to the order passed in
+      sorted_group = if group.any? { |event| event.partial_order.nil? }
+                       group.map.with_index { |event, i| event.update_partial_order(i) }
+                     else
+                       group.sort_by(&:partial_order)
+                     end
+      sorted_group.each { |event| sorted << event }
+    end
+
+    sorted.reduce(input_accounts) do |accounts, event|
+      simulate(event, accounts)
+    end
+  end
+
+  def self.ensure_transaction!(accounts, event)
+    assets = sum_entries_under_account_type(:assets, accounts, event)
+    liabilities = sum_entries_under_account_type(:liabilities, accounts, event)
+    revenue = sum_entries_under_account_type(:revenue, accounts, event)
+    expenses = sum_entries_under_account_type(:expenses, accounts, event)
+
+    sum = assets - liabilities - revenue + expenses
+
+    if sum.nonzero?
+      report = accounts.map do |a|
+        "#{a.name}: #{a.entries.select { |e| e.event == event }.map(&:amount).sum}"
+      end.join("\n")
+
+      raise "Invalid transaction: must sum to zero, but summed to #{sum}. \n#{report}"
+    end
+  end
+
+  def self.sum_entries_under_account_type(type, accounts, event)
+    accounts.select { |a| a.class.account_type == type }.map do |a|
+      a.entries.select { |e| e.event == event }.map(&:amount).sum
+    end.sum
+  end
+end

data/lib/twobook/handler/booking_helpers.rb

@@ -0,0 +1,67 @@
+module Twobook
+  class Handler
+    # Mixin for Handler with some booking shorthand.
+    # Expects @account_in_process and @event_in_process to be set.
+    module BookingHelpers
+      def entry(amount, transaction_id: nil, data: {})
+        raise 'Cannot create entry - not currently processing an event' if @event_in_process.blank?
+        new_entry = Entry.new(amount, @event_in_process, transaction_id: transaction_id, data: data)
+        @event_in_process.entries << new_entry
+        new_entry
+      end
+
+      def record(account, amount: 0, **data)
+        account << entry(amount, data: data)
+      end
+
+      def book(amount, debit: nil, dr: nil, credit: nil, cr: nil)
+        to_debit = debit || dr
+        to_credit = credit || cr
+        raise 'Must credit one account and debit one account' unless to_debit && to_credit
+        transaction_id = SecureRandom.uuid
+        debit amount, to_debit, transaction_id: transaction_id
+        credit amount, to_credit, transaction_id: transaction_id
+      end
+
+      def debit(amount, account, **opts)
+        case account.class.account_type
+        when :assets
+          account << entry(amount, **opts)
+        when :liabilities
+          account << entry(-amount, **opts)
+        when :revenue
+          account << entry(-amount, **opts)
+        when :expenses
+          account << entry(amount, **opts)
+        else
+          raise "Invalid account type #{account.account_type}"
+        end
+      end
+
+      def credit(amount, account, **opts)
+        case account.class.account_type
+        when :assets
+          account << entry(-amount, **opts)
+        when :liabilities
+          account << entry(amount, **opts)
+        when :revenue
+          account << entry(amount, **opts)
+        when :expenses
+          account << entry(-amount, **opts)
+        else
+          raise "Invalid account type #{account.account_type}"
+        end
+      end
+
+      def add_account(account)
+        raise 'Cannot add accounts: not currently processing accounts' if @accounts_in_process.nil?
+        if @accounts_in_process.include?(account)
+          raise "Cannot add account #{account.name}: was already processing one with the same name."
+        end
+
+        @accounts_in_process << account
+        account
+      end
+    end
+  end
+end

data/lib/twobook/handler/query_helpers.rb

@@ -0,0 +1,83 @@
+module Twobook
+  class Handler
+    # Mixin for Handler with some query shorthand.
+    # Expects @accounts_in_process to be set when running a handler
+    # Expects @data_in_process to be set when looking up account requirements
+    module QueryHelpers
+      def one(query)
+        { requested: :one, query: query.convert_to_name_query }
+      end
+
+      def existing(query)
+        { requested: :existing, query: query.convert_to_name_query }
+      end
+
+      def many(query)
+        { requested: :many, query: query }
+      end
+
+      def where(constraints)
+        AccountQuery.where(constraints)
+      end
+
+      def satisfy_requirement(requested:, query:)
+        accounts = query.execute(@accounts_in_process)
+
+        case requested
+        when :one
+          existing = accounts.first
+          return existing if existing.present?
+          new = query.construct_account
+          @accounts_in_process << new
+          new
+        when :existing
+          it = accounts.first
+          if it.nil?
+            raise "Cannot process #{@event_in_process.inspect} with #{inspect}: " \
+              "no match for query #{query.inspect}). I have #{@accounts_in_process.join(', ')}"
+
+          end
+          it
+        when :many
+          Twobook.wrap_account_list!(accounts)
+        else
+          raise "Cannot satisfy requirement request #{requested}: not supported"
+        end
+      end
+
+      def respond_to_missing?(account_name, *_)
+        account_name.to_s =~ /_accounts?$/
+      end
+
+      def method_missing(account_label, *_)
+        super unless account_label.to_s =~ /_accounts?$/
+        super if @event_in_process.blank?
+
+        requirement = labelled_account_requirements.dig(account_label)
+        super unless requirement
+
+        satisfy_requirement(requirement)
+      end
+
+      def labelled_account_requirements
+        them = Utilities.match_params(
+          method(:accounts), @data_in_process, "Cannot generate accounts for #{inspect} with data #{@data_in_process}"
+        )
+
+        them.keys.map(&:to_s).each do |k|
+          raise "Invalid account label #{k} for #{inspect} (must end in _account(s))" unless k =~ /_accounts?/
+        end
+
+        them
+      end
+
+      def account_requirements
+        labelled_account_requirements.values
+      end
+
+      def accounts(*_)
+        {}
+      end
+    end
+  end
+end

data/lib/twobook/handler.rb

@@ -0,0 +1,59 @@
+require_relative 'handler/query_helpers'
+require_relative 'handler/booking_helpers'
+
+module Twobook
+  class Handler
+    include QueryHelpers
+    include BookingHelpers
+
+    attr_reader :event_in_process, :data_in_process
+
+    def initialize(event:, **data)
+      raise 'Must be initialized with an event' unless event.is_a?(Event)
+      @event_in_process = event
+      @data_in_process = {
+        **data,
+        **event.data,
+      }
+    end
+
+    def run(accounts)
+      raise 'No event set; was this handler initialized properly?' unless @event_in_process.present?
+      @accounts_in_process = accounts.map(&:clone)
+
+      Utilities.match_params(
+        method(:handle),
+        {
+          **@data_in_process,
+          happened_at: @event_in_process.happened_at,
+          event_name: @event_in_process.class.event_name,
+        },
+        "Cannot run handler #{self.class.handler_name} for event #{@event_in_process}",
+      )
+
+      @accounts_in_process
+    end
+
+    def handle
+      raise 'This handler needs a #handle method'
+    end
+
+    def name
+      self.class.handler_name
+    end
+
+    def self.handler_name
+      name.underscore.gsub("#{Twobook.configuration.accounting_namespace.underscore}/handlers/", '')
+    end
+
+    def self.from_name(name)
+      match = types.detect { |t| t.name =~ /#{name.camelize}$/ }
+      raise "Bad handler name: #{name}" unless match
+      match
+    end
+
+    def self.types
+      Utilities.types(self)
+    end
+  end
+end

data/lib/twobook/number_handling.rb

@@ -0,0 +1,22 @@
+require 'bigdecimal'
+
+class BigDecimal
+  # Makes it easier to work with these in a repl
+  def inspect
+    "#<BigDecimal '#{to_f}'>"
+  end
+
+  def as_json(*_)
+    truncate(Twobook::SCALE).to_f
+  end
+end
+
+module Twobook
+  ::BigDecimal.mode(::BigDecimal::ROUND_MODE, ::BigDecimal::ROUND_HALF_EVEN)
+  PRECISION = 15 # significant figures
+  SCALE = 6 # decimals after the point
+
+  def self.wrap_number(n)
+    ::BigDecimal.new(n, PRECISION).round(SCALE)
+  end
+end

data/lib/twobook/serialization.rb

@@ -0,0 +1,82 @@
+module Twobook
+  module Serialization
+    def self.serialize_event(event)
+      {
+        name: event.class.event_name,
+        data: event.data,
+        agreements: event.agreements.map { |a| serialize_agreement(a) },
+      }.as_json
+    end
+
+    def self.deserialize_event(serialized)
+      serialized.deep_symbolize_keys!
+
+      klass = Event.from_name(serialized[:name])
+      event = klass.new(
+        **deserialize_data(serialized[:data]),
+      )
+
+      event.agreements = serialized[:agreements].map { |a| deserialize_agreement(a) }
+      event
+    end
+
+    def self.serialize_agreement(agreement)
+      {
+        name: agreement.class.agreement_name,
+        data: agreement.data,
+      }.as_json
+    end
+
+    def self.deserialize_agreement(serialized)
+      serialized.deep_symbolize_keys!
+      klass = Agreement.from_name(serialized[:name])
+      klass.new(**deserialize_data(serialized[:data]))
+    end
+
+    def self.serialize_account(account, before_event: nil, allow_empty: true)
+      balance, data = if before_event.nil?
+                        [account.balance, account.data]
+                      else
+                        [
+                          account.balance_before_event(before_event),
+                          account.data_before_event(before_event),
+                        ]
+                      end
+
+      # If we don't allow empty accounts...
+      unless allow_empty
+        only_has_name_data = data.keys.all? { |key| key.in?(account.class.name_includes) }
+        return nil if balance.zero? && only_has_name_data
+      end
+
+      {
+        name: account.name,
+        balance: balance,
+        data: data,
+      }.as_json
+    end
+
+    def self.deserialize_account(serialized)
+      serialized.deep_symbolize_keys!
+      klass = Account.from_name(serialized[:name])
+      immutable_data = deserialize_data(serialized[:data].slice(*klass.name_includes))
+      mutable_data = deserialize_data(serialized[:data].slice(*klass.has))
+      account = klass.new(balance: serialized[:balance], **immutable_data)
+      account.update_mutable_data(mutable_data)
+      account
+    end
+
+    def self.deserialize_data(data)
+      converted = data.deep_symbolize_keys
+      converted.each { |k, v| converted[k] = try_parse_date(v) if k.to_s.end_with?("_at") }
+      converted
+    end
+
+    def self.try_parse_date(string)
+      return string if string.is_a?(Time)
+      Time.zone.parse(string)
+    rescue => _
+      raise "Could not convert _at data on account #{inspect}"
+    end
+  end
+end

data/lib/twobook/utilities.rb

@@ -0,0 +1,39 @@
+module Twobook
+  module Utilities
+    def self.match_params(method, available, error_message)
+      required = method.parameters.select { |p| p.first == :keyreq }.map(&:second)
+      optional = method.parameters.select { |p| p.first == :key }.map(&:second)
+
+      if method.parameters.any? { |p| p.first == :req || p.first == :opt }
+        raise "match_params only works with named parameters (was given #{method.parameters})"
+      end
+
+      missing = required - available.keys
+      raise "#{error_message} - missing parameters #{missing}" if missing.any?
+
+      params = available.slice(*(required + optional))
+      if params.any?
+        method.call(params)
+      else
+        method.call
+      end
+    end
+
+    # Lists all the leaf node descendants of a class.
+    # The files must already be loaded.
+    def self.types(klass, cache = false)
+      if cache
+        @types_cache ||= {}
+        return @types_cache[klass.name] ||= begin
+            klass.descendants
+                 .reject { |k| k.name.nil? || k.subclasses.reject { |s| s.name.nil? }.any? }
+                 .sort_by(&:name)
+          end
+      end
+
+      klass.descendants
+           .reject { |k| k.name.nil? || k.subclasses.reject { |s| s.name.nil? }.any? }
+           .sort_by(&:name)
+    end
+  end
+end

data/lib/twobook/version.rb

@@ -0,0 +1,3 @@
+module Twobook
+  VERSION = '0.1.1'
+end

data/lib/twobook.rb

@@ -0,0 +1,19 @@
+require 'twobook/version'
+require 'twobook/configuration'
+require 'active_support/inflector'
+require 'active_support/core_ext/object'
+require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/array/access'
+require 'active_support/core_ext/class/subclasses'
+require 'active_support/core_ext/enumerable'
+require 'twobook/number_handling'
+require 'twobook/utilities'
+require 'twobook/entry'
+require 'twobook/account'
+require 'twobook/account_query'
+require 'twobook/event'
+require 'twobook/handler'
+require 'twobook/agreement'
+require 'twobook/event_processing'
+require 'twobook/corrections'
+require 'twobook/serialization'

data/twobook.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'twobook/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'twobook'
+  spec.version       = Twobook::VERSION
+  spec.authors       = ['Michael Parry']
+  spec.email         = ['parry.my@gmail.com']
+
+  spec.summary       = 'Double-entry accounting with superpowers'
+  spec.description   = 'Database-optional double-entry accounting system with built-in corrections'
+  spec.homepage      = 'https://github.com/parry-my/twobook'
+  spec.license       = 'MIT'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'pry', '~> 0.10'
+  spec.add_development_dependency 'rb-readline', '~> 0.4.2'
+
+  spec.add_runtime_dependency 'activesupport', '>= 4.0.0'
+end