uuids

= UUIDs

{}[https://rubygems.org/gems/uuids] {}[https://travis-ci.org/nepalez/uuids] {}[https://codeclimate.com/github/nepalez/uuids] {}[https://gemnasium.com/nepalez/uuids] {}[https://coveralls.io/r/nepalez/uuids] {}[https://github.com/nepalez/uuids/blob/master/LICENSE.rdoc]

== About

The gem allows addressing ActiveRecord objects by {UUID}[http://en.wikipedia.org/wiki/Universally_Unique_Identifier]s following the {RFC4122}[http://www.ietf.org/rfc/rfc4122.txt] standard.

The gem requires Ruby 2.1+ and ActiveRecord 3.1+. It doesn't depend on full stack Rails and can be used in domain apps based on ActiveRecord.

=== Pattern

The module allows adressing records by UUID(s) instead of ID. A record can be identified by many UUIDs.

This makes it possible to merge records without touching external to the records.

For merging records it's sufficient to:

• reassign all their uuids to the united record.
• destroy old records, which no uuid refers to.

Whatever external models are referred by uuid to the deleted records, that references remains valid and will lead to the united record.

=== Example

Suppose you have models referred to cities. One day you discover a duplication among two cities: the "New York" and the "NEW YORK".

You should:

• reassign both UUIDs to "New York";
• safely remove the "NEW YORK" record.

You needn't track all records that refer to "NEW YORK". All those references will authomatically lead to merged record via old UUID.

Now the model of cities should know nothing about outer models that use it.

== Installation

Add this line to your application's Gemfile:

gem "uuids"

And then execute:

$ bundle

Or install it yourself as:

$ gem install uuids

Then run the command in the root of a end-up application:

$ uuids install -g

Use the -d key when installing the gem into a module that is not an end-up application (Rails engine etc.):

$ uuids install -d -g

(this will copy the gem's migrations to the host's dummy folder: +spec/dummy/db/migrate+).

The -g key allows copying gem's factory girl factories to the host application. Review them and remove unused.

== Usage

=== Adding UUIDs to models

Add the assotiation to your AR model with a has_uuids helper:

class City < ActiveRecord::Base
  include Uuids::Base

  has_uuids
end

This will add methods:

+#uuids+:: List of Uuids::Models::Uuid objects referred to the record. #uuid=(value):: assigns the UUID (an alias for #uuids.new value: value). +#uuid+:: main UUID for the record - a value of the first +uuids+ (ordered by value). .by_uuid(*values):: A scope for selecting unique records by UUID.

The first uuid is added by default. It can also be set manually:

# UUID generated by default:
city = City.create!
city.uuid.nil?
# => false

# UUID(s) assigned manually:
city = City.create! uuids: "6d9456a9-8f54-4ff7-ba0d-9854f1954417"
city.uuid
# => "6d9456a9-8f54-4ff7-ba0d-9854f1954417"

Destruction of object is forbidden while it has a +uuid+. You should reassign all object's UUIDs to another record in advance.

=== Referring model by UUID

# db/migrate/*_create_streets.rb
class CreateStreetsTable < ActiveRecord::Migration
  def change
    create_table :streets do |t|
      t.string :city_uuid, limit: 36
    end
    add_index :streets_table, :city_uuid
  end
end

# app/models/street.rb
class Street < ActiveRecord::Base
  include Uuids::Base

  belongs_by_uuid_to :city
end

This will add both getter and setter for the attribute:

street = Street.new name: "Damrak", city: City.new name: "Amsterdam"
street.city
# => #<City @name="Amsterdam" ... >
street.city_uuid == street.city.uuid # => true

=== Adding uuid

The module also contains the service object +Add+:

service = Uuids::Services::Add.new(
  value: "43523547-8230-5723-0457-234057254725",
  record: #<ActiveRecord::Base ... >
)
service.subscribe listener
service.run

Depending on the result of creation, the listener will receive either the :created, uuid, messages or :error, messages notification.

The service doesn't know what the record is. To provide more concise messaging, the service should be reloaded with a new name method.

module Users
  module Services
    class AddUuid < Uuids::Services::Add
      private
      def name
        # It is expected the record is a user, that responds to full_name.
        # Not the success message will be something near:
        # "The uuid ... has been added to the record Иван Иванов."
        record.full_name
      end
    end
  end
end

== Contributing

1. Fork it ( https://github.com/nepalez/uuids/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

== License

The plugin is distributed under {MIT license}[https://github.com/nepalez/uuids/blob/master/LICENSE.rdoc]