Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/instacart/amountable
An easy and transparent way to attach, manage and sum Money fields to your ActiveRecord models.
https://github.com/instacart/amountable
Last synced: 2 days ago
JSON representation
An easy and transparent way to attach, manage and sum Money fields to your ActiveRecord models.
- Host: GitHub
- URL: https://github.com/instacart/amountable
- Owner: instacart
- License: isc
- Created: 2015-12-09T18:13:31.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2023-05-13T02:22:40.000Z (over 1 year ago)
- Last Synced: 2024-10-06T17:45:46.152Z (about 1 month ago)
- Language: Ruby
- Size: 78.1 KB
- Stars: 124
- Watchers: 217
- Forks: 19
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Amountable
[](https://travis-ci.org/instacart/amountable)
[](https://badge.fury.io/rb/amountable)
This gem helps you integrate Money fields into your ActiveRecord models without having to add new columns each time.
It also helps manage and sum various components of your models to keep amount definitions consistent across your application.
## Installation
Add
```ruby
gem 'amountable', github: 'instacart/amountable'
```
to your `Gemfile`. Then run
```shell
bundle
```
and
```shell
rake amountable:install:migrations
```
and finally
```shell
rake db:migrate
```
## Usage
Setup your model
```ruby
class Order < ActiveRecord::Base
act_as_amountable
amount :subtotal, sets: [:total]
amount :delivery_fee, sets: [:total, :fees]
amount :bags_fee, sets: [:total, :fees]
amount :sales_tax, sets: [:total, :taxes]
amount :local_tax, sets: [:total, :taxes]
end
```
`act_as_amountable` can take the `storage` option:
```
act_as_amountable storage: :table
```
where `storage` can be either `:table`, the `amounts` table will be used to store amounts, or `:jsonb`, a JSONB field will be used on the amountable object to store amounts are json. If you use the JSONB format, you can specify the name of the column with the `column` option. The default value for the `storage` option is `:table`.
then create it
```ruby
order = Order.create(
subtotal: Money.new(123),
delivery_fee: Money.new(100),
bags_fee: Money.new(10),
sales_tax: Money.new(56)
)
order.subtotal
# => #
order.total
# => #
order.fees
# => #
order.taxes
# => #
```
## Implementation
When you run the migration, an `amounts` table will be created with a polymorphic relationship to an `amountable`, which in the above example would be your orders.
When the an order is created with some amounts, the associated `Amount` objects are persisted.
`Amount` objects are persisted in bulk, so there are no N + 1 queries. If an amount is zero, no `Amount` model is created.
If you choose the JSONB storage option, the `amounts` table will not be used. Instead a JSONB column on the target model will be used.