twitter_snowflake 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6823234421cda30700685779281840c03182376a020a90d15cac4f3a110bf10
+  data.tar.gz: e68055bf4fa8c33b23e2816bf15b80c8dc5ffa9e39642ffcd2b8baea0674762c
+SHA512:
+  metadata.gz: c43dc596687839df000374a8137fcd5cf4c9f0e9ef9480589aaed853fb83ffb82697113ca312ca3aa2b4511d4c8735b3a94a932ed66d54c0c8f263677f12e01c
+  data.tar.gz: 300004e8f1a00eeb413961c596fe23c1b40d6058f3283d3bfeb0f967b77cf1eff85ddb8b4479147ce6126cb1f0d8152bd651d06762ec3defa469904eeb23921c

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/profiles/
+/tmp/
+/.idea/
+.DS_Store
+*.gem
+**.sw*
+
+/vendor/bundle

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,105 @@
+# TwitterSnowflake.rb
+
+A Ruby library to handle Twitter snowflake IDs.
+
+## ⬇️ Installation
+
+There are two ways to install this library:
+
+**1. Bundler**
+
+Run `bundle init` to generate a Gemfile, append the following line to it and run `bundle install`.
+
+```
+gem 'twitter_snowflake', '~> 0.0.1'
+```
+
+**2. Gem**
+
+Or you can use Ruby's package manager: gem. Open your terminal and run the following command:
+
+```
+gem install twitter_snowflake
+```
+
+## 📦 Dependencies
+
+### Runtime
+
+TwitterSnowflake.rb does not rely on any third-party library.
+
+### Development
+
+- [YARD](https://rubygems.org/gems/yard/versions/0.9.20) – to generate documentation.
+- [Rubocop](https://rubygems.org/gems/rubocop/versions/0.76.0) – to spot bad code smells.
+
+## 📚 Documentation
+
+You can find the documentation in [Rubydoc](https://www.rubydoc.info/github/asyncnoodle/TwitterSnowflake.rb).
+
+## 🕹️ Usage
+
+To parse a snowflake ID, use `TwitterSnowflake.parse`:
+
+```ruby
+require 'twitter_snowflake'
+
+snowflake = TwitterSnowflake.parse 948_350_713_171_619_840
+  # => #<TwitterSnowflake::Snowflake:0x00005584b970d878
+  #       @epoch=1288834974657,
+  #       @id=948350713171619840,
+  #       @increment=0,
+  #       @process_id=19,
+  #       @time=2018-01-02 22:30:04 -0200,
+  #       @timestamp=1514939404181,
+  #       @worker_id=0>
+```
+
+If you don't need a whole `Snowflake` instance, you can use `TwitterSnowflake`'s utility class methods:
+
+```ruby
+TwitterSnowflake.timestamp 948_350_713_171_619_840 # => 1514939404181
+```
+
+Calculations are made with Twitter's epoch by default (`1_288_834_974_657`). You can change the epoch value by passing a keyword argument to `TwitterSnowflake.parse` or `TwitterSnowflake.timestamp`:
+
+```ruby
+discord_epoch = 1_420_070_400_000
+id = 649_027_890_029_133_824
+
+TwitterSnowflake.timestamp id, epoch: discord_epoch # => 1574810707338
+
+TwitterSnowflake.parse id, epoch: discord_epoch
+  # => <TwitterSnowflake::Snowflake:0x000056544c9e9818
+  #      @epoch=1420070400000,
+  #      @id=649027890029133824,
+  #      @increment=0,
+  #      @process_id=0,
+  #      @time=2019-11-26 20:25:07 -0300,
+  #      @timestamp=1574810707338,
+  #      @worker_id=1>
+```
+
+It is also possible to generate a snowflake yourself with `TwitterSnowflake.synthesize`:
+
+```ruby
+snowflake = TwitterSnowflake.synthesize(
+  epoch: 1_420_070_400_000, # defaults to Twitter's epoch if no value is provided
+  timestamp: 1_574_810_707_338,
+  worker_id: 1,
+  process_id: 0,
+  increment: 0,
+)
+
+p snowflake.id # => 649027890029133824
+```
+
+## 📄 License
+
+TwitterSnowflake.rb is licensed under [MIT](LICENSE).
+
+## ✏️ Contributors
+
+- [asyncnoodle](https://github.com/asyncnoodle) – author & maintainer.
+
+I'm looking to improve TwitterSnowflake.rb, so feel free to contribute!

data/lib/twitter_snowflake.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'twitter_snowflake/version'
+require 'twitter_snowflake/snowflake'
+
+# TwitterSnowflake is a library to parse snowflake IDs.
+module TwitterSnowflake
+  # Twitter's epoch in milliseconds. Used as default epoch to parse IDs.
+  TWITTER_EPOCH = 1_288_834_974_657
+
+  # Timestamp offset (low-order bit of the timestamp collection)
+  TIMESTAMP_BINARY_OFFSET = 22
+
+  # Worker ID offset (low-order bit of the worker ID collection)
+  WORKER_ID_BINARY_OFFSET = 17
+
+  # Mask to extract worker ID.
+  WORKER_ID_MASK = 0x3E000
+
+  # Process ID offset (low-order bit of the process ID collection)
+  PROCESS_ID_BINARY_OFFSET = 12
+
+  # Mask to extract process ID.
+  PROCESS_ID_MASK = 0x1F000
+
+  # Mask to extract increment.
+  INCREMENT_MASK = 0xFFF
+
+  class << self
+    # Creates a snowflake object for any given timestamp, worker ID, process ID and increment.
+    #
+    # @param epoch [Integer] base epoch in milliseconds to perform calculations.
+    # @param timestamp [Integer] the timestamp in milliseconds.
+    #
+    # @return [Snowflake] the generated snowflake.
+    def synthesize(timestamp:, worker_id: 0, process_id: 0, increment: 0, epoch: TWITTER_EPOCH)
+      id  = (timestamp - epoch) << TIMESTAMP_BINARY_OFFSET
+      id += (worker_id << WORKER_ID_BINARY_OFFSET)
+      id += (process_id << PROCESS_ID_BINARY_OFFSET)
+      id += increment
+
+      Snowflake.new(id: id, epoch: epoch)
+    end
+
+    # Parses a snowflake ID.
+    #
+    # @param id [Integer] the snowflake ID.
+    # @param epoch [Integer] base epoch in milliseconds to perform calculations.
+    #
+    # @return [Snowflake] a snowflake object.
+    def parse(id, epoch: TWITTER_EPOCH)
+      Snowflake.new(id: id, epoch: epoch)
+    end
+
+    # Extracts the timestamp from a snowflake ID.
+    #
+    # @param id [Integer] the snowflake ID.
+    # @param epoch [Integer] base epoch in milliseconds to perform calculations.
+    #
+    # @return [Integer] the timestamp in milliseconds.
+    def timestamp(id, epoch: TWITTER_EPOCH)
+      (id >> TIMESTAMP_BINARY_OFFSET) + epoch
+    end
+
+    # Extracts the worker ID from a snowflake ID.
+    #
+    # @param id [Integer] the snowflake ID.
+    #
+    # @return [Integer] the worker ID.
+    def worker_id(id)
+      (id & WORKER_ID_MASK) >> WORKER_ID_BINARY_OFFSET
+    end
+
+    # Extracts the process ID from a snowflake ID.
+    #
+    # @param id [Integer] the snowflake ID.
+    #
+    # @return [Integer] the process ID.
+    def process_id(id)
+      (id & PROCESS_ID_MASK) >> PROCESS_ID_BINARY_OFFSET
+    end
+
+    # Extracts the increment from a snowflake ID.
+    #
+    # @param id [Integer] the snowflake ID.
+    #
+    # @return [Integer] the increment.
+    def increment(id)
+      id & INCREMENT_MASK
+    end
+  end
+end

data/lib/twitter_snowflake/snowflake.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module TwitterSnowflake
+  # A snowflake ID as a Ruby object.
+  class Snowflake
+    # @return [Integer] the snowflake ID in its original form.
+    attr_reader :id
+
+    # @return [Integer] the base epoch in milliseconds to perform calculations.
+    attr_reader :epoch
+
+    # @return [Integer] the timestamp extracted from the ID in milliseconds.
+    attr_reader :timestamp
+
+    # @return [Integer] the worker ID extracted form the ID.
+    attr_reader :worker_id
+
+    # @return [Integer] the proccess ID extracted from the ID.
+    attr_reader :process_id
+
+    # @return [Integer] the increment extracted from the ID.
+    attr_reader :increment
+
+    # @return [Time] the timestamp as a Time object
+    attr_reader :time
+
+    # @param id [Integer] the ID itself.
+    # @param epoch [Intger] base epoch in milliseconds to perform calculations.
+    def initialize(id:, epoch:)
+      # Data used during extraction process
+      @id    = id
+      @epoch = epoch
+
+      # Extracting data
+      @timestamp  = TwitterSnowflake.timestamp(@id, epoch: @epoch)
+      @worker_id  = TwitterSnowflake.worker_id(@id)
+      @process_id = TwitterSnowflake.process_id(@id)
+      @increment  = TwitterSnowflake.increment(@id)
+
+      # Useful information
+      @time = Time.at(@timestamp / 1000.0)
+    end
+
+    # Checks if two snowflakes are equal. Two snowflakes are considered equal
+    # if both have the same ID and are based on the same epoch.
+    #
+    # @param other [Snowflake] the other snowflake.
+    #
+    # @return [Boolean] whether the snowflakes are equal or not.
+    def ==(other)
+      (@id == other.id) && (@epoch == other.epoch)
+    end
+
+    # Checks if this snowflake has been generated before another snowflake.
+    #
+    # @param other [Snowflake] the other snowflake.
+    #
+    # @return [Boolean] whether this snowflake has been generated before another snowflake or not.
+    def before?(other)
+      @timestamp < other.timestamp
+    end
+
+    # Checks if this snowflake has been generated after another snowflake.
+    #
+    # @param other [Snowflake] the other snowflake.
+    #
+    # @return [Boolean] whether this snowflake has been generated after another snowflake or not.
+    def after?(other)
+      @timestamp > other.timestamp
+    end
+  end
+end

data/lib/twitter_snowflake/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TwitterSnowflake
+  VERSION = '0.0.2'
+end

data/twitter_snowflake.gemspec

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'twitter_snowflake/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'twitter_snowflake'
+  spec.version = TwitterSnowflake::VERSION
+  spec.authors = %w[asyncnoodle]
+
+  spec.summary  = 'Ruby library to handle Twitter snowflake IDs.'
+  spec.homepage = 'https://github.com/asyncnoodle/TwitterSnowflake.rb'
+  spec.license  = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|examples|lib/discordrb/webhooks)/}) }
+  spec.require_paths = %w[lib]
+
+  spec.add_development_dependency 'rspec', '~> 3.8.0'
+  spec.add_development_dependency 'rubocop', '~> 0.74.0'
+  spec.add_development_dependency 'yard', '~> 0.9.9'
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: twitter_snowflake
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- asyncnoodle
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-11-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.8.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.74.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.74.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.9
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.9
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- lib/twitter_snowflake.rb
+- lib/twitter_snowflake/snowflake.rb
+- lib/twitter_snowflake/version.rb
+- twitter_snowflake.gemspec
+homepage: https://github.com/asyncnoodle/TwitterSnowflake.rb
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Ruby library to handle Twitter snowflake IDs.
+test_files: []