sideroo 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5553a7ee34ceb7c54c39d8d9d3fcf409515745f06a951a077fa3dade1ea8227b
+  data.tar.gz: 1bc91fa63750c7a9f97b904059bc94eecaea61ebaea85760d05483480baaea7e
+SHA512:
+  metadata.gz: d1054a3f260db3e4cfefe54e55b365e447ba6c90263f1ab68c6a8408c2bed63c64caf6a5dc54a4550e7c41425fc397a0f3d1c54c88bf20316d381490e0637f46
+  data.tar.gz: acad185b19f07e88a74af249bf845f6564f750d2d56896f78b00a2f39090f573244697395ad98bc86f9c1f90f269efc8b9da918ad177be36ebf9275fa38eef0c

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.3.6
+before_install: gem install bundler -v 2.1.4

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considerooed inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at ntd251@users.noreply.github.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in sideroo.gemspec
+gemspec
+
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"
+gem "redis", "~> 3.3"
+gem "redis-namespace", "~>1.6"

data/Gemfile.lock

@@ -0,0 +1,39 @@
+PATH
+  remote: .
+  specs:
+    sideroo (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.3)
+    rake (12.3.3)
+    redis (3.3.5)
+    redis-namespace (1.6.0)
+      redis (>= 3.0.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake (~> 12.0)
+  redis (~> 3.3)
+  redis-namespace (~> 1.6)
+  rspec (~> 3.0)
+  sideroo!
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Duong Nguyen
+
+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,587 @@
+# Sideroo
+
+> Declarative and auditable object-oriented library for Redis
+
+`Sideroo` is `Object Oriented Redis` (`ooredis`) spelled backward.
+
+## 1. Motivations
+
+This gem is aimed to provide
+- a **declarative** Redis key definition
+  ```rb
+  class TopStoriesCache < Sideroo::Set
+    key_pattern 'top_stories:{country}:{category}'
+    description 'Cache top stories by ID per country and category'
+    example 'top_stories:us:romance'
+    key_regex /^top_stories\:(\w{2})\:([^\:]+)$/ # OPTIONAL - read docs below
+  end
+  ```
+- an **intuitive** Redis key initialization
+  ```rb
+  cache = TopStoriesCache.new(country: 'us', category: 'romance')
+  # instead of repeating key = "top_stories:#{country}:#{category}"
+  ```
+- **object-oriented** methods for each Redis data type
+  ```rb
+  # Redis Set methods
+  cache.sadd(story_id) # instead of redis.sadd(key, story_id)
+  cache.smembers # instead of redis.smembers(key)
+  cache.sismember(member) # instead of redis.sismember(key, member)
+  ```
+- an **auditable** Redis key management
+  ```rb
+  TopStoriesCache.count # key count - COMING SOON
+  TopStoriesCache.all.map(&:key) # list all keys
+  TopStoriesCache.flush # delete all keys of the same pattern - COMING SOON
+
+  # Support `where` for key searching
+  # `each`, `map` for enumerable
+  TopStoriesCache.where(category: 'romance').each do |set|
+    # ...
+  end
+  ```
+- Potential **self-generated documentation** for Redis usage
+  ```rb
+  Sideroo.report # COMING SOON
+  ```
+
+All of these are done while maintaining a **thin** abstraction on top of `redis` gem.
+
+## 2. Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sideroo'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install sideroo
+
+
+## 3. Usage
+
+### 3.0. Configurations - REQUIRED
+
+```rb
+Sideroo.configure do |c|
+  c.redis_client = Redis.new
+end
+```
+
+Sideroo provides a thin OOP abstraction on top of `redis-rb`. Therefore, it's recommended to use `redis-rb` (with / without `redis-namespace`). Any Redis clients with the same interfaces are fine too.
+
+Most of the usage are just to abstract the `key` argument into the internal state of the obj.
+
+#### Examples
+
+For Redis `Set`
+
+```rb
+# in Redis
+key = "namespace:#{dimension_1}:#{dimension_2}"
+redis_client.scard(key)
+redis_client.sadd(key, member)
+
+# in Sideroo
+class MySet < Sideroo::Set
+  key_pattern 'namespace:{dimension_1}:{dimension_2}'
+end
+
+sideroo_set = MySet.new(
+  dimension_1: value_1,
+  dimension_2: value_2,
+)
+sideroo_set.scard
+sideroo_set.sadd(member)
+```
+
+### 3.1. Define a Redis usage
+
+Each Redis usages usually
+- have a key pattern
+- use a certain Redis data type
+
+`Sideroo` provides what you need and more.
+
+There are some configurations you can specify for each use-cases.
+
+#### `key_pattern` - String - required
+
+Pattern used by the use-case
+
+```rb
+key_pattern 'top_stories:{country}:{category}'
+```
+
+#### `key_regex` - Regexp - optional
+
+Regex for better pattern matching for search. See more in Section 5.
+
+Can be 100% optional if key namespacing is done well.
+
+```rb
+key_regex /^top_stories\:(\w{2})\:([^\:]+)$/
+```
+
+#### `description` - String - optional
+
+Provide description to the use-cases.
+
+```rb
+description 'Cache top stories per country and category'
+```
+
+#### `example` - String - optional
+
+Example of actual Redis keys would be used. If specified, you can utilize `example_valid?` check to validate `key_regex` in your specs.
+
+```rb
+example 'top_stories:us:romance'
+```
+
+#### Dynamic initalization
+
+When there are dynamic components inside the key pattern, e.g. `top_stories:{country}:{category}`, the constructor would detect and require `country` and `category` during initialization.
+
+
+```rb
+# Static cache key
+class TopUserCache < Sideroo::List
+  key_pattern 'top_users' # REQUIRED
+  description 'Cache 50 top users worldwide'
+end
+
+# 1-dimension cache key
+class CountryPolicyCache < Sideroo::String
+  key_pattern 'policy:{country}' # REQUIRED
+  key_regex /^page\:(\w{2})$/ # Optional. To resolve key conflicts with other usages if any.
+  description 'Cache Policy page per country'
+end
+
+CountryPolicyCache.new # MissingKeys: Missing country
+CountryPolicyCache.new(country: 'us') # Good
+CountryPolicyCache.new(gender: 'us') # UnexpectedKeys: Unexpected keys gender
+
+# 2-dimension cache key
+class TopStoriesCache < Sideroo::List
+  key_pattern 'top_stories:{country}:{category}'
+  description 'Cache top stories by ID per country and category'
+end
+
+TopStoriesCache.new # MissingKeys: Missing country, category
+TopStoriesCache.new(country: 'us') # MissingKeys: Missing category
+TopStoriesCache.new(country: 'us', category: 'romance') # GOOD
+TopStoriesCache.new(country: 'us', cateogry: 'romance', random_key: 'random_value') # UnexpectedKeys: Unexpected keys random_key
+```
+
+### 3.2. Object-oriented methods for each data type
+
+```rb
+class CountryPageCache < Sideroo::String
+  key_pattern 'page:{country}'
+  key_regex /^page\:(\w{2})$/
+end
+
+# The key-value params are auto detected
+page_cache = CountryPageCache.new(country: country)
+page_cache.get
+
+class TopStoriesCache < Sideroo::List
+  key_pattern 'top_stories:{country}:{category}'
+  description 'Cache top stories by ID per country and category'
+end
+
+# The key-value params are auto detected
+cache = TopStoryCache.new(country: 'sg', category: 10)
+cache.lpush(story_id)
+cache.set(story_id) # NoMethodError - since `set` is not a method of List type
+```
+
+### 3.3. Search and Enumerable
+
+```rb
+class TopStoriesCache < Sideroo::Set
+  key_pattern 'top_stories:{country}:{category}'
+  description 'Cache top stories by ID per country and category'
+end
+```
+
+```
+top_stories:sg:10
+top_stories:sg:20
+top_stories:us:10
+top_stories:us:12
+```
+
+```rb
+TopStoriesCache.all # Not recommended for large db
+TopStoriesCache.all.to_a
+
+TopStoriesCache.where(country: 'sg').to_a
+
+# Loop through `top_stories:sg:*`
+TopStoriesCache.where(country: 'sg').each do |list|
+  list.key # top_stories:sg:10
+  list.smembers # return story ids
+  # ...
+end
+
+TopStoriesCache.where(country: 'sg').map do |list|
+  #...
+end
+
+TopStoriesCache.where(country: 'sg').count
+```
+
+### 3.4. Report & Generate documentation - COMING SOON
+
+```rb
+Sideroo.report
+```
+
+```
+TBD
+```
+
+### 3.5. Audit keys
+
+```rb
+TopStoriesCache.count # Scan and count
+
+TopStoriesCache.all.to_a # NOT RECOMMENDED if there are too many keys
+```
+
+### 3.6. Flush keys - COMING SOON
+
+```rb
+TopStoriesCache.flush # Delete all keys of TopStoriesCache
+```
+
+---
+
+## 4. Data Types
+
+`Sideroo` provides support for 7 main Redis data types.
+
+All `key`-related Redis methods are supported by all below types.
+
+### KEY-related methods
+
+```rb
+class AnyRecord < Sideroo::Base
+  # ...
+end
+
+record = AnyRecord.new(...)
+
+record.del
+record.dump
+record.exists
+record.expire(duration_in_seconds)
+record.expireat(time_in_seconds)
+record.persist
+record.pexpire(duration_in_ms)
+record.pexpireat(time_in_ms)
+record.pttl
+record.rename(new_key)
+record.renamenx(new_key)
+record.restore(ttl, serialized_value, options)
+record.touch
+record.ttl
+record.type
+record.unlink
+```
+
+### 4.1. `Sideroo::String`
+
+Support all KEY-related methods and its own methods.
+
+```rb
+class MyStringCache < Sideroo::String
+  # ...
+end
+
+string = MyStringCache.new(...)
+
+string.append(value)
+string.decr
+string.decrby(value) # number
+string.get
+string.getbit(offset)
+string.getrange(start, stop)
+string.getset(value)
+string.incr
+string.incrby(value)
+string.incrbyfloat(value)
+string.psetex(ttl, value)
+string.set(value)
+string.setbit(offset, value)
+string.setex(ttl, value)
+string.setnx(value)
+string.setrange(offset, value)
+string.strlen
+```
+
+### 4.2. `Sideroo::Hash`
+
+Support all KEY-related methods and its own methods.
+
+```rb
+class MyHash < Sideroo::Hash
+  # ...
+end
+
+hash = MyHash.new(...)
+
+hash.hdel(*fields)
+hash.hexists(field)
+hash.hget(field)
+hash.hgetall
+hash.hincrby(field, increment)
+hash.hincrbyfloat(field, increment)
+hash.hkeys
+hash.hlen
+hash.hmget(*fields, &blk)
+hash.hmset(*attrs)
+hash.hscan(cursor, options = {})
+hash.hscan_each(options = {}, &block)
+hash.hset(field, value)
+hash.hsetnx(field, value)
+hash.hvals
+hash.mapped_hmget(*field)
+hash.mapped_hmset(hash)
+```
+
+### 4.3. `Sideroo::List`
+
+Support all KEY-related methods and its own methods.
+
+```rb
+class MyList < Sideroo::List
+  # ...
+end
+
+list = MyList.new(...)
+
+list.blpop(timeout:)
+list.brpop(timeout:)
+list.brpoplpush(destination, options = {})
+list.lindex(index) # => String
+list.linsert(where, pivot, value) # => Fixnum
+list.llen # => Fixnum
+list.lpop # => String
+list.lpush(value) # => Fixnum
+list.lpushx(value) # => Fixnum
+list.lrange(start, stop) # => Array<String>
+list.lrem(count, value) # => Fixnum
+list.lset(index, value) # => String
+list.ltrim(start, stop) # => String
+list.rpop # => String
+list.rpoplpush(source, destination) # => nil, String
+list.rpush(value) # => Fixnum
+list.rpushx(value) # => Fixnum
+```
+
+### 4.4. `Sideroo::Set`
+
+Support all KEY-related methods and its own methods.
+
+```rb
+class SiteSet < Sideroo::Set
+  # ...
+end
+
+set = SiteSet.new(...)
+
+set.sadd(member) # => Boolean, Fixnum
+set.scard
+set.sdiff(*other_keys)
+set.sinter(*other_keys)
+set.sismember(member)
+set.smembers
+set.smove(destination, member)
+set.spop(count = nil)
+set.srandmember(count = nil)
+set.srem(member)
+set.sscan(cursor, options = {}) # => String+
+set.sscan_each(options = {}, &block) # => Enumerator
+set.sunion(*other_keys)
+set.sdiffstore(destination, *other_keys)
+set.sdiffstore!(*other_keys)
+set.sinterstore(destination, *other_keys)
+set.sinterstore!(*other_keys)
+set.sunionstore(destination, *other_keys)
+set.sunionstore!(*other_keys)
+```
+
+### 4.5. `Sideroo::SortedSet`
+
+Support all KEY-related methods and its own methods.
+
+```rb
+class MySortedSet < Sideroo::SortedSet
+  # ...
+end
+
+sorted_set = MySortedSet.new(...)
+
+sorted_set.zadd(*args) # => Boolean, ...
+sorted_set.zcard # => Fixnum
+sorted_set.zcount(min, max) # => Fixnum
+sorted_set.zincrby(increment, member) # => Float
+sorted_set.zlexcount(min, max) # => Fixnum
+sorted_set.zpopmax(count = nil) # => Array<String, Float>+
+sorted_set.zpopmin(count = nil) # => Array<String, Float>+
+sorted_set.zrange(start, stop, options = {}) # => Array<String>, Arra
+sorted_set.zrangebylex(min, max, options = {}) # => Array<String>, Arra
+sorted_set.zrangebyscore(min, max, options = {}) # => Array<String>, Arra
+sorted_set.zrank(member) # => Fixnum
+sorted_set.zrem(member) # => Boolean, Fixnum
+sorted_set.zremrangebyrank(start, stop) # => Fixnum
+sorted_set.zremrangebyscore(min, max) # => Fixnum
+sorted_set.zrevrange(start, stop, options = {}) # => Object
+sorted_set.zrevrangebylex(max, min, options = {}) # => Object
+sorted_set.zrevrangebyscore(max, min, options = {}) # => Object
+sorted_set.zrevrank(member) # => Fixnum
+sorted_set.zscan(cursor, options = {}) # => String, Arra
+sorted_set.zscan_each(options = {}, &block) # => Enumerator
+sorted_set.zscore(member) # => Float
+sorted_set.zinterstore(destination, *other_keys)
+sorted_set.zinterstore!(*other_keys)
+sorted_set.zunionstore(destination, *other_keys)
+sorted_set.zunionstore!(*other_keys)
+```
+
+### 4.6. `Sideroo::Bitmap`
+
+Support all KEY-related methods and its own methods.
+
+```rb
+class MyBitmap < Sideroo::Bitmap
+  # ...
+end
+
+bitmap = MyBitmap.new(...)
+
+bitmap.getbit(offset)
+bitmap.setbit(offset, value)
+```
+
+### 4.7. `Sideroo::HyperLogLog`
+
+Support all KEY-related methods and its own methods.
+
+```rb
+class MyHLL < Sideroo::HyperLogLog
+  # ...
+end
+
+hll = MyHLL.new(...)
+
+hll.pfadd(member)
+hll.pfcount
+hll.pfmerge(destination, *other_keys)
+hll.pfmerge!(*other_keys)
+```
+
+---
+
+## 5. Known issues
+
+### 5.1. Key conflicts on search
+
+Redis search via `keys` and `scan` methods only support `glob`-style patterns.
+
+- `h?llo` matches `hello`, `hallo` and `hxllo`
+- `h*llo` matches `hllo` and `heeeello`
+- `h[ae]llo` matches `hello` and `hallo`, but not `hillo`
+- `h[^e]llo` matches `hallo`, `hbllo`, ... but not `hello`
+- `h[a-b]llo` matches `hallo` and `hbllo`
+
+`glob`-style patterns are not as comprehensive as Regexp. This introduces conflicts for similar key patterns.
+
+For examples,
+
+- `users:{country}:{gender}` would use search pattern `users:*:*`
+- `users:{age}` would use search pattern `users:*`
+
+The second pattern does cover the data set of the first pattern. This could be avoid by having better namespacing in your applications.
+
+e.g.`ucg:{country}:{gender}` vs. `u:{user_id}`.
+
+`Sideroo` also provides an additional matching options called `key_regex` for each `class`. This would allow deeper key selection.
+
+```rb
+class TopCountryGenderUsersCache < Sideroo::Set
+  key_pattern 'users:{country}:{gender}'
+  key_regex /^users\:([a-z]{2})\:([mf])$/
+  example 'users:sg:m'
+  description 'Top users per country per gender'
+end
+
+class UserStoriesCache < Sideroo::Set
+  key_pattern 'users:{user_id}'
+  key_regex /^users\:\d+$/
+  example 'users:12345'
+  description 'Top stories per users'
+end
+```
+
+## 6. Redis Clients
+
+Redis clients can be customized at 3 levels
+- Global
+- Class
+- Instance
+
+The lower level would inherit the config from parent level if a custom Redis client is not specified.
+
+### 6.1. Global `Sideroo` config
+
+```rb
+Sideroo.configure do |c|
+  c.redis_client = global_redis_client
+end
+```
+
+### 6.2. Class level config
+
+```rb
+class UserStoriesCache < Sideroo::Set
+  # ...
+  redis_client class_redis_client
+end
+```
+
+### 6.3. Instance level config
+
+```rb
+cache = UserStoriesCache.new(...)
+cache.use_client(instance_redis_client)
+```
+
+
+## 7. 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).
+
+## 8. Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sideroo. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/sideroo/blob/master/CODE_OF_CONDUCT.md).
+
+
+## 9. License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 10. Code of Conduct
+
+Everyone interacting in the Sideroo project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/sideroo/blob/master/CODE_OF_CONDUCT.md).