id_pack 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e8731fab4947eaab425af39652bdb53123f64b66
-  data.tar.gz: 7f571ff94f358063908bf0c8f0d763431c2c5a87
+  metadata.gz: 40f1290972ca537009fdccbb9f92d43b945fc7f0
+  data.tar.gz: aca88be54e625a021247f0d0e7cd890c3a4248cd
 SHA512:
-  metadata.gz: a9de58d8ce76c8f4aedcee05a7e0b2b7dac0838da532c8b7f90b23c347d16b3c9bc442a20110b7ec6635a7e117a0ae253c0339b045ace3a17188b2c201f2dac7
-  data.tar.gz: 7f81c9eef199e29ec689e0a632ade5b8fe536a2cfd11f9dfd02ca942b7ab10c562df01bd46249e8556467dc15d5bf313dc129d72e61a8827015eb12d7e172719
+  metadata.gz: 13a3bb10dd108bf19697cf285dbe16a91fb8dcf494c99bd4b667c1a81ea318b5d6088263b8c705694c7b637a6369f4ffa1f2967b6e41c56e133606f8b9ef8b51
+  data.tar.gz: 40644148114649ee617701d72a487eb18311ef2fc54bbeec9783f477e0220a02508534ffae7988a63c27fbe276a0d5ffaabaedd5e1453059b4d2d389e5452082

data/Gemfile

@@ -1,4 +1,6 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in uuid_pack.gemspec
+# Specify your gem's dependencies in id_pack.gemspec
 gemspec
+
+gem 'codecov', :require => false, :group => :test

data/Gemfile.lock

@@ -1,12 +1,18 @@
 PATH
   remote: .
   specs:
-    id_pack (0.1.0)
+    id_pack (1.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    codecov (0.1.10)
+      json
+      simplecov
+      url
     diff-lcs (1.3)
+    docile (1.1.5)
+    json (2.1.0)
     rake (10.5.0)
     rspec (3.6.0)
       rspec-core (~> 3.6.0)
@@ -21,12 +27,19 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.6.0)
     rspec-support (3.6.0)
+    simplecov (0.15.1)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    url (0.3.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.15)
+  codecov
   id_pack!
   rake (~> 10.0)
   rspec (~> 3.6)

data/README.adoc

@@ -0,0 +1,212 @@
+= id_pack
+
+image:https://img.shields.io/gem/v/id_pack.svg[
+	Gem Version, link="https://rubygems.org/gems/id_pack"]
+image:https://img.shields.io/travis/riboseinc/id_pack/master.svg[
+	Build Status, link="https://travis-ci.org/riboseinc/id_pack"]
+image:https://api.codeclimate.com/v1/badges/655d7aa547daa7b45148/maintainability[
+	"Code Climate - Maintainability", link="https://codeclimate.com/github/riboseinc/id_pack/maintainability"]
+image:https://img.shields.io/codecov/c/github/riboseinc/id_pack.svg[
+	"Test Coverage", link="https://codecov.io/gh/riboseinc/id_pack"]
+
+== Introduction
+
+This gem provides functionality to compress and decompress two different types
+of objects:
+
+1. a contiguous range or multiple contiguous ranges of integer ID
+2. a set of UUID
+
+as a single string.
+
+Both Ruby and Javascript implementations are provided.
+
+Javascript support for Rails is provided by means of a Rails engine (`IdPack::Engine`).
+
+Further, for integer ID ranges, it provides serialization of a concept called
+`sync_str`, which stands for "synchronization string".
+
+`sync_str` represents a mapping from ID to timestamp.
+It is typically generated on the client side for the server side.
+Armed with the `sync_str`, the server knows which objects the client requires,
+by comparing the timestamps from the `sync_str` with the update times of the
+corresponding objects from the database, so synchronization could be done with
+minimal waste of bandwidth.
+
+Timestamps are really just integers, _e.g._ `Time.now.to_i`.
+
+
+== Installation
+
+There are at least two ways to install this:
+
+A. The quickest way is to `gem install` on the terminal:
++
+[source,bash]
+....
+gem install id_pack
+....
+
+B. If your application has a `Gemfile`, add the following line:
++
+[source,ruby]
+....
+gem 'id_pack'
+....
++
+And then execute:
++
+[source,bash]
+....
+bundle
+....
+
+== Usage
+
+To experiment with the code, run `bin/console` for an interactive prompt.
+
+[source,ruby]
+----
+require 'id_pack'
+----
+
+=== IdPacker
+
+[source,ruby]
+----
+id_packer = IdPack::IdPacker.new
+----
+
+To encode/decode a set of IDs:
+
+[source,ruby]
+----
+ids         = [5, 6, 21, 23, 25]
+encoded_ids = id_packer.encode(ids)         #=> "_F~C_P.V"
+decoded_ids = id_packer.decode(encoded_ids) #=> [5, 6, 21, 23, 25]
+ids == decoded_ids                          #=> true
+----
+
+To work with `sync_str`:
+
+[source,ruby]
+----
+ids_synced_at = {
+  1  => 1510294889,
+  2  => 1510292639,
+  10 => 1510279639,
+}
+
+sync_str = id_packer.encode_sync_str(ids_synced_at)
+#=> "IwVmAYCYHYE4DYDMsg,IxA,IwVgTCAMQ,ExA,IwZgDBQ,IwBiA,AxA"
+
+decoded_sync_map = id_packer.decode_sync_str(sync_str)
+#=> {1=>1510294889, 2=>1510292639, 10=>1510279639}
+
+ids_synced_at == decoded_sync_map
+#=> true
+----
+
+==== Advanced `sync_str` usage
+
+`IdPacker#decode_sync_str` optionally supports a `base_timestamp`:
+
+[source,ruby]
+----
+base_timestamp2   = 1000
+decoded_sync_map2 = id_packer.decode_sync_str(sync_str, base_timestamp2)
+#=> {1=>1510295889, 2=>1510293639, 10=>1510280639}
+
+base_timestamp3   = - ids_synced_at.min[1]
+decoded_sync_map3 = id_packer.decode_sync_str(sync_str, base_timestamp3)
+#=> {1=>0, 2=>-2250, 10=>-15250}
+
+base_timestamp4   = - ids_synced_at.max[1]
+decoded_sync_map4 = id_packer.decode_sync_str(sync_str, base_timestamp4)
+#=> {1=>15250, 2=>13000, 10=>0}
+----
+
+`base_timestamp` is typically specified to reverse any normalization of
+timestamps done on the client side (not shown in this README).
+
+=== UuidPacker
+
+[source,ruby]
+----
+uuid_packer = IdPack::UuidPacker.new
+----
+
+[source,ruby]
+----
+uuids         = [
+  'ea8bed36-a73d-4fff-af36-32162274dfd1',
+  '22347af1-7c60-48e0-8cc5-a30746812267',
+  '3e514775-bfdb-44f9-92b2-c4c53a7dc89d',
+]
+----
+
+To encode/decode a set of UUIDs, first, specify the set of encoding characters:
+
+[source,ruby]
+----
+base_string = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+-_'
+----
+
+Also, decide whether we want to preserve the order of the UUIDs:
+
+[source,ruby]
+----
+ordered = true
+----
+
+[source,ruby]
+----
+encoded_uuids = uuid_packer.alphanum_compress(uuids, base_string, ordered)
+#=> "Rf2XIjQmNnr_8rzlbLfRV+ZEgWLgxaMxBxIGPo9eLES5E75coyNNSZ8i2_tdxRT4"
+
+decoded_uuids = uuid_packer.alphanum_decompress(encoded_uuids, base_string)
+#=> ["ea8bed36-a73d-4fff-af36-32162274dfd1", "22347af1-7c60-48e0-8cc5-a30746812267", "3e514775-bfdb-44f9-92b2-c4c53a7dc89d"]
+
+uuids == decoded_uuids
+#=> true
+----
+
+
+If we don't care for the order:
+
+[source,ruby]
+----
+ordered = false
+----
+
+[source,ruby]
+----
+unordered_encoded_uuids = uuid_packer.alphanum_compress(uuids, base_string, ordered)
+unordered_decoded_uuids = uuid_packer.alphanum_decompress(unordered_encoded_uuids, base_string)
+
+uuids == unordered_decoded_uuids
+#=> false
+
+uuids.sort == unordered_decoded_uuids.sort
+#=> true
+----
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `bundle exec rake spec` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/riboseinc/id_pack. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected
+to adhere to the http://contributor-covenant.org[Contributor Covenant]
+code of conduct.
+
+== License
+
+The gem is available as open source under the terms of the
+http://opensource.org/licenses/MIT[MIT License].

data/app/assets/javascripts/lib/id-packer.js

@@ -18,12 +18,12 @@
  *
  * Examples:
  *
- * // encrypt the items in an Array
+ * // encode the items in an Array
  * var collection = [5, 6, 21, 23, 25];
  * IdPacker.encodeHashKeys(collection);
  * => "_E~C_O.V"
  *
- * // encrypt the keys of an Object
+ * // encode the keys of an Object
  * var collection = {
  *   5: "a",
  *   6: "b",

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "uuid_pack"
+require "id_pack"
 
 # 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.

data/lib/id_pack/id_packer.rb

@@ -11,15 +11,15 @@ module IdPack
 #
 #     Example:
 #
-#       IdPack::IdPacker.encode([5, 6, 21, 23, 25]) # => "_F~C_P.V"
+#       IdPack::IdPacker.new.encode([5, 6, 21, 23, 25]) # => "_F~C_P.V"
 #
 #   decode:
 #     mainly used by the server to convert the compressed string back into
 #     the integer array
 #
-#       Example:
+#     Example:
 #
-#         IdPack::IdPacker.decode("_F~C_P.V") # => [5, 6, 21, 23, 25]
+#       IdPack::IdPacker.new.decode("_F~C_P.V") # => [5, 6, 21, 23, 25]
 
   class IdPacker
 

data/lib/id_pack/version.rb

@@ -1,3 +1,3 @@
 module IdPack
-  VERSION = "0.1.0".freeze
+  VERSION = "1.0.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: id_pack
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -66,7 +66,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- README.md
+- README.adoc
 - Rakefile
 - app/assets/javascripts/lib/id-packer.js
 - app/assets/javascripts/lib/lz-string.js
@@ -101,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Compression and packing methods for singular and collection IDs and UUIDs.

data/README.md

@@ -1,39 +0,0 @@
-# IdPack
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/id_pack`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'id_pack'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install id_pack
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/riboseinc/id_pack. This project is intended to be a safe,
-welcoming space for collaboration, and contributors are expected to adhere to
-the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-