redis-time-series 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58671cce77efea0c1b4f405e60dcd73cb3f01101fabdb0cb9bc8b11335392116
-  data.tar.gz: b9c7e56687b5eb7d5286a88990ca20c5d82f6857070ab953e6d74925d5cbefb6
+  metadata.gz: 60ddc8ba631c4016031490a9eb8c3e8659d6b38d3f21e3798a253ec3f63b2815
+  data.tar.gz: 7993209c75f9f23ed0fae6f918020f2a7a793575e6636e57c1bc225db3f3a63d
 SHA512:
-  metadata.gz: 402de8f815ef0ff2dfe9426d6be2e68508093c3a35d7def4721f5bfe9ba3a9b52d8b375600302b989c24fc10b4d9c7bc43249a81715267112fa4776d8429ea18
-  data.tar.gz: 3c6a554173d5f9c4a92a77c65c8c8fed8035395b3066ff0cbf222e1983347645fbabf1e498516218a042c3a3c0ad7d157ab5e39b1e22971a73189a5e3aba9496
+  metadata.gz: 1bd033ed2dfef155ba923ebee94089e41f507dcb8fcb63711a56585703d1603c32ff86b99067641b8a248587925d2bf489affd79822118e5fb42b05dbcf1c374
+  data.tar.gz: 553ffbea629efff4b1b436faf7542f35204cd9a0f47c2cf28dcd3ecc0261bd399eb19ac57a56985fc3fbeaef0e4b2e24786483bc385e06928fedcbad4f6709d0

data/.github/workflows/rspec.yml

@@ -16,13 +16,28 @@ jobs:
         image: redislabs/redistimeseries:latest
         ports:
           - 6379:6379/tcp
+    env:
+      CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
+      GIT_COMMIT_SHA: ${{ github.sha }}
+      GIT_BRANCH: ${{ github.head_ref }}
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: 2.6
+    - name: Set up CodeClimate
+      run: |
+        curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+        chmod +x ./cc-test-reporter
+        ./cc-test-reporter before-build
     - name: Install dependencies
       run: bundle install
     - name: Run specs
       run: bundle exec rake spec
+    - name: Upload coverage report
+      run: ./cc-test-reporter after-build -t simplecov coverage/.resultset.json
+    - uses: actions/upload-artifact@v2
+      with:
+        name: coverage
+        path: coverage/

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.5.0
+* Fix aggregations for TS.RANGE command (#34)
+* Extract client handling into Client module (#32)
+* Add `uncompressed` param to TS.ADD, TS.INCRBY, TS.DECRBY (#35)
+* Add `Redis::TimeSeries::Rule` object (#38)
+* Add [YARD documentation](https://rubydoc.info/gems/redis-time-series) (#40)
+
 ## 0.4.0
 * Added [hash-based filter DSL](https://github.com/dzunk/redis-time-series/tree/7173c73588da50614c02f9c89bf2ecef77766a78#filter-dsl)
 * Removed `Time#ts_msec` monkey-patch

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    redis-time-series (0.4.0)
+    redis-time-series (0.5.0)
       redis (~> 4.0)
 
 GEM
@@ -16,8 +16,10 @@ GEM
     coderay (1.1.3)
     concurrent-ruby (1.1.6)
     diff-lcs (1.3)
+    docile (1.3.2)
     i18n (1.8.3)
       concurrent-ruby (~> 1.0)
+    json (2.3.1)
     method_source (1.0.0)
     minitest (5.14.1)
     pry (0.13.1)
@@ -38,6 +40,11 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-support (3.9.3)
+    simplecov (0.17.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
     thread_safe (0.3.6)
     tzinfo (1.2.7)
       thread_safe (~> 0.1)
@@ -53,6 +60,7 @@ DEPENDENCIES
   rake (~> 13.0)
   redis-time-series!
   rspec (~> 3.0)
+  simplecov (< 0.18)
 
 BUNDLED WITH
    1.17.2

data/README.md

@@ -1,5 +1,8 @@
 [![RSpec](https://github.com/dzunk/redis-time-series/workflows/RSpec/badge.svg)](https://github.com/dzunk/redis-time-series/actions?query=workflow%3ARSpec+branch%3Amaster)
 [![Gem Version](https://badge.fury.io/rb/redis-time-series.svg)](https://badge.fury.io/rb/redis-time-series)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-brightgreen)](https://rubydoc.info/gems/redis-time-series)
+[![Maintainability](https://api.codeclimate.com/v1/badges/19a5925c20318508b4a4/maintainability)](https://codeclimate.com/github/dzunk/redis-time-series/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/19a5925c20318508b4a4/test_coverage)](https://codeclimate.com/github/dzunk/redis-time-series/test_coverage)
 
 # RedisTimeSeries
 
@@ -73,6 +76,10 @@ Add a single value with a timestamp
 ```ruby
 ts.add 1234, 3.minutes.ago # Used ActiveSupport here, but any Time object works fine
 => #<Redis::TimeSeries::Sample:0x00007fa6ce05f3f8 @time=2020-06-25 23:39:54 -0700, @value=0.1234e4>
+
+# Optionally store data uncompressed
+ts.add 5678, uncompressed: true
+=> #<Redis::TimeSeries::Sample:0x00007f93f43cdf68 @time=2020-07-18 23:15:29 -0700, @value=0.5678e4>
 ```
 Add multiple values with timestamps
 ```ruby
@@ -89,6 +96,10 @@ ts.increment # alias of incrby
 => 1593154255069
 ts.decrement # alias of decrby
 => 1593154257344
+
+# Optionally store data uncompressed
+ts.incrby 4, uncompressed: true
+=> 1595139299769
 ```
 ```ruby
 ts.get
@@ -120,31 +131,53 @@ ts.get
 ```
 Get a range of values
 ```ruby
-ts.range 10.minutes.ago..Time.current # Time range as an argument
+# Time range as an argument
+ts.range(10.minutes.ago..Time.current)
 => [#<Redis::TimeSeries::Sample:0x00007fa25f13fc28 @time=2020-06-25 23:50:51 -0700, @value=0.57e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25f13db58 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25f13d900 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25f13d680 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
-ts.range from: 10.minutes.ago, to: Time.current # Time range as keyword args
+    #<Redis::TimeSeries::Sample:0x00007fa25f13db58 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25f13d900 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25f13d680 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
+
+# Time range as keyword args
+ts.range(from: 10.minutes.ago, to: Time.current)
 => [#<Redis::TimeSeries::Sample:0x00007fa25dc01f00 @time=2020-06-25 23:50:51 -0700, @value=0.57e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25dc01d20 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25dc01b68 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
- #<Redis::TimeSeries::Sample:0x00007fa25dc019b0 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
+    #<Redis::TimeSeries::Sample:0x00007fa25dc01d20 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25dc01b68 @time=2020-06-25 23:50:57 -0700, @value=0.57e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25dc019b0 @time=2020-06-25 23:51:30 -0700, @value=0.58e2>]
+
+# Limit number of results with count argument
+ts.range(10.minutes.ago..Time.current, count: 2)
+=> [#<Redis::TimeSeries::Sample:0x00007fa25dc01f00 @time=2020-06-25 23:50:51 -0700, @value=0.57e2>,
+    #<Redis::TimeSeries::Sample:0x00007fa25dc01d20 @time=2020-06-25 23:50:55 -0700, @value=0.58e2>]
+
+# Apply aggregations to the range
+ts.range(from: 10.minutes.ago, to: Time.current, aggregation: [:avg, 10.minutes])
+=> [#<Redis::TimeSeries::Sample:0x00007fa25dc01f00 @time=2020-06-25 23:50:00 -0700, @value=0.575e2>]
 ```
 Get info about the series
 ```ruby
 ts.info
 => #<struct Redis::TimeSeries::Info
+ series=
+  #<Redis::TimeSeries:0x00007ff46da9b578 @key="ts3", @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>,
  total_samples=3,
- memory_usage=4184,
- first_timestamp=1594060993011,
- last_timestamp=1594060993060,
+ memory_usage=4264,
+ first_timestamp=1595187993605,
+ last_timestamp=1595187993629,
  retention_time=0,
  chunk_count=1,
  max_samples_per_chunk=256,
  labels={"foo"=>"bar"},
  source_key=nil,
- rules=[]>
+ rules=
+  [#<Redis::TimeSeries::Rule:0x00007ff46db30c68
+    @aggregation=#<Redis::TimeSeries::Aggregation:0x00007ff46db30c18 @duration=3600000, @type="avg">,
+    @destination_key="ts1",
+    @source=
+     #<Redis::TimeSeries:0x00007ff46da9b578
+      @key="ts3",
+      @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>>]>
+
 # Each info property is also a method on the time series object
 ts.memory_usage
 => 4208
@@ -152,6 +185,7 @@ ts.labels
 => {"foo"=>"bar"}
 ts.total_samples
 => 3
+
 # Total samples also available as #count, #length, and #size
 ts.count
 => 3
@@ -222,15 +256,19 @@ Redis::TimeSeries.where(person: Person.new('John'))
 ### Compaction Rules
 Add a compaction rule to a series.
 ```ruby
-# `dest` needs to be created before the rule is added.
+# Destintation time series needs to be created before the rule is added.
 other_ts = Redis::TimeSeries.create('other_ts')
 
-# Note: aggregation durations are measured in milliseconds
-ts.create_rule(dest: other_ts, aggregation: [:count, 6000])
+# Aggregation buckets are measured in milliseconds
+ts.create_rule(dest: other_ts, aggregation: [:count, 60000]) # 1 minute
 
-# Can also provide a string key instead of a time series object
+# Can provide a string key instead of a time series object
 ts.create_rule(dest: 'other_ts', aggregation: [:avg, 120000])
 
+# If you're using Rails or ActiveSupport, you can provide an
+# ActiveSupport::Duration instead of an integer
+ts.create_rule(dest: other_ts, aggregation: [:avg, 2.minutes])
+
 # Can also provide an Aggregation object instead of an array
 agg = Redis::TimeSeries::Aggregation.new(:avg, 120000)
 ts.create_rule(dest: other_ts, aggregation: agg)
@@ -238,9 +276,26 @@ ts.create_rule(dest: other_ts, aggregation: agg)
 # Class-level method also available
 Redis::TimeSeries.create_rule(source: ts, dest: other_ts, aggregation: ['std.p', 150000])
 ```
+Get existing compaction rules
+```ruby
+ts.rules
+=> [#<Redis::TimeSeries::Rule:0x00007ff46e91c728
+  @aggregation=#<Redis::TimeSeries::Aggregation:0x00007ff46e91c6d8 @duration=3600000, @type="avg">,
+  @destination_key="ts1",
+  @source=
+   #<Redis::TimeSeries:0x00007ff46da9b578 @key="ts3", @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>>]
+
+# Get properties of a rule too
+ts.rules.first.aggregation
+=> #<Redis::TimeSeries::Aggregation:0x00007ff46d146d38 @duration=3600000, @type="avg">
+ts.rules.first.destination
+=> #<Redis::TimeSeries:0x00007ff46d8a3d60 @key="ts1", @redis=#<Redis client v4.2.1 for redis://127.0.0.1:6379/0>>
+```
+
 Remove an existing compaction rule
 ```ruby
 ts.delete_rule(dest: 'other_ts')
+ts.rules.first.delete
 Redis::TimeSeries.delete_rule(source: ts, dest: 'other_ts')
 ```
 

data/bin/setup

@@ -3,10 +3,12 @@
 system 'bundle install'
 system 'docker pull redislabs/redistimeseries:latest'
 container_id = `docker run -p 6379:6379 -dit --rm redislabs/redistimeseries`
+at_exit { system "docker stop #{container_id}" }
 
 require 'bundler/setup'
 require 'active_support/core_ext/numeric/time'
 require 'redis'
+require 'redis-time-series'
 
 Redis.current.flushall
 ts1 = Redis::TimeSeries.create('ts1')
@@ -26,5 +28,4 @@ ts3.incrby 2
 sleep 0.01
 ts3.decrement
 
-at_exit { system "docker stop #{container_id}" }
 system "docker logs -f #{container_id}"

data/lib/ext/time_msec.rb

@@ -1,8 +1,29 @@
 # frozen_string_literal: true
+
+# The +TimeMsec+ module is a refinement for the +Time+ class that makes it easier
+# to work with millisecond timestamps.
+#
+# @example
+#   Time.now.to_i    # 1595194259
+#   Time.now.ts_msec # NoMethodError
+#
+#   using TimeMsec
+#
+#   Time.now.to_i    # 1595194259
+#   Time.now.ts_msec # 1595194259000
+#
+#   Time.from_msec(1595194259000) # 2020-07-19 14:30:59 -0700
 module TimeMsec
   refine Time do
+    # TODO: convert to #to_msec
     def ts_msec
       (to_f * 1000.0).to_i
     end
   end
+
+  refine Time.singleton_class do
+    def from_msec(timestamp)
+      at(timestamp / 1000.0)
+    end
+  end
 end

data/lib/redis-time-series.rb

@@ -1,13 +1,13 @@
 require 'bigdecimal'
 require 'forwardable'
 require 'ext/time_msec'
+require 'redis/time_series/client'
 require 'redis/time_series/errors'
 require 'redis/time_series/aggregation'
 require 'redis/time_series/filters'
+require 'redis/time_series/rule'
 require 'redis/time_series/info'
 require 'redis/time_series/sample'
 require 'redis/time_series'
 
-class RedisTimeSeries
-  VERSION = '0.4.0'
-end
+class RedisTimeSeries; end

data/lib/redis/time_series.rb

@@ -2,120 +2,233 @@
 using TimeMsec
 
 class Redis
+  # The +Redis::TimeSeries+ class is an interface for working with time-series data in
+  # Redis, using the {https://oss.redislabs.com/redistimeseries RedisTimeSeries} module.
+  #
+  # You can't use this gem with vanilla Redis, the time series module must be compiled
+  # and loaded. The easiest way to do this is by running the provided Docker container.
+  # Refer to the {https://oss.redislabs.com/redistimeseries/#setup setup guide} for more info.
+  #
+  # +docker run -p 6379:6379 -it --rm redislabs/redistimeseries+
+  #
+  # Once you're up and running, you can create a new time series and start recording data.
+  # Many commands are documented below, but you should refer to the
+  # {https://oss.redislabs.com/redistimeseries/commands command documentation} for the most
+  # authoritative and up-to-date reference.
+  #
+  # @example
+  #   ts = Redis::TimeSeries.create('time_series_example')
+  #   ts.add(12345)
+  #   ts.get
+  #   #=> #<Redis::TimeSeries::Sample:0x00007ff00d942e60 @time=2020-07-19 16:52:48 -0700, @value=0.12345e5>
   class TimeSeries
+    extend Client
     extend Forwardable
 
     class << self
+      # Create a new time series.
+      #
+      # @param key [String] the Redis key to store time series data in
+      # @option options [Hash] :labels
+      #   A hash of label-value pairs to apply to this series.
+      # @option options [Redis] :redis (self.class.redis) a different Redis client to use
+      # @option options [Integer] :retention
+      #   Maximum age for samples compared to last event time (in milliseconds).
+      #   With no value, the series will not be trimmed.
+      # @option options [Boolean] :uncompressed
+      #   When true, series data will be stored in an uncompressed format.
+      #
+      # @return [Redis::TimeSeries] the created time series
+      # @see https://oss.redislabs.com/redistimeseries/commands/#tscreate
       def create(key, **options)
-        new(key, **options).create(labels: options[:labels])
+        new(key, redis: options.fetch(:redis, redis)).create(**options)
       end
 
+      # Create a compaction rule for a series. Note that both source and destination series
+      # must exist before the rule can be created.
+      #
+      # @param source [String, TimeSeries] the source series (or key) to apply the rule to
+      # @param dest [String, TimeSeries] the destination series (or key) to aggregate the data
+      # @param aggregation [Array(<String, Symbol>, Integer), Aggregation]
+      #   The aggregation to apply. Can be an {Aggregation} object, or an array of
+      #   aggregation_type and duration +[:avg, 120000]+
+      #
+      # @return [String] the string "OK"
+      # @raise [Redis::TimeSeries::AggregationError] if the given aggregation params are invalid
+      # @raise [Redis::CommandError] if the compaction rule cannot be applied to either series
+      #
+      # @see TimeSeries#create_rule
+      # @see https://oss.redislabs.com/redistimeseries/commands/#tscreaterule
       def create_rule(source:, dest:, aggregation:)
-        args = [
-          source.is_a?(self) ? source.key : source.to_s,
-          dest.is_a?(self) ? dest.key : dest.to_s,
-          Aggregation.parse(aggregation).to_a
-        ]
-        redis.call 'TS.CREATERULE', *args.flatten
+        cmd 'TS.CREATERULE', key_for(source), key_for(dest), Aggregation.parse(aggregation).to_a
       end
 
+      # Delete an existing compaction rule.
+      #
+      # @param source [String, TimeSeries] the source series (or key) to remove the rule from
+      # @param dest [String, TimeSeries] the destination series (or key) the rule applies to
+      #
+      # @return [String] the string "OK"
+      # @raise [Redis::CommandError] if the compaction rule does not exist
       def delete_rule(source:, dest:)
-        args = [
-          source.is_a?(self) ? source.key : source.to_s,
-          dest.is_a?(self) ? dest.key : dest.to_s
-        ]
-        redis.call 'TS.DELETERULE', *args
+        cmd 'TS.DELETERULE', key_for(source), key_for(dest)
       end
 
+      # Delete all data and remove a time series from Redis.
+      #
+      # @param key [String] the key to remove
+      # @return [1] if the series existed
+      # @return [0] if the series did not exist
       def destroy(key)
         redis.del key
       end
 
       def madd(data)
         data.reduce([]) do |memo, (key, value)|
-          if value.is_a?(Hash) || (value.is_a?(Array) && value.first.is_a?(Array))
-            # multiple timestamp => value pairs
-            value.each do |timestamp, nested_value|
-              timestamp = timestamp.ts_msec if timestamp.is_a? Time
-              memo << [key, timestamp, nested_value]
-            end
-          elsif value.is_a? Array
-            # single [timestamp, value]
-            key = key.ts_msec if key.is_a? Time
-            memo << [key, value]
-          else
-            # single value, no timestamp
-            memo << [key, '*', value]
-          end
+          memo << parse_madd_values(key, value)
           memo
         end.then do |args|
-          puts "DEBUG: TS.MADD #{args.join(' ')}" if ENV['DEBUG']
-          redis.call('TS.MADD', args.flatten).each_with_index.map do |result, idx|
+          cmd('TS.MADD', args).each_with_index.map do |result, idx|
             result.is_a?(Redis::CommandError) ? result : Sample.new(result, args[idx][2])
           end
         end
       end
 
+      # Search for a time series matching the provided filters. Refer to the {Filters} documentation
+      # for more details on how to filter.
+      #
+      # @example Using a filter string
+      #   Redis::TimeSeries.query_index('foo=bar')
+      #   #=> [#<Redis::TimeSeries:0x00007ff00e222788 @key="ts3", @redis=#<Redis...>>]
+      # @example Using the .where alias with hash DSL
+      #   Redis::TimeSeries.where(foo: 'bar')
+      #   #=> [#<Redis::TimeSeries:0x00007ff00e2a1d30 @key="ts3", @redis=#<Redis...>>]
+      #
+      # @param filter_value [Hash, String] a set of filters to query with
+      # @return [Array<TimeSeries>] an array of series that matched the given filters
+      #
+      # @see Filters
+      # @see https://oss.redislabs.com/redistimeseries/commands/#tsqueryindex
+      # @see https://oss.redislabs.com/redistimeseries/commands/#filtering
       def query_index(filter_value)
         filters = Filters.new(filter_value)
         filters.validate!
-        puts "DEBUG: TS.QUERYINDEX #{filters.to_a.join(' ')}" if ENV['DEBUG']
-        redis.call('TS.QUERYINDEX', *filters.to_a).map { |key| new(key) }
+        cmd('TS.QUERYINDEX', filters.to_a).map { |key| new(key) }
       end
       alias where query_index
 
-      def redis
-        @redis ||= Redis.current
+      private
+
+      def key_for(series_or_string)
+        series_or_string.is_a?(self) ? series_or_string.key : series_or_string.to_s
       end
 
-      def redis=(client)
-        @redis = redis
+      def parse_madd_values(key, raw)
+        if raw.is_a?(Hash) || (raw.is_a?(Array) && raw.first.is_a?(Array))
+          # multiple timestamp => value pairs
+          raw.map do |timestamp, value|
+            [key, timestamp, value]
+          end
+        elsif raw.is_a? Array
+          # single [timestamp, value]
+          [key, raw.first, raw.last]
+        else
+          # single value, no timestamp
+          [key, '*', raw]
+        end
       end
     end
 
-    attr_reader :key, :redis, :retention, :uncompressed
+    # @return [String] the Redis key this time series is stored in
+    attr_reader :key
 
-    def initialize(key, options = {})
+    # @param key [String] the Redis key to store the time series in
+    # @param redis [Redis] an optional Redis client
+    def initialize(key, redis: self.class.redis)
       @key = key
-      @redis = options[:redis] || self.class.redis
-      @retention = options[:retention]
-      @uncompressed = options[:uncompressed] || false
+      @redis = redis
     end
 
-    def add(value, timestamp = '*')
-      timestamp = timestamp.ts_msec if timestamp.is_a? Time
-      ts = cmd 'TS.ADD', key, timestamp, value
+    # Add a value to the series.
+    #
+    # @param value [Numeric] the value to add
+    # @param timestamp [Time, Numeric] the +Time+, or integer timestamp in milliseconds, to add the value
+    # @param uncompressed [Boolean] if true, stores data in an uncompressed format
+    #
+    # @return [Sample] the value that was added
+    # @raise [Redis::CommandError] if the value being added is older than the latest timestamp in the series
+    def add(value, timestamp = '*', uncompressed: nil)
+      ts = cmd 'TS.ADD', key, timestamp, value, ('UNCOMPRESSED' if uncompressed)
       Sample.new(ts, value)
     end
 
-    def create(labels: nil)
-      args = [key]
-      args << ['RETENTION', retention] if retention
-      args << 'UNCOMPRESSED' if uncompressed
-      args << ['LABELS', labels.to_a] if labels&.any?
-      cmd 'TS.CREATE', args.flatten
+    # Issues a TS.CREATE command for the current series.
+    # You should use class method {Redis::TimeSeries.create} instead.
+    # @api private
+    def create(retention: nil, uncompressed: nil, labels: nil)
+      cmd 'TS.CREATE', key,
+          (['RETENTION', retention] if retention),
+          ('UNCOMPRESSED' if uncompressed),
+          (['LABELS', labels.to_a] if labels&.any?)
       self
     end
 
+    # Create a compaction rule for this series.
+    #
+    # @param dest [String, TimeSeries] the destination series (or key) to aggregate the data
+    # @param aggregation [Array(<String, Symbol>, Integer), Aggregation]
+    #   The aggregation to apply. Can be an {Aggregation} object, or an array of
+    #   aggregation_type and duration +[:avg, 120000]+
+    #
+    # @return [String] the string "OK"
+    # @raise [Redis::TimeSeries::AggregationError] if the given aggregation params are invalid
+    # @raise [Redis::CommandError] if the compaction rule cannot be applied to either series
+    #
+    # @see TimeSeries.create_rule
     def create_rule(dest:, aggregation:)
       self.class.create_rule(source: self, dest: dest, aggregation: aggregation)
     end
 
+    # Delete an existing compaction rule.
+    #
+    # @param dest [String, TimeSeries] the destination series (or key) the rule applies to
+    #
+    # @return [String] the string "OK"
+    # @raise [Redis::CommandError] if the compaction rule does not exist
+    #
+    # @see TimeSeries.delete_rule
     def delete_rule(dest:)
       self.class.delete_rule(source: self, dest: dest)
     end
 
-    def decrby(value = 1, timestamp = nil)
-      args = [key, value]
-      args << timestamp if timestamp
-      cmd 'TS.DECRBY', args
+    # Decrement the current value of the series.
+    #
+    # @param value [Integer] the amount to decrement by
+    # @param timestamp [Time, Integer] the Time or integer millisecond timestamp to save the new value at
+    # @param uncompressed [Boolean] if true, stores data in an uncompressed format
+    #
+    # @return [Integer] the timestamp the value was stored at
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsincrbytsdecrby
+    def decrby(value = 1, timestamp = nil, uncompressed: nil)
+      cmd 'TS.DECRBY', key, value, (timestamp if timestamp), ('UNCOMPRESSED' if uncompressed)
     end
     alias decrement decrby
 
+
+    # Delete all data and remove this time series from Redis.
+    #
+    # @return [1] if the series existed
+    # @return [0] if the series did not exist
     def destroy
       redis.del key
     end
 
+    # Get the most recent sample for this series.
+    #
+    # @return [Sample] the most recent sample for this series
+    # @return [nil] if there are no samples in the series
+    #
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsget
     def get
       cmd('TS.GET', key).then do |timestamp, value|
         return unless value
@@ -123,28 +236,46 @@ class Redis
       end
     end
 
-    def incrby(value = 1, timestamp = nil)
-      args = [key, value]
-      args << timestamp if timestamp
-      cmd 'TS.INCRBY', args
+    # Increment the current value of the series.
+    #
+    # @param value [Integer] the amount to increment by
+    # @param timestamp [Time, Integer] the Time or integer millisecond timestamp to save the new value at
+    # @param uncompressed [Boolean] if true, stores data in an uncompressed format
+    #
+    # @return [Integer] the timestamp the value was stored at
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsincrbytsdecrby
+    def incrby(value = 1, timestamp = nil, uncompressed: nil)
+      cmd 'TS.INCRBY', key, value, (timestamp if timestamp), ('UNCOMPRESSED' if uncompressed)
     end
     alias increment incrby
 
+    # Get information about the series.
+    # Note that all properties of {Info} are also available on the series itself
+    # via delegation.
+    #
+    # @return [Info] an info object about the current series
+    #
+    # @see Info
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsinfo
     def info
-      cmd('TS.INFO', key).then(&Info.method(:parse))
+      Info.parse series: self, data: cmd('TS.INFO', key)
     end
-    def_delegators :info, *Info.members
-    %i[count length size].each { |m| def_delegator :info, :total_samples, m }
+    def_delegators :info, *Info.members - [:series] + %i[count length size source]
 
+    # Assign labels to the series using +TS.ALTER+
+    #
+    # @param val [Hash] a hash of label-value pairs
+    # @return [Hash] the assigned labels
+    #
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsalter
     def labels=(val)
-      cmd 'TS.ALTER', key, 'LABELS', val.to_a.flatten
+      cmd 'TS.ALTER', key, 'LABELS', val.to_a
     end
 
     def madd(*values)
       if values.one? && values.first.is_a?(Hash)
         # Hash of timestamp => value pairs
         args = values.first.map do |ts, val|
-          ts = ts.ts_msec if ts.is_a? Time
           [key, ts, val]
         end.flatten
       elsif values.one? && values.first.is_a?(Array)
@@ -164,30 +295,50 @@ class Redis
       cmd 'TS.MADD', args
     end
 
-    def range(range, count: nil, agg: nil)
-      if range.is_a? Hash
-        args = range.fetch(:from), range.fetch(:to)
-      elsif range.is_a? Range
-        args = range.min, range.max
-      end
-      args.map! { |ts| (ts.to_f * 1000).to_i }
-      args.append('COUNT', count) if count
-      args.append('AGGREGATION', agg) if agg
-      cmd('TS.RANGE', key, args).map do |ts, val|
-        Sample.new(ts, val)
+    # Get a range of values from the series
+    #
+    # @param range [Hash, Range] a time range, or hash of +from+ and +to+ values
+    # @param count [Integer] the maximum number of results to return
+    # @param aggregation [Array(<String, Symbol>, Integer), Aggregation]
+    #   The aggregation to apply. Can be an {Aggregation} object, or an array of
+    #   aggregation_type and duration +[:avg, 120000]+
+    #
+    # @return [Array<Sample>] an array of samples matching the range query
+    #
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsrangetsrevrange
+    def range(range, count: nil, aggregation: nil)
+      if range.is_a?(Hash)
+        # This is to support from: and to: passed in as hash keys
+        # `range` will swallow all parameters if they're all hash syntax
+        count = range.delete(:count)
+        aggregation = range.delete(:aggregation)
+        range = range.fetch(:from)..range.fetch(:to)
       end
+      cmd('TS.RANGE',
+          key,
+          range.min,
+          range.max,
+          (['COUNT', count] if count),
+          Aggregation.parse(aggregation)&.to_a
+         ).map { |ts, val| Sample.new(ts, val) }
     end
 
+    # Set data retention time for the series using +TS.ALTER+
+    #
+    # @param val [Integer] the number of milliseconds data should be retained. +0+ means retain forever.
+    # @return [Integer] the retention value of the series
+    #
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsalter
     def retention=(val)
-      @retention = val.to_i
+      # TODO: this should also accept an ActiveSupport::Duration
       cmd 'TS.ALTER', key, 'RETENTION', val.to_i
     end
 
-    private
-
-    def cmd(name, *args)
-      puts "DEBUG: #{name} #{args.join(' ')}" if ENV['DEBUG']
-      redis.call name, *args
+    # Compare series based on Redis key and configured client.
+    # @return [Boolean] whether the two TimeSeries objects refer to the same series
+    def ==(other)
+      return false unless other.is_a?(self.class)
+      key == other.key && redis == other.redis
     end
   end
 end

data/lib/redis/time_series/aggregation.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 class Redis
   class TimeSeries
+    # An aggregation is a combination of a mathematical function, and a time window over
+    # which to apply that function. In RedisTimeSeries, aggregations are used to downsample
+    # data from a source series to a destination series, using compaction rules.
+    #
+    # @see Redis::TimeSeries#create_rule
+    # @see Redis::TimeSeries::Rule
+    # @see https://oss.redislabs.com/redistimeseries/commands/#aggregation-compaction-downsampling
     class Aggregation
       TYPES = %w[
         avg
@@ -17,33 +24,61 @@ class Redis
         var.s
       ]
 
-      attr_reader :type, :duration
-
+      # @return [String] the type of aggregation to apply
+      # @see TYPES
+      attr_reader :type
       alias aggregation_type type
+
+      # @return [Integer] the time window to apply the aggregation over, in milliseconds
+      attr_reader :duration
       alias time_bucket duration
 
+      # Parse a method argument into an aggregation.
+      #
+      # @param agg [Array, Aggregation] an aggregation object, or an array of type and duration +[:avg, 60000]+
+      # @return [Aggregation] the parsed aggregation, or the original argument if already an aggregation
+      # @raise [AggregationError] when given an unparseable value
       def self.parse(agg)
+        return unless agg
         return agg if agg.is_a?(self)
         return new(agg.first, agg.last) if agg.is_a?(Array) && agg.size == 2
         raise AggregationError, "Couldn't parse #{agg} into an aggregation rule!"
       end
 
+      # Create a new Aggregation given a type and duration.
+      # @param type [String, Symbol] one of the valid aggregation {TYPES}
+      # @param duration [Integer, ActiveSupport::Duration]
+      #   A time window to apply this aggregation over.
+      #   If you're using ActiveSupport, duration objects (e.g. +10.minutes+) will be automatically coerced.
+      # @return [Aggregation]
+      # @raise [AggregationError] if the given aggregation type is not valid
       def initialize(type, duration)
-        unless TYPES.include? type.to_s
+        type = type.to_s.downcase
+        unless TYPES.include? type
           raise AggregationError, "#{type} is not a valid aggregation type!"
         end
-        @type = type.to_s
-        @duration = duration.to_i
+        @type = type
+        if defined?(ActiveSupport::Duration) && duration.is_a?(ActiveSupport::Duration)
+          @duration = duration.in_milliseconds
+        else
+          @duration = duration.to_i
+        end
       end
 
+      # @api private
+      # @return [Array]
       def to_a
         ['AGGREGATION', type, duration]
       end
 
+      # @api private
+      # @return [String]
       def to_s
         to_a.join(' ')
       end
 
+      # Compares aggregations based on type and duration.
+      # @return [Boolean] whether the given aggregations are equivalent
       def ==(other)
         parsed = self.class.parse(other)
         type == parsed.type && duration == parsed.duration

data/lib/redis/time_series/client.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+using TimeMsec
+
+class Redis
+  class TimeSeries
+    # The client module handles connection management for individual time series, and
+    # the parent {TimeSeries} class methods. You can enable or disable debugging, and set
+    # a default Redis client to use for time series objects.
+    module Client
+      def self.extended(base)
+        base.class_eval do
+          attr_reader :redis
+
+          private
+
+          def cmd(name, *args)
+            self.class.send :cmd_with_redis, redis, name, *args
+          end
+        end
+      end
+
+      # Check debug status. Defaults to on with +DEBUG=true+ environment variable.
+      # @return [Boolean] current debug status
+      def debug
+        @debug.nil? ? [true, 'true', 1].include?(ENV['DEBUG']) : @debug
+      end
+
+      # Enable or disable debug output for time series commands. Enabling debug will
+      # print commands to +STDOUT+ as they're executed.
+      #
+      # @example
+      #   [1] pry(main)> @ts1.get
+      #   => #<Redis::TimeSeries::Sample:0x00007fc82e9de150 @time=2020-07-19 15:01:13 -0700, @value=0.56e2>
+      #   [2] pry(main)> Redis::TimeSeries.debug = true
+      #   => true
+      #   [3] pry(main)> @ts1.get
+      #   DEBUG: TS.GET ts1
+      #    => #<Redis::TimeSeries::Sample:0x00007fc82f11b7b0 @time=2020-07-19 15:01:13 -0700, @value=0.56e2>
+      #
+      # @return [Boolean] new debug status
+      def debug=(bool)
+        @debug = !!bool
+      end
+
+      # @return [Redis] the current Redis client. Defaults to +Redis.current+
+      def redis
+        @redis ||= Redis.current
+      end
+
+      # Set the default Redis client for time series objects.
+      # This may be useful if you already use a non-time-series Redis database, and want
+      # to use both at the same time.
+      #
+      # @example
+      #   # config/initializers/redis_time_series.rb
+      #   Redis::TimeSeries.redis = Redis.new(url: 'redis://my-redis-server:6379/0')
+      #
+      # @param client [Redis] a Redis client
+      # @return [Redis]
+      def redis=(client)
+        @redis = client
+      end
+
+      private
+
+      def cmd(name, *args)
+        cmd_with_redis redis, name, *args
+      end
+
+      def cmd_with_redis(redis, name, *args)
+        args = args.flatten.compact.map { |arg| arg.is_a?(Time) ? arg.ts_msec : arg }
+        puts "DEBUG: #{name} #{args.join(' ')}" if debug
+        redis.call name, args
+      end
+    end
+  end
+end

data/lib/redis/time_series/errors.rb

@@ -1,13 +1,17 @@
 class Redis
   class TimeSeries
-    # Base error class for convenient `rescue`ing
-    class Error < StandardError; end
+    # Base error class for convenient +rescue+-ing.
+    #
+    # Descendant of +Redis::BaseError+, so you can rescue that and capture all
+    # time-series errors, as well as standard Redis command errors.
+    class Error < Redis::BaseError; end
 
-    # Invalid filter error is raised when attempting to filter without at least
-    # one equality comparison ("foo=bar")
+    # +FilterError+ is raised when a given set of filters is invalid (i.e. does not contain
+    # a equality comparison "foo=bar"), or the filter value is unparseable.
+    # @see Redis::TimeSeries::Filters
     class FilterError < Error; end
 
-    # Aggregation error is raised when attempting to create anaggreation with
+    # +AggregationError+ is raised when attempting to create an aggreation with
     # an unknown type, or when calling a command with an invalid aggregation value.
     # @see Redis::TimeSeries::Aggregation
     class AggregationError < Error; end

data/lib/redis/time_series/info.rb

@@ -1,29 +1,79 @@
 # frozen_string_literal: true
 class Redis
   class TimeSeries
+    # The Info struct wraps the result of the +TS.INFO+ command with method access.
+    # It also applies some limited parsing to the result values, mainly snakifying
+    # the property keys, and instantiating Rule objects if necessary.
+    #
+    # All properties of the struct are also available on a TimeSeries object itself
+    # via delegation.
+    #
+    # @!attribute [r] chunk_count
+    #   @return [Integer] number of memory chunks used for the time-series
+    # @!attribute [r] first_timestamp
+    #   @return [Integer] first timestamp present in the time-series (milliseconds since epoch)
+    # @!attribute [r] labels
+    #   @return [Hash] a hash of label-value pairs that represent metadata labels of the time-series
+    # @!attribute [r] last_timestamp
+    #   @return [Integer] last timestamp present in the time-series (milliseconds since epoch)
+    # @!attribute [r] max_samples_per_chunk
+    #   @return [Integer] maximum number of samples per memory chunk
+    # @!attribute [r] memory_usage
+    #   @return [Integer] total number of bytes allocated for the time-series
+    # @!attribute [r] retention_time
+    #   @return [Integer] retention time, in milliseconds, for the time-series.
+    #     A zero value means unlimited retention.
+    # @!attribute [r] rules
+    #   @return [Array<Rule>] an array of configured compaction {Rule}s
+    # @!attribute [r] series
+    #   @return [TimeSeries] the series this info is from
+    # @!attribute [r] source_key
+    #   @return [String, nil] the key of the source series, if this series is the destination
+    #     of a compaction rule
+    # @!attribute [r] total_samples
+    #   @return [Integer] the total number of samples in the series
+    #
+    # @see TimeSeries#info
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsinfo
     Info = Struct.new(
-      :total_samples,
-      :memory_usage,
+      :chunk_count,
       :first_timestamp,
+      :labels,
       :last_timestamp,
-      :retention_time,
-      :chunk_count,
       :max_samples_per_chunk,
-      :labels,
-      :source_key,
+      :memory_usage,
+      :retention_time,
       :rules,
+      :series,
+      :source_key,
+      :total_samples,
       keyword_init: true
     ) do
-      def self.parse(raw_array)
-        raw_array.each_slice(2).reduce({}) do |h, (key, value)|
+      # @api private
+      # @return [Info]
+      def self.parse(series:, data:)
+        data.each_slice(2).reduce({}) do |h, (key, value)|
           # Convert camelCase info keys to snake_case
           h[key.gsub(/(.)([A-Z])/,'\1_\2').downcase] = value
           h
         end.then do |parsed_hash|
+          parsed_hash['series'] = series
           parsed_hash['labels'] = parsed_hash['labels'].to_h
+          parsed_hash['rules'] = parsed_hash['rules'].map { |d| Rule.new(source: series, data: d) }
           new(parsed_hash)
         end
       end
+
+      alias count total_samples
+      alias length total_samples
+      alias size total_samples
+
+      # If this series is the destination of a compaction rule, returns the source series of the data.
+      # @return [TimeSeries, nil] the series referred to by {source_key}
+      def source
+        return unless source_key
+        @source ||= TimeSeries.new(source_key, redis: series.redis)
+      end
     end
   end
 end

data/lib/redis/time_series/rule.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    # A compaction rule applies an aggregation from a source series to a destination series.
+    # As data is added to the source, it will be aggregated based on any configured rule(s) and
+    # distributed to the correct destination(s).
+    #
+    # Compaction rules are useful to retain data over long time periods without requiring exorbitant
+    # amounts of memory and storage. For example, if you're collecting data on a minute-by-minute basis,
+    # you may want to retain a week's worth of data at full fidelity, and a year's worth of data downsampled
+    # to hourly, which would require 60x less memory.
+    class Rule
+      # @return [Aggregation] the configured aggregation for this rule
+      attr_reader :aggregation
+
+      # @return [String] the Redis key of the destination series
+      attr_reader :destination_key
+
+      # @return [TimeSeries] the data source of this compaction rule
+      attr_reader :source
+
+      # Manually instantiating a rule does nothing, don't bother.
+      # @api private
+      # @see Info#rules
+      def initialize(source:, data:)
+        @source = source
+        @destination_key, duration, aggregation_type = data
+        @aggregation = Aggregation.new(aggregation_type, duration)
+      end
+
+      # Delete this compaction rule.
+      # @return [String] the string "OK"
+      def delete
+        source.delete_rule(dest: destination_key)
+      end
+
+      # @return [TimeSeries] the destination time series this rule refers to
+      def destination
+        @dest ||= TimeSeries.new(destination_key, redis: source.redis)
+      end
+      alias dest destination
+
+      # @return [String] the Redis key of the source series
+      def source_key
+        source.key
+      end
+    end
+  end
+end

data/lib/redis/time_series/sample.rb

@@ -1,23 +1,39 @@
 # frozen_string_literal: true
 class Redis
   class TimeSeries
+    # A sample is an immutable value object that represents a single data point within a time series.
     class Sample
-      TS_FACTOR = 1000.0
+      using TimeMsec
 
-      attr_reader :time, :value
+      # @return [Time] the sample's timestamp
+      attr_reader :time
+      # @return [BigDecimal] the decimal value of the sample
+      attr_reader :value
 
+      # Samples are returned by time series query methods, there's no need to create one yourself.
+      # @api private
+      # @see TimeSeries#get
+      # @see TimeSeries#range
       def initialize(timestamp, value)
-        @time = Time.at(timestamp / TS_FACTOR)
+        @time = Time.from_msec(timestamp)
         @value = BigDecimal(value)
       end
 
-      def ts_msec
-        (time.to_f * TS_FACTOR).to_i
+      # @return [Integer] the millisecond value of the sample's timestamp
+      # @note
+      #   We're wrapping the method provided by the {TimeMsec} refinement for convenience,
+      #   otherwise it wouldn't be callable on {time} and devs would have to litter
+      #   +using TimeMsec+ or +* 1000.0+ wherever they wanted the value.
+      def to_msec
+        time.ts_msec
       end
 
+      # @return [Hash] a hash representation of the sample
+      # @example
+      #   {:timestamp=>1595199272401, :value=>0.2e1}
       def to_h
         {
-          timestamp: ts_msec,
+          timestamp: to_msec,
           value: value
         }
       end

data/lib/redis/time_series/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    VERSION = '0.5.0'
+  end
+end

data/redis-time-series.gemspec

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'redis-time-series'
+require 'redis/time_series/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'redis-time-series'
-  spec.version       = RedisTimeSeries::VERSION
+  spec.version       = Redis::TimeSeries::VERSION
   spec.authors       = ['Matt Duszynski']
-  spec.email         = ['mattduszynski@gmail.com']
+  spec.email         = ['dzunk@hey.com']
 
   spec.summary       = %q{A Ruby adapter for the RedisTimeSeries module.}
   # spec.description   = %q{TODO: Write a longer description or delete this line.}
@@ -38,4 +38,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pry', '~> 0.13'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'simplecov', '< 0.18' # https://github.com/codeclimate/test-reporter/issues/413
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis-time-series
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Matt Duszynski
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-18 00:00:00.000000000 Z
+date: 2020-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -94,9 +94,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.18'
 description: 
 email:
-- mattduszynski@gmail.com
+- dzunk@hey.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -116,10 +130,13 @@ files:
 - lib/redis-time-series.rb
 - lib/redis/time_series.rb
 - lib/redis/time_series/aggregation.rb
+- lib/redis/time_series/client.rb
 - lib/redis/time_series/errors.rb
 - lib/redis/time_series/filters.rb
 - lib/redis/time_series/info.rb
+- lib/redis/time_series/rule.rb
 - lib/redis/time_series/sample.rb
+- lib/redis/time_series/version.rb
 - redis-time-series.gemspec
 homepage: https://github.com/dzunk/redis-time-series
 licenses: